root-mcp

Servidor MCP para archivos ROOT CERN

Documentación

CERN ROOT MCP Server

Servidor MCP de CERN ROOT

Un servidor MCP y una herramienta CLI que permiten a los LLM interactuar con archivos CERN ROOT.

Espejo del repositorio: Este repositorio está duplicado en CERN GitLab para usuarios de CERN. Los lanzamientos de PyPI se publican a través de GitHub Actions utilizando publicación confiable basada en atestación.

ROOT-MCP permite a los Modelos de Lenguaje de Gran Tamaño (LLM) comprender y analizar de forma nativa archivos CERN ROOT.

Al exponer un conjunto de herramientas especializadas a través del Protocolo de Contexto de Modelo (MCP) o una interfaz CLI eficiente en tokens, convierte a Claude (y otros agentes compatibles con MCP) en asistentes de investigación física capaces que pueden:

Inspeccionar estructuras de archivos ROOT (Trees, RNTuples, Branches, Histogramas)
Analizar distribuciones de datos (calcular histogramas, estadísticas)
Calcular cantidades cinemáticas (masa invariante)
Visualizar resultados (graficar histogramas 1D/2D directamente)
Filtrar datos usando cortes físicos ("selecciones")

Por qué esto es importante: En lugar de pedirle a un LLM que "escriba un script" que tengas que depurar y ejecutar, puedes pedirle al LLM que "Compruebe la distribución de pT de muones en este archivo" y lo hará directamente.

Dos interfaces: Servidor MCP y CLI

ROOT-MCP proporciona dos formas de interactuar con archivos ROOT:

1. Servidor MCP (para Claude Desktop y clientes MCP)

Soporte completo del protocolo JSON-RPC
Entrada/salida estructurada para uso programático
Ideal para: clientes LLM compatibles con MCP, flujos de trabajo automatizados

2. CLI de ROOT (`root-cli`)

Salida legible para humanos por defecto
Arquitectura más simple (sin proceso de servidor)
Ideal para: interacción directa con LLM, depuración, scripting

Ambas interfaces comparten el mismo backend y admiten las 17 herramientas de análisis.

Inicio rápido

1. Instalación

pip install root-mcp

Opcional: Para acceso remoto a archivos mediante el protocolo XRootD:

pip install "root-mcp[xrootd]"

2. Configuración

La vía más rápida: no se necesita archivo de configuración:

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

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

O establece una variable de entorno una sola vez:

export ROOT_MCP_DATA_PATH=/path/to/your/data

CLI de ROOT (Recomendado para interacción con LLM)

La CLI proporciona una interfaz eficiente en tokens y legible para humanos que ofrece ahorros significativos de tokens en comparación con el protocolo JSON de MCP.

Uso básico

# 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"

Ejemplo de flujo de trabajo con LLM

Pídele a tu LLM: "Grafica la distribución de pT de muones"

El LLM genera:

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"

Documentación

Consulta docs/skills/root-cli.md para la referencia completa de comandos con ejemplos.

Servidor MCP

Comandos de una línea sin configuración:

# 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 sirve el endpoint HTTP Streamable de MCP para implementaciones centralizadas. Requiere autenticación explícita, validación de Origin, política central restrictiva y configuraciones seguras de dirección de enlace antes de iniciar.

Para implementaciones compartidas, comienza con la documentación del operador: docs/operator/central_deployment.md y docs/operator/security_checklist.md. Las configuraciones iniciales restrictivas y los manifiestos de Kubernetes se encuentran en examples/central/.

Los operadores pueden previsualizar y aplicar la retención de exportaciones con root-mcp cleanup-exports --config /etc/root-mcp/config.yaml --dry-run. El script de prueba HTTP externo en scripts/smoke_external_http_client.py inicia un servidor central temporal y lo verifica con el cliente HTTP Streamable de MCP.

Genera una configuración inicial (opcional):

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

Archivo de configuración manual: para configuraciones persistentes, recursos remotos o ROOT nativo:

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)

Advertencia de uso local: El valor predeterminado permisivo allowed_roots: [] está pensado para sesiones stdio locales de confianza. No expongas esa configuración como un servicio HTTP compartido; restringe las raíces y exige un perfil de implementación autenticado antes del uso central o multiusuario.

Selección de modo:

mode: "core" — Ligero: operaciones de archivos y estadísticas básicas
mode: "extended" — Análisis completo: histogramas, ajustes, cinemática, correlaciones

Cambia de modo en tiempo de ejecución con la herramienta switch_mode — sin necesidad de reiniciar.

Ejecutar con Claude Desktop

Añade a tu claude_desktop_config.json:

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

O con un archivo de configuración persistente:

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

Arquitectura

ROOT-MCP organiza las capacidades de análisis en niveles de análisis:

Modo núcleo: E/S de archivos, lectura de datos y estadísticas básicas
Modo extendido: Capacidades de análisis completas, incluidos ajustes, cinemática y correlaciones

El modo se controla mediante configuración, y el servidor carga automáticamente solo los componentes que necesitas. También está disponible el cambio de modo en tiempo de ejecución.

Soporte opcional de ROOT nativo

ROOT-MCP puede integrarse opcionalmente con una instalación nativa de ROOT/PyROOT para desbloquear capacidades más allá de lo que proporciona uproot:

run_root_code: Ejecutar código arbitrario de PyROOT/Python y obtener resultados estructurados
run_rdataframe: Calcular histogramas usando RDataFrame de ROOT (sin necesidad de código repetitivo)
run_root_macro: Ejecutar macros C++ de ROOT mediante gROOT.ProcessLine

Esta característica es completamente opcional — ROOT-MCP funciona completamente sin ROOT instalado. Cuando ROOT está disponible y habilitado, estas herramientas adicionales aparecen automáticamente.

Requisitos: Una instalación funcional de ROOT (mediante conda-forge, paquete del sistema o archivo binario comprimido). ROOT no se puede instalar con pip en este momento.

Habilitarlo estableciendo enable_root: true en tu config.yaml:

features:
  enable_root: true

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

Usa get_server_info para verificar la disponibilidad de ROOT en tiempo de ejecución:

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

Documentación

El sitio completo de documentación está construido con Sphinx y cubre la instalación, la configuración, las 20 herramientas MCP, los patrones de integración con LLM y la guía para desarrolladores con referencia de API generada automáticamente.

Leer en línea: La documentación está alojada en documentación de root-mcp

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

Para recarga en vivo mientras escribes documentación:

cd docs && make livehtml

Aspectos destacados:

Guía de usuario — instalación, inicio rápido, modos, configuración, integración con LLM
Referencia de herramientas — catálogo completo de todas las herramientas y sus cargas JSON
Referencia de CLI — referencia completa de comandos para root-cli con ejemplos
Guía para desarrolladores — arquitectura, resumen de módulos, configuración de desarrollo, contribuciones
Referencia de API — generada automáticamente a partir de docstrings del código fuente

Cita

Si usas ROOT-MCP en tu investigación, por favor cita:

@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}
}

Licencia

Licencia MIT: consulta LICENSE para más detalles.

root-mcp

Documentación

Servidor MCP de CERN ROOT

Dos interfaces: Servidor MCP y CLI

1. Servidor MCP (para Claude Desktop y clientes MCP)

2. CLI de ROOT (root-cli)

Inicio rápido

1. Instalación

2. Configuración

CLI de ROOT (Recomendado para interacción con LLM)

Uso básico

Ejemplo de flujo de trabajo con LLM

Documentación

Servidor MCP

Comandos de una línea sin configuración:

Ejecutar con Claude Desktop

Arquitectura

Soporte opcional de ROOT nativo

Documentación

Cita

Licencia

2. CLI de ROOT (`root-cli`)