spectra-mcp-server

Part 1 of the client-server agent tutorial. An MCP server that exposes cosmology tools — CLASS matter power spectra compared against eBOSS DR14 Lyman-α forest data — to any LLM agent.

Part 2, the multi-agent client that drives this server, lives in multiagent-client-demo. Setup instructions for both repos are in that repo's prep.md.

The one idea this repo teaches

The science code stays normal Python. The MCP wrapper only publishes it.

• tools/ is an ordinary science package: parameter dictionaries, a CLASS call, matplotlib. It never imports MCP. The power-spectrum example lives in tools/spectra_tools.py; your own science goes in sibling modules.
• mcp_server/ is a ~70-line generic wrapper. It reads one line of config from pyproject.toml, imports the science package, and registers every function listed in its __all__ as an MCP tool.

[tool.mcp-server]
tool_modules = ["tools"]

Your type hints, Pydantic Field constraints, and docstrings become the tool schema agents see. To build your own server: drop your modules into tools/ (or point that one config line at your own package), list the public functions in __all__, done.

Layout

data/DR14_pm3d_19kbins.txt        eBOSS DR14 Ly-α P(k): 19 bins of (k, P, σ)
tools/
  cosmology.py                    CLASS parameter sets (Planck 2018) + run_class()
  spectra_tools.py                the 4 tool functions + ArtifactResult contract
  __init__.py                     __all__ — ONLY these names become tools
mcp_server/                       generic drop-in wrapper (FastMCP)
notebooks/01_manual_pipeline.ipynb  the walkthrough: science → tools → server
tests/test_tools.py               tools tested as plain Python, no MCP needed

About the data file

DR14_pm3d_19kbins.txt is taken verbatim from marius311/mpk_compilation (Chabanier, Millea & Palanque-Delabrouille 2019, arXiv:1905.08103): the z = 0 linear matter power spectrum inferred from the eBOSS DR14 Ly-α forest. Mind the file's mixed units — k is in 1/Mpc while P(k), σ are in (Mpc/h)³ (the source notebook plots errorbar(k/h, Pk)). tools/spectra_tools.py does the k/h conversion once, on load; read the file any other way and the data appears offset from theory by a factor ~2.

Tools

tool	what it does
get_eboss_data()	return the 19 observed (k, P(k), σ) bins
list_cosmology_models()	valid model names (lcdm, nu_mass, wcdm) + tunables
compute_power_spectrum(model, output_dir, ...)	run CLASS, write pk_<model>.csv
plot_power_spectra(spectrum_files, output_dir, ...)	two-panel figure: P(k) + data, ratio panel

Two conventions worth copying into any science MCP server:

1. Every tool returns {status, files, message, metadata} (ArtifactResult).
2. Arrays move between tools as file paths, never through the agent's context window.

Install

conda create -n spectra-tutorial python=3.12 -y
conda activate spectra-tutorial
pip install -e ".[dev]"       # classy compiles from source; see prep.md if it fails
pytest                        # 7 tests, no server or API key needed

Run the server

Streamable HTTP — the server is a visible process with a URL:

python -m mcp_server --transport streamable-http --port 8000
# clients connect to http://127.0.0.1:8000/mcp

stdio — do not start it yourself; the client spawns it as a subprocess:

{"spectra": {"transport": "stdio", "command": "python",
             "args": ["-m", "mcp_server"], "cwd": "<this repo>"}}

Spelling tripwire: this CLI says streamable-http (hyphen); most Python client configs say streamable_http (underscore).

Start with the notebook

notebooks/01_manual_pipeline.ipynb builds everything up in order: the data, the science by hand, the same science as tools, then the server. Committed outputs let you read it without running anything.