hydroemu-mcp-server

Un servidor MCP que expone emuladores de simulaciones hidrodinámicas cosmológicas HACC — modelos preentrenados de procesos gaussianos SEPIA — como herramientas para cualquier agente LLM.

La única idea que enseña este repositorio

El código científico permanece en Python habitual. El envoltorio MCP solo lo publica.

• tools/ es un paquete científico ordinario. Nunca importa MCP. Las herramientas del emulador viven en tools/hydro_tools.py; el envoltorio central de SEPIA está en tools/emulator.py.

• mcp_server/ es un envoltorio genérico de ~70 líneas. Lee una línea de configuración de pyproject.toml, importa el paquete científico y registra cada función listada en su __all__ como una herramienta MCP.

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

Tus anotaciones de tipo, restricciones de Field de Pydantic y docstrings se convierten en el esquema de herramientas que ven los agentes. Para construir tu propio servidor: coloca tus módulos en tools/ (o apunta esa línea de configuración a tu propio paquete), lista las funciones públicas en __all__, listo.

Related MCP server: MCP Refana Server

Estructura

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

Parámetros

7 parámetros en total (5 de subred + 2 de cosmología):

Diseño: 110 simulaciones (cajas de 400 Mpc/h) a partir de un diseño de hipercubo latino.

Observables

Herramientas

Dos convenciones que vale la pena copiar en cualquier servidor MCP científico:

1. Cada herramienta devuelve {status, files, message, metadata} (ArtifactResult).

2. Los arreglos se mueven entre herramientas como rutas de archivo, nunca a través de la ventana de contexto del agente.

Instalación

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

Modelos preentrenados

Copia los pickles de SEPIA entrenados desde CosmoHydro/models/ al directorio models/:

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

Sin modelos, list_observables(), describe_parameters() y plot_observable_comparison() siguen funcionando; solo predict_observable y predict_observable_redshift requieren los pickles.

Ejecutar el servidor

HTTP transmisible — el servidor es un proceso visible con una URL:

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

Los clientes se conectan a http://127.0.0.1:8000/mcp. Detén el servidor con Ctrl+C (Ctrl+Z solo lo suspende, dejando el puerto ocupado — si eso ocurre, simplemente inicia el servidor de nuevo: detecta un mcp_server residual que mantiene el puerto y lo limpia automáticamente).

Para usar este servidor desde Claude Code, la aplicación de escritorio de Claude, Codex, Cursor o cualquier otro cliente MCP — consulta docs/mcp-clients.md; un .mcp.json incluido ya lo conecta a Claude Code.

Arquitectura

Este servidor sigue la misma arquitectura que spectra-mcp-server:

Gráficos del emulador

Consulta la galería completa para ver 24 gráficos de validación, sensibilidad y comparación de los cuadernos de entrenamiento de CosmoHydro. Destacados:

Arquitectura (detallada)

• mcp_server/ es un envoltorio MCP genérico y reutilizable (copia entre repositorios)

• tools/ contiene las funciones científicas específicas del dominio

• La configuración [tool.mcp-server] en pyproject.toml los conecta

• Todas las importaciones de SEPIA son perezosas (dentro de funciones, no en el ámbito del módulo)

• Los modelos se cargan en el primer uso y se almacenan en caché para llamadas posteriores