hydroemu-mcp-server

HACC 우주론적 유체 역학 시뮬레이션 에뮬레이터(사전 훈련된 SEPIA 가우시안 프로세스 모델)를 모든 LLM 에이전트를 위한 도구로 노출하는 MCP 서버입니다.

이 저장소가 가르치는 핵심 아이디어

과학 코드는 일반적인 Python으로 유지됩니다. MCP 래퍼는 단지 그것을 게시할 뿐입니다.

• tools/는 일반적인 과학 패키지입니다. MCP를 import하지 않습니다. 에뮬레이터 도구는 tools/hydro_tools.py에 있고, 핵심 SEPIA 래퍼는 tools/emulator.py에 있습니다.

• mcp_server/는 약 70줄짜리 범용 래퍼입니다. pyproject.toml에서 한 줄의 설정을 읽고, 과학 패키지를 import하며, __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개 우주론):

설계: 라틴 하이퍼큐브 설계(Latin hypercube design)를 기반으로 한 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)

사전 훈련된 모델

CosmoHydro/models/에서 훈련된 SEPIA pickle 파일을 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()은 여전히 작동합니다. pickle 파일이 필요한 것은 predict_observable과 predict_observable_redshift뿐입니다.

서버 실행

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와 동일한 아키텍처를 따릅니다:

에뮬레이터 플롯

CosmoHydro 훈련 노트북의 24개 검증, 민감도, 비교 플롯은 전체 갤러리를 참조하세요. 주요 내용:

아키텍처 (상세)

• mcp_server/는 범용 드롭인 MCP 래퍼입니다 (저장소 간 복사 가능)

• tools/는 도메인별 과학 함수를 포함합니다

• pyproject.toml의 [tool.mcp-server] 설정이 둘을 연결합니다

• 모든 SEPIA import는 지연(lazy) 방식입니다 (모듈 범위가 아닌 함수 내부에서)

• 모델은 첫 사용 시 로드되어 이후 호출에서는 캐시됩니다