MCP Server Sagemath

🚀 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 可執行文件：

1. src/config.ts 中的 config.sagePath（若設置為非空字符串）。
2. 環境變量 SAGE_PATH。
3. 系統 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 功能（繪圖、符號計算等）。
• 優化長時間任務的會話複用與資源管理。
• 增強錯誤分類與限流策略。