hydroemu-mcp-server

An MCP server that exposes HACC cosmological hydrodynamic simulation emulators — pre-trained SEPIA Gaussian Process models — as tools for any LLM agent.

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 core SEPIA wrapper is in tools/emulator.py.

• 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.

Related MCP server: copamind-mcp

Layout

models/                           Pre-trained SEPIA pickles (copy from CosmoHydro/models/)
tools/
  emulator.py                    Core SEPIA wrapper: lazy load, predict, redshift interpolation
  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

7 parameters total (5 subgrid + 2 cosmology):

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

Observables

Tools

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 hydroemu python=3.12 -y
conda activate hydroemu
pip install -e ".[dev]"
pytest                        # tests pass without SEPIA models (fixture data)

Pre-trained models

Copy the trained SEPIA pickles from CosmoHydro/models/ into the models/ directory:

cp -r /path/to/CosmoHydro/models/GSMF_multiz models/
cp -r /path/to/CosmoHydro/models/HMF_multiz models/
# ... etc for each observable

Without models, list_observables(), describe_parameters(), and plot_observable_comparison() still work; only predict_observable and predict_observable_redshift require the pickles.

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:

Emulator Plots

See the full gallery for 24 validation, sensitivity, and comparison plots from the CosmoHydro training notebooks. Highlights:

Architecture (detailed)

• 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 SEPIA imports are lazy (inside functions, not at module scope)

• Models are loaded on first use and cached for subsequent calls