Table of contents

• Why arithma
• Quick start
  • Build profiles
• Integration
• Tool catalog
• Examples
• Architecture
• Precision guarantees
• Development
  • Project layout
• Documentation
• Contributing
• License

Why arithma

graph LR
    LLM["LLM<br/>Claude / GPT / ..."]
    A["arithma<br/>173 tools · stdio"]
    R["Precise<br/>results"]
    LLM -- JSON-RPC --> A --> R
    style A fill:#8b5cf6,color:#fff,stroke:#fff,stroke-width:2px
    style LLM fill:#6366f1,color:#fff
    style R fill:#16a34a,color:#fff

• Precision first — BigDecimal with DECIMAL128 semantics (34 digits, HALF_UP), 128-bit transcendentals via astro-float.
• Zero C deps — pure Rust, single static binary for Linux, macOS, and Windows.
• Portable SIMD — runtime dispatch across SSE2 / AVX2 / AVX-512 / NEON via wide.
• IANA timezones — embedded via jiff, no libicu.
• Tested — 690 unit tests + 234 stdio integration tests across 23 categories, full suite in under a second.
• Stateless — every call is independent; safe to fan out concurrently.

[!NOTE] arithma is built specifically for LLM tool-use. Every response is a compact, line-oriented string — TOOL: OK | KEY: value | … on success, TOOL: ERROR\nREASON: [CODE] … on failure — so it round-trips safely through the MCP boundary and is trivial for an LLM to parse.

Quick start

git clone https://github.com/farchanjo/arithma.git
cd arithma
cargo build --release
./target/release/arithma   # binary: ~3 MB

[!IMPORTANT] Rust 1.94+ is required (pinned in rust-toolchain.toml).

Build profiles

Integration

claude mcp add arithma -- /absolute/path/to/target/release/arithma

{
  "mcpServers": {
    "arithma": {
      "command": "/absolute/path/to/target/release/arithma"
    }
  }
}

(printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}\n';
 printf '{"jsonrpc":"2.0","method":"notifications/initialized"}\n';
 printf '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}\n';
 sleep 0.3) | ./target/release/arithma 2>/dev/null | head -c 500

Tool catalog

173 tools · 23 categories. Full reference with inputs, outputs, and examples lives in docs/TOOLS.md.

Examples

All tools use the standard MCP tools/call JSON-RPC method. Every response is a single string in the arithma wire format.

[!TIP] Pass numeric values as strings (e.g. "0.1", not 0.1) to preserve arbitrary precision across the JSON boundary.

Response format at a glance

Tool names are rendered in SCREAMING_SNAKE_CASE. Error codes: DOMAIN_ERROR, OUT_OF_RANGE, DIVISION_BY_ZERO, PARSE_ERROR, INVALID_INPUT, UNKNOWN_VARIABLE, UNKNOWN_FUNCTION, OVERFLOW, NOT_IMPLEMENTED.

Real round-trips

→ add             {"first":"0.1","second":"0.2"}
← ADD: OK | RESULT: 0.3

→ divide          {"first":"10","second":"3"}
← DIVIDE: OK | RESULT: 3.33333333333333333333

→ sin             {"degrees":30}
← SIN: OK | RESULT: 0.5

→ evaluateWithVariables
  {"expression":"2*x + y","variables":"{\"x\":3,\"y\":1}"}
← EVALUATE_WITH_VARIABLES: OK | RESULT: 7.0

→ convert         {"value":"1","fromUnit":"km","toUnit":"mi","category":"LENGTH"}
← CONVERT: OK | RESULT: 0.6213711922373339696174341843633182

→ compoundInterest
  {"principal":"1000","annualRate":"5","years":"10","compoundsPerYear":12}
← COMPOUND_INTEREST: OK | RESULT: 1647.009497690283034841743827660086

→ subnetCalculator {"address":"192.168.1.0","cidr":24}
← SUBNET_CALCULATOR: OK | NETWORK: 192.168.1.0 | BROADCAST: 192.168.1.255
  | MASK: 255.255.255.0 | WILDCARD: 0.0.0.255 | FIRST_HOST: 192.168.1.1
  | LAST_HOST: 192.168.1.254 | USABLE_HOSTS: 254 | IP_CLASS: C

Error example

→ divide {"first":"1","second":"0"}
← DIVIDE: ERROR
  REASON: [DIVISION_BY_ZERO] cannot divide by zero

Full wire-level walkthrough: docs/API.md.

Architecture

graph TB
    Client["MCP client<br/>(Claude / Cursor / ...)"]
    Main["main.rs<br/>Tokio + stdio"]
    Server["server.rs<br/>#[tool_router] — 173 tools"]
    Tools["tools/*<br/>23 category modules"]
    Engine["engine/*<br/>expression · units · BigDecimal"]

    Client -- JSON-RPC --> Main --> Server --> Tools --> Engine

    style Main fill:#8b5cf6,color:#fff,stroke:#fff,stroke-width:2px
    style Server fill:#6366f1,color:#fff
    style Tools fill:#1e40af,color:#fff
    style Engine fill:#1e40af,color:#fff

Deep dive: docs/ARCHITECTURE.md.

Precision guarantees

[!WARNING] The fast evaluate path uses f64 for speed and is subject to standard IEEE-754 rounding. Use evaluateExact when you need 128-bit precision.

Development

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --lib                 # 690 unit tests
python3 scripts/test_stdio.py    # 234 stdio integration tests

All four must pass before committing. See docs/DEVELOPMENT.md for layout, conventions, and the contribution workflow.

Project layout

arithma/
├── Cargo.toml                   Dependencies, lint + release profiles
├── rust-toolchain.toml          Rust 1.94+ pin
├── src/
│   ├── main.rs                  Binary entry, stdio MCP transport
│   ├── lib.rs                   Library exports
│   ├── server.rs                #[tool_router] — all 173 tools
│   ├── engine/                  Expression parser, unit registry, BigDecimal helpers
│   ├── mcp/                     MCP message helpers
│   └── tools/                   23 category modules
├── scripts/test_stdio.py        Full stdio integration test
└── docs/                        INDEX · ARCHITECTURE · TOOLS · DEVELOPMENT · API

Documentation

Contributing

Issues and PRs welcome. Keep the workflow green:

• cargo fmt — formatted.
• cargo clippy --all-targets -- -D warnings — zero warnings.
• cargo test --lib — all unit tests pass.
• python3 scripts/test_stdio.py — all 234 stdio tests pass.
• en-US only in code, commits, and docs.

Use the Angular commit format: <type>(<scope>): <subject>.

License

Licensed under the Apache License, Version 2.0.