内容
# SageMath MCP 服务器
[](https://creativecommons.org/publicdomain/zero/1.0/)
[](https://www.npmjs.com/package/@justice8096/sagemath-mcp-server)
一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，暴露 [SageMath](https://www.sagemath.org/) — 一个包含 100 多个软件包的计算机代数系统 — 给像 Claude 这样的 LLM 客户端。与大多数“数学 MCP”包装单个库（SymPy、mathjs）不同，这个服务器通过子进程包装整个 SageMath 堆栈，以便模型可以访问真正的符号数学，而不是算术。
## 为什么
LLM 在精确算术方面表现不佳，在多步代数方面很脆弱，在符号操作方面不可靠。正确的方法是将概念推理保留在模型中，将机械计算委托给工具 — 这是患有计算障碍的人使用计算器所使用的相同技巧。SageMath 为这种委托提供了最广泛的工具表面：因式分解、积分、特征值、数论、LaTeX 渲染和绘图都位于一个接口后面。
## 工具
| 工具 | 描述 |
|---|---|
| `sage_evaluate` | 运行任意 SageMath 表达式。 |
| `sage_solve_equation` | 符号求解代数/超越方程。 |
| `sage_differentiate` | 计算导数（任意阶，任意变量）。 |
| `sage_integrate` | 不定积分和定积分。 |
| `sage_simplify` | 简化表达式（`default`、`full`、`trig`、`rational`）。 |
| `sage_factor` | 因式分解多项式或整数。 |
| `sage_matrix_ops` | 在 `QQ` / `RR` / `ZZ` / `CC` 上计算行列式、逆、特征值、秩、RREF、转置。 |
| `sage_plot` | 绘制表达式并返回 base64 PNG。 |
| `sage_latex_convert` | 将 SageMath 表达式转换为 LaTeX。 |
| `sage_number_theory` | `is_prime`、`next_prime`、`factor`、`euler_phi`、`gcd`、`lcm`、`prime_range`、`sigma`、`moebius`。 |
所有工具都遵循相同的模式模式（参见 [`src/schemas/common.ts`](src/schemas/common.ts))。
## 安装
服务器需要本地安装 SageMath 或 Docker，以便在主机上启动 SageMath 进程。
### 选项 1：npm + 本地 SageMath
```bash
npm install -g @justice8096/sagemath-mcp-server
# 需要 `sage` 在 PATH 上 — 参见 https://doc.sagemath.org/html/en/installation/
sagemath-mcp
```
### 选项 2：Docker（不需要本地 SageMath）
```bash
docker compose up
# 使用官方 sagemath/sagemath 镜像；服务器在容器内运行
```
### 选项 3：从源代码
```bash
git clone https://github.com/justice8096/sagemath-mcp-server.git
cd sagemath-mcp-server
npm install
npm run build
npm start
```
## 配置 MCP 客户端
### Claude Desktop / Claude Code（stdio 传输）
将以下内容添加到 `~/.claude.json`（或等效的 Claude Desktop 配置）：
```json
{
"mcpServers": {
"sagemath": {
"command": "sagemath-mcp"
}
}
}
```
### 远程 / HTTP 传输
```bash
TRANSPORT=http API_KEY=your-secret-key npm start
```
然后将 MCP HTTP 客户端指向 `http://<host>:3000/mcp`，并带有匹配的 `API_KEY` 头。
## 架构
- **TypeScript** 包装器，运行时为 Node.js ≥ 18。
- **子进程包装** — 包装器代码为 CC0；SageMath 仍为 GPL-3.0，并作为单独进程运行，这是根据 [GNU GPL FAQ on aggregation](https://www.gnu.org/licenses/gpl-faq.en.html) 的规范安全交互模型。嵌入式 FFI 将传播版权；子进程执行则不。
- **双重传输** — stdio（Claude Desktop、Claude Code、本地 MCP 客户端）和 Streamable HTTP（远程部署，可选 `API_KEY` 环境变量）。
- **国际化** — 英语、西班牙语、法语通过 [`src/i18n.ts`](src/i18n.ts) 和 [`locales/`](locales)。
- **多格式构建** — `build.ts` 从同一源代码清单中发出 Claude 插件、OpenAI 函数调用、n8n 节点、MCP 服务器描述符、CLI 工具和 YAML 提示库输出。
## 配置
| 环境变量 | 默认值 | 用途 |
|---|---|---|
| `TRANSPORT` | `stdio` | `stdio` 或 `http`。 |
| `PORT` | `3000` | 当 `TRANSPORT=http` 时的 HTTP 端口。 |
| `API_KEY` | （无） | 如果设置，HTTP 请求必须包含匹配的 `API_KEY` 头。 |
| `SAGE_TIMEOUT` | `30000` | 每个调用的 SageMath 超时毫秒数。 |
| `SAGE_DOCKER_IMAGE` | `sagemath/sagemath:latest` | 当本地未安装 SageMath 时使用的镜像。 |
## 安全
- 所有 SageMath 输入都经过消毒处理，以去除子进程执行前的 shell 元字符；参见 [`src/services/sage-executor.ts`](src/services/sage-executor.ts)。
- HTTP 传输需要 `API_KEY`（如果设置）— 没有默认凭证。
- 参见 [`SECURITY.md`](SECURITY.md) 和 [`THREAT_MODEL.md`](THREAT_MODEL.md) 以获取完整的安全态势。
- 预提交审计套件位于 [`audits/`](audits/)：SAST/DAST 扫描、供应链审计、CWE 映射、LLM 合规性报告、贡献分析。
## 许可证
此包装器在 [CC0-1.0](LICENSE)（公共领域）下发布。SageMath 本身仍为 GPL-3.0；子进程执行模型使许可证保持独立。参见 [`SECURITY.md`](SECURITY.md) 和项目的 [合规性分析](https://github.com/justice8096/sagemath-mcp-server/blob/main/audits/llm-compliance-report.md) 以获取法律推理。
## 状态
`v1.0.0` — 公共版本。包装器层稳定；SageMath 表面功能丰富且稳定。 在 https://github.com/justice8096/sagemath-mcp-server/issues 提交问题。
