A pure-Rust Model Context Protocol server that exposes 173 expert-grade calculator tools to any LLM. Arbitrary-precision math, correctly-rounded transcendentals, finance, calculus, statistics, combinatorics, geometry, complex numbers, matrices, physics, chemistry, crypto/encoding, networking, electronics, unit conversion, and date/time — all behind a single static stdio binary.
Quick start · Integration · Tool catalog · Examples · Architecture · Docs
- Why arithma
- Quick start
- Integration
- Tool catalog
- Examples
- Architecture
- Precision guarantees
- Development
- Documentation
- Contributing
- License
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 —
BigDecimalwith DECIMAL128 semantics (34 digits, HALF_UP), 128-bit transcendentals viaastro-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, nolibicu. - 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.
git clone https://github.com/farchanjo/arithma.git
cd arithma
cargo build --release
./target/release/arithma # binary: ~3 MBImportant
Rust 1.94+ is required (pinned in rust-toolchain.toml).
| Profile | Command | Use case |
|---|---|---|
| Native | cargo build --release |
Fastest on this machine (target-cpu=native). |
| Portable | RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --profile release-portable |
Haswell+/AVX2, redistributable. |
| Dev | cargo build |
Debug symbols, incremental compilation. |
Claude Code
claude mcp add arithma -- /absolute/path/to/target/release/arithmaClaude Desktop / generic MCP clients
Add the following to your client's MCP config (mcp.json or equivalent):
{
"mcpServers": {
"arithma": {
"command": "/absolute/path/to/target/release/arithma"
}
}
}Cursor, Windsurf, OpenCode
All of these speak the same stdio MCP protocol. Point their config at the arithma binary path — no extra flags required.
Verify the server responds
(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 500The response must contain tools/list with all 173 tools.
173 tools · 23 categories. Full reference with inputs, outputs, and examples lives in docs/TOOLS.md.
| # | Category | Tools | Highlights |
|---|---|---|---|
| 1 | Basic math | 7 | add, subtract, multiply, divide, power, modulo, abs |
| 2 | Scientific | 7 | sqrt, log, log10, factorial, sin, cos, tan |
| 3 | Expression engine | 4 | evaluate, evaluateExact + variable variants — pi, e, tau, phi constants and 30+ functions (trig, hyperbolic, exp, log, gcd, hypot, factorial, …) |
| 4 | Vectors & arrays | 4 | sumArray, dotProduct, scaleArray, magnitudeArray |
| 5 | Finance | 6 | compoundInterest, loanPayment, presentValue, futureValueAnnuity, returnOnInvestment, amortizationSchedule |
| 6 | Calculus | 4 | derivative, nthDerivative, definiteIntegral, tangentLine |
| 7 | Unit conversion | 2 | convert, convertAutoDetect (21 categories, 118 units) |
| 8 | Cooking | 3 | Volume, weight, oven temperature (incl. gas mark) |
| 9 | Measure reference | 4 | listCategories, listUnits, getConversionFactor, explainConversion |
| 10 | Date & time | 5 | Timezone conversion, formatting, differences, IANA listing |
| 11 | Tape calculator | 1 | calculateWithTape with running totals |
| 12 | Graphing & roots | 3 | plotFunction, solveEquation, findRoots |
| 13 | Networking | 13 | Subnetting, VLSM, IPv4/IPv6, throughput, TCP window |
| 14 | Analog electronics | 14 | Ohm's law, filters, impedance, resonance, 555 timers |
| 15 | Digital electronics | 10 | Bases, two's complement, Gray code, ADC/DAC, Nyquist |
| 16 | Statistics | 16 | mean, median, mode, stdDev, percentile, correlation, linearRegression, normalPdf/Cdf, tTestOneSample, binomialPmf, confidenceInterval |
| 17 | Combinatorics & number theory | 7 | combination, permutation, fibonacci, isPrime, nextPrime, primeFactors, eulerTotient (exact arbitrary precision) |
| 18 | Geometry | 12 | Circle/sphere/cone/cylinder, Heron triangle, Shoelace polygon, regular polygon, 2D/3D distances |
| 19 | Complex numbers | 10 | Add/mult/div/power/sqrt, magnitude, phase, polar⇄rect (degrees) |
| 20 | Crypto & encoding | 10 | MD5, SHA-1/256/512, Base64, URL, hex, CRC-32 |
| 21 | Matrices | 10 | Add, multiply, transpose, determinant, inverse, trace, rank, 2x2 eigenvalues, cross product, Gaussian elimination |
| 22 | Physics | 12 | Kinematics, projectile motion, Newton's law, gravity, Doppler, wavelength, Planck, ideal gas, heat transfer, Stefan-Boltzmann, escape & orbital velocity |
| 23 | Chemistry | 9 | Molar mass (nested formulas), pH/pOH, molarity, molality, Henderson-Hasselbalch, half-life, decay constant, ideal-gas moles |
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.
| Shape | Layout |
|---|---|
| Scalar success | TOOL: OK | RESULT: value |
| Multi-field success | TOOL: OK | KEY_1: v1 | KEY_2: v2 | … |
| Tabular success (block) | TOOL: OK\n<fields>\nROW_1: k=v | k=v\nROW_2: … |
| Error | TOOL: ERROR\nREASON: [CODE] text\n[DETAIL: k=v] |
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.
→ 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
→ divide {"first":"1","second":"0"}
← DIVIDE: ERROR
REASON: [DIVISION_BY_ZERO] cannot divide by zero
Full wire-level walkthrough: docs/API.md.
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
| Crate | Role |
|---|---|
rmcp |
Official Rust MCP SDK (protocol + schema). |
tokio |
Multi-threaded async runtime for stdio I/O. |
bigdecimal + num-bigint |
Arbitrary-precision arithmetic (DECIMAL128). |
astro-float |
128-bit, correctly-rounded transcendentals. |
jiff |
IANA timezones, embedded database. |
wide |
Portable SIMD dispatch. |
tracing |
Structured logging to stderr (stdout stays clean). |
Deep dive: docs/ARCHITECTURE.md.
| Domain | Precision | Method |
|---|---|---|
| Basic arithmetic | Exact | BigDecimal |
| Division | 20 decimal places | HALF_UP per DECIMAL128 |
sin / cos / tan |
Exact at 0/30/45/60/90° | Lookup + astro-float fallback |
factorial |
Exact for n ∈ [0, 20] |
u64 table |
evaluate |
~15–17 digits | f64 fast path |
evaluateExact |
~34 digits | 128-bit astro-float |
| Unit conversion | 34 digits | DECIMAL128 factors |
| Financial | 34 digits | DECIMAL128 context |
| Date / Time | IANA standard | Embedded tz database |
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.
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 testsAll four must pass before committing. See docs/DEVELOPMENT.md for layout, conventions, and the contribution workflow.
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
| Doc | Purpose |
|---|---|
docs/INDEX.md |
Navigation starting point. |
docs/ARCHITECTURE.md |
Module layout, data flow, design decisions. |
docs/TOOLS.md |
Every tool: inputs, outputs, examples. |
docs/DEVELOPMENT.md |
Build, test, lint, contribute. |
docs/API.md |
MCP integration and calling conventions. |
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>.
Licensed under the Apache License, Version 2.0.
Built by @farchanjo · fabricio@archanjo.com