Axiom — Advanced Math

Axiom — 高级数学 MCP 服务

为大模型提供精确的符号与数值数学计算——通过 Model Context Protocol 和 shell 命令接入真正的计算机代数系统（Giac/Xcas）。以 axiom-math 发布。

快速开始

立即作为 CLI 使用：

npx -y axiom-math compute 'integrate(sin(x)^3,x)'   # -cos(x)+cos(x)^3/3
npx -y axiom-math verify 'diff(x^3,x) = 3*x^2'      # exit 0 — it holds

在任意客户端的配置中作为 MCP 服务使用：

{ "command": "npx", "args": ["-y", "axiom-math"] }

作为 Agent 技能使用——添加 skills/axiom-math/SKILL.md，其中介绍了三个命令及其退出码。

为什么选择 Axiom？

大模型经常会算错，尤其是在符号数学、精确分数和多步骤问题上。Axiom 通过两个层次提供经过验证的精确结果：

• math.js — 快速数值计算（算术、三角函数、矩阵）
• Giac/Xcas WASM — 符号计算（微积分、代数、方程求解）

基准测试结果（GLM-5.1，2026 年 5 月）

数据集	基线	+MCP	差值
GSM8K (100)	96.0%	98.0%	+2.0%
MATH L3 (50)	70.0%	80.0%	+10.0%
MATH L4 (50)	50.0%	62.0%	+12.0%
MATH L5 (50)	38.0%	52.0%	+14.0%
CAS-quick (60)	55.0%	70.0%	+15.0%
Omni-MATH ≥7 (50)	0.0%	0–4%	（上限）

关键洞察：

• Phase 0 评分器（LaTeX/Unicode 规范化 + 符号等价性）是所有数据集中最主要的价值驱动因素
• CAS-quick 从 26.7%（4 月评分器上线前）提升至 70%（评分器上线后），这是单项最大增幅
• 当前 LLM+CAS 方案在 Omni-MATH ≥7 上已达到上限；需要从根本上采用不同的方法（Lean/Coq、微调、RAG）

完整结果见 benchmark/results/ 和 docs/superpowers/specs/（各阶段分析）

---

功能

Axiom 提供 3 个 MCP 工具。几乎所有操作都通过 compute 完成，它是一个统一入口，可解析 CAS 风格的问题字符串并将其路由到相应的内部引擎——调用方只需了解一个工具，而非几十个。

工具	用途
compute	求解任意数学问题。传入 CAS 风格的字符串（solve(...)、diff(...)、det([[...]])、C(10,3)、2+3*sin(pi/4)）或任意 Giac/Xcas 表达式。
verify	通过符号和/或数值方法，独立验证数学结论（恒等式、解或计算结果）。
plot	将二维函数图像渲染为 SVG 图片。

compute 涵盖的内容

compute 可识别 CAS 风格的动词，并在以下领域中进行分派。无法识别的内容会回退到原始 Giac/Xcas 求值。

领域	动词 / 示例
算术与单位	2+3*sin(pi/4)、100 km/h to m/s
方程求解	solve(x^2-4=0, x)、csolve(...)（复数）、solve_system([x+y=5, x-y=1], [x,y])
微积分	diff、int、limit、taylor、desolve（任意阶常微分方程，以及线性常系数系统）
多元微积分	gradient、hessian、jacobian、divergence、curl、partial、iint/iiint（多重积分）、critical_points、lagrange、tangent_plane、directional_derivative
代数	factor、simplify、expand、partfrac
线性代数	det、inv、eigenvals、eigenvects、rref、rank、tran、ker、qr、lu、cholesky、svd、norm、cond
数论	ifactor、isprime、euler、analyze
组合数学	C(n,k)、P(n,k)、stirling、bell、catalan、derangements、multinomial
概率	binomial、normal、poisson、geometric、hypergeometric、chi_square、student_t、f_distribution、beta、exponential
假设检验	t_test（单样本 / 双样本 / 配对）、anova、chi_square_test
数值方法	newton、bisection、secant、romberg、simpson
二维几何	distance、midpoint、slope、area_*、perimeter、circumference、line_intersection、point_line_distance、angle_between_lines
三维几何	distance3d、midpoint3d、dot、cross、vector_norm、angle_vectors、plane_from_points、point_plane_distance、line_plane_intersection、plane_plane_angle、line_line_distance、volume_tetrahedron、volume_sphere、volume_parallelepiped
变换与级数	laplace、ilaplace、fourier/fft/ifft、sum、product
精确值	to_exact、to_decimal、simplify_fraction
回归与数列	linear_regression/fit、polynomial_regression、sequence（模式识别）

---

安装

该软件包在 npm 上的名称为 axiom-math。 正常使用无需安装——npx 会获取并缓存它：

npx -y axiom-math compute '2+2'

或者安装它，让 axiom-math 命令可通过 PATH 使用：

npm install -g axiom-math

需要 Node.js >= 20。 首次运行时会下载约 3.8 MB 的内容（编译为 WebAssembly 的 CAS 引擎），并耗时几秒；之后的运行会使用 npx 缓存。

从源代码构建

适用于贡献者，或需要运行修改后的构建版本时：

git clone https://github.com/tufantunc/axiom-advanced-math-mcp.git
cd axiom-advanced-math-mcp
npm install
npm run build

Docker

# Build and run
docker-compose -f docker/docker-compose.yml up -d

# Check logs
docker-compose -f docker/docker-compose.yml logs -f

# Stop
docker-compose -f docker/docker-compose.yml down

---

用法

CLI（STDIO 传输）

# Run with stdio transport (default)
npm start

# Development mode
npm run dev

Claude Desktop 集成：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": [
    {
      "name": "axiom-math",
      "command": "npx",
      "args": ["-y", "axiom-math"]
    }
  ]
}

从本地检出版本运行，而非使用 npm 时——将 args 指向构建后的入口点：

"args": ["/path/to/axiom-advanced-math-mcp/dist/cli.js"]

命令行

同一个二进制文件也可作为一次性 CLI 使用，因此 Agent 无需 MCP 配置即可将其用作技能。不带参数时，它是 MCP 服务；带子命令时，它会执行一次计算并退出。

npx -y axiom-math compute 'integrate(sin(x)^3,x)'
npx -y axiom-math compute -q 'solve(x^2-4=0,x)'     # {-2, 2}
npx -y axiom-math verify 'sin(x)^2+cos(x)^2 = 1'    # exit 0 if true
npx -y axiom-math plot 'sin(x)' -o wave.svg
echo 'diff(x^3,x)' | npx -y axiom-math compute -q   # 3*x^2

标志	含义
-q	仅打印一个值，供脚本使用
--json	结构化输出
--latex	以 LaTeX 为重点的文本（仅限 compute）
-h、--help	用法说明，或子命令的用法说明

退出代码：0 成功 · 1 工具或用法错误 · 2 verify 检查了该命题，结果为假。

2 表示数学判定，因此未经过检查的命题不会使用该代码：无法解析、CAS 无法计算，或上标存在多种解读的命题，都会以代码 1 退出，且 stdout 为空。 因此，axiom-math verify '...' && ... 不会将语法错误误判为反证。

可直接使用的 Agent 技能位于 skills/axiom-math/SKILL.md。

HTTP 传输

# Start HTTP server (default: http://127.0.0.1:3000)
npm run start:http

# Development HTTP
npm run dev:http

HTTP 传输是无状态的：每个 POST /mcp 请求都会独立处理，不会签发 Mcp-Session-Id，请求之间也不会保留会话状态。 此服务不会发送服务端主动通知，因此不会丢失任何内容；并且它可以水平扩展，无需共享状态。

方法	路径	行为
POST	/mcp	处理一条 JSON-RPC 消息
GET	/mcp	405 — 不提供 SSE 流
DELETE	/mcp	405 — 没有需要终止的会话
GET	/health	就绪时返回 200，CAS 引擎未就绪时返回 503

安全性： 未提供身份验证和速率限制。默认绑定地址为 127.0.0.1，但 docker/docker-compose.yml 会设置 MCP_HOST=0.0.0.0。如果要暴露端口，请将其置于具备身份验证和速率限制功能的反向代理之后——docker/reverse-proxy/ 提供了一个可用且经过测试的方案（nginx + 基本身份验证 + 每客户端并发上限，应用本身不发布任何端口）。 SECURITY.md 详细说明了整体安全状况——哪些内容受到保护、哪些不受保护，以及如何报告漏洞。

POST /mcp 还会根据允许列表验证 Host 标头（默认包括 localhost、127.0.0.1、[::1]），以阻止 DNS 重绑定——恶意网页可以让受害者的浏览器将攻击者域名解析为 127.0.0.1，并借此访问此服务。如果你通过局域网地址、主机名或环回地址以外的反向代理域名访问服务，请设置 MCP_ALLOWED_HOSTS，否则每个 POST /mcp 请求都会收到 403。此检查不是身份验证——它只限制哪些主机名可以访问端点，与请求者身份无关。

环境变量：

变量	默认值	描述
MCP_PORT	3000	HTTP 服务端口
MCP_HOST	127.0.0.1	HTTP 服务主机
MCP_ALLOWED_HOSTS	仅限环回地址（localhost、127.0.0.1、[::1]）	POST /mcp 的 Host 标头允许列表，以逗号分隔（防 DNS 重绑定）。显式设置的值会替换默认值，而不是在默认值基础上扩展。
AXIOM_EVAL_TIMEOUT_MS	10000	每次求值的超时时间，单位为毫秒。限制一次 CAS 调用和一次 js-compute 调用（任意精度整数运算、算术运算、绘图采样），因此调低此值会同时收紧两者的限制。接受纯数字或带 ms/s 后缀的值（10000、250ms、10s），并限制在定时器可支持的范围内（1–2147483647ms）；不含数字或非正数的值会回退为 10000，并显示警告。未设置或为空时会静默使用默认值。
AXIOM_INTEGRATION_BUDGET_MS	max(3 × AXIOM_EVAL_TIMEOUT_MS, 30000)	单次多调用数值例程（积分、求根）的墙上时钟预算。限制 CAS 调用的总耗时，而 AXIOM_EVAL_TIMEOUT_MS 限制单次调用耗时。验证方式与 AXIOM_EVAL_TIMEOUT_MS 相同，被拒绝的值会输出到 stderr。
AXIOM_JS_COMPUTE_HEAP_MB	512	执行任意精度整数运算和 mathjs 求值的子进程的堆上限。超出此上限会导致触发问题的计算失败；排在其后的调用会重新发送给替代工作进程，且服务器仍会保持运行。接受整数 MB，可选后缀（512、512MB、2GB）。值会向下取整到整数 MB，并限制在 [16, 1048576] 范围内，且不会将上限放宽到高于所写的值：低于 16 时子进程无法启动；高于 1048576 时此服务器会将其封顶（V8 支持更大的值，但超过约 1.76e13 后，其 size_t 算术会溢出，导致实际堆比请求的更小）。只有不含数字的值才会回退为 512。每次修正都会输出到 stderr。基于 mathjs 的工具（quick_calc、plot）至少需要 48——实测其启动导入需要约 46MB，44MB 时会失败；低于此值时会按名称拒绝这些工具并说明原因，而不会将其作为工作进程故障处理。
AXIOM_COMPUTE_HYGIENE	未设置	设置为 1 以启用计算输出后处理

有一项限制不可配置：超过 100,000 个字符的结果会被拒绝，而不会返回；因此，像 1:2000000 这样的表达式会报告其元素数量，而不是将 2400 万个字符发送到调用方的上下文中。

某些输入会被拒绝而不是返回答案，因为任何答案都毫无意义。计算结果为 NaN（例如 0/0）时会报错；结果为无穷大时会返回并附带警告，因为计算完成后，真正的无穷大与超出双精度范围的值无法区分。t 检验要求其实际检验的数据存在变异——paired_t 比较的是差值，因此差值必须有变异；而 Welch 的 two_sample_t 只要求两个样本中有一个存在变异。列联表必须包含非负计数，不得有全零行或列，各行长度必须相同，且行数和列数都必须大于 1。单因素 ANOVA 要求组内存在一定变异，且观测数多于组数。此外，当数值过大，导致统计量本身溢出为无穷大时，上述检验都会被拒绝，因为溢出的统计量已不再是有效的统计量。当数值方法的表达式不依赖于求解或积分所针对的变量，或者 CAS 返回符号表达式而非数值时，该方法会被拒绝——此前会将符号表达式的首项作为结果报告。 以列表形式编写的微分方程组 — desolve([y'=z, z'=-y], x) — 会被改写为 CAS 求解的矩阵形式，并返回每个函数的解。各分量按方程的书写顺序返回，JSON 封装会在 components 字段中标明它们，因为没有该字段，[[cos(x),-sin(x)]] 无法解读。

初始条件必须为每个函数都提供，且取值点相同；也可以完全不提供 — 不完整的初始条件会被拒绝，而不是忽略。此外，以下情况也会被拒绝，且各自会给出原因：关于未知函数不是线性的方程组；系数依赖于自变量；阶数高于一阶的导数（将 y''=z 改写为 y'=w, w'=z）；方程超过九个；以及 CAS 无法完成求解的方程组。

无穷结果规则适用于算术求值。来自 CAS 的符号 +infinity（例如极限或发散积分）是正常答案，不会附带警告。

MCP Inspector

npm run inspect

---

工具参考

compute

所有数学计算的统一入口。传入 CAS 风格的问题字符串；路由器会解析它，并将其分发给相应的引擎。

参数	类型	描述
problem	string（必填）	CAS 风格的问题，例如 solve(x^2-4=0, x)、diff(x^3, x)、det([[1,2],[3,4]])、gradient(x^2+y^2, [x,y])。
domain	real | complex | numeric | exact	域提示（默认值为 real）。complex → 复数解；numeric → 强制使用数值方法；exact → 精确符号形式。
precision	integer 1–50	小数位数（默认值为 10）。
format	text | latex | json	输出格式（默认值为 text）。json 返回结构化封装。

示例：

{ "problem": "solve(x^2 - 5*x + 6 = 0, x)" }
{ "problem": "int(x^2*sin(x), x)", "format": "latex" }
{ "problem": "lagrange(x*y, x+y, 1, [x, y])" }
{ "problem": "volume_tetrahedron([0,0,0],[1,0,0],[0,1,0],[0,0,1])" }
{ "problem": "binomial cdf n=10 k=3 p=0.5", "format": "json" }

verify

独立检查数学结论。可作为对模型给出的结果进行核验的工具支持型第二意见。

参数	类型	描述
claim	string（必填）	要检查的结论，例如 "sin(x)^2 + cos(x)^2 = 1"（恒等式）、"x=2 satisfies x^2-4=0"（解）、"diff(x^3, x) = 3*x^2"（计算结果）。
method	numeric | symbolic | both	验证方法（默认值为 both）。

返回四个字段：verified、evaluated、confidence 和 checks_performed。

应首先查看 evaluated。当没有任何检查得出可用答案时，它的值为 false — 例如结论无法解析、CAS 无法求值，或结论含有多种解读方式的上标 — 此时 verified: false 表示“未知”，而非“已证伪”。将两者视为相同，会把语法错误误当成反证。

plot

将一个二维函数绘制为 SVG 图像。

参数	类型	描述
expression	字符串（必填）	要绘制的函数，例如 "sin(x)"、"x^2 - 3*x + 1"。
variable	字符串	变量名称（默认为 x）。
x_min, x_max	数字	X 范围（默认为 −10 … 10）。
y_min, y_max	数字	Y 范围（若未指定，则自动检测）。
width, height	数字	图像尺寸（单位为 px，默认为 600 × 400）。
title	字符串	可选的图表标题。

返回一张经过 base64 编码的 SVG 图像（包含坐标轴、网格、标签和渐近线检测）以及一段文字说明。

提示词

该服务还注册了引导式 MCP 提示词，可将 compute/verify 串联起来，构建多步工作流：solve-step-by-step、analyze-function、verify-identity、convert-units、analyze-dataset、solve-ode-system 和 regression-workflow。

---

运行基准测试

默认生产方案（自动包含 grader-v2）：

cd benchmark
npm install

# Set provider API key (one of):
export ZAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export OPENROUTER_API_KEY=...

# Run benchmarks (provider defaults from --zai/--anthropic/--openrouter flags)
npm run cas:quick:zai      # CAS-quick (60 problems, ~30 min)
npm run gsm8k:quick:zai    # GSM8K-quick (100 problems, ~30 min)
npm run math:quick:zai     # MATH L3-L5 quick (150 problems, ~75 min)

可选消融功能（默认关闭）

• --features=output-hygiene — 工具输出后处理（Unicode 规范化、可选简化、静默失败警告）。实时测量中，CAS 的表现仅提高 +1 个百分点。
• --features=grader-v3 — 方程右侧提取 + 逗号分隔列表集合匹配。CAS 的表现仅提高 +1 个百分点。
• --features=self-consistency — N=3 多数投票（降低方差；成本为 3 倍；CAS 准确率没有提升）。

示例：

npm run cas:quick:zai -- --features=output-hygiene,grader-v3

有关每个标志的实时消融分析，请参见 docs/superpowers/specs/2026-05-*-results.md。

尝试过但无效的方法

本项目经历了五个阶段（Phase 0–4）的广泛消融测试。以下实验方法经过实时测试后被弃用：

• Phase 1：结构化 JSON 输出并附加 \boxed{} — 模型将框选内容改写为 LaTeX 样式，导致答案提取失败。CAS 表现整体下降。
• Phase 2：8K token 预算（tokens-8k） — 给了模型更多空间跑题，而不是帮助其从截断中恢复。CAS 表现整体下降 −6.7 个百分点。
• Phase 3：通过自一致性提高准确率 — N=3 投票未能提升准确率（Wang 等人的研究成果无法在 CAS 上复现）；仅保留为降低方差的方法工具。
• Phase 4：奥赛专用脚手架提示词 — 参与度有所提升（未调用工具的比例从 84% 降至 74%），但准确率仍为 0%。奥赛级问题不在提示词工程干预的适用范围内。

每个阶段的逐题分析均见 docs/superpowers/specs/2026-05-*-results.md。失败情况的如实记录作为项目档案予以保留。

---

架构

Compute 网关 → 路由器 → 领域处理程序

┌─────────────────────────────────────────────────────────────┐
│              MCP Protocol Layer (stdio / HTTP)               │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
   ┌─────────┐          ┌──────────┐          ┌─────────┐
   │ compute │          │  verify  │          │  plot   │
   └────┬────┘          └──────────┘          └─────────┘
        │  route() → extract args → dispatch
        ▼
┌─────────────────────────────────────────────────────────────┐
│  Domain handlers: calculus, algebra, matrix, multivariable,  │
│  geometry / geometry3d, combinatorics, probability,          │
│  hypothesis testing, number theory, numerical methods, …     │
└─────────────────────────────────────────────────────────────┘
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   math.js    │     │  Giac/Xcas   │     │ Exact engine │
│ (numerical)  │     │  (symbolic)  │     │ (fractions)  │
└──────────────┘     └──────────────┘     └──────────────┘

compute 不会要求调用方选择处理程序。路由器根据问题字符串与有序规则进行匹配，匹配的提取器负责解析参数，分发器则调用相应的领域处理程序。未匹配的输入会回退到原始 Giac/Xcas。

响应格式

文本格式的响应按行组织，以便大模型（以及基准测试评分器）可靠地提取答案：

{
  "content": [
    { "type": "text", "text": "Result: 400/11" },
    { "type": "text", "text": "Decimal: 36.3636363636" },
    { "type": "text", "text": "LaTeX: \\frac{400}{11}" },
    { "type": "text", "text": "" },
    { "type": "text", "text": "The answer is 400/11 (≈ 36.36)" }
  ],
  "isError": false
}

---

基准测试结果

数据集

数据集	问题数	难度
GSM8K	100	小学数学（算术）
MATH L3	50	高中数学
MATH L4	50	高级高中数学
MATH L5	50	奥赛级数学
Omni-MATH ≥7	50	专家级数学

如何运行

命令请参见上文的 运行基准测试。简而言之，在 仓库根目录运行：

npm run benchmark:zai         # quick sample, GLM-5.1
npm run benchmark:full:zai    # all datasets
npm run benchmark:l5:zai      # one difficulty tier

将 :zai 替换为 :openrouter 即可更改提供商。benchmark/ 目录是 一个独立的 npm 项目，包含更细粒度的脚本（cas:quick:zai、 gsm8k:quick:zai，……）；在根目录运行 npm run benchmark:* 会转交给这些脚本执行。

环境变量：

变量	必需条件	描述
ZAI_API_KEY	zai 提供商	你的 z.ai API 密钥
OPENROUTER_API_KEY	openrouter 提供商	你的 OpenRouter API 密钥

---

开发

脚本

命令	描述
npm run build	编译 TypeScript 到 dist/ 并复制 WASM 资源
npm start	运行 STDIO 服务
npm run dev	以开发模式运行（tsx）
npm run start:http	运行 HTTP 服务
npm run dev:http	以开发模式运行 HTTP 服务
npm test	单元测试——无需构建
npm run test:integration	集成测试——先构建，再测试 dist/
npm run test:watch	以监听模式运行单元测试
npm run test:coverage	运行单元测试并生成覆盖率报告
npm run typecheck	执行类型检查，不生成输出
npm run lint	使用 oxlint 执行代码检查
npm run lint:fix	自动修复代码检查问题
npm run format	使用 Prettier 格式化
npm run format:check	检查格式，不写入更改
npm run inspect	打开 MCP Inspector 并连接 STDIO 服务

测试

测试套件分为两部分。npm test 运行单元测试，无需构建； npm run test:integration 会先构建，再测试打包后的 dist/ 输出，因此可以发现单元测试套件无法捕获的问题——已发布二进制文件的 参数分发、MCP 握手和退出代码。

npm test                  # unit
npm run test:integration  # integration (runs npm run build first)
npm run test:watch        # unit, watch mode
npm run test:coverage     # unit, with coverage

测试覆盖率： 单元测试 + 集成测试套件，100% 通过率。运行 npm test 查看当前测试数量——数量变化太频繁，无法在此保持同步。

WASM 构建（Giac）

npm run build:giac:wasm

# Build a specific upstream ref instead of master
GIAC_REF=v1.9.x npm run build:giac:wasm

此命令会运行 scripts/build-giac-wasm.sh，使用 docker build 构建 docker/build-giac-wasm/Dockerfile（不涉及 Compose 文件），并将 giac.wasm.js 直接写入 src/server/giac/——无需手动复制。需要本地运行 Docker Desktop（或其他 Docker 守护进程）。每个任务的构建日志会写入 logs/giac-build/。

---

贡献

欢迎提交 Bug 报告和拉取请求——有关环境设置、CI 执行的检查，以及本代码库中一些不易从代码中直接看出的事项，请参阅 CONTRIBUTING.md。

---

许可证

GNU 通用公共许可证 v3.0 或更高版本——请参阅 LICENSE。

Axiom 嵌入了 Giac/Xcas，其许可证为 GPL-3.0-or-later，因此组合后的作品采用相同许可证。详情和 署名信息：THIRD-PARTY-NOTICES.md。

GPL 会影响我的 Agent 吗？

不会。 您的 Agent 通过模型上下文协议与 Axiom 通信——这是一个独立进程，通过 stdio 或 HTTP 通信。彼此独立的程序通过接口进行通信，不构成组合著作，因此将 Axiom 与您自己的 Agent 一起运行，不会对您的代码施加任何许可义务，无论您的代码采用何种许可。GPL 不限制您运行该软件，包括将其作为服务运行。

Copyleft 条款仅在您重新分发 Axiom 本身时适用——将其（无论是否修改）随您交付给他人的产品一并提供。在这种情况下，请按照 GPL-3.0 提供源代码，并保留原有声明。