# ami-mcp v0.2.4

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]

[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]

[![Coverage][coverage-badge]][coverage-link]

<!-- --8<-- [start:intro] -->

An MCP server that wraps [ATLAS AMI](https://ami.in2p3.fr) (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.

<!-- --8<-- [end:intro] -->

<!-- --8<-- [start:what-it-does] -->

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

<!-- --8<-- [end:what-it-does] -->

<!-- --8<-- [start:installation] -->

## Installation

```bash
pip install ami-mcp
```

Or with pixi (recommended for ATLAS facilities):

```bash
pixi add ami-mcp
```

<!-- --8<-- [end:installation] -->

<!-- --8<-- [start:requirements] -->

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

<!-- --8<-- [end:requirements] -->

<!-- --8<-- [start:quick-start] -->

## Quick start

### 1. Set up authentication

```bash
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):

```bash
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

```bash
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):

```json
{
  "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):

```json
{
  "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):

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

<!-- --8<-- [end:quick-start] -->

<!-- --8<-- [start:deployment] -->

## Deploying on Kubernetes

A Helm chart at [`charts/ami-mcp`](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](https://ami-mcp.readthedocs.io/en/latest/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`](CLAUDE.md#testing-on-the-uchicago-analysis-facility)).

<!-- --8<-- [end:deployment] -->

<!-- --8<-- [start:tools] -->

## Available tools

### AMI queries

| Tool                   | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `ami_execute`          | Execute any AMI command string (primary power tool)            |
| `ami_get_dataset_info` | Get metadata for a dataset (nFiles, nEvents, status, etc.)     |
| `ami_get_dataset_prov` | Get provenance chain with lineage summary; filter by data type |
| `ami_list_datasets`    | Search for datasets by name pattern (supports `%` wildcards)   |

### PMG hashtags

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

### Physics metadata

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

### Cross-section database

| Tool                      | Description                                                 |
| ------------------------- | ----------------------------------------------------------- |
| `ami_list_xsec_databases` | List available PMGxsecDB\_\*.txt files                      |
| `ami_lookup_xsec`         | Look up DSID cross-section, filter eff, k-factor in xsec DB |

### Validation

| Tool                  | Description                                                  |
| --------------------- | ------------------------------------------------------------ |
| `ami_validate_sample` | Check hashtag classification and compare metadata to xsec DB |

<!-- --8<-- [end:tools] -->

<!-- --8<-- [start:example-prompts] -->

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

<!-- --8<-- [end:example-prompts] -->

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/kratsg/ami-mcp/actions/workflows/ci.yml/badge.svg
[actions-link]:             https://github.com/kratsg/ami-mcp/actions
[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/kratsg/ami-mcp/discussions
[pypi-link]:                https://pypi.org/project/ami-mcp/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/ami-mcp
[pypi-version]:             https://img.shields.io/pypi/v/ami-mcp
[rtd-badge]:                https://readthedocs.org/projects/ami-mcp/badge/?version=latest
[rtd-link]:                 https://ami-mcp.readthedocs.io/en/latest/?badge=latest
[coverage-badge]:           https://codecov.io/github/kratsg/ami-mcp/branch/main/graph/badge.svg
[coverage-link]:            https://codecov.io/github/kratsg/ami-mcp

<!-- prettier-ignore-end -->