{"id":50141048,"url":"https://github.com/farchanjo/arithma","last_synced_at":"2026-05-24T01:05:15.812Z","repository":{"id":353034761,"uuid":"1217658308","full_name":"farchanjo/arithma","owner":"farchanjo","description":"The Ultimate LLM Calculator Engine — 87 precision math tools via MCP. Pure Rust, zero C deps, arbitrary-precision arithmetic, finance, electronics, networking, unit conversion.","archived":false,"fork":false,"pushed_at":"2026-04-22T21:14:42.000Z","size":523,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T22:29:04.078Z","etag":null,"topics":["anthropic","calculator","claude","mcp","model-context-protocol","rust","stdio"],"latest_commit_sha":null,"homepage":"https://github.com/farchanjo/arithma","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/farchanjo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-22T05:16:59.000Z","updated_at":"2026-04-22T21:14:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/farchanjo/arithma","commit_stats":null,"previous_names":["farchanjo/math-calc-mcp","farchanjo/arithma"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/farchanjo/arithma","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Farithma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Farithma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Farithma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Farithma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/farchanjo","download_url":"https://codeload.github.com/farchanjo/arithma/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/farchanjo%2Farithma/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33417491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T22:14:44.296Z","status":"ssl_error","status_checked_at":"2026-05-23T22:14:43.778Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","calculator","claude","mcp","model-context-protocol","rust","stdio"],"created_at":"2026-05-24T01:05:14.563Z","updated_at":"2026-05-24T01:05:15.792Z","avatar_url":"https://github.com/farchanjo.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# arithma\n\n### The Ultimate LLM Calculator Engine\n\n[![Rust](https://img.shields.io/badge/rust-1.94%2B-orange.svg?logo=rust)](https://www.rust-lang.org)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](./LICENSE)\n[![MCP](https://img.shields.io/badge/MCP-1.5-purple.svg)](https://modelcontextprotocol.io)\n[![Tests](https://img.shields.io/badge/tests-434-brightgreen.svg)](./scripts/test_stdio.py)\n[![Binary size](https://img.shields.io/badge/binary-~3%20MB-lightgrey.svg)](#build-profiles)\n[![Tools](https://img.shields.io/badge/tools-87-success.svg)](./docs/TOOLS.md)\n\nA pure-Rust [**Model Context Protocol**](https://modelcontextprotocol.io) 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.\n\n[Quick start](#quick-start) · [Integration](#integration) · [Tool catalog](#tool-catalog) · [Examples](#examples) · [Architecture](#architecture) · [Docs](#documentation)\n\n\u003c/div\u003e\n\n---\n\n## Table of contents\n\n- [Why arithma](#why-arithma)\n- [Quick start](#quick-start)\n  - [Build profiles](#build-profiles)\n- [Integration](#integration)\n- [Tool catalog](#tool-catalog)\n- [Examples](#examples)\n- [Architecture](#architecture)\n- [Precision guarantees](#precision-guarantees)\n- [Development](#development)\n  - [Project layout](#project-layout)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Why arithma\n\n```mermaid\ngraph LR\n    LLM[\"LLM\u003cbr/\u003eClaude / GPT / ...\"]\n    A[\"arithma\u003cbr/\u003e173 tools · stdio\"]\n    R[\"Precise\u003cbr/\u003eresults\"]\n    LLM -- JSON-RPC --\u003e A --\u003e R\n    style A fill:#8b5cf6,color:#fff,stroke:#fff,stroke-width:2px\n    style LLM fill:#6366f1,color:#fff\n    style R fill:#16a34a,color:#fff\n```\n\n- **Precision first** — `BigDecimal` with DECIMAL128 semantics (34 digits, HALF_UP), 128-bit transcendentals via `astro-float`.\n- **Zero C deps** — pure Rust, single static binary for Linux, macOS, and Windows.\n- **Portable SIMD** — runtime dispatch across SSE2 / AVX2 / AVX-512 / NEON via `wide`.\n- **IANA timezones** — embedded via `jiff`, no `libicu`.\n- **Tested** — 690 unit tests + 234 stdio integration tests across 23 categories, full suite in under a second.\n- **Stateless** — every call is independent; safe to fan out concurrently.\n\n\u003e [!NOTE]\n\u003e 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.\n\n---\n\n## Quick start\n\n```bash\ngit clone https://github.com/farchanjo/arithma.git\ncd arithma\ncargo build --release\n./target/release/arithma   # binary: ~3 MB\n```\n\n\u003e [!IMPORTANT]\n\u003e Rust **1.94+** is required (pinned in [`rust-toolchain.toml`](./rust-toolchain.toml)).\n\n### Build profiles\n\n| Profile | Command | Use case |\n|:---|:---|:---|\n| **Native** | `cargo build --release` | Fastest on this machine (`target-cpu=native`). |\n| **Portable** | `RUSTFLAGS=\"-C target-cpu=x86-64-v3\" cargo build --profile release-portable` | Haswell+/AVX2, redistributable. |\n| **Dev** | `cargo build` | Debug symbols, incremental compilation. |\n\n---\n\n## Integration\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nclaude mcp add arithma -- /absolute/path/to/target/release/arithma\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Desktop / generic MCP clients\u003c/b\u003e\u003c/summary\u003e\n\nAdd the following to your client's MCP config (`mcp.json` or equivalent):\n\n```json\n{\n  \"mcpServers\": {\n    \"arithma\": {\n      \"command\": \"/absolute/path/to/target/release/arithma\"\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor, Windsurf, OpenCode\u003c/b\u003e\u003c/summary\u003e\n\nAll of these speak the same stdio MCP protocol. Point their config at the `arithma` binary path — no extra flags required.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eVerify the server responds\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n(printf '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1\"}}}\\n';\n printf '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}\\n';\n printf '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}\\n';\n sleep 0.3) | ./target/release/arithma 2\u003e/dev/null | head -c 500\n```\n\nThe response must contain `tools/list` with all 173 tools.\n\n\u003c/details\u003e\n\n---\n\n## Tool catalog\n\n**173 tools · 23 categories.** Full reference with inputs, outputs, and examples lives in [`docs/TOOLS.md`](./docs/TOOLS.md).\n\n| # | Category | Tools | Highlights |\n|:-:|:---|:-:|:---|\n| 1 | Basic math | 7 | `add`, `subtract`, `multiply`, `divide`, `power`, `modulo`, `abs` |\n| 2 | Scientific | 7 | `sqrt`, `log`, `log10`, `factorial`, `sin`, `cos`, `tan` |\n| 3 | Expression engine | 4 | `evaluate`, `evaluateExact` + variable variants — `pi`, `e`, `tau`, `phi` constants and 30+ functions (trig, hyperbolic, exp, log, `gcd`, `hypot`, `factorial`, …) |\n| 4 | Vectors \u0026 arrays | 4 | `sumArray`, `dotProduct`, `scaleArray`, `magnitudeArray` |\n| 5 | Finance | 6 | `compoundInterest`, `loanPayment`, `presentValue`, `futureValueAnnuity`, `returnOnInvestment`, `amortizationSchedule` |\n| 6 | Calculus | 4 | `derivative`, `nthDerivative`, `definiteIntegral`, `tangentLine` |\n| 7 | Unit conversion | 2 | `convert`, `convertAutoDetect` (21 categories, 118 units) |\n| 8 | Cooking | 3 | Volume, weight, oven temperature (incl. gas mark) |\n| 9 | Measure reference | 4 | `listCategories`, `listUnits`, `getConversionFactor`, `explainConversion` |\n| 10 | Date \u0026 time | 5 | Timezone conversion, formatting, differences, IANA listing |\n| 11 | Tape calculator | 1 | `calculateWithTape` with running totals |\n| 12 | Graphing \u0026 roots | 3 | `plotFunction`, `solveEquation`, `findRoots` |\n| 13 | Networking | 13 | Subnetting, VLSM, IPv4/IPv6, throughput, TCP window |\n| 14 | Analog electronics | 14 | Ohm's law, filters, impedance, resonance, 555 timers |\n| 15 | Digital electronics | 10 | Bases, two's complement, Gray code, ADC/DAC, Nyquist |\n| 16 | Statistics | 16 | `mean`, `median`, `mode`, `stdDev`, `percentile`, `correlation`, `linearRegression`, `normalPdf/Cdf`, `tTestOneSample`, `binomialPmf`, `confidenceInterval` |\n| 17 | Combinatorics \u0026 number theory | 7 | `combination`, `permutation`, `fibonacci`, `isPrime`, `nextPrime`, `primeFactors`, `eulerTotient` (exact arbitrary precision) |\n| 18 | Geometry | 12 | Circle/sphere/cone/cylinder, Heron triangle, Shoelace polygon, regular polygon, 2D/3D distances |\n| 19 | Complex numbers | 10 | Add/mult/div/power/sqrt, magnitude, phase, polar⇄rect (degrees) |\n| 20 | Crypto \u0026 encoding | 10 | MD5, SHA-1/256/512, Base64, URL, hex, CRC-32 |\n| 21 | Matrices | 10 | Add, multiply, transpose, determinant, inverse, trace, rank, 2x2 eigenvalues, cross product, Gaussian elimination |\n| 22 | Physics | 12 | Kinematics, projectile motion, Newton's law, gravity, Doppler, wavelength, Planck, ideal gas, heat transfer, Stefan-Boltzmann, escape \u0026 orbital velocity |\n| 23 | Chemistry | 9 | Molar mass (nested formulas), pH/pOH, molarity, molality, Henderson-Hasselbalch, half-life, decay constant, ideal-gas moles |\n\n---\n\n## Examples\n\nAll tools use the standard MCP `tools/call` JSON-RPC method. Every response is a single string in the arithma wire format.\n\n\u003e [!TIP]\n\u003e Pass numeric values as **strings** (e.g. `\"0.1\"`, not `0.1`) to preserve arbitrary precision across the JSON boundary.\n\n### Response format at a glance\n\n| Shape | Layout |\n|:---|:---|\n| Scalar success | `TOOL: OK \\| RESULT: value` |\n| Multi-field success | `TOOL: OK \\| KEY_1: v1 \\| KEY_2: v2 \\| …` |\n| Tabular success (block) | `TOOL: OK\\n\u003cfields\u003e\\nROW_1: k=v \\| k=v\\nROW_2: …` |\n| Error | `TOOL: ERROR\\nREASON: [CODE] text\\n[DETAIL: k=v]` |\n\nTool 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`.\n\n### Real round-trips\n\n```text\n→ add             {\"first\":\"0.1\",\"second\":\"0.2\"}\n← ADD: OK | RESULT: 0.3\n\n→ divide          {\"first\":\"10\",\"second\":\"3\"}\n← DIVIDE: OK | RESULT: 3.33333333333333333333\n\n→ sin             {\"degrees\":30}\n← SIN: OK | RESULT: 0.5\n\n→ evaluateWithVariables\n  {\"expression\":\"2*x + y\",\"variables\":\"{\\\"x\\\":3,\\\"y\\\":1}\"}\n← EVALUATE_WITH_VARIABLES: OK | RESULT: 7.0\n\n→ convert         {\"value\":\"1\",\"fromUnit\":\"km\",\"toUnit\":\"mi\",\"category\":\"LENGTH\"}\n← CONVERT: OK | RESULT: 0.6213711922373339696174341843633182\n\n→ compoundInterest\n  {\"principal\":\"1000\",\"annualRate\":\"5\",\"years\":\"10\",\"compoundsPerYear\":12}\n← COMPOUND_INTEREST: OK | RESULT: 1647.009497690283034841743827660086\n\n→ subnetCalculator {\"address\":\"192.168.1.0\",\"cidr\":24}\n← SUBNET_CALCULATOR: OK | NETWORK: 192.168.1.0 | BROADCAST: 192.168.1.255\n  | MASK: 255.255.255.0 | WILDCARD: 0.0.0.255 | FIRST_HOST: 192.168.1.1\n  | LAST_HOST: 192.168.1.254 | USABLE_HOSTS: 254 | IP_CLASS: C\n```\n\n### Error example\n\n```text\n→ divide {\"first\":\"1\",\"second\":\"0\"}\n← DIVIDE: ERROR\n  REASON: [DIVISION_BY_ZERO] cannot divide by zero\n```\n\nFull wire-level walkthrough: [`docs/API.md`](./docs/API.md).\n\n---\n\n## Architecture\n\n```mermaid\ngraph TB\n    Client[\"MCP client\u003cbr/\u003e(Claude / Cursor / ...)\"]\n    Main[\"main.rs\u003cbr/\u003eTokio + stdio\"]\n    Server[\"server.rs\u003cbr/\u003e#[tool_router] — 173 tools\"]\n    Tools[\"tools/*\u003cbr/\u003e23 category modules\"]\n    Engine[\"engine/*\u003cbr/\u003eexpression · units · BigDecimal\"]\n\n    Client -- JSON-RPC --\u003e Main --\u003e Server --\u003e Tools --\u003e Engine\n\n    style Main fill:#8b5cf6,color:#fff,stroke:#fff,stroke-width:2px\n    style Server fill:#6366f1,color:#fff\n    style Tools fill:#1e40af,color:#fff\n    style Engine fill:#1e40af,color:#fff\n```\n\n| Crate | Role |\n|:---|:---|\n| [`rmcp`](https://crates.io/crates/rmcp) | Official Rust MCP SDK (protocol + schema). |\n| [`tokio`](https://crates.io/crates/tokio) | Multi-threaded async runtime for stdio I/O. |\n| [`bigdecimal`](https://crates.io/crates/bigdecimal) + [`num-bigint`](https://crates.io/crates/num-bigint) | Arbitrary-precision arithmetic (DECIMAL128). |\n| [`astro-float`](https://crates.io/crates/astro-float) | 128-bit, correctly-rounded transcendentals. |\n| [`jiff`](https://crates.io/crates/jiff) | IANA timezones, embedded database. |\n| [`wide`](https://crates.io/crates/wide) | Portable SIMD dispatch. |\n| [`tracing`](https://crates.io/crates/tracing) | Structured logging to stderr (stdout stays clean). |\n\nDeep dive: [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md).\n\n---\n\n## Precision guarantees\n\n| Domain | Precision | Method |\n|:---|:---|:---|\n| Basic arithmetic | Exact | `BigDecimal` |\n| Division | 20 decimal places | HALF_UP per DECIMAL128 |\n| `sin` / `cos` / `tan` | Exact at 0/30/45/60/90° | Lookup + `astro-float` fallback |\n| `factorial` | Exact for `n ∈ [0, 20]` | `u64` table |\n| `evaluate` | ~15–17 digits | `f64` fast path |\n| `evaluateExact` | ~34 digits | 128-bit `astro-float` |\n| Unit conversion | 34 digits | DECIMAL128 factors |\n| Financial | 34 digits | DECIMAL128 context |\n| Date / Time | IANA standard | Embedded tz database |\n\n\u003e [!WARNING]\n\u003e The fast `evaluate` path uses `f64` for speed and is subject to standard IEEE-754 rounding. Use `evaluateExact` when you need 128-bit precision.\n\n---\n\n## Development\n\n```bash\ncargo fmt --check\ncargo clippy --all-targets --all-features -- -D warnings\ncargo test --lib                 # 690 unit tests\npython3 scripts/test_stdio.py    # 234 stdio integration tests\n```\n\nAll four must pass before committing. See [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md) for layout, conventions, and the contribution workflow.\n\n### Project layout\n\n```\narithma/\n├── Cargo.toml                   Dependencies, lint + release profiles\n├── rust-toolchain.toml          Rust 1.94+ pin\n├── src/\n│   ├── main.rs                  Binary entry, stdio MCP transport\n│   ├── lib.rs                   Library exports\n│   ├── server.rs                #[tool_router] — all 173 tools\n│   ├── engine/                  Expression parser, unit registry, BigDecimal helpers\n│   ├── mcp/                     MCP message helpers\n│   └── tools/                   23 category modules\n├── scripts/test_stdio.py        Full stdio integration test\n└── docs/                        INDEX · ARCHITECTURE · TOOLS · DEVELOPMENT · API\n```\n\n---\n\n## Documentation\n\n| Doc | Purpose |\n|:---|:---|\n| [`docs/INDEX.md`](./docs/INDEX.md) | Navigation starting point. |\n| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Module layout, data flow, design decisions. |\n| [`docs/TOOLS.md`](./docs/TOOLS.md) | Every tool: inputs, outputs, examples. |\n| [`docs/DEVELOPMENT.md`](./docs/DEVELOPMENT.md) | Build, test, lint, contribute. |\n| [`docs/API.md`](./docs/API.md) | MCP integration and calling conventions. |\n\n---\n\n## Contributing\n\nIssues and PRs welcome. Keep the workflow green:\n\n- [x] `cargo fmt` — formatted.\n- [x] `cargo clippy --all-targets -- -D warnings` — zero warnings.\n- [x] `cargo test --lib` — all unit tests pass.\n- [x] `python3 scripts/test_stdio.py` — all 234 stdio tests pass.\n- [x] en-US only in code, commits, and docs.\n\nUse the [Angular commit format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit): `\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e`.\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0](./LICENSE).\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built by** [@farchanjo](https://github.com/farchanjo) · [fabricio@archanjo.com](mailto:fabricio@archanjo.com)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarchanjo%2Farithma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffarchanjo%2Farithma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffarchanjo%2Farithma/lists"}