Jacobian

Pure mathematics for agents: search for examples and counterexamples, compute exactly, and independently check what a result proves.

Jacobian is an MCP server that gives AI agents two tools for high-level mathematics. math.find discovers typed mathematical operations and math.run executes one selected operation. The same mathematical library is also available through a CLI and native Python API.

Quickstart

For a one-time setup:

npx jacobian setup

For a guided user-local install:

curl -fsSL https://raw.githubusercontent.com/morluto/jacobian/main/npm/install.sh | sh

The installer resolves an npm release to an exact version, installs the small launcher without lifecycle scripts, configures selected MCP clients, and verifies the local server. The Python package environment is approximately 160 MB; if Python 3.12 is not already available, uv's managed Python adds about 110 MB. Add --defer-runtime to postpone both until first use:

curl -fsSL https://raw.githubusercontent.com/morluto/jacobian/main/npm/install.sh | \
  sh -s -- --client codex --yes --defer-runtime

For repeated use:

npm install -g jacobian
jacobian setup
jacobian upgrade
jacobian doctor

For the Python distribution:

python -m pip install jacobian

That package includes Jacobian's exact maintained Python backend stack: SymPy, NetworkX, Z3, Python-FLINT, and cvc5. A normal Python or npm installation therefore exposes the same built-in Python-backed operation portfolio. The tested binary-install contract is CPython 3.12 or 3.13 on glibc Linux x86-64; the release gate installs the built wheel and starts Jacobian on both Python versions. Other systems may have compatible upstream wheels, but are not part of the tested release contract yet. In particular, Alpine/musl cannot install the complete mandatory stack from PyPI.

The launcher supports Claude, Codex, Cursor, Gemini, and OpenCode. It requires Node.js 18 or newer plus CPython 3.12/3.13 or uv; the guided installer can install its pinned uv release after confirmation. Run jacobian mcp to start the server directly.

The Python distribution contains the mathematical kernel, CLI, and MCP server. The npm package is a sub-100 KB thin launcher and MCP client installer for that same implementation; it is not a separate JavaScript API. It bundles one TOML parser for fail-closed Codex configuration updates and runs no install-time scripts. The larger download is the local Python mathematical runtime, not a JavaScript dependency tree.

To run the exact code in a clone, follow Configure an agent from a source checkout.

Compute, then check when needed

An ordinary operation returns mathematics first. For example, matrix.determinant.compute accepts one exact rational matrix and returns its determinant inline. If independent replay matters, the agent may separately run matrix.determinant.verify with that exact input and candidate result.

The producer and checker are distinct catalog IDs with independent implementations. Computation does not certify itself, and a timeout, cancellation, error, or incomplete bounded search remains a non-conclusion.

The introductory tutorial runs this determinant pair through the public MCP surface.

Available mathematics

The built-in portfolio covers work in:

• polynomial maps and polynomial algebra;
• exact linear algebra;
• graphs, paths, colorings, and isomorphism;
• SAT and SMT models and proof artifacts;
• finite and universal algebra;
• polytopes; and
• Lean declaration discovery and proof checking.

Some operations require optional external executables or formal runtimes. An operation available in the active catalog is invocable; catalog membership does not grant verification authority. Read operation://catalog or use math.find to inspect the active catalog. Use math.run to invoke a selected operation.

See the domain operation library for the maintained operation portfolio and native and formal backend setup for optional executable requirements.

Verification model

Jacobian separates mathematical production from independent checking. A producer cannot certify its own output.

Subject + Candidate → Independent checker → Bound record

Only an operator-authorized checker may emit a verified record, bound to the exact subject, candidate, evidence, protocol, scope, semantics, certificate format, and checker identity. Availability and provider provenance do not grant that authority.

No witness is not proof. A failed search, timeout, cancellation, error, or completed bounded search without a witness leaves the claim UNKNOWN.

The architecture document describes the complete trust boundary.

Status

Jacobian 0.11.0 is a pre-stable release. Its published package, operation, and artifact contracts describe the current supported surface; ongoing operation research may change experimental contracts between releases.

Documentation

• Documentation home — tutorials, how-to guides, reference, and explanations
• First verified result — a complete runnable example
• Architecture — runtime structure and trust boundaries
• Product model — operation contracts, ownership, and project boundaries
• Tool reference — MCP resources and invocation contracts
• Native and formal providers — provider and Lean setup
• Remote deployment — HTTP deployment and authentication

Contributing

Jacobian uses Python 3.12, uv, and a small Makefile:

make setup
make test-unit
make check

Read CONTRIBUTING.md before changing code. It documents focused test commands, verification rules, documentation placement, and pull-request expectations.

License

MIT