希格斯物理分析 MCP 服务器

Constrain beyond-Standard-Model physics from LHC Higgs measurements, directly from Claude.

Pythia wraps the Lilith library as an MCP server,
giving AI assistants access to 24 particle physics analysis tools.

⚸   ☽   ✦   ☾   ⚸

_{the oracle speaks for the Higgs; the night-engine does the math}

The Oracle & the Night  •  Getting Started  •  Tools  •  Examples  •  Architecture  •  Citations

[!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.

Interactive 3D Collider Digital Twin & Engineering Blueprints

Physical Explainer: The Pythia LHC Higgs Calorimeter Bench

An interactive isometric precision instrument built with wheresryan22/anatomy embodying Higgs decay branching ratio calorimetry:

Launch Interactive Physical Explainer · (Local: docs/figures/pythia-collider.html)

Figure: The Pythia LHC Higgs Calorimeter Bench. An optical decay carriage stepping six Higgs decay channels beneath a quadrupole collision chamber, dual coupling verniers (CV, CF), and a signal strength dial. Feeler plunger measures branching fraction step height while dials register gauge boson and fermion reduced couplings.

Launch Interactive 3D WebGL Digital Twin (LHC Detector & Event Display) (Interactive Three.js digital twin featuring cutaway 4-layer particle detector, Golden Channel H -> ZZ -> 4μ event with reconstructed invariant mass m_4μ = 125.09 GeV, Diphoton H -> γγ, VBF forward jet tags, and 3D Lilith likelihood surface).*

Sheet 1: Higgs Boson Production & Decay Phenomenology Blueprint

Full vector Feynman diagrams for all 5 LHC production modes (ggF, VBF, WH, ZH, ttH), precision decay branching ratios, SMEFT dimension-6 operators, and electroweak coupling modifiers (κ-framework).

Figure 1: Standard ISO Drawing PYTHIA-HEP-DWG-001 (Rev 2.1). Vector SVG available at results/higgs_feynman_phenomenology_blueprint.svg.

Sheet 2: Lilith-2 Experimental Likelihood & BSM Constraints Blueprint

Signal strength likelihood contours (μ_ggF+ttH vs μ_VBF+VH) with 68% and 95% CL ellipses from ATLAS + CMS Run 2/3 datasets, Two-Higgs-Doublet Model (2HDM) alignment limit constraints, and profile likelihood evaluation architecture.

Figure 2: Standard ISO Drawing PYTHIA-BSM-DWG-002 (Rev 1.9). Vector SVG available at results/lilith_likelihood_constraints_blueprint.svg.

⚸  •  ☽  •  ✦  •  ☾  •  ⚸

⚸ The Oracle and the Night

Two names sit at the heart of this project, and both were chosen on purpose.

Pythia, here, is not the event generator but the Pythia herself: the priestess of the Oracle at Delphi. She breathed the vapors that rose from the cleft in the rock and gave answers to the questions mortals feared to ask. This server is her modern tripod. You put a question to the Higgs sector in plain language, and the oracle answers from the data.

Lilith ⚸ is the engine beneath the floor. Its authors named it Light Likelihood Fit for the Higgs, and also, knowingly, after the lady of the night from the older stories. Pythia keeps the double meaning. The ⚸ glyph is the Black Moon, Lilith's own sigil: the empty focus of the Moon's orbit, the point you find only by where everything else turns around it. Fitting, for a hunt after new physics in the places the Standard Model leaves dark.

The sigils are a lens for thinking, never evidence. Every number Pythia returns comes from ATLAS and CMS, not from omens. The Higgs, so far, is stubbornly Standard-Model-like, and saying so honestly is the whole point of a likelihood fit.

☾  •  ✦  •  ⚸  •  ✦  •  ☽

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 24 tools organized into five categories.

Core Analysis

Data Management

Data Ingestion

Turn external measurements into the Lilith <expmu> format the engine actually consumes.

[!NOTE] Live HEPData access. HEPData's /search/ and table-download endpoints sit behind a Cloudflare bot challenge, so they are not reliably reachable from automated/server requests. Pythia handles this gracefully: discovery falls back to INSPIRE-HEP, and the ingest pipeline accepts a downloaded table JSON (tableJson) so conversion works fully offline. Generated files are written to the user data directory (LILITH_USER_DATA_DIR), never into the bundled Lilith database.

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
│   ├── ingest.ts          # Data ingestion: HEPData -> Lilith <expmu>, parser, builder
│   ├── utils.test.ts      # Unit tests (116 tests via Vitest)
│   └── ingest.test.ts     # Ingestion tests (16 tests; round-trips all 87 real files)
├── 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. Redirects are only followed to an allowlist of physics-data hosts over HTTPS, so an open-redirect upstream cannot be used for SSRF.
• XXE prevention — XML submitted to validate_input is rejected if it declares a DOCTYPE or ENTITY, since the underlying parser resolves entities.
• 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"
}

⚸ Dedication

For Sabine Kraml (@sabinekraml) and the Lilith team, who built the engine that does all the physics here. A small dedication, in the old tongue:

Nescio num vere Lilith, Sabina, voces,
an iocus iste tuus, noctis an umbra redit.
Quidquid agis, faveo tibi plaudoque libenter;
si iuvet ulla manus, tu modo, diva, voca.

_{I do not know whether you are truly calling Lilith, Sabine, or whether this is your jest, or whether night's own shadow returns. Whatever you are doing, I favor it and applaud it gladly; if any hand may help, you, illustrious one, need only call. ⚸}

Acknowledgments

References

License

GNU General Public License v3.0 — Pythia and the bundled Lilith library are both GPL-3.0 licensed.

⚸   ☽   ✦   ☾   ⚸

"The Higgs boson is the key to understanding the origin of mass in the universe."
— Peter Higgs

_{The oracle answers only from the data. Built for open science and particle physics research.}