Sagemath MCP

SageMath MCP服务器

          

通用数学 模型上下文协议 （MCP）服务器，允许LLM客户端完全访问 SageMath 的 ---最全面的开源数学系统之一。建于 FastMCP 3.x，服务器为每个MCP会话维护一个专用的SageMath进程，以便变量、函数和假设在工具调用中保持不变。

无论任务是符号微积分、数论、线性代数、微分方程、绘图、组合数学、图论、群论还是基本算术，服务器都会提供 33个MCP工具 ---由完整SageMath引擎支持的所有数学工具，以及 evaluate_sage_streaming （流媒体包装器）和HTTP /health 终点。

______________________________________________________________________

目录

• 功能概览
• 架构概述
• 快速开始
• 详细工具参考

- evaluate_sage——开放式执行 - 微积分工具 - 代数和简化工具 - 线性代数工具 - 微分方程 - 数论 - 统计 - 可视化 - 会话管理和可观察性

• 安全沙盒
• LLM客户端配置
• 部署
• 配置参考
• CLI 参考
• 发展
• CLI集成测试
• 项目布局
• 技术栈
• 更新日志
• 路线图
• 贡献

______________________________________________________________________

功能概览

______________________________________________________________________

架构概述

┌──────────────────────────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Gemini CLI, Codex CLI, etc.)       │
└──────────────────────┬───────────────────────────────────────────┘
                       │  MCP protocol (stdio or HTTP)
                       ▼
┌──────────────────────────────────────────────────────────────────┐
│  server.py --- FastMCP 3.x Application                          │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │ 18 MCP Tools│  │ 3 Resources  │  │ Middleware              │  │
│  │ (evaluate,  │  │ (session,    │  │ - Request logging       │  │
│  │  solve,     │  │  monitoring, │  │ - Response caching      │  │
│  │  diff, ...)│  │  docs)       │  │ - Progress heartbeats   │  │
│  └──────┬──────┘  └──────────────┘  └────────────────────────┘  │
│         │                                                        │
│  ┌──────▼──────────────────────────────────────────────────────┐ │
│  │ session.py --- SageSessionManager                           │ │
│  │  Per-client session map with asyncio locks, idle culling    │ │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │ │
│  │  │ Session A   │  │ Session B   │  │ Session C   │  ...   │ │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │ │
│  └─────────┼───────────────┼───────────────┼──────────────────┘ │
└────────────┼───────────────┼───────────────┼────────────────────┘
             │               │               │
             ▼               ▼               ▼
     ┌───────────────────────────────────────────────┐
     │  _sage_worker.py --- Subprocess Workers       │
     │  JSON stdin/stdout protocol                    │
     │                                                │
     │  ┌────────────┐   ┌──────────────────────┐    │
     │  │ security.py│──▶│ AST validation       │    │
     │  │            │   │ before every exec()   │    │
     │  └────────────┘   └──────────────────────┘    │
     │                                                │
     │  Persistent namespace: vars, functions,        │
     │  classes survive across calls                   │
     └────────────────────────────────────────────────┘

请求流程： MCP客户端→ server.py tool → SageSessionManager.get_or_create() → SageSession.evaluate() → JSON请求 _sage_worker.py 子进程→ AST验证→ exec() 在持久命名空间中→ 返回JSON响应。

关键设计决策：

• 过程隔离： 每个会话都在单独的子进程中运行SageMath。一个会话中的崩溃或超时不会影响其他会话。
• 有意义的会议： 变量、函数和假设在同一MCP会话内的工具调用中持续存在，从而实现了多步骤的数学工作流程。
• 默认安全设置： 每个代码片段在执行前都会经过一个基于AST的验证器，无论使用何种工具，都会阻止危险的操作。
• 进展心跳： 长时间运行的计算会发出周期性的进度事件（约1.5秒），因此客户端可以显示活动指示器并检测停滞。

______________________________________________________________________

快速开始

从PyPI安装

pip install sagemath-mcp

# Run the server over stdio (default)
sagemath-mcp

# Or expose an HTTP endpoint
sagemath-mcp --transport streamable-http --host 127.0.0.1 --port 8314

如果命令不在您的 PATH，跑 python -m sagemath_mcp.server --help.

从源头开发

git clone https://github.com/XBP-Europe/sagemath-mcp.git
cd sagemath-mcp

# Install dependencies (use uv or pip)
uv pip install -e .[dev]

# Run the server over stdio (default)
uv run sagemath-mcp

# Run with streaming-friendly HTTP transport
uv run sagemath-mcp --transport streamable-http --host 127.0.0.1 --port 8314

可选：自动启动Sage容器

如果您想在不本地安装的情况下获得即用型Sage运行时，请运行：

make sage-container  # or ./scripts/setup_sage_container.sh

在Windows PowerShell上：

pwsh -File scripts/setup_sage_container.ps1

Docker镜像

使用内置的MCP服务器构建一个可运行的容器：

docker build -t sagemath-mcp:latest .
docker run -p 8314:8314 sagemath-mcp:latest --transport streamable-http

发布的图像发布到 ghcr.io/xbp-europe/sagemath-mcp 并与Cosign签署。 使用以下工具验证下载的工件：

cosign verify ghcr.io/xbp-europe/sagemath-mcp:latest \
  --certificate-identity "https://github.com/XBP-Europe/sagemath-mcp/.github/workflows/release.yml@refs/tags/vX.Y.Z" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

Docker Compose

docker compose up --build

组合服务公开端口 8314 在主机和容器上，并在以下位置装载存储库 /workspace.容器以非根目录运行 sage 用户（UID/GID 1000）匹配基础图像。通过编辑环境块来调整运行时设置（例如，增加 SAGEMATH_MCP_EVAL_TIMEOUT 或调整 SAGEMATH_MCP_MAX_STDOUT)发射前。

______________________________________________________________________

详细工具参考

evaluate_sage ---开放式SageMath执行

主要工具。在持久工作进程内执行任意SageMath代码。在一次调用中定义的变量、函数、类和假设将在同一MCP会话中的后续调用中继续存在。

退货 一 EvaluateResult 对象：

行为细节：

• 代码运行时，服务器发出 进展心跳 大约每1.5秒一次，这样客户端就可以显示活动指示器。
• 如果评估超过超时，则重新启动工作进程，并 TimeoutError 提高。之前通话的所有会话状态都将丢失。
• 如果启动代码(from sage.all import * 默认情况下）在worker启动时失败，后续每次 evaluate_sage 调用返回clear StartupError 而不是令人困惑的NameError。
• AST安全验证器在执行之前对每个代码段运行（请参见 安全沙盒).

特定领域示例 （这些包含在工具描述LLM中，请参阅）：

有状态的多步骤工作流程：

> evaluate_sage(code="var('a'); f = (a + 1)^5")
  result_type: "statement", result: null

> evaluate_sage(code="expand(f)")
  result_type: "expression", result: "a^5 + 5*a^4 + 10*a^3 + 10*a^2 + 5*a + 1"

> evaluate_sage(code="diff(f, a, 2)")
  result_type: "expression", result: "20*(a + 1)^3"

______________________________________________________________________

微积分工具

differentiate_expression

计算表达式的符号导数。致电Sage diff(expr, var, order) 内部。

退货： {"derivative": "...", "order": N}

> differentiate_expression(expression="x^5", variable="x", order=3)
  {"derivative": "60*x^2", "order": 3}

> differentiate_expression(expression="sin(x)*cos(x)")
  {"derivative": "cos(x)^2 - sin(x)^2", "order": 1}

integrate_expression

计算不定积分或定积分。致电Sage integrate() 功能。

两者 lower_bound 和 upper_bound 对于定积分，必须同时提供，或者对于不定积分，两者都省略。只提供一个会引发错误。

退货： {"integral": "...", "definite": true/false}

> integrate_expression(expression="x^2")
  {"integral": "1/3*x^3", "definite": false}

> integrate_expression(expression="x^2", lower_bound="0", upper_bound="1")
  {"integral": "1/3", "definite": true}

> integrate_expression(expression="e^(-x^2)", lower_bound="-oo", upper_bound="oo")
  {"integral": "sqrt(pi)", "definite": true}

limit_expression

当变量接近一个点时，计算表达式的极限。致电Sage limit() 功能。

退货： {"limit": "..."}

> limit_expression(expression="sin(x)/x", point="0")
  {"limit": "1"}

> limit_expression(expression="1/x", point="0", direction="plus")
  {"limit": "+Infinity"}

> limit_expression(expression="(1 + 1/n)^n", variable="n", point="oo")
  {"limit": "e"}

series_expansion

围绕一个点计算泰勒级数或劳伦特级数展开。致电Sage .series() 方法。

退货： {"series": "...", "point": "...", "order": N}

> series_expansion(expression="e^x", order=5)
  {"series": "1 + x + 1/2*x^2 + 1/6*x^3 + 1/24*x^4 + O(x^5)", "point": "0", "order": 5}

> series_expansion(expression="1/(1-x)", point="0", order=4)
  {"series": "1 + x + x^2 + x^3 + O(x^4)", "point": "0", "order": 4}

______________________________________________________________________

代数和简化工具

solve_equation

求解一个方程或一组联立方程。致电Sage solve() 功能。方程式通过拆分来解析 =：字符串 "x^2 - 1 = 0" 成为Sage方程式 x^2 - 1 == 0.

退货： {"solutions": [...]}

> solve_equation(equation="x^2 - 5*x + 6 = 0")
  {"solutions": ["x == 2", "x == 3"]}

> solve_equation(equation=["x + y = 10", "x - y = 2"], variable=["x", "y"])
  {"solutions": [[x == 6, y == 4]]}

> solve_equation(equation="sin(x) = 1/2", variable="x")
  {"solutions": ["x == 1/6*pi"]}

simplify_expression

申请Sage simplify() 函数将符号表达式简化为更简单的形式。

退货： {"simplified": "..."}

> simplify_expression(expression="(x^2 - 1)/(x - 1)")
  {"simplified": "x + 1"}

> simplify_expression(expression="sin(x)^2 + cos(x)^2")
  {"simplified": "1"}

expand_expression

使用Sage扩展产品、幂和三角/对数恒等式 expand().

退货： {"expanded": "..."}

> expand_expression(expression="(x + 1)^3")
  {"expanded": "x^3 + 3*x^2 + 3*x + 1"}

> expand_expression(expression="(a + b)*(a - b)")
  {"expanded": "a^2 - b^2"}

factor_expression

使用Sage对符号表达式或整数进行因子分析 factor().

退货： {"factored": "..."}

> factor_expression(expression="x^3 - 1")
  {"factored": "(x - 1)*(x^2 + x + 1)"}

> factor_expression(expression="60")
  {"factored": "2^2 * 3 * 5"}

calculate_expression

计算符号表达式并返回其字符串表示形式和数值（如果可能）。使用Sage的 sage_eval() 内部带有预先声明的变量 x, y, z, t.

退货： {"string": "...", "numeric": float} ---the numeric 当表达式无法转换为浮点数时，字段会被省略。

> calculate_expression(expression="factorial(10)")
  {"string": "3628800", "numeric": 3628800.0}

> calculate_expression(expression="sqrt(2)")
  {"string": "sqrt(2)", "numeric": 1.4142135623730951}

> calculate_expression(expression="pi")
  {"string": "pi", "numeric": 3.141592653589793}

______________________________________________________________________

线性代数工具

matrix_multiply

在符号环上乘以两个矩阵(SR).输入矩阵是嵌套的数字列表。

退货： {"product": [[...], ...]} ---条目为浮点数时为实数，否则为字符串。

> matrix_multiply(matrix_a=[[1, 2], [3, 4]], matrix_b=[[5, 6], [7, 8]])
  {"product": [[19.0, 22.0], [43.0, 50.0]]}

matrix_operation

执行单个矩阵运算。支持对符号环上的矩阵进行六次操作。

退货： {"operation": "...", "result": ...} ---结果类型因操作而异：

> matrix_operation(matrix=[[1, 2], [3, 4]], operation="determinant")
  {"operation": "determinant", "result": -2.0}

> matrix_operation(matrix=[[2, 1], [1, 2]], operation="eigenvalues")
  {"operation": "eigenvalues", "result": [3.0, 1.0]}

> matrix_operation(matrix=[[1, 2, 3], [0, 1, 4], [5, 6, 0]], operation="inverse")
  {"operation": "inverse", "result": [[-24.0, 18.0, 5.0], [20.0, -15.0, -4.0], [-5.0, 4.0, 1.0]]}

> matrix_operation(matrix=[[1, 2], [3, 6]], operation="rank")
  {"operation": "rank", "result": 1}

______________________________________________________________________

微分方程

solve_ode

使用Sage求解常微分方程 desolve()。使用Sage的公式将方程式指定为字符串 diff() 符号。求解器返回具有任意常数的通解(_C, _K1, _K2等等）。

退货： {"solution": "..."}

> solve_ode(equation="diff(y(x),x) + y(x) = 0")
  {"solution": "_C*e^(-x)"}

> solve_ode(equation="diff(y(x),x,x) - y(x) = 0")
  {"solution": "_K1*e^(-x) + _K2*e^x"}

> solve_ode(equation="diff(y(x),x) = x*y(x)")
  {"solution": "_C*e^(1/2*x^2)"}

> solve_ode(equation="diff(y(t),t) + 2*y(t) = sin(t)", function="y", variable="t")
  {"solution": "..."}

______________________________________________________________________

数论

number_theory_operation

使用Sage的内置函数执行常见的数论运算。

退货： {"operation": "...", "result": ...} ---结果类型各不相同：

> number_theory_operation(operation="is_prime", a=997)
  {"operation": "is_prime", "result": true}

> number_theory_operation(operation="factor_integer", a=2520)
  {"operation": "factor_integer", "result": "2^3 * 3^2 * 5 * 7"}

> number_theory_operation(operation="next_prime", a=100)
  {"operation": "next_prime", "result": 101}

> number_theory_operation(operation="gcd", a=48, b=180)
  {"operation": "gcd", "result": 12}

> number_theory_operation(operation="lcm", a=12, b=18)
  {"operation": "lcm", "result": 36}

______________________________________________________________________

统计

statistics_summary

使用Sage计算数值数据集的描述性统计 mean() 和 sqrt() 功能。

退货： 一本包含以下内容的词典：

> statistics_summary(data=[2, 4, 4, 4, 5, 5, 7, 9])
  {"mean": 5.0, "median": 4.5, "population_variance": 4.0, "sample_variance": 4.571..., ...}

______________________________________________________________________

可视化

plot_expression

渲染表达式的2D图，并将其作为base64编码的PNG图像返回。致电Sage plot() 函数，并将结果序列化到内存中的PNG缓冲区。

退货： {"image_base64": "...", "format": "png"}

返回的base64字符串可以直接在任何支持内联图像的客户端中呈现（例如，通过 ` 标签或Markdown `).

> plot_expression(expression="sin(x)*e^(-x/5)", range_min=-5, range_max=20)
  {"image_base64": "iVBORw0KGgo...", "format": "png"}

> plot_expression(expression="x^3 - 3*x", range_min=-3, range_max=3)
  {"image_base64": "...", "format": "png"}

______________________________________________________________________

会话管理和可观察性

reset_sage_session

清除当前会话中的所有变量、函数和定义。底层工作进程继续运行（快速）。相当于重新启动一个新的Sage shell。

退货： {"message": "Session cleared"}

cancel_sage_session

通过终止工作进程并启动新进程来中止任何正在进行的计算。当计算卡住或耗时过长时使用此选项。所有会话状态都丢失。

退货： {"message": "Session cancelled and restarted"}

MCP资源

______________________________________________________________________

安全沙盒

所有代码---是否来自 evaluate_sage 或者由辅助工具内部生成——在执行之前通过基于AST的安全验证器。

被阻止的内容：

允许的内容：

强制限制：

错误处理： 当代码违反安全策略时，服务器会返回一条明确的错误消息来标识违规行为（例如，“对禁用函数'eval'的调用被阻止”），并记录一条警告。会话仍然有效——后续调用可以成功。

______________________________________________________________________

LLM客户端配置

通过MCP连接的客户端会自动收到以下指导：

• 有意义的会议 ---每一次对话都有一位专注的Sage员工。定义一次符号

（例如。， var('x'), f = ...)并在后续的工具调用中重用它们。

• 使用正确的工具 ---寻找专业助手(solve_equation, differentiate_expression等等）用于结构化JSON输出。退回到 evaluate_sage 对于其他任何事情。
• 链计算 ---在一次调用中分配结果，并在下次调用中引用它们。会话中的所有状态都保持不变。
• 超时 ---长时间计算会发出心跳进度事件。通过以下方式调整每次通话超时 timeout 参数。
• 安全 ---AST验证器阻止任意导入， eval/exec，以及文件系统/进程调用。更喜欢Sage图元；如果发生违规，请使用支持的API重写工作流。

客户端特定设置

克劳德桌面 ---添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "sagemath": {
      "command": "uv",
      "args": ["run", "sagemath-mcp"]
    }
  }
}

克劳德代码 ---添加到 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "sagemath": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "sagemath-mcp"]
    }
  }
}

Codex CLI：

codex mcp add sagemath --command uv --args "run" "sagemath-mcp"

Gemini CLI：

gemini mcp add sagemath --transport stdio --command uv --arg run --arg sagemath-mcp

对于HTTP传输，首先公开端点(sagemath-mcp --transport streamable-http --host 0.0.0.0 --port 8314)并将客户指向 http://HOST:8314/mcp.

______________________________________________________________________

部署

stdio（默认）

uv run sagemath-mcp

最适合本地LLM客户端（Claude Desktop、Claude Code、Codex CLI）。客户端将服务器作为子进程生成，并通过stdin/stdout进行通信。

HTTP/可流式传输HTTP

uv run sagemath-mcp --transport streamable-http --host 127.0.0.1 --port 8314

最适合远程客户端、基于浏览器的工具或共享环境。支持流式响应和取消。

Docker Compose

docker compose up --build

暴露 http://127.0.0.1:8314/mcp.以非root身份运行 sage 用户（UID/GID 1000）。compose文件将存储库装载到 /workspace 并接受所有环境变量的覆盖 SAGEMATH_MCP_* 设置。

Kubernetes（Helm）

helm install sagemath charts/sagemath-mcp \
  --set image.repository=ghcr.io/xbp-europe/sagemath-mcp \
  --set image.tag=latest

关键值： service.port, env （环境覆盖图）， args （CLI参数）， ingress.*。该图表强制非根执行(runAsUser/runAsGroup 1000).审查 values.yaml 用于全套可配置旋钮。发布工作流通过以下方式验证图表 helm lint 和 helm template 在出版之前。

______________________________________________________________________

配置参考

所有配置都是通过环境变量完成的。不需要配置文件。

运行时设置

安全设置

______________________________________________________________________

CLI 参考

usage: sagemath-mcp [--transport {stdio,http,streamable-http,sse}]
                    [--host HOST] [--port PORT] [--path PATH]
                    [--log-level LOG_LEVEL]

# Default: stdio transport for Claude Desktop / Codex CLI
sagemath-mcp

# HTTP transport for browser-based or remote clients
sagemath-mcp --transport streamable-http --host 0.0.0.0 --port 8314

# Debug logging
sagemath-mcp --log-level DEBUG

# With uv
uv run sagemath-mcp --transport streamable-http --host 127.0.0.1 --port 8314

______________________________________________________________________

发展

先决条件

• Python 3.12+ 紫外线 安装
• Docker（可选，用于集成测试和Sage容器）
• SageMath（可选，用于没有Docker的本地开发）

命令

uv pip install -e .[dev]       # Install with dev extras
make lint                       # ruff check (ruff 0.15+)
make test                       # pytest (pure Python, no Sage needed)
make integration-test           # pytest inside Sage Docker container
make build                      # sdist + wheel via scripts/build_release.py
make cli-integration            # Run CLI integration tests (Claude + Gemini)
make sage-container             # Bootstrap the Sage Docker container

运行测试

如果没有本地SageMath安装，您仍然可以运行所有242个单元测试——该测试套件用轻量级Python解释器替换Sage worker来验证会话管道。代码覆盖率为 99% 跨所有核心模块。

# Run all unit tests
uv run pytest

# Run a single test
uv run pytest tests/test_server.py -k "test_solve_equation"

# Run with coverage
uv run pytest --cov=sagemath_mcp --cov-report=term-missing

代码检查

Ruff，行长100，目标Python 3.12。规则：E、F、W、B、UP、ASYNC、RUF、I（进口分拣）。跑 make lint 在承诺之前。

Git挂钩

克隆后配置Git挂钩：

git config core.hooksPath .githooks

预推钩自动旋转。

______________________________________________________________________

CLI集成测试

该项目包括一个全面的端到端测试套件，通过真实的LLM CLI调用验证MCP服务器。位于 tests/cli_integration/.

概述

• 43个测试用例 跨越9个数学领域
• 测试两者 克劳德代码 (claude --print)以及 双子星命令行工具 (gemini -p)
• 执行过程中的实时进度报告
• 多层验证：子字符串匹配、数字提取、非确定性输出的软失败
• JSON结果导出用于历史跟踪

跑步

# Run against both CLIs
make cli-integration

# Or use the standalone runner with options
python -m tests.cli_integration.run_cli_tests --cli claude --domain calculus
python -m tests.cli_integration.run_cli_tests --cli both --parallel
python -m tests.cli_integration.run_cli_tests --cli gemini --domain algebra,number_theory

域名覆盖范围

______________________________________________________________________

项目布局

sagemath-mcp/
├── pyproject.toml                  # Project metadata, dependencies, tool config
├── README.md                       # This file
├── USAGE.md                        # Detailed usage guide
├── CLAUDE.md                       # Claude Code project instructions
├── Dockerfile                      # Production container (SageMath + MCP server)
├── docker-compose.yml              # Local development stack
├── Makefile                        # Common commands (test, lint, build, etc.)
├── src/sagemath_mcp/
│   ├── server.py                   # FastMCP 3.x app: 33 tools, 3 resources, /health, middleware
│   ├── session.py                  # Sage worker lifecycle, session management, idle culling
│   ├── _sage_worker.py             # Subprocess worker: code execution, AST validation, LaTeX
│   ├── security.py                 # AST validator, SecurityPolicy, configurable allowlists
│   ├── config.py                   # SageSettings from environment variables
│   ├── models.py                   # Pydantic models (EvaluateResult, SessionSnapshot, etc.)
│   ├── monitoring.py               # Thread-safe evaluation metrics (EvaluationMetrics)
│   └── py.typed                    # PEP 561 type hint marker
├── tests/
│   ├── conftest.py                 # Shared FakeContext fixture
│   ├── test_server.py              # Tool & resource unit tests
│   ├── test_session.py             # Session lifecycle, timeout, reset, cancel
│   ├── test_security.py            # AST validation, policy configuration
│   ├── test_config.py              # Environment variable parsing
│   ├── test_sage_worker.py         # Worker protocol, LaTeX, startup errors
│   ├── test_integration.py         # Real Sage: monitoring, timeout, cancellation
│   ├── test_use_cases.py           # End-to-end Sage workflows
│   └── cli_integration/            # LLM CLI end-to-end tests (43 cases)
│       ├── run_cli_tests.py        # Standalone runner with rich reporting
│       ├── test_cases.py           # All test case definitions
│       ├── validate.py             # Multi-tier output validation
│       ├── runner.py               # Claude/Gemini CLI invocation
│       ├── cli_config.py           # MCP server setup/teardown for CLIs
│       ├── test_claude.py          # Pytest wrapper for Claude
│       └── test_gemini.py          # Pytest wrapper for Gemini
├── charts/sagemath-mcp/            # Helm chart for Kubernetes
├── scripts/                        # Build, release, CI scripts
├── docs/reference_md/              # SageMath reference docs (Markdown)
└── .github/workflows/
    ├── ci.yml                      # 6 parallel jobs: lint, test (3.12+3.13), security
    │                               #   (pip-audit), helm, integration, smoke
    ├── release.yml                 # Multi-Python test, build, GHCR push, PyPI publish
    └── version-bump.yml            # Manual version bump + tag workflow

______________________________________________________________________

技术栈

______________________________________________________________________

更新日志

v0.2.0（2026-04-03）

新的MCP工具（添加了18个工具）

服务器从单一 evaluate_sage 该工具包含33个MCP工具（31个Sage支持，2个基础设施）。每个工具都接受结构化参数，运行AST安全验证器，并返回键入的JSON响应。

微积分（4个工具）：

• differentiate_expression ---任何顺序的符号衍生品。支持所有Sage认可的表达式，包括三角函数、指数函数、对数函数和用户定义函数。这 order 参数处理高阶导数，无需重复调用。
• integrate_expression ---不定积分和定积分。接受符号边界("-oo", "oo", "pi/2")对于不适当的积分。返回下游处理的结果是确定的还是不确定的。
• limit_expression ---单边和双边限制。这 direction 参数("plus" / "minus")能够分别计算左极限和右极限，这对于分析不连续性至关重要。
• series_expansion ---泰勒和劳伦特系列围绕任何一点。这 order 参数控制项的数量，输出包括Big-O余数项。

代数与简化（5个工具）：

• solve_equation ---单方程组和联立方程组。解析人类可读的方程式字符串（拆分 =)因此客户不需要构建Sage语法。支持包括三角根在内的符号解。
• simplify_expression ---应用Sage的 simplify() 它尝试多种简化策略（三角恒等式、代数规则等），并返回找到的最简单形式。
• expand_expression ---使用Sage扩展产品、权力和身份 expand()可用于验证代数恒等式或准备表达式以供进一步操作。
• factor_expression ---同时考虑符号多项式和整数。返回人类可读的因子分解字符串（例如。， "2^2 * 3 * 5" 对于整数）。
• calculate_expression ---计算任何表达式，并返回其符号字符串形式和数字浮点值（如果可能）。预先声明变量 x, y, z, t 为了方便起见。

线性代数（2个工具）：

• matrix_multiply ---在符号环上乘以两个矩阵。接受嵌套列表输入，并使用适当的类型强制返回嵌套列表输出。
• matrix_operation ---执行行列式、逆、特征值、秩、RREF和转置运算。每个操作都返回适当类型的结果（标量、矩阵或列表）。

微分方程（1个工具）：

• solve_ode ---使用Sage解决一阶和高阶ODE desolve().返回具有任意常数的通解。支持非标准ODE表示法的自定义函数名和变量名。

数论（1个工具）：

• number_theory_operation ---一个工具中的五个操作： is_prime, factor_integer, next_prime, gcd, lcm每个函数都直接映射到相应的Sage函数，并进行适当的整数验证。

统计（1个工具）：

• statistics_summary ---使用Sage在一次调用中计算8个描述性统计数据（平均值、中位数、总体/样本方差、总体/抽样标准偏差、最小值、最大值） mean() 和 sqrt() 为了精确计算。

可视化（1个工具）：

• plot_expression ---渲染2D函数图并返回base64编码的PNG图像。使用Sage的 plot() 具有可配置的范围界限。这 base64 和 io 专门为此工具将导入添加到安全列表中。

会话管理（2个工具）：

• reset_sage_session ---清除所有会话状态（变量、函数、定义），而不终止工作进程。快速操作，可在同一会话内重新启动。
• cancel_sage_session ---终止工作进程并启动一个新进程。当计算卡住时使用。所有的国家都失去了，但一个干净的工人是有保证的。

增强 evaluate_sage

核心评估工具得到了重大改进：

• 特定领域示例 添加到工具描述中，以便LLM知道Sage可以做什么：客户看到的描述中包含了组合学、图论、数论、几何、概率论、群论、多项式环和编码理论示例。
• 启动错误传播 ---如果 from sage.all import * （或自定义启动代码）失败，后续调用返回清除 StartupError 使用原始的异常消息，而不是令人困惑的 NameError.
• 结果类型简化 ---删除未使用的 "void" 字面意思来自 result_type，只留下 "expression" 和 "statement".

CLI集成测试套件

一个新的端到端测试套件通过真实的LLM CLI调用验证MCP服务器：

• 43个测试用例 跨越9个数学领域（微积分、代数、线性代数、ODE、数论、统计学、绘图、通用计算、会话管理）
• 双CLI支持 ---测试克劳德代码(claude --print)Gemini CLI(gemini -p)
• 实时进度报告 ---每个测试在完成时打印状态，并带有颜色编码的通过/失败指示器和经过的时间
• 并行执行 --- --parallel flag通过以下方式同时运行两个CLI ThreadPoolExecutor
• 域过滤 --- --domain calculus,algebra 仅运行选定的测试域
• 多层验证 ---首先检查预期的子字符串（不区分大小写），然后从输出中提取数字，然后回退到软失败以获得非确定性答案。检查错误指示器 *之后* 内容匹配，以避免LLM在正确答案中提到“MCP服务器”时出现假阴性。
• JSON结果导出 ---每次运行都会保存带时间戳的JSON结果以进行历史跟踪
• Pytest集成 --- test_claude.py 和 test_gemini.py 将所有案例包装为参数化的pytest测试，并进行适当的跳过/失败处理

依赖升级

基础设施现代化

Python版本：

• Python的最小值从3.11提高到 3.12Python 3.12带来了5-15%的性能改进（PEP 709内联理解，更快 asyncio)，所有CI/CD发布工作流现在仅在3.12和3.13上测试。
• Ruff目标更新自 py311 到 py312.

CI/CD大修：

• 平行工作结构 ---单片CI作业被拆分为6个独立的作业(lint, test, security, helm, integration, smoke)这是并行运行的。棉绒和测试在约1分钟内完成；集成和烟雾测试只有在通过后才能运行。
• 矩阵测试 ---单元测试现在可以在Python 3.12和3.13上运行（以前只在CI中测试了一个版本；矩阵测试是为发布保留的）。
• 紫外线缓存 --- enable-cache: true 添加到全部 astral-sh/setup-uv 步骤，消除跨运行的冗余依赖下载。
• 覆盖率报告 ---pytest运行时使用 --cov 并上传 coverage.xml 作为构建工件。
• 依赖安全扫描 新 pip-audit 作业检查所有已安装包中的已知漏洞。
• GitHub操作Node.js 24 ---所有操作都受到影响： checkout@v5, setup-uv@v7, setup-python@v6, download-artifact@v6, build-push-action@v6, upload-artifact@v4.

Docker：

• 从固定的基础图像 sagemath/sagemath:latest 到 sagemath/sagemath:10.5 用于可重复构建。这 latest 标签是不确定的，可能会在SageMath发布新版本时中断构建。

Kubernetes（Helm chart）：

• 添加 活性探针 （HTTP端口上的TCP套接字，30秒初始延迟，15秒周期，3个故障阈值）---如果服务器没有响应，则重新启动pod。
• 添加 准备就绪探测器 （TCP套接字，10秒初始延迟，10秒周期）---在启动或瞬态故障期间从服务端点删除pod。
• 添加 启动探头 （TCP套接字，5秒初始延迟，5秒周期，12次故障=60秒预算）---为SageMath提供初始化时间(from sage.all import * 可能需要10-20秒）而不会触发活性失败。
• 所有探头参数均可通过以下方式配置 values.yaml.

项目元数据：

• pyproject.toml 作者已从占位符更新为“XBP Europe”
• 添加PyPI分类器：开发状态、目标受众、Python版本、许可证、主题
• 添加了项目网址：主页、存储库、问题、变更日志

测试覆盖率

测试套件从136扩展到 242个单元测试 分支机构覆盖率为 99% 跨所有核心模块。新测试包括：

• 会话错误路径：没有Python解释器，SAGE_VENV/PYTHONPATH环境处理，重置失败（worker终止， ok=False), _terminate_worker 在运行过程中， cull_idle 没有过时的会话
• 服务器错误分支： evaluate_sage 没有上下文/没有会话id， SecurityViolation 错误类型、非安全错误类型， SageProcessError 和 __cause__
• 安全： _format_violation 只有空白行代码， log_violations=False 分支，调试日志成功验证

剩下的1%是防御性的 if ctx is not None 在实践中始终正确的分支，以及需要真正安装Sage的Sage二进制路径。

错误修复

• MCP资源序列化 --- monitoring_resource 和 session_resource 现在通过以下方式返回JSON字符串 model_dump_json() 而不是原始的Pydantic模型对象。FastMCP 3.x需要资源才能返回 str 或 ResourceContent而不是模型。CI指标验证脚本和所有测试都已相应更新。
• ASYNC240棉绒固定器 ---移动 Path(__file__).resolve() 从异步函数内部到模块级别 _PROJECT_ROOT 常量，以避免异步上下文中的同步文件系统调用。
• CLI集成验证器 ---现在对错误指示器检查（如“我不能”、“MCP服务器”等短语）进行评估 *之后* 预期的子字符串匹配，防止在正确答案提到MCP服务器时出现假阴性。
• 破碎的 -- CLI命令中的分隔符 ---之前显示的所有文档 uv run sagemath-mcp -- --transport streamable-http 这会失败，因为argparse处理 -- 作为一种立场论证。修复了README、安装、CLAUDE、使用、分发和监控文档中的问题。
• 许可证文件不匹配 ---LICENSE文件包含Apache 2.0文本，但 pyproject.toml 麻省理工学院宣布。替换为正确的MIT许可证文本。
• 版本同步 --- __init__.py 回退版本（ 0.1.2)Helm chart版本/appVersion（ 0.1.0)已更新以匹配 pyproject.toml (0.2.0).
• 缺失 pytest-cov 依赖 ---CI覆盖步骤失败，因为 pytest-cov 不在开发依赖项中。旁边添加 pip-audit.
• 抑制 PytestUnraisableExceptionWarning ---外观异步子进程传输终结器警告不再出现在测试输出中。

文档

• 完成README重写 ---添加了目录、架构图、技术栈表、变更日志、CLI集成测试部分，以及每个工具参数和返回类型的详细示例。
• 用法.md 更新了新的工具工作流和部署选项。
• CLAUDE.md 为Claude Code项目说明添加。
• 安装.md 将Python版本从3.11更新到3.12。

v0.1.2（2025-11-02）

首次公开发布。 服务器提供了一个MCP工具(evaluate_sage)在持久会话中执行任意SageMath代码。初始版本中的关键功能：

• evaluate_sage 工具 ---使用LaTeX输出、stdout捕获和可配置的每次调用超时执行任何SageMath代码。变量和函数在同一MCP会话内的调用之间持久存在。
• 会话隔离 ---每个MCP客户端都有一个专门的Sage worker子流程。一个会话中的崩溃或超时不会影响其他会话。
• 基于AST的安全沙箱 ---每个代码片段在执行前都会经过验证，从而阻止 eval/exec、文件系统操作、进程生成和未经授权的导入。可通过环境变量进行配置。
• 进展心跳 ---长时间运行的计算会发出周期性的进度事件（约1.5秒），因此客户端可以显示活动指示器。
• 多个传输 ---stdio（用于克劳德桌面）、HTTP、流式HTTP和SSE。
• Docker部署 ---Dockerfile、Docker Compose和非根执行Kubernetes的Helm chart（UID/GID 1000）。
• CI/CD管道 ---GitHub Actions提供lint、单元测试、集成测试（Docker中的真正Sage）、Docker Compose冒烟测试、Helm验证、签名GHCR镜像发布和PyPI发布。
• 监控资源 ---用于会话快照、聚合指标和SageMath文档链接的MCP资源。

______________________________________________________________________

路线图

看 ROADMAP.md 对于完整的优先计划。亮点：

第一阶段——高价值工具：

• symbolic_sum / symbolic_product ---符号求和与乘积
• combinatorics_operation ---二项式、排列、组合、分割、加泰罗尼亚语、斐波那契
• plot3d_expression ---两个变量函数的3D曲面图

第2阶段——中等价值工具：

• distribution_operation ---概率分布（PDF、CDF、抽样、分位数）
• find_root ---数字根查找（补充符号 solve_equation)
• 多表达式绘图——在一个绘图中叠加多个函数
• vector_calculus_operation ---梯度、散度、旋度、拉普拉斯算子

第3阶段——强化：

• 更富有 evaluate_sage 示例（傅里叶/拉普拉斯变换、模运算、递归）
• 超文本传输协议 /health Helm探针的端点
• 流式部分输出用于长时间计算
• 磁盘支持的会话持久性

需求

• Python 3.12+
• 本地SageMath安装可在 PATH （使用Sage 10.x测试）或Docker。
• FastMCP兼容的MCP客户端（例如Claude Desktop、Claude Code、Codex CLI、Gemini CLI）。

贡献

我们欢迎问题和拉取请求！回顾 行为准则 和 贡献指南 在打开PR之前。对于漏洞披露， 按照中的步骤进行操作 安全.md所有权违约定义见 .

许可证

麻省理工学院