AI导哈

ROOT文件分析工具

一个允许LLM与CERN ROOT文件交互的MCP服务器和CLI工具，提供文件检查、数据分析、可视化等功能。

  • by MohamedElashri
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 MohamedElashri/root-mcp

使用说明

CERN ROOT MCP Server

An MCP server and CLI tool that allow LLMs to interact with CERN ROOT files.

存储库镜像：此存储库镜像到 CERN GitLab CERN用户。PyPI版本通过GitHub Actions使用基于证明的可信发布发布。

ROOT-MCP 使大型语言模型（LLM）能够以本机方式理解和分析CERN ROOT文件。

通过以下方式公开一组专用工具 模型上下文协议（MCP） 或令牌有效 CLI接口，它将克劳德（和其他符合MCP的代理人）转变为有能力的物理研究助理，可以：

  • 检查 ROOT文件结构（树、RNtuple、分支、直方图）
  • 分析 数据分布（计算直方图、统计）
  • 计算 运动量（不变质量）
  • 可视化 结果（直接绘制1D/2D直方图）
  • 过滤器 使用物理切割（“选择”）的数据

为什么这很重要：与其要求LLM“编写一个必须调试和运行的脚本”，您可以要求LLM “检查此文件中的μon-pT分发” 它将会 只管去做.

两个接口：MCP服务器和CLI

ROOT-MCP提供 两种方式 与ROOT文件交互：

1.MCP服务器（用于克劳德桌面和MCP客户端）

  • 完全支持JSON-RPC协议
  • 用于编程的结构化输入/输出
  • 最适合：符合MCP的LLM客户端、自动化工作流程

2.根CLI(root-cli)

  • 默认情况下为人类可读输出
  • 更简单的架构（无服务器进程）
  • 最适合：直接LLM交互、调试、脚本编写

这两个接口共享相同的后端，并支持所有17个分析工具。

快速开始

1.安装

pip install root-mcp

可选：通过XRootD协议进行远程文件访问：

pip install "root-mcp[xrootd]"

2.配置

最快路径——无需配置文件：

# MCP Server
root-mcp --data-path /path/to/your/data

# CLI (token-efficient)
root-cli -d /path/to/your/data ls

或者设置一次环境变量：

export ROOT_MCP_DATA_PATH=/path/to/your/data

ROOT CLI（建议用于LLM交互）

CLI提供了 令牌高效，与MCP JSON协议相比，人类可读的界面提供了显著的令牌节省。

基本用法

# List files
root-cli ls

# Inspect a file
root-cli inspect /data/sample.root

# Create histogram with fit
root-cli histogram /data/sample.root events muon_pt --bins 100 --fit gaussian

# Read data with selection
root-cli read /data/sample.root events met muon_pt --selection "met > 50"

# Plot results
root-cli plot1d /tmp/root_mcp/muon_pt_hist.json -o plot.png --title "Muon pT"

LLM工作流示例

问你的法学硕士： “绘制μon-pT分布图”

LLM生成：

root-cli histogram /data/sample.root events muon_pt --bins 50 && \
root-cli plot1d /tmp/root_mcp/muon_pt_hist.json -o muon_pt.png --title "Muon pT Distribution"

文档

看 docs/skills/root-cli.md 完整的命令参考示例。

MCP服务器

零配置单行程序：

# Core mode (lightweight, no scipy/matplotlib needed)
root-mcp --data-path /data --mode core

# Explicit stdio transport (same runtime as the compatibility default)
root-mcp serve-stdio --data-path /data

# Extended mode with native ROOT, restricted to one directory
root-mcp --data-path /data --enable-root --allowed-root /data

# Remote XRootD resource, no YAML needed
root-mcp --resource cms=root://xrootd.cern.ch//store --allow-remote --mode extended

# Docker / container — fully env-var driven
ROOT_MCP_DATA_PATH=/data ROOT_MCP_MODE=extended ROOT_MCP_EXPORT_PATH=/exports root-mcp

# Quiet server (only warnings+) with a cache increase
root-mcp --data-path /data --log-level WARNING --cache-size 100

root-mcp serve-http 为中心的MCP Streamable HTTP端点提供服务 部署。它需要显式身份验证、源验证、限制性中心 在启动之前，请检查策略和安全绑定地址设置。

对于共享部署，请从操作员文档开始： docs/operator/central_deployment.md 和 docs/operator/security_checklist.md. 限制性的启动器配置和Kubernetes清单 examples/central/.

操作员可以通过以下方式预览和应用导出保留 root-mcp cleanup-exports --config /etc/root-mcp/config.yaml --dry-run. 外部HTTP冒烟脚本位于 scripts/smoke_external_http_client.py 启动临时中央服务器，并使用MCP Streamable HTTP进行检查 客户。

生成启动器配置（可选）：

root-mcp init --permissive   # creates config.yaml pre-filled with current directory

手动配置文件 --对于持久设置、远程资源或本机ROOT：

server:
  mode: "extended"   # "core" or "extended"

resources:
  - name: "my_analysis"
    uri: "file:///path/to/data"
    allowed_patterns: ["*.root"]

security:
  allowed_roots: []  # empty = any local path is accessible (permissive)

本地使用警告：宽容 allowed_roots: [] 默认值是有意的 用于受信任的本地stdio会话。不要将该配置公开为共享 HTTP服务；限制根并要求经过身份验证的部署配置文件 在中央或多用户使用之前。

模式选择：

  • mode: "core" --轻量级：文件操作和基本统计
  • mode: "extended" --全面分析：直方图、拟合、运动学、相关性

使用以下命令在运行时切换模式 switch_mode 工具--无需重新启动。

使用Claude Desktop运行

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "root-mcp": {
      "command": "root-mcp",
      "args": ["--data-path", "/path/to/your/data"]
    }
  }
}

或者使用持久配置文件：

{
  "mcpServers": {
    "root-mcp": {
      "command": "root-mcp",
      "env": {
        "ROOT_MCP_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

建筑

ROOT-MCP将分析功能组织为 分析层:

  • 核心模式：文件I/O、数据读取和基本统计
  • 扩展模式：全面的分析能力，包括拟合、运动学和相关性

该模式通过配置进行控制，服务器仅自动加载所需的组件。运行时模式切换也可用。

可选的本地ROOT支持

ROOT-MCP可以选择与本机集成 ROOT/PyROOT 安装以解锁超出范围的功能 uproot 提供：

  • run_root_code：执行任意PyROOT/Python代码并获得结构化结果
  • run_rdataframe：使用ROOT的RDataFrame计算直方图（不需要样板）
  • run_root_macro：通过执行C++ROOT宏 gROOT.ProcessLine

此功能是 完全可选 --ROOT-MCP在没有安装ROOT的情况下完全工作。当ROOT可用并启用时，这些附加工具会自动出现。

需求：一个可用的ROOT安装（通过 康达锻造厂、系统包或二进制tarball）。此时无法安装ROOT。

启用它 通过设置 enable_root: true 在你的 config.yaml:

features:
  enable_root: true

# Optional: tune execution settings
root_native:
  execution_timeout: 60
  working_directory: "/tmp/root_mcp_native"

使用 get_server_info 在运行时检查ROOT可用性：

{
  "root_native_available": true,
  "root_native_enabled": true,
  "root_version": "6.32/02",
  "root_features": {"rdataframe": true, "roofit": true, "tmva": false}
}

文档

完整的文档网站是用Sphinx构建的，涵盖了安装、， 配置、所有20个MCP工具、LLM集成模式和开发人员 带有自动生成API参考的指南。

在线阅读：文档托管在 根mcp文档

pip install "root-mcp[docs]"
./scripts/build_docs.sh
# open docs/_build/html/index.html

在编写文档时进行实时重新加载：

cd docs && make livehtml

亮点：

  • 用户指南 --安装、快速启动、模式、配置、LLM集成
  • 工具参考 --所有工具及其JSON有效载荷的完整目录
  • CLI参考 --带示例的完整根cli命令参考
  • 开发者指南 --架构、模块概述、开发设置、贡献
  • API 参考 --从源文档字符串自动生成

引用

如果您在研究中使用ROOT-MCP，请引用：

@software{root_mcp,
  title = {ROOT-MCP: Production-Grade MCP Server for CERN ROOT Files},
  author = {Mohamed Elashri},
  year = {2025},
  url = {https://github.com/MohamedElashri/root-mcp}
}

许可证

MIT许可证-请参阅 许可证 了解详情。

相关 MCP