codecalc

# codecalc — universal code & logic calculator for AI models

<!-- mcp-name: io.github.The-40-Thieves/codecalc -->

**codecalc is an offline, self-hosted MCP server that gives an AI agent a
calculator, a code runner, and a logic checker — so it gets a *correct* answer
instead of a guessed one.** It runs code in **31 languages**, does exact
symbolic math, solves SMT/logic problems, and measures complexity, all exposed
as **52 MCP tools**.

Three things nobody else offers together cleanly:

- **Offline-core** — ships no model, no API key, no gateway, no telemetry.
  The core opens no sockets; network access is opt-in and only where a
  specific tool's job needs it (the Piston provider, `install_package`, the
  runtime-update tools, executed code unless `no_net`, and a one-time
  in-process grammar download on first `analyze_complexity` — full breakdown
  in the network-boundary table below).
- **Safe execution of untrusted code** — an opt-in *strict* isolation
  boundary (gVisor+Docker on Linux, AppContainer on Windows) layered above
  the default rlimit sandbox, fail-closed and attested.
- **Verification tools** — `verify_translation` proves a port to another
  language behaves identically, `verify_optimization` proves an optimization
  preserved behavior, and `z3_check` proves or refutes logic with an SMT
  solver.

## When to use codecalc

Use it when you want a free, local, private, hardened code-runner and
verifier that an MCP agent can call directly — no vendor account, no cloud
spend, nothing leaving the machine except where a tool's job explicitly
requires it.

Reach for something else when you want managed cloud scale instead of
self-hosting (a hosted sandbox like E2B or Modal), or when you're not
self-hosting at all and the model vendor's built-in code interpreter already
covers what you need.

**CodeCalc's core opens no sockets.** No model gateway or telemetry is built
in. `tests/test_offline.py` asserts this for the top-level core modules. The
opt-in Piston provider is the deliberate exception: its wire client lives under
`codecalc/provider_adapters/` and is registered only when
`CODECALC_PISTON_URL` is configured.

That is a claim about the **package**, not about every tool call, and the
difference is worth stating rather than leaving a reader to discover:

| layer | reaches the network? |
|---|---|
| CodeCalc core | **No HTTP client, model gateway, or telemetry.** One dependency exception: `analyze_complexity` may download a grammar on first use (see below) |
| configured Piston provider | **Yes, explicitly.** Calls only the operator-supplied `CODECALC_PISTON_URL`; credentials stay in its authorization header and are redacted from results |
| `install_package` | **Yes, by design.** It runs uv / npm / gem / cargo, which fetch from their registries. Installer hooks also run *outside* the sandbox — see [SECURITY.md](SECURITY.md) |
| `runtimes_status`, `update_runtimes` | **Yes.** They shell out to mise / rustup / swiftly / npm, which check remote versions |
| code you execute | **Yes, unless `no_net=True`** — and that shim needs the native executor, so the pure-Python fallback reports it in `unenforced` instead of applying it. Set `CODECALC_REQUIRE_NATIVE=1` to turn "fallback in use" into a startup failure instead of a result you have to notice by reading `unenforced` |

The earlier wording here was an unqualified "it makes no network calls", which
the structural test cannot support and three of the tools above contradict. A
guarantee stated more broadly than it is enforced is the failure this repo keeps
correcting, so it is corrected here too.

**The grammar download, stated plainly, because it is the one that is easy to
miss.** The other three paths above go through a CHILD PROCESS, which is what
`tests/test_offline.py` says it cannot see. This one does not:
`tree-sitter-language-pack` ships a ~5 MB extension and fetches each grammar on
first use, **in-process**, into a local cache — 28 grammars, 89 MB, about 15
seconds on a cold cache. So the first `analyze_complexity` call for a given
language opens a socket from inside the server.

It is verified (the pack checks a signature and raises on a checksum mismatch),
it is cached, and it never happens again for that language. But "the package
itself never reaches the network" was not true, and this row used to say it was.

**For an offline or egress-restricted install**, warm the cache first — it is one
command, and afterwards nothing here reaches the network. If you installed
codecalc (`pip install`/`uvx`, not a source checkout), `scripts/` did not come
with it, so use the shipped console script instead:

```bash
codecalc-prefetch-grammars                    # installed: fetch all 28 grammars
codecalc-prefetch-grammars --print-cache-dir  # installed: the directory to copy
```

Building from source? The script still works and calls the same code:

```bash
python scripts/prefetch_grammars.py                    # fetch all 28 grammars
python scripts/prefetch_grammars.py --print-cache-dir  # the directory to copy
```

`codecalc doctor` reports whether that cache is populated, so this is
discoverable before it matters rather than after a tool call degrades.

## codecalc vs. the alternatives

codecalc is not a general cloud sandbox and not a vendor code interpreter. It
overlaps with several things and beats them in only one narrow place — forcing a
model to *measure* a claim instead of asserting it. Where that isn't what you
need, one of these is the better tool, and this table says so plainly.

| You want… | Better fit | Why |
|---|---|---|
| To just run some Python/JS quickly, zero setup | Your model vendor's built-in interpreter | Already there, already sandboxed, nothing to install |
| Heavy or multi-tenant workloads, managed scale | A cloud sandbox (E2B, Modal, Daytona) | Per-tenant Firecracker/gVisor isolation codecalc does not claim by default |
| Pure arithmetic or symbolic math, nothing else | A small calculator or SymPy MCP | Lower token cost; none of the 31-language runtime machinery |
| **A model to stop _guessing_ numbers, equivalence, and speedups — locally, privately, with graded evidence** | **codecalc** | Exact rationals, `verify_translation`/`verify_optimization`, and `unenforced`/grade honesty — offline, no account |

**Do not reach for codecalc if** you need multi-tenant or network-exposed
isolation (its threat model is explicitly single-operator, local, stdio), if
zero-setup convenience matters more than measurement, or if a hosted interpreter
already covers your case. It earns its keep only when the *correctness of the
claim* — not just "it ran" — is the point.

## Install

> [!NOTE]
> Published as **`codecalc` 0.3.2** on PyPI (`pip install codecalc`) and the
> **`codecalc-exec` 0.3.2** executor on crates.io
> ([#91](https://github.com/The-40-Thieves/codecalc/issues/91)). Every release
> artifact carries a keyless sigstore **build-provenance attestation** — verify
> one with `gh attestation verify <file> --repo The-40-Thieves/codecalc`; PyPI
> wheels additionally carry PEP 740 attestations.

**From source**, if you would rather build the executor yourself:

```bash
git clone https://github.com/The-40-Thieves/codecalc
cd codecalc
uv sync --all-extras                 # or: pip install -e '.[full]'
cargo build --release --manifest-path executor/Cargo.toml
mkdir -p bin                         # bin/ is gitignored, so a fresh clone has none
cp executor/target/release/codecalc-exec bin/
uv run codecalc doctor               # verify: backend should read `rust`
```

Without the `cargo build`, everything still runs on the pure-Python fallback —
`doctor` will say so, and the network table below says what that costs.

**After the first release**, this becomes the install:

```bash
uvx 'codecalc[full]'          # run it directly, no environment to manage
# or
pip install 'codecalc[full]'  # into your own virtualenv
```

**Why `[full]`.** The base install is the MCP surface and the sandbox executor:
31 language runtimes, sessions, packages, ~32 MB. The symbolic half — sympy and
z3 — is 88.6 MB measured, and a caller who only runs code should not download an
SMT solver to do it. So it is an extra:

| install | size | what you get |
|---|---|---|
| `codecalc` | ~32 MB | execute_code, sessions, packages, complexity-free tools |
| `codecalc[symbolic]` | +83 MB | evaluate_expression, solve, limits, truth tables, z3, units |
| `codecalc[parsing]` | +5 MB installed, **+89 MB fetched on first use** | analyze_complexity via tree-sitter |
| `codecalc[full]` | ~120 MB | everything |

Nothing fails silently: a tool whose extra is missing returns
`{"ok": false, "error": "sympy is not installed. It ships in the 'symbolic'
extra: pip install 'codecalc[symbolic]' ..."}`, and `codecalc doctor` lists
which extras are present before you make a call.

`.github/workflows/release.yml` publishes a platform-tagged wheel per target
(Linux x86_64/aarch64 musl, macOS x86_64/aarch64, Windows x86_64), each
carrying the matching `codecalc-exec` binary and — where the platform has
one — its `--no-net` shim, so `executor.backend() == "rust"` on install
without a manual build step. No wheel for your platform, or installed from
source instead? Everything still runs; see the network table above for what
falls back and to `unenforced` in that case.

Point an MCP client at the installed command. **The key differs by client** —
`mcpServers` for most, `servers` for VS Code, `context_servers` for Zed — so
these are given separately rather than as one snippet to adapt:

**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS), `%APPDATA%\Claude\claude_desktop_config.json` (Windows) · **Cursor**
(`.cursor/mcp.json`) and **Claude Code** (`.mcp.json`) use the same shape:

```json
{ "mcpServers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"] } } }
```

**VS Code** — `.vscode/mcp.json`, top-level key is `servers`:

```json
{ "servers": { "co