codecalc — universal code & logic calculator for AI models

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.

Fastest path: uvx 'codecalc[full]' setup --write registers codecalc with your MCP client automatically. New to MCP, or want more detail first? See QUICKSTART.md, or the Install section below.

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 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.

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

Quickstart with codecalc setup

The fastest path to a working MCP connection, without reading the rest of this section:

uvx 'codecalc[full]' setup            # prints what it would do — nothing on disk changes
uvx 'codecalc[full]' setup --write    # applies it: merges your client's config, copies the skill

It detects which MCP client is installed (Claude Desktop, Claude Code, Cursor, VS Code, Zed — pass --client=NAME if none or several are found), reuses codecalc doctor's own backend/extras/grammar-cache checks, prints the exact config block in that client's own JSON shape with absolute paths already filled in, runs two real canaries (execute_code, evaluate_expression) to prove the connection would work, and ends in one verdict: ready / degraded / not-ready. --write is the only mode that changes anything — it MERGES the codecalc entry into your existing client config (every other server stays exactly as it was) and backs up the original to <path>.codecalc-bak first. codecalc --help lists every subcommand.

[!NOTE] Published as codecalc 0.6.0 on PyPI (pip install codecalc) and the codecalc-exec 0.6.0 executor on crates.io (#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.

The published install (simplest — no build step, and what most people want):

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

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

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.

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:

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.

Editions

Four names for the capability sets above, plus the two that live outside pyproject.toml entirely — a Docker image and an opt-in isolation boundary. The invariant that makes "edition" a meaningful word here: in the edition that lists a tool, that tool is functional — never listed-but-missing-its-extra. A tool an edition doesn't have returns the dependency_missing contract error naming the extra that provides it (see above), not a silent failure or a tool that appears to exist and doesn't work.

codecalc doctor reports which of these you're actually running (backend, extras present, strict_runtime prerequisites) — read it before assuming a capability rather than after a tool call surprises you.

.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:

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

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

{ "servers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"] } } }

Zed — ~/.config/zed/settings.json, key is context_servers:

{ "context_servers": { "codecalc": { "command": "uvx", "args": ["codecalc[full]"], "env": {} } } }

Windows paths need doubled backslashes in JSON. If you installed into a venv rather than using uvx, point at the interpreter directly:

{ "mcpServers": { "codecalc": {
    "command": "C:\\path\\to\\venv\\Scripts\\python.exe",
    "args": ["-m", "codecalc"] } } }

Run codecalc doctor to print a config block with the absolute paths of your install already filled in.

Install the skill too. The tools cannot help a model that never reaches for them — a model confident about 0.1 + 0.2 does not feel uncertain, it feels finished. codecalc/SKILL.md ships inside the package and says when calling is mandatory (any non-integer, any comparison you will state, anything past 2^53, any number stated as a claim), when it is noise (2 + 3 + 4 needs no tool), and how results must be reported — passed: true means "equivalent on N inputs", never "verified". codecalc doctor prints its path; copy it into your client's skills directory. check_claims.py gates it, so it cannot name a tool that does not exist or a field no tool returns.

Not sure what your install actually resolved? Ask it, rather than finding out from a tool call later:

codecalc doctor          # or: python -m codecalc doctor

This is the install verification step. It exits 0 when the install can execute — a writable workspace and a resolved backend — and 1 when it cannot, so it works unchanged in a Dockerfile, a provisioning script or a CI job. A missing optional extra or an uninstalled Haskell does not fail it: those are facts about the host, not a broken install, and a check that goes red for them is one people learn to ignore.

It prints the execution backend and the binary behind it, whether installs are confined, the status of every one of the 31 runtimes, whether the workspace is writable, and a client config block with absolute paths filled in. All of that is otherwise discoverable only by making a tool call and reading backend, unenforced, or a failure.

codecalc doctor --json   # the same report, for scripts
codecalc doctor --deep   # actually RUN each runtime, and read its version

--json emits the report and nothing else, against a published schema (docs/contract/doctor-v1.schema.json) carrying the same contract_version and the same policy as a tool result.

Each runtime reports one of four states, and the difference between two of them is which measurement was actually taken:

status_basis says which pass produced them. Without --deep nothing is ever reported available, because nothing was executed, and claiming otherwise for a binary that was merely found on PATH would be a stronger measurement than was taken.

Building the Rust core yourself, or running from a checkout? See "Build the Rust core" and "Run the server" below.

Use it from an MCP client

One-click install: both buttons register uvx codecalc[full] (the recommended Full edition) and require uv to be installed.

The shortest version of the config above — this registers codecalc as a stdio MCP server. The console entry point is codecalc, so uvx codecalc launches it directly:

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

Installed with pip install codecalc instead? Point at the resolved command with no args:

{
  "mcpServers": {
    "codecalc": { "command": "codecalc" }
  }
}

Network boundary

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:

These distinctions are stated precisely on purpose: a guarantee described more broadly than it is enforced is exactly the failure mode this project works to avoid, so "offline-core" is scoped to what the structural test can actually support rather than claimed as a blanket "no network calls".

A PEP 723 block alone, with no dependencies argument, can trigger the install above. execute_code/session_run read the block out of the source text itself — a caller who passes no dependencies argument at all still gets a confined uv/npm subprocess and real egress if the code they submit happens to carry a # /// script block, whenever the refusal rule above does not apply. This is logged distinctly (dependency_install_implicit in the audit trail, alongside install_denied) so an operator can tell "source text alone triggered this" from an explicit install_package/dependencies= call. To disable it: no_net=True on the call, or a deny-network/strict CODECALC_CAPABILITY_POLICY — either one refuses before any fetch, block or no block. execute_code_stream, run_submit, and compare_execution never read this block at all: none of them accept a dependencies argument, so a # /// script block in code passed to any of them is inert text, not a trigger.

Two ceilings govern a dependency-bearing run, not one. The run's own timeout bounds the sandboxed step; it says nothing about installing dependencies FIRST, outside the sandbox. A separate, fixed budget (codecalc.dependencies.DEFAULT_DEPENDENCY_INSTALL_BUDGET_SECONDS, 120s, aggregate across every dependency of one run) bounds that step instead — exceeding it refuses the run with a stamped timeout naming the budget, before the run's own timeout clock even starts. A sessionless run's dependency workdir is also held to a disk quota — reusing CODECALC_SESSION_DISK_QUOTA_MB (below), the same cap a session workspace already has — and a run that grows past it after a successful install is refused with a stamped resource_exhausted naming the measured size and the cap.

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. So the offline-core claim is scoped to steady state: this first-use grammar fetch is the one in-process exception, which is why it is called out here rather than glossed over.

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:

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:

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.

Architecture (language-per-strength)

Python orchestrates; Rust executes; sympy/z3 reason. Each layer does what it's best at. The Rust binary is preferred automatically; a pure-Python executor is the fallback if the binary is missing.

Older-computer support

• No modern instruction-set requirements — rustc targets a generic CPU by default and nothing overrides it. (executor/.cargo/config.toml explains why -C target-cpu=generic is deliberately NOT written there: it would be a no-op that reads like a guarantee.)
• Static musl builds run on any Linux regardless of glibc version: bin/codecalc-exec-x86_64-musl, bin/codecalc-exec-aarch64-musl (~430K each; the exact size moves with every toolchain bump, so it is not pinned here)
• Size-optimized profile (opt-level="z", LTO, panic=abort, stripped) — measured, not assumed: against an otherwise identical opt-level=3 build, z came out 1.02 ± 0.26 times faster on the executor's own path (i.e. no detectable difference) while being 16% smaller. The executor spends its time in syscalls, not arithmetic, so there was nothing for a higher optimisation level to speed up.
• Lazy sympy/z3 imports. Both are imported on first use, so a session that only executes code never pays for them. This claimed "~40ms, not ~600ms" for a long time while being wrong in both directions: the server took 1.9s to start, and sympy was not actually lazy — units.py imported it at module scope and server.py imports units, so every start paid 437ms for it. Deferring that took spawn-to-first-response from 1888ms to 1243ms (measured, median of 7). The remaining ~870ms is the mcp SDK's own import, which is not ours to remove.
• The fork-bomb measurement is taken once, and only when it is needed. Sizing RLIMIT_NPROC means reading /proc/<pid>/status for every process on the machine. That walk used to run during argument parsing and again for every step: a C compile-and-run opened 1767 status files on a 590-process box to answer one question three times, and --lang notalanguage paid the full cost to produce a one-line error. Measured lazily and cached, an error costs 1.1ms instead of 13.3ms and a compiled run 78ms instead of 104ms.
• list_languages probes runtime availability and reports which languages actually work on the machine (graceful degradation on minimal installs)

Build the Rust core

cd executor
cargo build --release                          # native
cargo zigbuild --release --target x86_64-unknown-linux-musl   # static x86_64 (uses zig)
cargo zigbuild --release --target aarch64-unknown-linux-musl  # static arm64
# Copy the executable AND its --no-net shim together. build.rs rebuilds the
# shim whenever blocknet.c changes, but the executor looks for it beside the
# BINARY, so installing only the binary leaves the previous shim in place — and
# a stale shim silently enforces the old policy while every "is it there?"
# check still passes. Copy both or neither.
mkdir -p ../bin                                # bin/ is gitignored, so a fresh clone has none
cp target/release/codecalc-exec target/release/blocknet.so ../bin/

Requires: Rust 1.97+, a C compiler for the --no-net shim (the build warns and carries on without one; on macOS, or a Linux kernel without seccomp support, --no-net then reports itself in unenforced rather than pretending — a Linux kernel with seccomp support enforces it in-kernel either way), and cargo-zigbuild for the static cross-builds (zig is used as the linker; no x86_64 GCC needed).

MCP tools (52) + MCP resources

Every session file is also exposed as an MCP resource: codecalc://session/<session_id>/files/<path> — images render inline for the model, text returns as text, other files download.

Exact arithmetic & programmer-mode: exact rationals, threshold checks, bit analysis, binary64 introspection.

Core tools

Grade vocabulary

verify_translation, verify_optimization and z3_check return grade + grade_basis (+ grade_rules_version) on top of their own result. The grade names how strong the evidence for a success actually is; it is derived from evidence those tools already emit, in codecalc/grades.py — the verifiers never assign their own grade.

z3_check's sat verdicts are graded ungraded, not solver_proven, even though sat is just as decisive a verdict as unsat. The ticket's motivating pattern is proving a property P by asserting not-P and checking unsat; a caller running that pattern who gets sat back has learned P is FALSE, and solver_proven on that result would let a reader who skims grade without result mistake a counterexample for a proof. sat's grade_basis says so explicitly: satisfiability was decided, but solver_proven is reserved for unsat so a counterexample can never wear a proof grade. Widening sat back into solver_proven later is additive; narrowing it after callers depend on the wider behaviour would not be, so this ships narrow now. Full reasoning: codecalc/grades.py's module docstring.

algebraic_equiv is deliberately NOT graded: it compares two expressions via sympy.simplify(a - b) == 0, a CAS transformation rather than a decision procedure with a checkable certificate, and it is one simplifier's opinion rather than two independent implementations agreeing. None of the three grades describes that evidence honestly.

Runtime self-update

Every language is mapped to its package manager, and codecalc can update its own runtimes:

runtimes_status is always safe. update_runtimes refuses to mutate unless apply=True is passed explicitly — and it only touches the package manager that owns each language (never the Rust sandbox, which has no update powers).

One of those managers is elevated: apt updates system packages, so its command starts with sudo. apply=True is an argument a connected model controls, so that branch takes a second key the model does not have — the host must set CODECALC_ALLOW_RUNTIME_APPLY=1. Without it the apt command is reported as skipped with ok: false and the variable named, while the unprivileged managers still run. sudo -n already fails closed where a password is required; this covers the passwordless-sudo rule common on developer machines and CI images, which is exactly where -n does not stop it.

Run the server

cd /path/to/codecalc && .venv/bin/python -m codecalc.server
# stdio transport — register with any MCP client

# The identical tool/resource registry over stateless Streamable HTTP:
.venv/bin/python -m codecalc.server serve-http --host 127.0.0.1 --port 8000

Streamable HTTP binds to loopback by default. Bearer-token auth (CODECALC_HTTP_TOKEN) is required for any non-loopback bind — serve-http refuses to start on a routable address if the token is unset, and the token comparison is constant-time — and optional on loopback, where an MCP client spawning the process is already inside the trust boundary. Setting a token does not change the single-operator threat model: put an authenticating reverse proxy and the stronger process/container isolation described in SECURITY.md in front of it before exposing it beyond one operator's own machine.

Point an MCP client at it:

{ "mcpServers": { "codecalc": { "command": "/path/to/codecalc/.venv/bin/python",
                                "args": ["-m", "codecalc.server"],
                                "env": {
                                  "PYTHONPATH": "/path/to/codecalc",
                                  "CODECALC_RUNTIME_PATH": "/path/to/mise/shims:/usr/local/bin:/usr/bin:/bin"
                                } } } }

MCP protocol

Protocol revision 2026-07-28, on the official mcp SDK 2.0. Not fastmcp: fastmcp 3.x pins mcp>=1.24,<2.0 and so cannot reach this revision at all.

Verifying that is less obvious than it looks. mcp.types.LATEST_PROTOCOL_VERSION reads 2026-07-28 regardless of what a given connection negotiated, and the same server answers on either protocol depending only on how you connect:

So tests/test_mcp_protocol.py asserts the negotiated value from a real connection. The legacy path still works — backward compatibility is a feature — it just must not be mistaken for the new protocol.

Worth noting for anyone reading the spec's headline change: 2026-07-28 removes protocol-level sessions, and directs servers needing cross-call state to use "explicit, server-minted handles passed as ordinary tool arguments". That is exactly what codecalc's session_id already is.

The result contract

Every result carries contract_version, currently 1.4.0. The published schema is docs/contract/result-v1.schema.json and the policy behind it — what MAJOR/MINOR/PATCH may change, the twelve-month deprecation window, worked success/failure/timeout examples, and the migration path from unversioned servers — is in docs/contract/README.md.

For in-process Python use, the supported protocol-neutral service boundary—and the session/storage internals that are deliberately not public—is documented in docs/embedding.md.

Two things a caller should know before reading anything else:

• ok means "ran and exited 0". A program that behaves exactly as intended and exits 3 comes back ok: false, exit_code: 3, verdict: "RTE". To tell a failed program from a failed request, read verdict — a request that never reached a runtime has no verdict at all, and has a code instead.
• code is the branch target, not error. Eight stable values; the prose in error is free to improve and is not a contract. An unrecognised code must be treated as internal — that is what lets a 1.x client survive a 2.0.0 server, though adding a code is still a MAJOR change, because the published enum is closed and a strict validator rejects the result first.
• Truncation reports a size, not just a flag. output_truncated says output was cut; stdout_bytes / stderr_bytes say by how much — the bytes the program actually produced, before the cap. A 200 000-character print under max_output_kb=1 returns 1 039 bytes of stdout and stdout_bytes: 200001, so a caller can size a retry instead of guessing. null there means not measured (nothing ran); a program that printed nothing reports 0.

The schema is JSON Schema 2020-12 — the dialect MCP 2026-07-28 defaults tool outputSchema to — so a client can validate our results with it directly. scripts/check_contract.py regenerates it from codecalc/contract.py and fails on a diff, and separately re-derives both backends' verdict vocabularies from main.rs and executor.py: check_parity.py compares the two backends' key sets and is structurally blind to a new verdict value, which would leave the published enum short and make a strictly validating client reject a good result.

Configuration

All optional. codecalc runs with none of these set.

The strict service runs on Linux x86_64 or ARM64 with Docker Engine, cgroup v2, and an explicitly registered gVisor runsc runtime. Its executor image must be pinned by @sha256: digest on the execution path. That image is published to GHCR (ghcr.io/the-40-thieves/codecalc-exec, multi-arch amd64+arm64) by the publish-executor-image workflow, which an operator dispatches (workflow_dispatch); the workflow commits the immutable digest into docker/executor-image.lock, and published_strict_image() resolves it as the production default. Until that first dispatch no digest is pinned and the execution path fails closed — it never falls back to the mutable local diagnostic tag (codecalc-exec:strict), which doctor and the conformance suite keep using. The default systrap platform works without KVM, so the same authenticated service can be used from Linux, macOS, and Windows; strict clients never fall back to native local execution.

Provisioning and running any of the three strict backends in production — the gVisor+Docker host, Windows AppContainer hardening, and the macOS/Windows remote-client configuration — is covered in docs/deployment/README.md, separate from the provider interface itself in docs/contract/provider-v1.md.

Both backends resolve CODECALC_RUNTIME_PATH identically, and scripts/check_parity.py fails CI if the Rust and Python copies of that contract ever drift — including if a machine-specific home directory finds its way back into the default.

Tool-definition token cost

codecalc's tools/list returns 52 definitions. Measured with o200k_base as a proxy, that is roughly 9,200 tokens of descriptions and input schemas, and every client pays it before the first user message.

codecalc does not hide its tools behind a discovery facade, and that is deliberate: the tool surface is where per-operation approval prompts, audit names and typed schemas live, and collapsing 52 tools into one dispatcher makes install_package and percentage look like the same permission to a client that approves by tool name. The cost is real, but the client is the better place to solve it, because the client can defer definitions without giving up the schemas or the per-tool boundary.

If you are paying too much for codecalc's definitions:

• Claude Code defers every MCP tool by default — tool search is on by default, with no token floor codecalc needs to clear. auto loads a server's tools upfront only while their definitions total under 10% of the context window and defers all of them once that 10% is reached; false loads everything upfront regardless of size (Claude Code MCP docs, https://code.claude.com/docs/en/mcp, retrieved 2026-09-07). calc_exact, execute_code, verify_translation, verify_optimization, and list_languages carry _meta["anthropic/alwaysLoad"] (per that same doc, "your 3-5 most frequently used tools") so they stay loaded even when a client defers everything else; install_package and update_runtimes carry _meta["anthropic/requiresUserInteraction"], which forces a permission prompt on every call regardless of the session's permission mode — both change the host and both fetch from a registry.
• Claude API, via the MCP connector, takes defer_loading once on the toolset's default_config, or per tool in configs. Deferred definitions stay out of the system-prompt prefix, prompt caching is preserved, and a matching tool is expanded into its full definition when the model searches for it.
• OpenAI's Responses API has the same knob under a different name: defer_loading: true on an MCP server tool definition (OpenAI Responses MCP tool guide, https://developers.openai.com/api/docs/guides/tools-connectors-mcp, retrieved 2026-09-07).
• VS Code caps a single chat request at 128 enabled tools and groups excess tools behind "virtual tools" above a configurable threshold (VS Code agent tools docs, dated 2026-09-02, https://code.visualstudio.com/docs/copilot/agents/agent-tools). Windsurf / Cascade caps at 100 total tools (Cascade MCP docs, https://docs.devin.ai/desktop/cascade/mcp, retrieved 2026-09-07).
• The MCP specification itself has no deferral mechanism — no tool search, grouping, tags, or toolsets; a server can only publish ttlMs/cacheScope hints and paginate tools/list (MCP spec 2026-07-28, https://modelcontextprotocol.io/specification/2026-07-28/server/tools, retrieved 2026-09-07). A client without one of the mechanisms above pays the full cost regardless of what codecalc does.
• Any client can filter which of the 52 tools it exposes to the model. Nothing here requires codecalc to change.

A server-side facade remains under consideration for clients with no such mechanism (docs/design/2026-08-10-tool-facade.md), and is not implemented.

Trimming a description to cut this cost is exactly the change scripts/tool_select_eval.py exists to gate: an offline, labeled eval of whether a deterministic lexical (BM25) selector still picks the right tool for a plain-language ask, scored against the live tools/list text. Measured v1 baseline (196 hand-labeled prompts, none containing their own target tool's name — see the script's own docstring): 60.71% top-1 / 75.51% top-3 accuracy on the full surface (62.75% / 63.0% top-1 on dev / core respectively). It is a lexical proxy, not a model — see the script's module docstring for exactly what a green run does and does not prove.

The checked-in baseline PINS the exact labeled corpus by content hash (prompt_set_sha256); a --baseline compare against a corpus that no longer hashes to it fails with a distinct "corpus changed" error rather than silently scoring a smaller, easier prompt set against the old numbers. And because a tool can be top-1-wrong against full's 51 distractors (zero headroom to lose) while still having real headroom against core's much smaller distractor set, both the regression compare and the ablation self-check (replacing real descriptions with a generic stub, one tool at a time, across every candidate tool — no sampling) run separately against all three of full/dev/core, wired into CI via tests/test_tool_select_eval.py so the gate is proven live, on every surface, on every run — not just at the PR that added it.

Reducing the tool surface

For an operator who would rather not configure every client, codecalc also has a first-party knob: CODECALC_TOOLS registers only a chosen slice of the 52-tool surface, so a client that never enables tool search still pays for a smaller tools/list.

On a client with no deferral mechanism of its own, the client's own allow-list does the same job from the other end — OpenAI's allowed_tools, Gemini CLI's includeTools/excludeTools, or Codex CLI's enabled_tools/disabled_tools all narrow what a given session sees without touching the server.

Every tool also now carries a ToolAnnotations hint (readOnlyHint, destructiveHint, idempotentHint, openWorldHint — see codecalc/server.py's GROUP_ANNOTATIONS/TOOL_ANNOTATION_OVERRIDES tables for the value on each of the 52). Codex CLI's writes approval mode (v0.144.0+) reads readOnlyHint directly: a tool marked readOnlyHint: true skips the approval prompt, everything else still asks. That covers the whole calculator group (25/25 pure) plus the read-only members of the mixed groups — list_languages/list_execution_providers/runtimes_status in execution, z3_check/algebraic_equiv in verification, session_list/session_files/session_read_file/session_artifacts/ run_inspect in sessions, and analyze_complexity in analysis — without codecalc doing anything client-specific; the annotation is the same hint every MCP client reads, writes just happens to be the mode that consumes it.

This is not the facade the section above declines to build. Every tool a group activates keeps its own name, its own typed input schema and its own per-tool approval prompt — a group that is not active simply never registers its tools with the MCP SDK at all, so they are absent from tools/list and rejected by tools/call, not merely hidden behind a dispatcher a client could still invoke by guessing the name.

Every tool belongs to exactly one group:

CODECALC_TOOLS takes a comma-separated list of group names, preset names, or both:

CODECALC_TOOLS=calculator            # just the calculator (25 tools)
CODECALC_TOOLS=core                  # same thing, by preset name
CODECALC_TOOLS=calculator,execution  # two groups, unioned
CODECALC_TOOLS=dev                   # a coding-assistant slice (39 tools)

Unset or empty registers every group — 52 tools, same as today — so nothing changes for an operator who does not set this. An unknown group or preset name is a loud startup failure naming the bad value and every known group/preset, never a silent fallback to "everything" or "nothing": either direction would turn a typo into a footgun nobody notices until it matters. codecalc doctor prints the active groups, the full group→tools mapping, and how many tools this process actually registered, whatever CODECALC_TOOLS is set to.

Client-side deferred loading (the section above) and this env var compose cleanly: point a client with no deferred-loading mechanism at a CODECALC_TOOLS-restricted process, or use both — a smaller declared surface still benefits from being deferred.

Test

Each file is a standalone script that prints one PASS/FAIL line per assertion and exits non-zero if any failed — no test runner, no plugins.

cd /path/to/codecalc

# everything. `|| break` used to be `|| break` alone, which stopped at the
# first failure AND left the loop exiting 0 — a red suite reported success to
# anything wrapping this command. This form runs them all and carries the
# failure out.
fail=0
for f in tests/test_*.py; do PYTHONPATH=. .venv/bin/python "$f" || { echo "FAILED: $f"; fail=1; }; done
for f in scripts/*.py;    do PYTHONPATH=. .venv/bin/python "$f" || { echo "FAILED: $f"; fail=1; }; done
[ "$fail" -eq 0 ]   # the exit status of the whole run

# or individually
PYTHONPATH=. .venv/bin/python tests/test_smoke.py           # every language, via the Rust executor
PYTHONPATH=. .venv/bin/python tests/test_mcp_all.py         # every tool over MCP stdio, answers checked
PYTHONPATH=. .venv/bin/python tests/test_executor_sweep.py  # sandbox regressions

62 test files and 16 CI-invoked scripts, 2184 assertions. "CI-invoked" means referenced by path (scripts/<name>.py) from a job in .github/workflows/*.yml — scripts/check_claims.py derives the count that way and gates it, so a script wired into a workflow without this sentence changing, or this sentence bumped without a workflow change, fails the build. Nothing in the suite needs the internet, so none of it is ever skipped for lack of a network.

It can skip for lack of a capability, and that is correct rather than a regression: a machine without a symlink privilege, without a given language runtime, or without a built native executor cannot exercise the cases that need them. The suite reports three distinct outcomes — the property holds, the property is broken, and this machine cannot exercise it — and every skip names its real cause. A nonzero skip count on Windows or in fallback mode is the healthy result; what would be wrong is a skip reading as a pass.

This paragraph previously claimed zero skips unconditionally. That became false the moment the suite learned to distinguish the third outcome, and nothing gated it: check_claims.py gates the counts below, not the prose around them. The counts are gated by scripts/check_claims.py: they were written by hand once and were stale within three pull requests, which is exactly the failure the rest of that script exists to prevent. Four of the files are regression suites named after the sweep that produced them — test_bug_sweep, test_executor_sweep, test_python_sweep, test_network_modules — and each one's docstring states the defect it locks out and how it was reproduced, because a regression test whose reason has been forgotten is the first one deleted.

Two rules the suite holds itself to, learned from breaking both:

• Assert the value, not the shape. Three of these files once had no assertions at all: they called tools, printed the output and exited 0. They caught a crash and never a wrong answer — a runtimes_status total replaced with -999 passed, printing total = -999.
• Don't pin what varies. benchmark and compare_execution rank by measured time, so their winner moves under load; their structure is asserted and their timing is not. runtimes_status is checked against itself — the summary must agree with the data it summarises — so it holds on any machine rather than describing this one.

Platform support

Linux, macOS and Windows. The three do not offer the same primitives, and the executor reports which ones it could not apply in an unenforced array on every result rather than letting a caller assume they all held.

The native table below describes the local provider and is not a hostile-code security boundary. On macOS, <host>-strict instead uses the explicitly