金大哥 - mcp-server-sagemath MCP 详情

article

README

🚀 MCP SageMath 服务端

本项目是基于 Model Context Protocol (MCP) 的本地 SageMath 服务端，目前提供了两项实用工具，可用于查询本地 SageMath 版本以及执行 SageMath 脚本并获取输出结果。当前项目处于早期预览阶段（v0.0.1）。

🚀 快速开始

本项目是基于 Model Context Protocol (MCP) 的本地 SageMath 服务端，为开发者提供了便捷的方式来与本地 SageMath 进行交互。在开始使用前，请确保满足以下环境要求：

Node.js 18 及以上版本（推荐 20+）。
本地已安装 SageMath，并能够通过命令行访问其可执行文件。

✨ 主要特性

双传输模式：默认采用 STDIO 模式，也可通过环境变量轻松切换到 HTTP 模式，同时支持 GET /mcp 与 POST /mcp 两种请求方式。
无状态 HTTP 会话：有效避免因重复初始化而导致的错误，确保服务的稳定性。
可靠的子进程封装：当 SageMath 不可用时，会返回结构化错误信息，不会导致服务崩溃。
可配置的 SageMath 路径：支持通过源代码配置与环境变量覆盖，默认会回退到系统 PATH 查找 SageMath 可执行文件。

📦 安装指南

在项目根目录下，执行以下命令进行依赖安装：

npm install

💻 使用示例

基础用法

STDIO（默认模式）

构建项目：

npm run build

启动服务：

node dist/index.js

测试示例客户端：

npx -y tsx src/test/stdio-client.ts

HTTP 模式（需手动启用）

启动开发服务器：

MCP_TRANSPORT=http npm run dev

默认监听 http://localhost:3000/mcp，可通过 PORT 环境变量调整端口。

进行测试：

MCP_TRANSPORT=http npx -y tsx src/test/client.ts

端点说明：
- GET /mcp：用于 SSE/流式 JSON-RPC。
- POST /mcp：标准 JSON-RPC over HTTP。

高级用法

MCP 客户端配置示例

STDIO

{
  "mcpServers": {
    "sagemath-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
      "autoApprove": ["sagemath.version", "sagemath.evaluate"],
      "env": {
        // "SAGE_PATH": "/absolute/path/to/sage" // 可选
      }
    }
  }
}

HTTP

{
  "mcpServers": {
    "sagemath-server-http": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "http",
        "PORT": "3000"
      }
    }
  }
}

📚 详细文档

配置 SageMath 路径

项目在运行时按照以下优先级查找 SageMath 可执行文件：

src/config.ts 中的 config.sagePath（若设置为非空字符串）。
环境变量 SAGE_PATH。
系统 PATH 中的 sage 命令。

默认情况下，config.sagePath 会读取 SAGE_PATH 环境变量的值；如需固定路径，可在该文件内显式填写，例如：

export const config = {
  sagePath: "/opt/sage/bin/sage",
};

提供的工具

`sagemath.version`

输出字段：stdout, stderr, exitCode, durationMs, timedOut。
适用于检测 SageMath 是否安装及版本信息。

`sagemath.evaluate`

输入：
- code (string) — 必填，SageMath 脚本。
- timeoutMs (number) — 可选，超时时间，默认 10000 ms。
输出同上。
执行流程：将代码写入临时文件后调用 SageMath 执行。

测试

STDIO 回归测试：npx -y tsx src/test/stdio-client.ts
HTTP 回归测试：MCP_TRANSPORT=http npx -y tsx src/test/client.ts

🔧 技术细节

本项目在设计上充分考虑了稳定性和可扩展性，采用了可靠的子进程封装技术，确保在 SageMath 不可用时能够返回结构化错误信息，避免服务崩溃。同时，支持双传输模式，用户可以根据实际需求选择合适的通信方式。

📄 许可证

本项目采用 MIT License，详见 LICENSE。

鸣谢

Model Context Protocol 社区及 SDK。
SageMath 开源数学系统。

⚠️ 重要提示

sagemath.evaluate 可运行任意 SageMath 代码，请仅在可信环境使用。

💡 使用建议

建议在需要时结合容器或沙箱进一步隔离，并设置资源配额。

Roadmap

扩展更多 SageMath 功能（绘图、符号计算等）。
优化长时间任务的会话复用与资源管理。
增强错误分类与限流策略。

mcp-server-sagemath