Skip to main content
Glama

MCP Refana Server

Model Context Protocol (MCP) server for Mu2e refana analysis workflows. Exposes core analysis functions as MCP tools for integration with agentic frameworks.

Environment Setup

This project requires the Mu2e analysis environment. On Mu2e gpvm's, activate the environment first:

source /cvmfs/mu2e.opensciencegrid.org/env/ana/current/bin/activate

This provides:

  • pyutils - Python interface to EventNtuple

  • uproot - ROOT file handling

  • awkward - Ragged array support

  • numpy, scipy, scikit-learn, xgboost, matplotlib

Related MCP server: rucio-mcp

Features

  • Event Counting: Signal/background extraction in kinematic regions

  • Cut Analysis: Definition and application of analysis cuts

  • Sensitivity Computation: Discovery significance, CLs limits, Feldman-Cousins intervals

  • ML Selection: BDT-based signal/background discrimination setup

  • Analysis Summaries: Dataset-level analysis results

Installation

# Activate Mu2e analysis environment
source /cvmfs/mu2e.opensciencegrid.org/env/ana/current/bin/activate

# Install mcp-refana in development mode
cd mcp-refana
pip install -e .

Running the Server

Important: Always activate the Mu2e environment before running.

# Source Mu2e environment
source /cvmfs/mu2e.opensciencegrid.org/env/ana/current/bin/activate

# Start server with stdio transport (default)
mcp-refana-server --transport stdio

Or with HTTP transport:

source /cvmfs/mu2e.opensciencegrid.org/env/ana/current/bin/activate
mcp-refana-server --transport streamable-http

Available Tools

healthcheck()

Returns server status.

count_signal_background(mom_list, time_list, mc_list, mom_range, time_range, sign)

Extract signal and background event counts in a defined kinematic window.

Parameters:

  • mom_list: Reconstructed momentum values

  • time_list: Reconstructed time values

  • mc_list: MC truth labels

  • mom_range: [min, max] momentum window

  • time_range: [min, max] time window

  • sign: "minus" (electrons) or "plus" (positrons)

Returns: Signal/background counts and statistics

analyze_cuts(cut_definitions, sign)

Initialize analysis cut configuration.

compute_sensitivity(s_expected, b_expected, b_sys_uncertainty, exposure, efficiency)

Compute physics sensitivity metrics:

  • Asimov significance Z

  • 95% CLs upper limit

  • 90% Feldman-Cousins confidence interval

initialize_ml_selector()

Set up machine learning event selector.

get_cut_efficiency(cuts_applied, n_total, n_surviving)

Calculate efficiency metrics for applied cuts.

summarize_analysis(dataset_name, sign, n_events_processed, signal_count, background_count, ml_score_mean)

Generate analysis summary for a dataset.

Integration with HEP-Multiagent

Register this server in the multiagent's config.py:

"refana": {
    "command": ["mcp-refana-server", "--transport", "stdio"],
    "description": "Mu2e refana analysis server",
}

Then use in worker nodes for agentic analysis workflows.

Architecture

src/mcp_refana/
├── __init__.py
├── server.py              # FastMCP server setup
└── mcp_tools/
    ├── __init__.py
    └── refana_wrappers.py # Tool definitions wrapping refana code

The server wraps the core refana analysis classes (Count, Analyze, MLSelect, SensitivityAnalyzer) as MCP tools, making them accessible to agents via tool calls.

Dependencies

  • mcp: Model Context Protocol framework

  • refana: Core analysis code (count, analyze, ML selection, sensitivity)

  • numpy, scipy: Numerical computing

  • scikit-learn, xgboost: Machine learning

  • uproot, awkward: ROOT file handling

  • matplotlib: Visualization

Development

Run tests:

pytest tests/

Format code:

ruff check . --fix

Contact

Sophie Middleton, Huma Jafree

Available Tools

4 tools
create_dataset_filelistA

Create a filelist for analysis from a SAM dataset definition.

    This tool prepares a dataset for use with refana analysis tools.
    
    Args:
        defname: SAM definition name (e.g., 'ensembleMDS3c')
        location: File location ('disk', 'tape', 'scratch', 'nersc')
        max_files: Limit to first N files (useful for testing)
        output_path: Path to save filelist (if None, generates temp path)
        
    Returns:
        Dictionary with filelist path and dataset information
    

Inputs: defname (required), location, max_files, output_path. Returns: object

get_dataset_infoA

Get information about a specific SAM dataset definition.

    Args:
        defname: SAM definition name (e.g., 'ensembleMDS3c')
        location: File location ('disk', 'tape', 'scratch', 'nersc')
        
    Returns:
        Dictionary with dataset information: file count, size, availability
    

Inputs: defname (required), location. Returns: object

list_available_datasetsA

List available SAM dataset definitions for Mu2e analysis.

    Returns:
        Dictionary with available datasets and their descriptions
    

Inputs: no named parameters. Returns: object

summarize_analysisA

Generate a summary of analysis results for a dataset.

    Args:
        dataset_name: Name of the dataset analyzed
        sign: Particle sign
        n_events_processed: Total events processed
        signal_count: Reconstructed signal events
        background_count: Reconstructed background events
        ml_score_mean: Mean ML BDT score (if available)
        
    Returns:
        Dictionary with analysis summary
    

Inputs: dataset_name (required), sign, signal_count, ml_score_mean, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing datasets, retrieving dataset info, creating filelists, and summarizing analysis results. No overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case, making them predictable and easy to navigate.

    Tool Count5/5

    Four tools is appropriate for a specialized analysis server, covering key steps without being excessive or insufficient.

    Completeness4/5

    The set covers dataset discovery, preparation, and result summarization, but lacks a tool to trigger or configure an actual analysis run, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      An MCP server that connects LLMs to CERN GitLab to discover and analyze High Energy Physics code, documentation, and analysis examples. It provides 14 tools for repository browsing, dependency parsing, and CI/CD configuration analysis.
      15
      150 PyPI
      4
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that exposes Rucio distributed data management operations as tools for LLMs. Designed for ATLAS physicists working with grid data on analysis facilities, but usable with any Rucio instance.
      6
      Apache 2.0
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to discover available Mu2e analyses and run them on art files, returning parsed physics metrics and job results.
      -