# Jacobian — Typed Math Tools for AI Agents > Give AI agents typed math tools through MCP. Inspect contracts, run exact operations, and compose results with a pinned Python release. ## Install Merge the JSON below into your `.mcp.json`: ## Quick Use Install Python 3.12 and uv first, then stage the included `.mcp.json` entry and merge it into your MCP client configuration after reviewing it. The package version is pinned. ```json { "mcpServers": { "jacobian": { "command": "uvx", "args": [ "--python", "3.12", "--from", "jacobian==0.22.0", "jacobian-mcp" ] } } } ``` ## Intro Jacobian gives AI agents a typed mathematical vocabulary through MCP, plus a Python API and CLI. Use it to inspect an operation's contract and compute exact results instead of asking the model to approximate them in text. Best for agents working with algebra, graphs, or bounded symbolic computation; works with MCP hosts such as Claude Code, Cursor, and Codex. The 0.22.0 release was checked on 2026-10-03: an isolated Python 3.12 installation returned gcd 6 and coefficients -1 and 3 for inputs 84 and 30. MCP initialization and tool discovery were also checked. This smoke test does not validate every mathematical operation; upstream's supported binary-install contract remains CPython 3.12/3.13 on glibc Linux x86-64, with some optional system backends. ## Original upstream README **English** · [简体中文](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/README.zh-CN.md)

Jacobian

An executable mathematical vocabulary for agents: discover one typed operation, run it, and compose its result.

CI PyPI npm Supported Python versions MIT license

Jacobian is an MCP server that gives AI agents a searchable vocabulary of typed mathematical operations. `math.find` matches a mathematical need or inspects one exact contract, and `math.run` executes it and returns its typed result. The same mathematical library is also available through a CLI and native Python API. Each operation establishes one stable, reusable mathematical postcondition rather than prescribing a workflow or proof strategy. Results are exact where claimed and make approximation, incompleteness, or uncertainty explicit. **Jacobian's hypothesis is that mathematical reasoning benefits from an executable vocabulary of semantically scoped, bounded operations.** Rather than exposing large domain solvers or precomposed workflows, Jacobian exposes mathematical primitives that agents can search for and compose into solutions beyond what any individual operation was designed to solve. The library supplies trustworthy mathematical moves; the reasoning model decides which moves to make, how to combine their results, and when to stop. Keeping the operations semantically narrow and domain-owned preserves that search space instead of baking one proof strategy or workflow into the tools themselves. See [Executable mathematical vocabulary](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/executable-mathematical-vocabulary.md) for what semantic atomicity means and how the operation vocabulary grows. ## Quickstart Set up Jacobian for your agents with a single command. The setup command requires Node.js 20.17+, 22.13+, or 23.5+ and `uvx` on your `PATH`. ```sh npx jacobian@latest setup ``` Choose detected agents and review the changes before they are written. Setup does not install Node.js, Python, `uv`, or an agent. For automation, preview an explicit plan with `npx jacobian@latest setup --codex --dry-run`; use `--yes` only with explicit agent flags or `--all`. To refresh an existing registration explicitly, run `npx jacobian@latest upgrade` and select the agents to update. The generated launcher pins the exact release resolved by npm. Run the canonical Python MCP command without installing Jacobian globally: ```sh uvx --python 3.12 --from jacobian jacobian-mcp ``` Where an MCP host requires an npm command, the npm package is a deterministic carrier for that same command: ```sh npx jacobian mcp ``` For a persistent installation: ```sh python -m pip install jacobian jacobian-mcp ``` That package includes Jacobian's exact maintained Python backend stack: SymPy, NetworkX, Z3, and Python-FLINT. 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. Singular and QEPCAD are optional system runtimes for a small subset of operations. The Python installation does not provision them, and ordinary operations do not require Docker. Python callers can use `jacobian.backends.check_backend`; MCP inspection reports availability in the server environment. See [backend requirements](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/backend-requirements.md) for exact coverage and setup. The Python distribution contains the mathematical kernel, CLI, and MCP server. The npm package deterministically maps its exact package version to the corresponding `uvx` invocation. ## Compute one bounded result An ordinary operation returns mathematics first. For example, `matrix.determinant.compute` accepts one exact rational matrix and returns its determinant directly. Callers compose results by passing their typed values to a subsequent operation. For a local terminal workflow, inspect the exact installed contract and run one of its examples with the CLI: ```sh jacobian inspect integer.compute.extended_gcd jacobian run integer.compute.extended_gcd --json '{"left":"84","right":"30"}' ``` The second command returns the gcd and Bézout coefficients as JSON. In an MCP host, use `math.find` in inspection mode to read the same contract and `math.run` with the same payload shape. See [Discover and invoke operations](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/invoke-domain-operations.md) for that agent workflow. ## Available mathematics The built-in portfolio covers work in: - polynomial maps and polynomial algebra; - exact linear algebra; - graphs, paths, colorings, and isomorphism; - bounded SAT and SMT solving; - finite algebra, probability, geometry, and topology. SAT and SMT operations use the maintained Z3 Python binding directly. Use `math.find` to match the mathematical result needed, then use its inspection mode on a promising operation before calling `math.run` once. See the [domain operation library](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/reference/domain-operation-library.md) for the maintained operation portfolio and [backend requirements](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/backend-requirements.md). ## Status Jacobian 0.22.0 is pre-stable. Its published package and operation contracts describe the supported surface; experimental operation contracts may change between releases. ## Documentation - [Documentation home](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/index.md): tutorials, how-to guides, reference, and explanations - [Architecture](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/architecture.md): runtime structure and trust boundaries - [Product model](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/product-blueprint.md): operation contracts, ownership, and project boundaries - [Tool reference](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/reference/tools.md): MCP resources and invocation contracts - [Backend requirements](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/backend-requirements.md): maintained Python backends - [Remote deployment](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/deploy-remote-mcp.md): HTTP deployment and authentication ## Contributing Jacobian uses Python 3.12, `uv`, and a small `Makefile`: ```sh make setup make affected AFFECTED_BASE=origin/main ``` Read [CONTRIBUTING.md](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/CONTRIBUTING.md) before changing code. It documents focused test commands, verification rules, documentation placement, and pull-request expectations. ## License [MIT](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/LICENSE) ## FAQ **Q: Does installing this asset automatically edit my global MCP configuration?** A: No. TokRepo stages the supplied files. Review and merge `.mcp.json` in the client you use. **Q: Which version and Python runtime does this entry use?** A: The supplied configuration pins Jacobian 0.22.0 and requests Python 3.12 through uvx. Upstream documents its tested platform contract and optional backends in the README. **Q: Has every operation been checked?** A: No. The local check covered server initialization, tool discovery, and one exact extended-GCD result. Check each operation's typed contract and backend availability before relying on it. ## Source & Thanks Created by [morluto](https://github.com/morluto). Licensed under [MIT](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/LICENSE). Source: [morluto/jacobian](https://github.com/morluto/jacobian), commit `0144d037894e6c33938fd66b841d336e15a79611`, package `0.22.0`. ```text MIT License Copyright (c) 2026 Jacobian contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` --- ## 快速使用 先安装 Python 3.12 和 uv，再检查随资产提供的 `.mcp.json`，将其中 `jacobian` 项合并到你使用的 MCP 客户端配置。这里固定使用 0.22.0，避免安装时版本悄悄变化。 ```json { "mcpServers": { "jacobian": { "command": "uvx", "args": [ "--python", "3.12", "--from", "jacobian==0.22.0", "jacobian-mcp" ] } } } ``` ## 简介 Jacobian 为 AI Agent 提供带类型约束的数学运算，支持 MCP、Python API 和 CLI。Agent 先查看运算契约，再调用具体运算并组合结果，适合代数、图论和符号计算任务。可用于支持 MCP 的 Claude Code、Cursor、Codex 等客户端。 2026-10-03 的隔离测试使用 Python 3.12 和 0.22.0：输入 84、30，扩展最大公约数运算返回 6，系数为 -1、3；MCP 初始化和工具发现也通过。这只证明这一组检查通过，不代表全部运算已验证。上游正式测试的平台范围仍为 glibc Linux x86-64 上的 CPython 3.12/3.13，部分运算需要额外后端。 ## 上游原始中文 README **[English](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/README.md)** · 简体中文

黑白档案照：黑板上雅可比行列式为常数，三个不同输入映到同一输出。

Jacobian

为智能体提供可执行的数学词汇：发现一个类型化操作，运行它，并组合其结果。

CI PyPI npm 支持的 Python 版本 MIT 许可证

Jacobian 是一个 MCP 服务器，为 AI 智能体提供一套可搜索、类型化的数学操作。`math.find` 用来匹配候选操作或读取一个操作的精确契约，`math.run` 执行该契约并返回类型化结果。同样的数学库也可以通过 CLI 和原生 Python API 直接使用。 每个操作只确立一个稳定、可复用的数学后置条件，而不是规定工作流或证明策略。声称精确的地方就会保持精确，近似、不完备或不确定性也会显式标出。 **Jacobian 的假设是：数学推理会受益于一套语义范围明确、有界且可执行的词汇。** 与其提供庞大的领域求解器或预先排好的工作流，Jacobian 只提供可搜索、可组合的数学原语——智能体可以把它们拼成超出单个操作设计目标的解法。库负责提供可信的数学步骤，模型决定怎么选、怎么组合、何时停。操作保持语义范围明确并由所属领域维护，避免把某种证明策略固化到工具里。 更多关于语义原子性的讨论，见[可执行的数学词汇](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/executable-mathematical-vocabulary.md)。 ## 快速开始 用一条命令为你的智能体配好 Jacobian，需要 Node.js 20.17+、22.13+ 或 23.5+，并确保 `uvx` 在 `PATH` 中： ```sh npx jacobian@latest setup ``` 它会检测已安装的智能体，让你在写入前确认改动。它不会帮你安装 Node.js、Python、`uv` 或智能体本身。需要自动化预览时，可用 `npx jacobian@latest setup --codex --dry-run` 查看计划；只有在明确指定 `--codex`、`--all` 等参数时才加 `--yes`。 不用全局安装，也可直接运行标准的 Python MCP 命令： ```sh uvx --python 3.12 --from jacobian jacobian-mcp ``` 若 MCP 客户端只能通过 npm 命令启动，npm 包会原样转发到同一条命令： ```sh npx jacobian mcp ``` 需要长期安装时： ```sh python -m pip install jacobian jacobian-mcp ``` 这个包自带了 Jacobian 维护的完整 Python 后端栈：SymPy、NetworkX、Z3 和 Python-FLINT。所以无论是常规的 Python 安装还是 npm 安装，你拿到的都是同一套基于 Python 的内置操作。官方测试过的环境是 glibc Linux x86-64 上的 CPython 3.12 / 3.13，发版时会在这两个版本上安装构建好的 wheel 并启动验证。其他系统也可能有可用的上游 wheel，但不在官方测试范围内。特别地，Alpine/musl 无法从 PyPI 装全必需的后端。 Python 发行包里包含了数学内核、CLI 和 MCP 服务器。npm 包本身不提供 JavaScript API，只是把当前 npm 包的精确版本映射到对应的 `uvx` 调用。 ## 计算一个有界结果 普通操作直接返回数学结果。例如，`matrix.determinant.compute` 接收一个精确的有理数矩阵，直接返回它的行列式。你可以把类型化的结果传给下一个操作，串起来完成更复杂的计算。 在本地终端中，先查看已安装操作的精确契约，再运行其中一个示例： ```sh jacobian inspect integer.compute.extended_gcd jacobian run integer.compute.extended_gcd --json '{"left":"84","right":"30"}' ``` 第二条命令会以 JSON 返回最大公约数和 Bézout 系数。在 MCP 主机中，用 用 `math.find` 的检查模式查看同一份契约，再用相同形状的 payload 调用 `math.run`。具体的 智能体调用流程见[发现和调用操作](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/invoke-domain-operations.md)。 ## 可用的数学能力 内置能力覆盖： - 多项式映射与多项式代数； - 精确线性代数； - 图、路径、着色与同构； - 有界 SAT 和 SMT 求解； - 有限代数、概率、几何与拓扑。 SAT 和 SMT 操作直接调用 Z3 的 Python 绑定。用 `math.find` 匹配所需的数学结果并查看候选操作的契约，最后用 `math.run` 执行一次。 请参阅[领域操作库](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/reference/domain-operation-library.md)了解操作契约与准入规则，用 `math.find` 查找实际操作，并参阅[后端要求](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/backend-requirements.md)。 ## 状态 Jacobian 0.22.0 仍为预稳定版本。已发布包和操作契约即为受支持的接口，实验性契约可能在后续版本中调整。 ## 文档 - [文档首页](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/index.md)：教程、操作指南、参考和原理说明 - [架构](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/architecture.md)：运行时结构与信任边界 - [产品模型](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/explanation/product-blueprint.md)：操作契约、归属和项目边界 - [工具参考](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/reference/tools.md)：MCP 资源与调用契约 - [后端要求](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/backend-requirements.md)：维护的 Python 后端 - [远程部署](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/docs/how-to/deploy-remote-mcp.md)：HTTP 部署与身份认证 ## 贡献 Jacobian 使用 Python 3.12、`uv` 和精简的 `Makefile`： ```sh make setup make handoff LANE=math TESTS=tests/math/graphs/test_graph_distance_matrix.py ``` 改代码前请先读 [CONTRIBUTING.md](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/CONTRIBUTING.md)，里面有聚焦的测试命令、校验规则、文档组织和 PR 要求。 ## 许可证 [MIT](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/LICENSE) ## 常见问题 **会自动修改全局 MCP 配置吗？** 不会。TokRepo 先暂存资产文件，由你或 Agent 检查后合并 `.mcp.json`。 **为什么固定版本？** 这次测试的是 0.22.0，配置同时指定 Python 3.12。升级前应再次查看上游运算契约和后端要求。 **全部数学能力都已经测试了吗？** 没有。本轮验证了服务器初始化、工具发现和一次扩展最大公约数计算；其他运算应根据其具体契约及后端可用性验证。 ## Source & Thanks Created by [morluto](https://github.com/morluto). Licensed under [MIT](https://github.com/morluto/jacobian/blob/0144d037894e6c33938fd66b841d336e15a79611/LICENSE). Source: [morluto/jacobian](https://github.com/morluto/jacobian), commit `0144d037894e6c33938fd66b841d336e15a79611`, package `0.22.0`. ```text MIT License Copyright (c) 2026 Jacobian contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` --- Source: https://tokrepo.com/en/workflows/jacobian-typed-math-tools-ai-agents-5489e797 Author: MCP Hub