root-mcp

Servidor MCP para arquivos ROOT CERN

Documentação

CERN ROOT MCP Server

Servidor CERN ROOT MCP

Um servidor MCP e uma ferramenta CLI que permitem que LLMs interajam com arquivos CERN ROOT.

Espelho do Repositório: Este repositório é espelhado no CERN GitLab para usuários do CERN. As versões do PyPI são publicadas via GitHub Actions usando publicação confiável baseada em atestação.

ROOT-MCP capacita Grandes Modelos de Linguagem (LLMs) a entender e analisar nativamente arquivos CERN ROOT.

Ao expor um conjunto de ferramentas especializadas por meio do Model Context Protocol (MCP) ou de uma interface CLI eficiente em tokens, ele transforma o Claude (e outros agentes compatíveis com MCP) em assistentes de pesquisa em física capazes de:

Inspecionar estruturas de arquivos ROOT (Trees, RNTuples, Branches, Histogramas)
Analisar distribuições de dados (Calcular Histogramas, Estatísticas)
Calcular grandezas cinemáticas (Massa Invariante)
Visualizar resultados (Plotar histogramas 1D/2D diretamente)
Filtrar dados usando cortes de física ("seleções")

Por que isso importa: Em vez de pedir a um LLM para "escrever um script" que você precisa depurar e executar, você pode pedir ao LLM para "Verificar a distribuição de pT do múon neste arquivo" e ele simplesmente fará isso.

Duas Interfaces: Servidor MCP e CLI

O ROOT-MCP oferece duas formas de interagir com arquivos ROOT:

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

Suporte completo ao protocolo JSON-RPC
Entrada/saída estruturada para uso programático
Melhor para: clientes LLM compatíveis com MCP, fluxos de trabalho automatizados

2. CLI ROOT (`root-cli`)

Saída legível para humanos por padrão
Arquitetura mais simples (sem processo de servidor)
Melhor para: interação direta com LLM, depuração, scripts

Ambas as interfaces compartilham o mesmo backend e suportam todas as 17 ferramentas de análise.

Início Rápido

1. Instalação

pip install root-mcp

Opcional: Para acesso remoto a arquivos via protocolo XRootD:

pip install "root-mcp[xrootd]"

2. Configuração

Caminho mais rápido — nenhum arquivo de configuração necessário:

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

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

Ou defina uma variável de ambiente uma vez:

export ROOT_MCP_DATA_PATH=/path/to/your/data

CLI ROOT (Recomendado para Interação com LLM)

A CLI oferece uma interface eficiente em tokens e legível para humanos que proporciona economias significativas de tokens em comparação com o protocolo JSON do 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"

Exemplo de Fluxo de Trabalho com LLM

Pergunte ao seu LLM: "Plotar a distribuição de pT do múon"

O LLM gera:

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"

Documentação

Consulte docs/skills/root-cli.md para a referência completa de comandos com exemplos.

Servidor MCP

Comandos de uma linha com configuração zero:

# 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 serve o endpoint HTTP Streamable do MCP para implantações centrais. Ele exige autenticação explícita, validação de Origin, política central restritiva e configurações seguras de endereço de bind antes de iniciar.

Para implantações compartilhadas, comece com a documentação do operador: docs/operator/central_deployment.md e docs/operator/security_checklist.md. Configurações iniciais restritivas e manifestos Kubernetes estão em examples/central/.

Operadores podem visualizar e aplicar a retenção de exportação com root-mcp cleanup-exports --config /etc/root-mcp/config.yaml --dry-run. O script de teste HTTP externo em scripts/smoke_external_http_client.py inicia um servidor central temporário e o verifica com o cliente HTTP Streamable do MCP.

Gerar uma configuração inicial (opcional):

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

Arquivo de configuração manual — para configurações persistentes, recursos remotos ou 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)

Aviso de uso local: O padrão permissivo allowed_roots: [] é destinado a sessões stdio locais confiáveis. Não exponha essa configuração como um serviço HTTP compartilhado; restrinja as raízes e exija um perfil de implantação autenticado antes do uso central ou multiusuário.

Seleção de Modo:

mode: "core" — Leve: operações de arquivo e estatísticas básicas
mode: "extended" — Análise completa: histogramas, ajustes, cinemática, correlações

Alterne os modos em tempo de execução com a ferramenta switch_mode — sem necessidade de reinicialização.

Executar com Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Ou com um arquivo de configuração persistente:

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

Arquitetura

O ROOT-MCP organiza as capacidades de análise em níveis de análise:

Modo Core: E/S de arquivos, leitura de dados e estatísticas básicas
Modo Estendido: Capacidades completas de análise, incluindo ajustes, cinemática e correlações

O modo é controlado via configuração, e o servidor carrega automaticamente apenas os componentes que você precisa. A alternância de modo em tempo de execução também está disponível.

Suporte Opcional a ROOT Nativo

O ROOT-MCP pode opcionalmente integrar-se a uma instalação nativa de ROOT/PyROOT para desbloquear capacidades além do que o uproot oferece:

run_root_code: Executar código PyROOT/Python arbitrário e obter resultados estruturados
run_rdataframe: Calcular histogramas usando o RDataFrame do ROOT (sem necessidade de código boilerplate)
run_root_macro: Executar macros C++ ROOT via gROOT.ProcessLine

Este recurso é totalmente opcional — o ROOT-MCP funciona completamente sem ROOT instalado. Quando o ROOT está disponível e habilitado, essas ferramentas adicionais aparecem automaticamente.

Requisitos: Uma instalação funcional do ROOT (via conda-forge, pacote do sistema ou tarball binário). O ROOT não é instalável via pip neste momento.

Habilitar definindo enable_root: true no seu config.yaml:

features:
  enable_root: true

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

Use get_server_info para verificar a disponibilidade do ROOT em tempo de execução:

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

Documentação

O site completo de documentação é construído com Sphinx e cobre instalação, configuração, todas as 20 ferramentas MCP, padrões de integração com LLM e o guia do desenvolvedor com referência de API gerada automaticamente.

Leia online: A documentação está hospedada em documentação do root-mcp

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

Para recarregamento automático ao escrever documentação:

cd docs && make livehtml

Destaques:

Guia do Usuário — instalação, início rápido, modos, configuração, integração com LLM
Referência de Ferramentas — catálogo completo de todas as ferramentas e seus payloads JSON
Referência CLI — referência completa de comandos para root-cli com exemplos
Guia do Desenvolvedor — arquitetura, visão geral dos módulos, configuração de desenvolvimento, contribuição
Referência de API — gerada automaticamente a partir dos docstrings do código-fonte

Citação

Se você usar o ROOT-MCP em sua pesquisa, por favor cite:

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

Licença

Licença MIT — consulte LICENSE para detalhes.

root-mcp

Documentação

Servidor CERN ROOT MCP

Duas Interfaces: Servidor MCP e CLI

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

2. CLI ROOT (root-cli)

Início Rápido

1. Instalação

2. Configuração

CLI ROOT (Recomendado para Interação com LLM)

Uso Básico

Exemplo de Fluxo de Trabalho com LLM

Documentação

Servidor MCP

Comandos de uma linha com configuração zero:

Executar com Claude Desktop

Arquitetura

Suporte Opcional a ROOT Nativo

Documentação

Citação

Licença

2. CLI ROOT (`root-cli`)