MCP SageMath Server

基于 Model Context Protocol (MCP) 的本地 SageMath 服务端，当前提供两项工具：

• sagemath_version：查询本地 SageMath 版本。
• sagemath_evaluate：执行 SageMath 脚本并返回标准输出/错误。
• sagemath_health：轻量级自检，验证 SageMath 可用性。

项目处于早期预览阶段（v0.0.1）。

功能概览

• 双传输模式：默认 STDIO，可通过环境变量切换到 HTTP（同时支持 GET /mcp 与 POST /mcp）。
• 无状态 HTTP 会话：避免重复初始化导致的错误。
• 可靠的子进程封装：当 SageMath 不可用时返回结构化错误，不会崩溃。
• 可配置的 SageMath 路径：支持源代码配置与环境变量覆盖，默认回退到系统 PATH。

环境要求

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

配置 SageMath 路径

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

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

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

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

安装

• 本项目根目录下执行

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_version

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

sagemath_evaluate

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

sagemath_health

• 无输入；尝试执行 print(1+1)。
• 输出字段：ok（布尔）、message（字符串）、details（包含 stdout/stderr/exitCode 等）。
• 用途：Agent 在启动前快速探活。

测试

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

面向 Agent 的兼容性提示（Claude / Trae / 其他 MCP 客户端）

• 统一结构化输出：所有工具均返回 structuredContent（JSON 对象），并附带简短文本提示；不再需要从 content[0].text 手动 JSON 解析。
• 推荐探活流程：HTTP/STDIO 连接后先调用 sagemath_health 确认 SageMath 可用，再调用其他工具。
• HTTP 端点：默认 http://localhost:3000/mcp（可改 PORT）。支持 GET /mcp（SSE/流式 JSON-RPC）与 POST /mcp。
• STDIO：直接执行 node dist/index.js（或开发模式 npx -y tsx src/index.ts）。
• 安全提示：sagemath_evaluate 可执行任意 Sage 代码；HTTP 模式建议放在受控网络或加鉴权/限流。

配置示例（可折叠）

~/.config/modelcontext/mcp.json 里增加：

{
  "mcpServers": {
    "sagemath-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
      "autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
      "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"
      },
      "client": {
        "url": "http://localhost:3000/mcp"
      }
    }
  }
}

若希望 Claude 直接以 STDIO 启动：

{
  "mcpServers": {
    "sagemath-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-sagemath/dist/index.js"],
      "autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
      "env": {
        // "SAGE_PATH": "/absolute/path/to/sage"
      }
    }
  }
}

Claude Desktop/MCP 配置中添加：

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

{
  "mcpServers": {
    "sagemath-server-dev": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/Users/halois/workdir/Toolkit/mcps/mcp-server-sagemath/src/index.ts"
      ],
      "autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"],
      "env": {
        // "SAGE_PATH": "/absolute/path/to/sage"
      }
    }
  }
}

{
  "mcpServers": {
    "sagemath-server-http": {
      "command": "node",
      "args": ["/Users/halois/workdir/Toolkit/mcps/mcp-server-sagemath/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "http",
        "PORT": "3000"
        // "SAGE_PATH": "/absolute/path/to/sage"
      },
      "client": {
        "url": "http://localhost:3000/mcp"
      },
      "autoApprove": ["sagemath_version", "sagemath_evaluate", "sagemath_health"]
    }
  }
}

安全提示

• sagemath_evaluate 可运行任意 SageMath 代码，请仅在可信环境使用。
• 建议在需要时结合容器或沙箱进一步隔离，并设置资源配额。

Roadmap

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

许可证

MIT License，详见 LICENSE。

鸣谢

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

更新日志

• 0.0.2（未发布）：增加 sagemath_health 自检工具；统一工具返回的 structuredContent，客户端无需手动解析 content；README 增补 Codex/Claude STDIO/HTTP 配置示例。
• 0.0.1：初始版本，提供 sagemath_version 与 sagemath_evaluate。