hydroemu-mcp-server

MCP-сервер, который предоставляет эмуляторы космологических гидродинамических симуляций HACC — предобученные модели SEPIA Gaussian Process — как инструменты для любого LLM-агента.

Главная идея этого репозитория

Научный код остаётся на обычном Python. MCP-обёртка только публикует его.

• tools/ — обычный научный пакет. Он никогда не импортирует MCP. Инструменты эмулятора находятся в tools/hydro_tools.py; основная обёртка SEPIA — в tools/emulator.py.

• mcp_server/ — универсальная обёртка примерно на 70 строк. Она читает одну строку конфигурации из pyproject.toml, импортирует научный пакет и регистрирует каждую функцию из его __all__ как MCP-инструмент.

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

Ваши аннотации типов, ограничения Pydantic Field и docstring'и становятся схемой инструментов, которую видят агенты. Чтобы собрать собственный сервер: поместите свои модули в tools/ (или укажите эту одну строку конфигурации на свой пакет), перечислите публичные функции в __all__ — готово.

Related MCP server: MCP Refana Server

Структура

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

Параметры

Всего 7 параметров (5 подрешёточных + 2 космологических):

Дизайн: 110 симуляций (боксы 400 Мпк/ч) из латинского гиперкуба.

Наблюдаемые величины

Инструменты

Две конвенции, которые стоит перенять в любой научный MCP-сервер:

1. Каждый инструмент возвращает {status, files, message, metadata} (ArtifactResult).

2. Массивы передаются между инструментами как пути к файлам, никогда через контекстное окно агента.

Установка

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

Предобученные модели

Скопируйте обученные pickle-файлы SEPIA из CosmoHydro/models/ в каталог models/:

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

Без моделей list_observables(), describe_parameters() и plot_observable_comparison() всё равно работают; только predict_observable и predict_observable_redshift требуют pickle-файлы.

Запуск сервера

Streamable HTTP — сервер является видимым процессом с URL:

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

Клиенты подключаются к http://127.0.0.1:8000/mcp. Остановите сервер с помощью Ctrl+C (Ctrl+Z только приостанавливает его, оставляя порт занятым — если это произошло, просто запустите сервер снова: он обнаружит оставшийся mcp_server, удерживающий порт, и автоматически очистит его).

Чтобы использовать этот сервер из Claude Code, десктопного приложения Claude, Codex, Cursor или любого другого MCP-клиента — см. docs/mcp-clients.md; проверенный .mcp.json уже подключает его к Claude Code.

Архитектура

Этот сервер следует той же архитектуре, что и spectra-mcp-server:

Графики эмулятора

См. полную галерею с 24 графиками валидации, чувствительности и сравнения из обучающих ноутбуков CosmoHydro. Основные:

Архитектура (подробно)

• mcp_server/ — универсальная MCP-обёртка (копируется между репозиториями)

• tools/ — доменные научные функции

• pyproject.toml [tool.mcp-server] — конфигурация, связывающая их

• Все импорты SEPIA — ленивые (внутри функций, не на уровне модуля)

• Модели загружаются при первом использовании и кэшируются для последующих вызовов