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
# 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 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)模式选择：
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许可证-请参阅 许可证 了解详情。