mcp-server-sagemath

@GaloisHLee/mcp-server-sagemath

0 Stars 6 次浏览 GaloisHLee 更新于 2026-08-23

开发者工具

该服务暂未提供标准配置，请参考 README 手动接入

服务介绍

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 可执行文件

src/config.ts 中的 config.sagePath若设置为非空字符串
环境变量 SAGE_PATH
系统 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 客户端

统一结构化输出所有工具均返回 structuredContentJSON 对象并附带简短文本提示不再需要从 content[0].text 手动 JSON 解析
推荐探活流程HTTP/STDIO 连接后先调用 sagemath_health 确认 SageMath 可用再调用其他工具
HTTP 端点默认 http://localhost:3000/mcp可改 PORT支持 GET /mcpSSE/流式 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客户端无需手动解析 contentREADME 增补 Codex/Claude STDIO/HTTP 配置示例
0.0.1初始版本提供 sagemath_version 与 sagemath_evaluate

查看源码项目主页