Uproot MCP Server

根除mcp服务器

用于执行ROOT文件分析的MCP服务器 连根拔起. 它充当EIC数据分析工作流的计算后端，读取大型ROOT数据集 并返回适合显示、制表或 MCP客户端的可视化。

此服务器是以下项目的合作伙伴 xrootd mcp服务器 并遵循类似的结构，使用Python作为主要语言来实现原生根除 整合。

特性

• 文件结构检查：列出ROOT文件中的所有键、树、分支和叶子
• 树元数据：每个分支的详细信息，包括类型、条目计数和压缩
• 汇总统计：任何分支的平均值、标准差、最小值、最大值、百分位数（p25/p50/p75）和非有限值计数
• 带选择的组织编程：具有可配置区间、显式范围和布尔切割表达式的1-D直方图
• 沙盒内核执行：在受限沙盒中运行任意多分支Python计算（无导入，无文件I/O）
• 本地和远程文件：适用于本地路径和XRootD URL(root://server//path/to/file.root)
• JSON输出：所有结果都以JSON序列化字典的形式返回，便于客户端使用

安装

使用Docker（推荐）

拉取并运行发布到GitHub容器注册表的最新映像：

docker run -i --rm \
  ghcr.io/eic/uproot-mcp-server:latest

使用Docker Compose与Watchtower

捆绑 docker-compose.yml 同时启动MCP服务器 守望塔，它会自动拉动 每当有新图像发布到时，都会重新启动容器 ghcr.io:

docker compose up -d

守望台默认每小时轮询一次更新。覆盖间隔（in 秒）与 WATCHTOWER_POLL_INTERVAL 环境变量：

WATCHTOWER_POLL_INTERVAL=1800 docker compose up -d

来源

git clone https://github.com/eic/uproot-mcp-server.git
cd uproot-mcp-server
python -m venv .venv
source .venv/bin/activate
pip install -e .

用于XRootD远程文件访问(root://server//path URL），安装可选 XRootD客户端：

pip install -e ".[xrootd]"

依赖项

• Python≥3.10
• uproot ≥ 5.0
• numpy ≥ 1.24
• awkward ≥ 2.0
• mcp ≥ 1.0
• RestrictedPython ≥ 7.0
• *（可选）* xrootd ≥5.4——要求 root:// 网址

用法

启动服务器（stdio传输）

source .venv/bin/activate
python -m uproot_mcp_server.server
# or, after pip install:
uproot-mcp-server

MCP客户端配置

本地安装

使用完整路径添加到MCP客户端配置文件（例如Claude Desktop） 对于虚拟环境内的可执行文件：

{
  "mcpServers": {
    "uproot": {
      "command": "/path/to/uproot-mcp-server/.venv/bin/uproot-mcp-server"
    }
  }
}

替换 /path/to/uproot-mcp-server 带有克隆存储库的绝对路径。

码头工人

{
  "mcpServers": {
    "uproot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/eic/uproot-mcp-server:latest"]
    }
  }
}

可用工具

get_file_structure

返回ROOT文件的顶级结构（所有键和每个TTree的摘要）。

{
  "file_path": "/data/events.root"
}

get_tree_info

返回单个TTree的详细元数据，包括所有分支和叶子。

{
  "file_path": "/data/events.root",
  "tree_name": "events"
}

get_branch_statistics

计算单个分支的汇总统计数据（均值、标准差、最小值、最大值、百分位数）。 支持可选的布尔选择剪切和输入范围。

{
  "file_path": "/data/events.root",
  "tree_name": "events",
  "branch_name": "MCParticles.momentum.x",
  "cut": "MCParticles.charge != 0",
  "entry_start": 0,
  "entry_stop": 10000
}

histogram_branch

生成具有可选选择、可配置箱和显式范围的分支的1-D直方图。

{
  "file_path": "root://dtn-eic.jlab.org//path/to/file.root",
  "tree_name": "events",
  "branch_name": "MCParticles.momentum.x",
  "bins": 100,
  "range_min": -5.0,
  "range_max": 5.0,
  "cut": "MCParticles.charge != 0"
}

响应包括 edges （箱边界）， counts, underflow, overflow, entries, mean，以及 std.

execute_kernel

在一个或多个分支上执行任意Python计算 沙盒环境. 内核接收 dict[branch_name, array] 并且可以返回数组、标量或字典。

{
  "file_path": "/data/events.root",
  "tree_name": "events",
  "kernel_code": "def kernel(events):\n    px = events['px']\n    py = events['py']\n    pz = events['pz']\n    return np.sqrt(px**2 + py**2 + pz**2)\n",
  "branches": ["px", "py", "pz"],
  "page": 0,
  "page_size": 1000
}

沙盒限制 --以下代码在内核中被阻塞：

有以下内核版本：

• np --完整的numpy包
• ak --完整的笨拙阵列包
• 安全内置： len, range, list, dict, tuple, set, int, float, bool, str, abs, min, max, sum, round, zip, enumerate, map, filter, sorted, reversed, isinstance, print，以及标准异常类型

响应 （数组结果）：

{
  "result_type": "array",
  "data": [1.2, 3.4, ...],
  "total": 9698,
  "page": 0,
  "page_size": 1000,
  "page_count": 10,
  "has_more": true,
  "file_path": "...",
  "tree_name": "events",
  "branches": ["px", "py", "pz"]
}

对于标量或字典结果， result_type 是 "scalar" 或 "dict" 并且没有分页字段。

执行超时： 内核在一个隔离的子进程中运行，该子进程在30秒的挂钟时间后被强制终止（SIGTERM然后SIGKILL）。

发展

运行测试

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

远程集成测试

设置 UPROOT_TEST_REMOTE_FILE 将环境变量设置为XRootD URL以启用 远程文件测试：

export UPROOT_TEST_REMOTE_FILE="root://dtn-eic.jlab.org//work/eic2/EPIC/RECO/24.07.0/epic_craterlake/DIS/NC/18x275/q2_0.001_1.0/pythia8NCDIS_18x275_minQ2=0.001_beamEffects_xAngle=-0.025_hiDiv_1.0000.eicrecon.tree.edm4eic.root"
pytest tests/ -v

许可证

麻省理工学院