consigcody94/pythia-mcp

[!IMPORTANT] Lilith Attribution — All physics calculations are performed by Lilith-2, developed by Sabine Kraml and collaborators at LPSC Grenoble. Pythia is an MCP interface layer. Please star the original repo and cite the Lilith papers in any research output.

Overview

The 125 GeV Higgs boson, discovered at CERN in 2012, is the cornerstone of electroweak symmetry breaking. Precision measurements of its couplings to other particles provide one of the most powerful probes for physics beyond the Standard Model (BSM).

Pythia bridges this frontier physics with conversational AI. Instead of manually running Python scripts and parsing XML, you ask Claude:

"What constraints does LHC data place on a Type-II two-Higgs-doublet model with tan(beta) = 2?"

Under the hood, Pythia generates validated XML input, invokes Lilith's likelihood engine against the full ATLAS + CMS dataset, and returns structured results — all through the Model Context Protocol.

Getting Started

Prerequisites

Install

git clone https://github.com/consigcody94/pythia-mcp.git
cd pythia-mcp
npm install
npm run build
pip install numpy scipy

Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pythia": {
      "command": "node",
      "args": ["/path/to/pythia-mcp/dist/index.js"],
      "env": {
        "LILITH_DIR": "/path/to/pythia-mcp/lilith",
        "PYTHON_CMD": "python3"
      }
    }
  }
}

Verify

cd lilith
python run_lilith.py userinput/example_couplings.xml

You should see a -2log(likelihood) value printed to stdout.

Tools

Pythia exposes 28 tools organized into four categories.

Core Analysis

Data Management

Physics Models

CERN Open Data

Examples

Check SM Consistency

"Compute the Standard Model likelihood and tell me if the Higgs data is consistent with the SM."

Test Modified Couplings

"Calculate the likelihood for C_t = 0.9, C_V = 1.1"

{ "mode": "couplings", "Ct": 0.9, "CV": 1.1 }

Two-Higgs-Doublet Model

"Analyze a Type-II 2HDM with tan(beta) = 2 and sin(beta - alpha) = 0.99"

{ "type": "II", "tanBeta": 2, "sinBetaMinusAlpha": 0.99 }

Parameter Scan

"Scan the C_V–C_F plane from 0.8 to 1.2"

{
  "param1": { "name": "CV", "min": 0.8, "max": 1.2, "steps": 50 },
  "param2": { "name": "CF", "min": 0.8, "max": 1.2, "steps": 50 }
}

Physics Reference

Reduced Couplings (kappa-framework)

The kappa-framework parameterizes deviations from SM Higgs couplings as multiplicative modifiers:

Signal strength: μ = σ_obs / σ_SM. A value of μ = 1 is consistent with the Standard Model.

Supported Production & Decay Modes

Production: ggH, VBF, WH, ZH, ttH, tH, bbH

Decay: γγ, ZZ, WW, bb, ττ, μμ, cc, Zγ, gg, invisible

Architecture

pythia-mcp/
├── src/
│   ├── index.ts           # MCP server, request handlers, tool dispatch
│   ├── utils.ts           # Validation, XML generation, physics models
│   └── utils.test.ts      # Unit tests (71 tests via Vitest)
├── lilith/                # Bundled Lilith-2 library
│   ├── run_lilith.py      # CLI entry point
│   ├── lilith/            # Core Python package
│   │   ├── main.py        # Lilith class — likelihood engine
│   │   └── internal/      # Couplings, BRs, likelihood computation
│   ├── data/              # Experimental database (ATLAS, CMS, Tevatron)
│   └── userinput/         # Example XML input files
├── .github/workflows/     # CI: build (Node 18/20/22) + test
├── package.json
├── tsconfig.json
└── vitest.config.ts

Security

• Input validation — All coupling, mass, and branching-ratio parameters are range-checked before use.
• XML injection prevention — All user-supplied values are escaped before embedding in XML.
• Path traversal protection — Dataset paths are resolved and verified against a base directory.
• ReDoS prevention — User-supplied regex patterns are length-limited and checked for dangerous constructs.
• API safety — HTTP requests enforce 30s timeouts, redirect depth limits, and response caching with TTL.
• Subprocess limits — Python process output is capped at 1 MB to prevent memory exhaustion.

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run unit tests
npm run test:watch   # Run tests in watch mode
npm run dev          # Run with ts-node (development)

Environment Variables

Citations

If you use Pythia in research, you must cite the Lilith papers:

@article{Bernon:2015hsa,
    author  = "Bernon, J\'er\'emy and Dumont, B\'eranger",
    title   = "{Lilith: a tool for constraining new physics from Higgs measurements}",
    journal = "Eur. Phys. J. C",
    volume  = "75",
    pages   = "440",
    year    = "2015",
    doi     = "10.1140/epjc/s10052-015-3645-9",
    eprint  = "1502.04138",
    archivePrefix = "arXiv"
}

@article{Kraml:2019sis,
    author  = "Kraml, Sabine and others",
    title   = "{Lilith-2: improved constraints on new physics from Higgs measurements}",
    year    = "2019",
    eprint  = "1908.03952",
    archivePrefix = "arXiv"
}

Acknowledgments

References

License

— Pythia and the bundled Lilith library are both GPL-3.0 licensed.