Ajisai

Ajisai MCP server

Ajisai's MCP surface makes the language useful as a bounded, deterministic and diagnostic computation kernel for AI agents. The server remains a thin adapter: the Rust CLI owns language semantics and generated artifacts own vocabulary.

Ajisai promises exactness in its supported numeric domain, rather than unqualified “no rounding errors”. Operations such as explicit rounding and functions outside that domain retain their documented semantics.

This README is the server's own record of what it does and how it is verified; the readiness tracker and the hand-off memo that once accompanied it in docs/dev/ were retired when their exit criteria were met. Host-by-host resource ceilings are compared in docs/dev/mcp-host-profiles.md.

Install and connect

Requirements: Node 20 or newer. Nothing else — no build step, no cargo, no native binary: the package carries its WASM backend.

The server is published on npm as ajisai-mcp-server and listed in the official MCP Registry as io.github.masamoto1982/ajisai. Most MCP clients take a JSON server entry. Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json) and Cursor (.cursor/mcp.json) all use this shape:

{

"mcpServers": { "ajisai": { "command": "npx", "args": ["-y", "ajisai-mcp-server"] } } }

npx -y ajisai-mcp-server --doctor exits 0 when the installed copy can actually compute.

From a checkout

A clone runs the same server without npm, which is how the repository's own tests and an unreleased engine are reached. The WASM backend is committed under wasm/generated/, so a fresh clone computes immediately.

git clone https://github.com/masamoto1982/Ajisai.git

cd Ajisai/tools/mcp-server npm install node index.js --doctor # exits 0 when this copy can actually compute

The server entry then names the checkout's index.js:

{

"mcpServers": { "ajisai": { "command": "node", "args": ["/path/to/Ajisai/tools/mcp-server/index.js"] } } }

That is the whole configuration. No env block is needed, and pointing AJISAI_BIN at a native binary — as an earlier version of this file did in its only working example — is an optional override, not a prerequisite:

• AJISAI_BIN selects a native ajisai binary instead of the packaged WASM backend, which is how a Docker image that builds one in should be wired.
• AJISAI_REPO is a development-only fallback for discovering a locally built binary without naming it.

Without either, a native binary is discovered only when this package is run from an Ajisai checkout (tools/mcp-server beside rust/Cargo.toml), and then the more recently built of rust/target/release and rust/target/debug is used. An installed copy under node_modules never looks outside itself: it runs the packaged WASM backend.

The published package holds only what the server runs — the adapter, its two backends, the packaged assets and WASM module, README.md, CHANGELOG.md and LICENSE. The evaluation harness, its corpora and the tests stay in the repository (npm run test:pack fails if one ships).

Both backends answer identically (see Backends and provenance); the override is about deployment, not about results.

Checking an installation

The server is silent when it is healthy, which makes it indistinguishable from one that is wedged. The same executable answers for itself:

node index.js --version    # adapter, engine and specification versions, registry digest

node index.js --doctor # Node, assets, backend and two real computations node index.js --help

--doctor exits 0 when every check passes and 1 when any fails, so it can gate a container start or a support request. It computes 2 3 DIV 1 3 DIV ADD and 2 SQRT through the selected backend: a server that starts and loads its assets but answers wrongly is still broken, and only running something proves otherwise. With no arguments the process speaks MCP on stdin/stdout and writes nothing else there.

Agent surface

Execution tools accept source text only. Deliberately omitting file-path input prevents an AI tool call from becoming an arbitrary local-file reader.

check answers about the *form* of a program, never about running it: it tokenizes, parses, resolves names and verifies #:contract declarations (#:contract DOUBLE inputs=1 outputs=1 field=closed, one line per Word, in the keys CONTRACT answers in — inputs, outputs and field, and no other: any other term makes the directive malformed), all without execution. compute runs the same declaration check before executing anything, and a declaration the body contradicts, or a malformed one, stops the run: both tools answer it as an ordinary error — error.category: contractViolation and a message quoting the finding — with every finding in contractDecls.findings ({ severity, message }) and a verdict per Word in contractDecls.declarations, and compute names it outcome: error:contractViolation. A source without a directive carries no contractDecls. So a check that returns status: ok says the program is well-formed and its names resolve — it does not say the program will succeed, stay inside a ceiling, or produce a value rather than a NIL. Nothing that only a run can decide is decided here. Read it as "this will get as far as executing", and read compute for what executing it does.

The three source tools answer one program consistently, and tool-consistency.test.js (part of npm run selftest) holds them to it over every golden and corpus source:

• An error's outcome and its error.category name one category.
• Source that does not parse is malformedSource to all three — infer_contracts included.
• check ok means the run does not fail on the program's form or its names.
• Every suggested line infer_contracts answers, pasted back above the source, verifies under check.
• check is stricter than a run: it rejects a name nothing defines even inside a Word that is never called, which a run never reaches.

Three outcomes, kept distinct

outcome uses the ids of spec/outcomes.json, so a reasoned absence is told apart from a value without reading the top stack node.

All four tools answer with the same envelope (result.schema.json, also served as ajisai://schema/result), so one schema describes every result a caller can receive and there is no second contract to keep in step.

What a result costs

Every result arrives twice: as structuredContent, which a caller branches on, and serialized into a text content block, because MCP asks a tool with an output schema to also return the serialized JSON that way — a text-only client has no other route to any of it. That mirror stays. Replacing it with a prose summary is the one compaction that would actually lose information, and the self-test pins that a text-only client can still tell a value, a reason-carrying NIL, a language error and a host failure apart from the text alone.

What was removed is everything constant. 1 2 ADD answered 3,732 bytes, of which the answer — stack and stackDisplay — was 85: the rest was the twelve-entry limit table on every result (mcp.limits), and an execution receipt and observation digest no host verified. Five calls in one turn cost 5,000 tokens of that. Now:

• mcp.limitProfile names the profile (mcp-local-stdio); the ceilings are the ajisai://limits resource, read once. A ceiling that fires still names itself in error.resource and its value in message, and a host failure about one in error.limit, so no result needs the table to be acted on.
• resourceUsage — what the run spent against each ceiling — is sent; the engine reports no optimizer counters at all.
• The engine sends no receipt and no observation digest (envelope schema 5).
• An optional field carrying no value is absent, not null — message and error on a plain success, contractDecls on a source that declares nothing. Test for presence, not for `null`.

1 2 ADD is about 1 KB as sent, and what remains constant is its provenance. npm run eval:performance measures the whole response and the text block alone over the seven benchmark cases and fails against a committed medianResponseBytesBudget, so none of it can come back unnoticed. The budget is a ceiling to lower when a response genuinely shrinks, never one to raise so a regression passes.

A host failure is machine-readable: error.code is a stable identifier (invalidRequest, unknownTool, sourceTooLarge, backendUnavailable, capacityExhausted, timeout, responseTooLarge, malformedBackendResponse, backendFailure, registryUnavailable), error.retryable says whether trying again can help, and error.limit names the declared ceiling when the failure is about one. error.message is written for a model and carries no host paths, environment-variable names or spawn diagnostics; that detail goes to the server's stderr, where an operator is looking.

Saturating concurrentExecutions queues the caller for up to a second before answering capacityExhausted, so an ordinary burst becomes back-pressure rather than a retry loop the caller has to write.

Reading an algebraic value

2 SQRT answers with the value, a rendering of it, and an approximation. On the stack node, read:

The display renders exactly the terms beside it. Compute with exactTerms; the display is meant to be read rather than parsed.

The one that misleads is the node's own value: a rational approximation flagged semantics.approximate, so it looks exact and is not.

The display writes the canonical normal form, so equal values are written the same way: 8 SQRT and 2 SQRT 2 SQRT ADD both give 2/1*sqrt(2), and EQ decides they are the same number. Comparison decides equality here; string comparison does not — the string is display text, not a value. exactTerms does not appear on a rational or a vector of rationals, whose stackDisplay is already the whole value.

Errors

A language error is message — one line of text — and one object, error: { category, resource?, word?, line?, column? }. category is the spec/outcomes.json error category, the same id as in outcome, and is what to branch on; word is the Word the failure is attributed to, line and column where it was written, and resource, for resourceLimitExceeded, the entry of ajisai://limits that fired. An unknown Word is category: unknownWord with the name as written in word; word_contract answers that name with the closest known Words in suggestions.

responseBytes bounds the response as sent: the structured result, its serialized text mirror and provenance together. A *successful* result is kept under it by the engine rather than refused: under the agent profile a stack is sent whole up to 440 KiB (a 5,000-element vector of small integers), and past that