Root MCP Server

🚀 root_mcp_server: 用於ROOT的MCP服務器

用於通過PyROOT執行Python和C++代碼的模型上下文協議（MCP）服務器

這個最小化的MCP（模型上下文協議）服務器允許大語言模型（LLMs）和其他MCP客戶端直接使用PyROOT執行Python和C++代碼，無需HTTP端點或外部API。

✨ 主要特性

• 直接執行Python代碼：可自動使用PyROOT運行Python代碼。
• 直接執行C++代碼：通過ROOT的cling解釋器運行C++代碼。
• 進程內執行：所有代碼在同一進程中運行（無子進程隔離）。
• 錯誤檢測：通過返回碼和標準錯誤輸出自動檢測C++編譯錯誤。
• 控制檯日誌記錄：在MCP控制檯中以美觀的格式打印代碼執行結果。
• 圖形支持：支持TCanvas和ROOT圖形對象，並支持事件循環。

📦 安裝指南

前提條件

• 啟用了PyROOT的ROOT（6.x或更高版本）。
• Python 3.10或更高版本。

安裝包

pip install -e .

💻 使用示例

基礎用法

選項1：在VS Code中結合GitHub Copilot Chat使用

這是使用此MCP服務器最簡單的方法。

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()

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

高級用法

可用工具

服務器提供了兩個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()的返回碼。
• 掃描標準錯誤輸出中的錯誤關鍵字（error:、Error:、fatal error:）。 錯誤將以ok=false和詳細的錯誤消息進行報告。

控制檯日誌記錄

所有代碼執行都會記錄到標準錯誤輸出（MCP控制檯），包含以下內容：

• 帶有行號的美觀打印代碼。
• 執行狀態（✓ 成功 / ❌ 失敗）。
• 完整的標準輸出、標準錯誤輸出和錯誤詳細信息。 示例輸出：

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

圖形支持

服務器初始化TApplication並支持ROOT圖形：

• TCanvas窗口（可以禁用批處理模式）。
• 直方圖繪製。
• 用於交互式圖形的ROOT事件循環。
• 對象持久化以防止垃圾回收。

架構

以下是root_mcp_server項目的架構圖。該圖直觀展示了各個組件及其交互方式。

描述：

• MCP客戶端（VS Code / 命令行界面 / 編程方式）：連接到MCP服務器併發送執行請求。客戶端可以是交互式的（例如VS Code + Copilot Chat）或腳本化的命令行客戶端。
• FastMCP服務器：接收MCP工具調用（root_python、root_cpp）並將其分發到進程內執行器。
• RootExecutor（進程內PyROOT）：使用ROOT運行時運行Python或C++代碼，管理圖形模式，並可以為交互式畫布暴露一個嵌入式HTTP服務器（THttpServer）。
• ROOT Web畫布（THttpServer / JSROOT）：啟用圖形時，ROOT會話中創建的畫布可通過嵌入式HTTP服務器訪問；客戶端可以打開提供的URL以交互式檢查繪圖。
• 工件和輸出：執行結果（標準輸出/標準錯誤輸出和錯誤元數據）返回給MCP客戶端；交互式畫布可通過HTTP端點訪問。

這種架構使ROOT在進程內運行以實現低延遲執行，同時為交互式可視化提供基於Web的路徑。

🛠️ 開發相關

運行測試

# 測試基本功能
python test_mcp_client.py

# 測試持久圖形
python test_persistent_window.py

# 測試直方圖創建
python test_histogram.py

項目結構

root_mcp_server/
├── root_mcp_server/
│   ├── __init__.py
│   ├── cli.py          # 入口點
│   ├── executor.py     # 代碼執行 
│   └── server.py       # MCP服務器定義
├── test_mcp_client.py
├── test_persistent_window.py
├── test_histogram.py
└── README.md

📄 許可證

請參閱LICENSE文件。

👥 貢獻

歡迎貢獻代碼！請隨時提交拉取請求。

🙏 致謝

• 基於模型上下文協議構建。
• 由歐洲核子研究組織（CERN）的ROOT提供支持。