使用说明

ami-mcp v0.3.1

An MCP server that wraps ATLAS AMI (ATLAS Metadata Interface) and the PMG cross-section database, exposing them as tools for LLMs. Designed for ATLAS physicists who need to discover MC samples, look up cross-sections and filter efficiencies, and validate PMG hashtag classifications.

What it does

ami-mcp lets Claude (or any MCP-compatible LLM) query ATLAS metadata directly:

Discover samples: search for MC datasets by PMG hashtag classification (WeakBoson/Vjets/Baseline), by name pattern, or by arbitrary AMI query
Look up metadata: retrieve cross-sections, filter efficiencies, k-factors, dataset provenance, and AMI processing tag info
Query cross-section DB: look up DSID entries in the PMG xsec database files (PMGxsecDB_mc16.txt, etc.)
Validate samples: check hashtag classifications and compare metadata against the PMG cross-section database
General queries: execute arbitrary AMI command strings formulated by the LLM using the ami://query-language resource as a guide

Installation

pip install ami-mcp

Or with pixi (recommended for ATLAS facilities):

pixi add ami-mcp

Requirements

Python 3.10 or 3.11 (pyAMI requires <3.12)
A valid VOMS proxy (voms-proxy-init -voms atlas)
Grid CA certificates (available on CVMFS at ATLAS sites)

Quick start

1. Set up authentication

voms-proxy-init -voms atlas

When installed via pip (not pixi/conda-forge), also set X509_CERT_DIR. On CVMFS-based facilities (e.g. UChicago Analysis Facility, CERN lxplus):

export X509_CERT_DIR=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates

When installed via pixi or conda-forge, ca-policy-lcg is included and sets X509_CERT_DIR automatically — no extra step needed.

2. Test the server

ami-mcp serve

The server speaks MCP over stdio. Configure your MCP client to launch it.

3. Configure Claude Code

With pixi (recommended — X509_CERT_DIR is set automatically):

{
  "mcpServers": {
    "ami": {
      "type": "stdio",
      "command": "pixi",
      "args": ["run", "ami-mcp", "serve"],
      "env": {
        "ATLAS_PMGXSEC_PATH": "/cvmfs/atlas.cern.ch/repo/sw/database/GroupData/dev/PMGTools"
      }
    }
  }
}

With pip (must set X509_CERT_DIR manually):

{
  "mcpServers": {
    "ami": {
      "command": "ami-mcp",
      "args": ["serve"],
      "env": {
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "ATLAS_PMGXSEC_PATH": "/cvmfs/atlas.cern.ch/repo/sw/database/GroupData/dev/PMGTools"
      }
    }
  }
}

4. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "ami": {
      "command": "ami-mcp",
      "args": ["serve"],
      "env": {
        "X509_CERT_DIR": "/path/to/ca-certificates",
        "ATLAS_PMGXSEC_PATH": "/path/to/PMGTools"
      }
    }
  }
}

Deploying on Kubernetes

A Helm chart at charts/ami-mcp deploys the server over HTTP transport in either shared-secret (server-managed VOMS proxy + static bearer) or AF-credential-broker (per-user proxies) mode. See Deploying with Helm for the full guide. For running the server directly on a facility (e.g. the UChicago Analysis Facility), see the contributor guide (CLAUDE.md).

Available tools

All tools are read-only (read_only_hint=true in their MCP tool annotations) and query the external ATLAS AMI service or a local cross-section database (open_world_hint=true); there is no tool that mutates AMI or facility state.

AMI queries

Tool	Description	Read/write
`ami_execute`	Execute any AMI command string (primary power tool)	read-only
`ami_get_dataset_info`	Get metadata for a dataset (nFiles, totalEvents, status, etc.)	read-only
`ami_get_datasets_info`	Batch metadata lookup for multiple datasets (one AMI query per catalog)	read-only
`ami_get_dataset_prov`	Get provenance chain with lineage summary; filter by data type	read-only
`ami_list_datasets`	Search for datasets by name pattern (supports `%` wildcards)	read-only

PMG hashtags

Tool	Description	Read/write
`ami_search_by_hashtags`	Find datasets by hashtag combination (e.g. WeakBoson/Vjets/Baseline)	read-only
`ami_get_dataset_hashtags`	Look up PMGL1–PMGL4 classification for a dataset	read-only

Physics metadata

Tool	Description	Read/write
`ami_get_physics_params`	Get cross-section (nb→pb converted), filter efficiency, k-factor from AMI	read-only
`ami_get_ami_tag`	Get AMI processing tag info; accepts tag chains like `e8351_s3681_r13144`	read-only

Cross-section database

Tool	Description	Read/write
`ami_list_xsec_databases`	List available PMGxsecDB_*.txt files	read-only
`ami_lookup_xsec`	Look up DSID cross-section, filter eff, k-factor in xsec DB	read-only

Validation

Tool	Description	Read/write
`ami_validate_sample`	Check hashtag classification and compare metadata to xsec DB	read-only

Example prompts

Once configured, you can ask Claude things like:

"Find all Baseline WeakBoson/Vjets samples in mc21_13TeV"
"What are the cross-section and filter efficiency for DSID 700320?"
"Look up the hashtag classification for this EVNT dataset"
"Validate these samples against the mc21 cross-section database"
"Show me the provenance chain for this DAOD dataset"
"What AMI tag e8351 corresponds to — which generator version?"