ROOT MCP Server

---

精简的 MCP（Model Context Protocol）服务，可让大模型和其他 MCP 客户端直接使用 PyROOT 执行 Python 和 C++ 代码，无需 HTTP 端点或外部 API。

功能

• 直接执行 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

通过带有 GitHub Copilot Chat 的 VS Code 使用此 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()

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

可用工具

该服务提供两个 MCP 工具：

1. root_python

执行 Python 代码，ROOT 会自动在作用域中可用。

参数：

• 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 提供支持