SymPy Sandbox MCP

SymPy沙盒MCP

英语| 中文版

一种以生产为中心的MCP服务，让代理/LLM安全高效地运行SymPy。 它结合了AST策略检查、运行时资源限制和预热的worker，以提供低噪声、解析友好的结果。

特性

• 单一工具： sympy （输入只需要 code)
• 预热工人池，避免重复 import sympy
• 两层安全：AST防护+运行时资源限制
• 紧凑的结构化JSON输出，降低令牌开销
• 标准化错误代码，实现可靠的自动重试工作流

典型使用案例

• 符号代数、微分、积分、方程求解
• 用于Codex/Cursor/Claude Desktop/自定义MCP客户端的MCP工具集成
• 需要可控故障和干净错误信号的代理工作流

推荐集成（MCP客户端通过stdio）

呼叫示例：

fastmcp call \
  --command 'python -m sym_mcp.server' \
  --target sympy \
  --input-json '{"code":"import sympy as sp\\nx=sp.Symbol(\"x\")\\nprint(sp.factor(x**2-1))"}'

客户端配置(python -m，推荐）：

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "python",
      "args": ["-m", "sym_mcp.server"]
    }
  }
}

客户端配置（安装为 sym-mcp):

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "sym-mcp",
      "args": []
    }
  }
}

客户端配置(uvx):

{
  "mcpServers": {
    "sympy-sandbox": {
      "command": "uvx",
      "args": ["sym-mcp"]
    }
  }
}

快速开始

1） 要求

• Python 3.11+
• Linux/macOS（建议在生产环境中使用Linux）

2） 安装（先安装清华镜像）

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e .
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e ".[dev]"

3） 运行服务器（stdio）

python -m sym_mcp.server

4） 验证工具

fastmcp list --command 'python -m sym_mcp.server'

工具合同

工具名称

• sympy

输入

• code: str

笔记：

• 你必须 print() 最终输出。
• 如果没有打印任何内容， out 可能是空的。

输出（始终为紧凑的JSON字符串）

成功：

{"out":"x**2/2"}

失败：

{"code":"E_RUNTIME","line":3,"err":"ZeroDivisionError: division by zero","hint":"Runtime error. Check variable types, division-by-zero, or undefined names near the reported line."}

字段定义：

• out：stdout成功文本
• code：错误代码
• line：用户代码错误行，或 null
• err：紧凑的错误消息（消除了回溯噪声）
• hint：修复提示（基于配置的提示级别）
• 如果 out / err / hint 太长，将被截断 ...[truncated]

错误代码

• E_AST_BLOCK：被AST安全策略阻止
• E_SYNTAX：语法错误
• E_TIMEOUT：超时
• E_MEMORY：内存限制已触发
• E_RUNTIME：常规运行时错误
• E_WORKER：工作人员通信/状态故障
• E_INTERNAL：内部服务器错误

推荐的代理提示规则

1. 只使用数学Python代码。
2. 仅进口 sympy 或 math.
3. 总是 print() 最终答案。
4. 对于多个输出，使用多个 print() 线。
5. 故障时，尽量减少附近的补丁 line 然后重试。
6. 对于 E_TIMEOUT，先缩小规模；为了 E_MEMORY，减小对象大小/尺寸；为了 E_AST_BLOCK，删除不安全的声明。

例子：

import sympy as sp
x = sp.Symbol("x")
expr = (x + 1)**5
print(sp.expand(expr))

安全模型

执行前（AST策略）

• 仅 sympy / math 允许进口
• 危险功能被阻止(eval, exec, open, __import__等等）
• Dunder属性遍历被阻止（例如。 __class__)

执行期间（操作系统资源限制）

• 每任务CPU时间限制+超时终止
• 每个工人的内存限制通过 setrlimit
• 工作人员在发生故障时自动重建以保持服务器健康

建筑

• src/sym_mcp/server.py：MCP入口点和工具注册
• src/sym_mcp/security/ast_guard.py：AST验证
• src/sym_mcp/executor/worker_main.py：工人循环
• src/sym_mcp/executor/pool.py：异步预热进程池
• src/sym_mcp/executor/sandbox.py：受限执行和stdout捕获
• src/sym_mcp/errors/parser.py：错误规范化和代码映射
• src/sym_mcp/config.py：运行时配置

配置（环境变量）

• SYMMCP_POOL_SIZE：工作池大小，默认值 10
• SYMMCP_EXEC_TIMEOUT_SEC：每次执行超时（秒），默认值 3
• SYMMCP_MEMORY_LIMIT_MB：每个工作进程的内存上限（MB），默认值 150
• SYMMCP_QUEUE_WAIT_SEC：队列等待超时（秒），默认值 2
• SYMMCP_LOG_LEVEL：日志级别，默认值 INFO
• SYMMCP_MAX_OUTPUT_CHARS：输出截断阈值，默认值 1200
• SYMMCP_HINT_LEVEL：提示级别(none/short/medium)，默认值 medium

常见问题解答

为什么 out 空？

最有可能的是，代码没有 print() 最终结果。

为什么返回紧凑的JSON字符串？

代理更容易可靠地解析并降低令牌成本。

内存限制在macOS上总是稳定的吗？

setrlimit 行为因操作系统而异。Linux更适合生产环境。

它支持HTTP/SSE吗？

当前主要交付是 stdio稍后可以通过FastMCP传输扩展添加HTTP/SSE。

已知限制

• 这是受限的Python执行，而不是VM/容器级隔离
• 内存限制行为取决于操作系统
• 输出在阈值处被截断 ...[truncated] 后缀

发展

运行测试

PYTHONPATH=src pytest -q

基准

PYTHONPATH=src python scripts/benchmark.py --concurrency 100 --total 500

贡献

• 跑 PYTHONPATH=src pytest -q 在提交PR之前
• 添加新功能时，请更新：

- 错误代码文档 - README示例 - 相关单元/集成测试

• 发布过程： 发布.md