Hydroemu

An MCP server that exposes HACC cosmological hydrodynamic simulation emulators as tools for any LLM agent.

Powered by the cosmohydro_emu package — pre-trained SEPIA Gaussian Process models for 14 summary statistics from the CRK-HACC CosmoHydro simulation suite.

The one idea this repo teaches

The science code stays in usual Python. The MCP wrapper only publishes it.

• tools/ is an ordinary science package. It never imports MCP. The emulator tools live in tools/hydro_tools.py; the emulator backend is provided by the cosmohydro_emu package (lazily imported inside each tool function).
• 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

tools/
  hydro_tools.py                 The 5 MCP tool functions + ArtifactResult contract
  __init__.py                    __all__ — ONLY these names become tools
mcp_server/                      Generic drop-in wrapper (FastMCP)
tests/test_tools.py              Tools tested as plain Python, no MCP needed
docs/mcp-clients.md              Multi-client setup guide

Parameters

Most statistics use 7 parameters (5 subgrid + 2 cosmology). Gravity-only statistics (Pk_GO) use only the 2 cosmology parameters.

Parameter	Symbol	Range	Units
AGN wind coupling	κ_w	[2.0, 4.0]	—
AGN energy efficiency	e_w	[0.2, 1.0]	—
BH seed mass	M_seed	[0.6, 2.0]	10⁶ M☉
Kinetic feedback velocity	v_kin	[0.1, 1.2]	10⁴ km/s
Kinetic feedback efficiency	ε_kin	[0.02, 1.2]	10¹
Matter density	ω_m	[0.12, 0.155]	—
Fluctuation amplitude	σ₈	[0.7, 0.9]	—

Design: 110 simulations (400 Mpc/h boxes) from a Latin hypercube design.

Observables

Observable	Description	Category	Params	z range
GSMF	Galaxy Stellar Mass Function	summary	7	0–2
HMF	Halo Mass Function	summary	7	0–2
fGas	Cluster Gas Fraction	summary	7	0–1.0
Pk-ratio	Matter Power Spectrum Suppression	summary	7	0–2
CSFR	Cosmic Star Formation Rate	summary	7	single
CGD	Cluster Gas Density Profile	profile	7	0–0.5
CGED	Cluster Gas Electron Density Profile	profile	7	0–0.5
CPP	Cluster Gas Pressure Profile	profile	7	0–0.5
CTP	Cluster Gas Temperature Profile	profile	7	0–0.5
CEP	Cluster Gas Entropy Profile	profile	7	0–0.5
CEEP	Cluster Electron Entropy Profile	profile	7	0–0.5
CMP	Cluster Gas Metallicity Profile	profile	7	0–0.5
CYP	Cluster Compton-y (tSZ) Profile	profile	7	0–0.5
Pk_GO	Gravity-Only Matter Power Spectrum	gravity_only	2	0–2

Tools

tool	what it does
list_observables()	list all 14 emulated observables with metadata
describe_parameters(stat_name?)	parameter space with ranges (7 or 2 depending on stat)
predict_observable(stat_name, params..., z)	predict any observable at any z, write CSV
plot_prediction(stat_name, params..., z)	single-panel plot with 2σ uncertainty band
plot_observable_comparison(files, stat_name)	two-panel figure: observable + ratio

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

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest                        # tests pass — fixture data for plots, real models for predictions

The cosmohydro_emu package (and its SEPIA GP backend) is installed automatically as a dependency. All trained models are shipped inside cosmohydro_emu — no manual model copying needed.

Related: cosmohydro_emu Python package

The standalone cosmohydro_emu package provides the same SEPIA emulators as a pip-installable Python library (with additional statistics: Pk suppression, CSFR, and gravity-only Pk). This MCP server wraps the same underlying models for agent access.

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. Stop the server with Ctrl+C (Ctrl+Z only suspends it, leaving the port taken — if that happens, just start the server again: it detects a leftover mcp_server holding the port and clears it automatically).

To use this server from Claude Code, the Claude desktop app, Codex, Cursor, or any other MCP client — see docs/mcp-clients.md; a checked-in .mcp.json already wires it into Claude Code.

Architecture

This server follows the same architecture as spectra-mcp-server:

• mcp_server/ is a generic drop-in MCP wrapper (copy between repos)
• tools/ contains the domain-specific science functions
• pyproject.toml [tool.mcp-server] config wires them together
• All cosmohydro_emu imports are lazy (inside functions, not at module scope)
• Emulators are loaded on first use per tool call

Emulator Package

The emulator backend is cosmohydro_emu, which ships:

• Pre-trained SEPIA GP models for all 14 statistics
• Training data arrays (parameter designs, x-grids, redshifts)
• Metadata registry (plot info, parameter ranges, output transforms)
• Redshift interpolation between trained snapshot models

See the cosmohydro_emu documentation for the full Python API.