hydroemu-mcp-server

Ein MCP-Server, der HACC-kosmologische hydrodynamische Simulations-Emulatoren – vortrainierte SEPIA-Gaußprozessmodelle – als Werkzeuge für jeden LLM-Agenten bereitstellt.

Die eine Idee, die dieses Repo vermittelt

Der Wissenschaftscode bleibt in gewöhnlichem Python. Der MCP-Wrapper veröffentlicht ihn nur.

• tools/ ist ein gewöhnliches Wissenschaftspaket. Es importiert nie MCP. Die Emulator-Werkzeuge befinden sich in tools/hydro_tools.py; der zentrale SEPIA-Wrapper ist in tools/emulator.py.

• mcp_server/ ist ein generischer Wrapper mit etwa 70 Zeilen. Er liest eine Konfigurationszeile aus pyproject.toml, importiert das Wissenschaftspaket und registriert jede Funktion, die in dessen __all__ aufgeführt ist, als MCP-Werkzeug.

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

Deine Typannotationen, Pydantic-Field-Einschränkungen und Docstrings werden zum Werkzeugschema, das Agenten sehen. Um deinen eigenen Server zu bauen: Lege deine Module in tools/ ab (oder richte diese eine Konfigurationszeile auf dein eigenes Paket), liste die öffentlichen Funktionen in __all__ auf, fertig.

Related MCP server: MCP Refana Server

Aufbau

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

Parameter

Insgesamt 7 Parameter (5 Subgrid + 2 Kosmologie):

Design: 110 Simulationen (400 Mpc/h-Boxen) aus einem Latin-Hypercube-Design.

Observablen

Werkzeuge

Zwei Konventionen, die es wert sind, in jeden Wissenschafts-MCP-Server übernommen zu werden:

1. Jedes Werkzeug gibt {status, files, message, metadata} zurück (ArtifactResult).

2. Arrays werden zwischen Werkzeugen als Dateipfade übergeben, niemals durch den Kontextfenster des Agenten.

Installation

conda create -n hydroemu python=3.12 -y
conda activate hydroemu
pip install -e ".[dev]"
pytest                        # tests pass without SEPIA models (fixture data)

Vortrainierte Modelle

Kopiere die trainierten SEPIA-Pickles aus CosmoHydro/models/ in das Verzeichnis models/:

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

Ohne Modelle funktionieren list_observables(), describe_parameters() und plot_observable_comparison() weiterhin; nur predict_observable und predict_observable_redshift benötigen die Pickles.

Server ausführen

Streamable HTTP – der Server ist ein sichtbarer Prozess mit einer URL:

python -m mcp_server --transport streamable-http --port 8000

Clients verbinden sich mit http://127.0.0.1:8000/mcp. Stoppe den Server mit Ctrl+C (Ctrl+Z setzt ihn nur aus, sodass der Port belegt bleibt – falls das passiert, starte den Server einfach erneut: Er erkennt einen übrig gebliebenen mcp_server, der den Port hält, und räumt ihn automatisch auf).

Um diesen Server von Claude Code, der Claude-Desktop-App, Codex, Cursor oder einem anderen MCP-Client zu verwenden, siehe docs/mcp-clients.md; eine eingecheckte .mcp.json bindet ihn bereits in Claude Code ein.

Architektur

Dieser Server folgt derselben Architektur wie spectra-mcp-server:

Emulator-Diagramme

Siehe die vollständige Galerie für 24 Validierungs-, Sensitivitäts- und Vergleichsdiagramme aus den CosmoHydro-Trainingsnotebooks. Highlights:

Architektur (detailliert)

• mcp_server/ ist ein generischer Drop-in-MCP-Wrapper (zwischen Repos kopierbar)

• tools/ enthält die domänenspezifischen Wissenschaftsfunktionen

• pyproject.toml [tool.mcp-server]-Konfiguration verbindet sie

• Alle SEPIA-Importe sind lazy (innerhalb von Funktionen, nicht auf Modulebene)

• Modelle werden beim ersten Gebrauch geladen und für spätere Aufrufe zwischengespeichert