MCP Server Sagemath

🚀 MCP SageMath Server

Model Context Protocol (MCP) をベースにしたローカルの SageMath サーバーです。現在、2つのツールを提供しています。

• sagemath.version：ローカルの SageMath のバージョンを確認します。
• sagemath.evaluate：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 を呼び出して実行します。

テスト

• STDIO 回帰テスト：npx -y tsx src/test/stdio-client.ts
• HTTP 回帰テスト：MCP_TRANSPORT=http npx -y tsx src/test/client.ts

セキュリティに関する注意事項

• sagemath.evaluate は任意の SageMath コードを実行できるため、信頼できる環境でのみ使用してください。
• 必要に応じて、コンテナまたはサンドボックスを使用してさらに分離し、リソース制限を設定することをお勧めします。

📚 ドキュメント

Roadmap

• より多くの SageMath 機能（グラフ描画、記号計算など）を拡張する
• 長時間実行されるタスクのセッション再利用とリソース管理を最適化する
• エラー分類とレート制限ポリシーを強化する

ライセンス

MIT ライセンスです。詳細は LICENSE を参照してください。

謝辞

• Model Context Protocol コミュニティと SDK
• SageMath オープンソース数学システム