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