ROOT MCP Server

---

LLM やその他の MCP クライアントが、HTTP エンドポイントや外部 API を介さずに、PyROOT を使用して Python および C++ コードを直接実行できる、最小構成の MCP（Model Context Protocol）サーバーです。

特長

• Python の直接実行：PyROOT を自動的に利用できる状態で Python コードを実行します
• C++ の直接実行：ROOT の cling インタープリターを介して C++ コードを実行します
• プロセス内実行：すべてのコードを同じプロセス内で実行します（サブプロセスによる分離はありません）
• エラー検出：戻り値コードと stderr を用いて C++ のコンパイルエラーを自動検出します
• コンソールログ：MCP コンソールに、整形されたコードと実行結果を出力します
• グラフィックスのサポート：イベントループに対応した TCanvas および ROOT グラフィックスオブジェクトを利用できます

アーキテクチャ

以下は、root_mcp_server プロジェクトのアーキテクチャ図です。この画像は、コンポーネントとその相互作用を視覚的に表しています。

説明：

• MCP クライアント（VS Code / CLI / プログラム）：MCP サーバーに接続し、実行リクエストを送信します。クライアントには、対話型（例：VS Code + Copilot Chat）とスクリプト化された CLI クライアントがあります。
• FastMCP サーバー：MCP ツールの呼び出し（root_python、root_cpp）を受け取り、プロセス内の実行環境に振り分けます。
• RootExecutor（プロセス内 PyROOT）：ROOT ランタイムを使用して Python または C++ コードを実行し、グラフィックスモードを管理します。また、対話型キャンバス用の組み込み HTTP サーバー（THttpServer）を公開できます。
• ROOT Web Canvas（THttpServer / JSROOT）：グラフィックスが有効な場合、ROOT セッションで作成したキャンバスは組み込み HTTP サーバーから利用できます。クライアントは、提供された URL を開いてプロットを対話的に確認できます。
• 成果物と出力：実行結果（stdout/stderr およびエラーメタデータ）が MCP クライアントに返されます。対話型キャンバスには HTTP エンドポイントからアクセスできます。

このアーキテクチャでは、低遅延で実行できるよう ROOT をプロセス内で稼働させながら、Web を利用した対話型可視化の手段を提供します。

インストール

前提条件

• PyROOT が有効な ROOT（6.x 以降）
• Python 3.10+

パッケージのインストール

pip install -e .

使い方

オプション 1：GitHub Copilot Chat を使用した VS Code

この MCP サーバーを使う最も簡単な方法は、GitHub Copilot Chat を使用した VS Code です。

1. GitHub Copilot Chat 拡張機能をインストールする

VS Code に GitHub Copilot Chat 拡張機能がインストールされていることを確認してください。

2. VS Code で MCP サーバーを設定する

MCP サーバーの設定を VS Code の設定に追加します。settings.json を開き（Ctrl/Cmd + Shift + P → 「Preferences: Open User Settings (JSON)」）、次の設定を追加してください。

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Use ROOT MCP server for data analysis"
    }
  ],
  "mcp.servers": {
		"root/mcp-server": {
			"type": "stdio",
			"command": "root_mcp_server",
			"args": []
		}
  }
}

重要：/path/to/ROOT/build/bin/thisroot.sh を、ROOT のインストール先にある thisroot.sh スクリプトの実際のパスに置き換えてください。

3. Copilot Chat で使用する

設定が完了すると、GitHub Copilot Chat で MCP ツールを使用できます。

@workspace Use #root_python to execute Python code with PyROOT

@workspace Use #root_cpp to execute C++ code with ROOT

サーバーは、実行したコードと結果を MCP コンソールに自動的に記録します（VS Code の出力パネルに表示されます）。

オプション 2：コマンドライン

MCP サーバーを直接起動します。

root_mcp_server

オプション 3：プログラムからの使用

from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp.client.session import ClientSession

server_params = StdioServerParameters(
    command="bash",
    args=["-lc", "source /path/to/thisroot.sh && python3 -m root_mcp_server.cli"],
    env=None
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Execute Python code
        result = await session.call_tool("root_python", arguments={
            "code": "import ROOT; print(ROOT.gROOT.GetVersion())"
        })
        print(result)

利用可能なツール

サーバーは 2 つの MCP ツールを公開します。

1. root_python

ROOT をスコープ内で自動的に利用できる状態で Python コードを実行します。

引数：

• code（文字列）：実行する Python コード

戻り値：

{
  "ok": boolean,
  "stdout": string,
  "stderr": string,
  "error": string | null,
  "error_type": string | null
}

例：

code = """
import ROOT
h = ROOT.TH1F("h", "Gaussian", 100, -5, 5)
for i in range(10000):
    h.Fill(ROOT.gRandom.Gaus(0, 1))
print(f"Mean: {h.GetMean():.3f}")
"""

2. root_cpp

ROOT の cling インタープリターを介して C++ コードを実行します。

引数：

• code（文字列）：実行する C++ コード

戻り値：

{
  "ok": boolean,
  "stdout": string,
  "stderr": string,
  "error": string | null,
  "error_type": string | null
}

例：

TH1F* h = new TH1F("h", "Gaussian;X;Y", 100, -5, 5);
for(int i=0; i<10000; i++) h->Fill(gRandom->Gaus(0,1));
TCanvas* c = new TCanvas("c", "Canvas", 900, 600);
h->Draw();
c->Update();
std::cout << "Mean: " << h->GetMean() << std::endl;

機能の詳細

エラー検出

サーバーは、次の方法で C++ のコンパイルエラーを自動的に検出します。

• ROOT.gInterpreter.ProcessLine() の戻り値を確認します
• stderr でエラーを示すキーワード（error:、Error:、fatal error:）を検索します

エラーは ok=false と詳細なエラーメッセージで報告されます。

コンソールログ

すべてのコード実行は、次の内容とともに stderr（MCP コンソール）に記録されます。

• 行番号付きの整形されたコード
• 実行ステータス（✓ 成功 / ❌ 失敗）
• stdout、stderr、エラーの詳細情報

出力例：

============================================================
EXECUTING PYTHON CODE:
  1 | import ROOT
  2 | print(ROOT.gROOT.GetVersion())
============================================================
✓ EXECUTION SUCCESS
STDOUT:
6.39/01

グラフィックスのサポート

サーバーは TApplication を初期化し、ROOT グラフィックスをサポートします。

• TCanvas ウィンドウ（バッチモードは無効にできます）
• ヒストグラムのプロット
• インタラクティブなグラフィックスのための ROOT イベントループ
• ガベージコレクションを防ぐためのオブジェクトの保持

開発

テストの実行

# Test basic functionality
python test_mcp_client.py

# Test persistent graphics
python test_persistent_window.py

# Test histogram creation
python test_histogram.py

プロジェクト構成

root_mcp_server/
├── root_mcp_server/
│   ├── __init__.py
│   ├── cli.py          # Entry point
│   ├── executor.py     # Code execution 
│   └── server.py       # MCP server definition
├── test_mcp_client.py
├── test_persistent_window.py
├── test_histogram.py
└── README.md

ライセンス

LICENSE ファイルを参照してください。

貢献

皆さまからの貢献を歓迎します。Pull Request をお気軽に送信してください。

謝辞

• Model Context Protocol を使用して構築されています
• CERN の ROOT を利用しています