hydroemu-mcp-server

一个MCP服务器，将HACC宇宙学流体动力学模拟仿真器——预训练的SEPIA高斯过程模型——作为工具暴露给任何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 约束和文档字符串成为代理看到的工具模式。要构建自己的服务器：将你的模块放入 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 Mpc/h盒子）。

可观测量

工具

值得复制到任何科学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)

预训练模型

将训练好的SEPIA pickle文件从 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文件。

运行服务器

可流式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 相同的架构：

仿真器图

参见 完整图库 获取来自CosmoHydro训练笔记本的24个验证、敏感性和对比图。亮点：

架构（详细）

• mcp_server/ 是一个通用即插即用的MCP包装器（可在仓库间复制）

• tools/ 包含领域特定的科学函数

• pyproject.toml 中的 [tool.mcp-server] 配置将它们连接起来

• 所有SEPIA导入都是惰性的（在函数内部，而非模块作用域）

• 模型在首次使用时加载，并在后续调用中缓存