Summary and Setup

In most analyses the bottleneck is not the physics but the software around it: finding data, decoding a data model, getting branch names and units right, iterating on fitting and plotting code. This lesson shows how to hand that overhead to an AI assistant without giving up rigor: every step produces a number you can check, and the whole procedure is reproducible.

The worked example is a real measurement from the ePIC experiment: reconstructing the weak decay Λ⁰ → p π⁻ and extracting its yield from the proton–pion invariant-mass spectrum.

The lesson develops three ideas and applies them end to end:

  • an agentic assistant — a language model placed in a loop where it can read files, run code, and react to the results, rather than only returning text;
  • the Model Context Protocol (MCP) — an open standard for exposing analysis tools to any assistant, so the workflow is portable; and
  • persistent instructions (AGENTS.md and SKILL.md) — versioned context and procedures that make a run repeatable and auditable.

The lesson uses opencode, but the parts you build (MCP tool servers, a skill) work with any assistant.

Callout

What you will produce

A workflow in which an assistant opens a real ePIC reconstruction file, queries its schema through a verifiable tool interface, builds the Λ⁰ invariant-mass spectrum, and fits it — driven by natural-language requests, with results and provenance you can independently check.

Prerequisite

Prerequisites

  • Comfort at the command line (running commands, editing files).
  • Working knowledge of Python or ROOT is useful; the assistant writes most of the code.
  • Introductory particle-physics concepts (four-momentum, invariant mass, histograms, fitting).
  • No prior experience with AI tooling is assumed, and the core episodes need no paid account or GPU.

See the Setup page for installation.

This lesson originated at an ePIC workshop on generative AI for physics. It complements the other EIC tutorials, which cover locating and reading the data.

The tool servers run inside eic-shell; your assistant runs where you normally work. Install an AI assistant (this tutorial will use opencode), get eic-mcp, and one command starts the tool servers. Nothing else — no grid certificate, no data download — the MCP servers reuse eic-shell’s own uproot, xrdfs, and rucio (already logged in to the shared read-only eicread account).

Checklist

Quick checklist

1. eic-shell

Make sure ./eic-shell drops you into the container. (See environment setup guide.)

2. Choose an AI assistant

gold ring engraved with the words EIC

One assistant to rule them all? Any agentic assistant — one that can read/write your files and run commands, not just emit text — works, and MCP works with any. This tutorial is based on opencode.

Tool Interface Free access
opencode terminal open source (MIT); free hosted models (no key), bring your own key, or a local model
GitHub Copilot VS Code, CLI free tier; free Pro for verified students/educators/OSS maintainers
Gemini CLI terminal open source; generous free tier with a personal Google account
Codex terminal, IDE included with ChatGPT plans
Claude Code terminal, IDE included with Claude plans
Cursor dedicated editor free tier
Cline / Continue VS Code extensions open source; bring your own key

3. Install one

This lesson uses opencode:

BASH 

curl -fsSL https://opencode.ai/install | bash

The free hosted models work out of the box without any login. Run it on your own machine, not inside eic-shell.

If you prefer an editor — try VS Code plus the GitHub Copilot and Copilot Chat extensions (sign in with GitHub — students/educators get Pro free — and use Agent mode), or Cursor.

Callout

Not allowed to install anything?

eic-shell already has two assistants: Claude Code (claude) and the GitHub Copilot CLI (copilot). Run one inside the container, alongside the servers (step 4):

BASH 

eic-mcp config claude    # writes .mcp.json here  (copilot: eic-mcp config copilot)
claude                   # or: copilot

One browser login the first time; it prints a code to paste, so it works over SSH.

Callout

Check it works

Open an empty folder in your assistant and ask: “Create hello.py that prints the PDG Λ⁰ baryon mass in GeV, then run it.” It should write the file and run it, printing 1.115683. If it only shows code, switch on agent/edit mode — executing, not suggesting, is what is needed.

4. Start the MCP servers — eic-mcp up

This step is temporary: eic-mcp and the servers are becoming part of eic-shell itself. Once the image ships them there are no extra steps — no clone, no PATH line — and the commands stay exactly the same. Until then, clone the launcher — and this lesson’s repository, whose example files Episodes 4–5 use — into your home directory (or workdir):

BASH 

git clone https://github.com/eic/eic-mcp ~/eic-mcp
git clone https://github.com/eic/tutorial-mcp ~/tutorial-mcp
echo 'export PATH="$HOME/eic-mcp/bin:$HOME/.opencode/bin:$PATH"' >> ~/.bashrc && . ~/.bashrc

It runs the three servers (uproot, xrootd, rucio) inside eic-shell:

BASH 

cd ~/eic && eic-mcp up    # first run from your eic-shell folder — it remembers the image
Callout

macOS: two extra steps

On a Mac, eic-shell is Docker: it publishes no ports and does not share your home. Clone the launcher next to ./eic-shell instead, and publish the server ports once:

BASH 

cd ~/eic                                    # the folder with ./eic-shell (yours may differ)
git clone https://github.com/eic/eic-mcp
grep -q 9101 eic-shell || sed -i '' "s|^docker run |docker run -p 127.0.0.1:9101-9104:9101-9104 -v $PWD/eic-mcp/bin/eic-mcp:/usr/local/bin/eic-mcp:ro |" eic-shell
grep 'docker run' eic-shell                 # must now show the -p and -v flags
./eic-shell

That one edit publishes the ports and puts eic-mcp on the container’s PATH for good, so inside eic-shell there is nothing to export — just:

BASH 

eic-mcp up

Leave this window open: the container — and the servers inside it — only live while ./eic-shell runs. Your assistant stays on the Mac, in a second terminal; copy the ready-made config into the directory where you launch opencode:

BASH 

cp ~/tutorial-mcp/files/mcp-config/opencode.jsonc .

If your eic_xl image already ships the servers, they just start; otherwise the first run bootstraps them automatically (a one-time clone and build, a few minutes). Every later eic-mcp up starts in seconds. Episode 3 covers the per-session workflow — eic-mcp up / eic-mcp down, and eic-mcp config opencode to write your client config.

Callout

No credentials, no data download

The rucio server signs in automatically with the shared, read-only eicread account baked into eic-shell — the same one the rucio command line uses. You never enter a password and you never download a dataset: the assistant reads ROOT files in place over root://.