casino-mcp

Fortran CASINO 양자 몬테카를로 코드를 위한 MCP 제어 평면입니다. 실행을 시작하고, 무엇이 실행 중인지 알고, 중지하고, out 파일을 4000줄의 텍스트를 모델 컨텍스트에 넣는 대신 구조화된 데이터로 읽습니다.

알파(0.1.0). 네 가지 제어 도구와 out 파서는 완성되어 테스트되었습니다. 모델에 물리 결과를 반환하는 도구는 아직 배포되지 않았습니다. 인터페이스는 여전히 변경될 수 있습니다.

그것이 무엇이고, 무엇이 아닌지

CASINO에는 이미 기본 요소가 있습니다 — opt_plan, runqmc --auto-continue, multirun, envmc, make_E_v_dt. 그러나 그 사이의 계층, 즉 기계가 읽을 수 있는 결과, 실행된 것에 대한 기억, 그리고 단계 사이에 놓인 판단("분산이 평탄해졌는가?", "이 타임스텝이 여전히 선형 영역에 있는가?")을 위한 자리는 없습니다. 이 패키지가 바로 그 계층이며, 세 가지 규칙이 정직함을 유지합니다:

1. 모델이 생성하는 숫자는 없습니다. 도구가 반환하는 모든 값은 파일에서 읽히며 해당 줄을 함께 전달합니다. CASINO가 출력하지 않은 것은 추측이 아닌 이유와 함께 null로 반환됩니다.

2. 모든 결과는 기록에서 재현 가능합니다. 작업 기록은 명령, 프로세스 수, 그리고 실행된 casino 바이너리의 경로, 크기, 수정 시간을 고정합니다.

3. 파괴적인 것은 암시적으로 수행되지 않습니다. 실행은 이미 결과가 있는 디렉토리에서 시작을 거부하며, 해당 out이 커밋된 참조 데이터인 경우 더 강하게 거부합니다.

의도적으로 execute_shell(command) 도구는 없습니다. 모든 도구는 명명된 CASINO 작업이며 타입이 지정된 인수를 가집니다.

Related MCP server: fdmnes-mcp

설치

pip install casino-mcp          # needs Python 3.11+ and a working CASINO installation

체크아웃에서:

pip install -e '.[dev]'

이 패키지는 CASINO를 번들, 빌드 또는 대체하지 않습니다. runqmc를 구동하며, 이는 런타임으로 유지됩니다: 아키텍처 감지, MPI 변형, 배치 큐 제출 및 잠금 파일은 우리의 일이 아니라 그쪽의 일입니다.

Claude Code에 등록

.mcp.json, 프로젝트 범위:

{
  "mcpServers": {
    "casino": {
      "command": "casino-mcp",
      "args": ["serve"],
      "env": {
        "CASINO_HOME": "/home/you/bin/CASINO",
        "CASINO_ARCH": "linuxpc-gcc-parallel.openblas"
      }
    }
  }
}

도구

런타입(vmc, vmc_opt, vmc_dmc, …)은 workdir의 input 파일에서 가져옵니다. 런타입별 도구는 없습니다. 그렇게 하면 기능을 추가하지 않고 표면만 늘어나기 때문입니다.

명령줄

모델 없이 동일한 런타임 — 서버를 디버깅하는 방법이기도 합니다:

casino-mcp config                  # the resolved configuration, and the files it came from
casino-mcp run ./calc -p 4         # start a calculation
casino-mcp status 20260823-164511-qobn
casino-mcp stop   20260823-164511-qobn
casino-mcp jobs                    # the registry, newest first
casino-mcp parse ./calc            # the `out` file as JSON
casino-mcp serve                   # the MCP server on stdio

모든 하위 명령은 JSON을 출력하고 해당 JSON에 error가 포함되면 0이 아닌 종료 코드로 종료됩니다.

구성

구성 파일은 없습니다. MCP 서버는 등록된 곳에서 구성됩니다 — 위의 .mcp.json의 env 블록 — 그리고 CASINO 자체 변수는 이름을 유지하므로 한 번 설정하면 두 계층이 모두 구성됩니다:

그 외의 모든 것 — 하나의 MPI 프로세스, opt 바이너리, SIGTERM과 SIGKILL 사이의 20초, 유지되는 200개의 작업 기록 — 은 settings.py의 상수입니다. casino-mcp config는 서버가 현재 사용할 내용과 어떤 변수가 그렇게 말했는지 출력합니다. 도구 호출이 거부될 때 먼저 실행하세요.

CASINO_MCP_FORBID는 호출별 재정의가 없는 유일한 가드입니다. overwrite=true와 unlock=true는 다른 두 가드를 해제합니다. 여기에 나열된 디렉토리에서는 전혀 실행할 수 없으며, 이것이 커밋된 참조 계산 트리를 위한 올바른 위치가 되는 이유입니다.

작동 방식

Claude Code ──stdio──> server.py ──spawn──> launcher.py ──> runqmc ──> mpirun ──> casino
                          │                     │
                          │                     └─ writes status.json (exit code, end time)
                          └─ reads/writes jobs.json + one directory per job

상태는 계산 외부에 존재합니다, $XDG_STATE_HOME/casino-mcp/ 아래:

jobs.json                    index: job_id -> record
jobs/<job_id>/meta.json      what was launched, frozen at spawn
jobs/<job_id>/status.json    written by the launcher when the run ends
jobs/<job_id>/runqmc.log     runqmc's own output (not CASINO's `out`)

계산 디렉토리는 CASINO가 넣는 것만 받습니다.

런처 프로세스가 필요한 이유. runqmc는 mpirun -np N casino를 exec하는 bash 스크립트입니다. 해당 pid에 신호를 보내면 트리가 고아가 됩니다. 런처는 자체 세션에서 실행되므로 killpg가 모든 것에 도달하고, 종료 코드는 MCP 서버가 재시작되어도 유지되며, runqmc의 출력은 JSON-RPC 스트림 대신 로그로 이동합니다. 재활용된 pid는 살아있는 작업으로 통과할 수 없습니다: /proc/<pid> 시작 시간이 비교되며, 좀비는 실행 중으로 간주되지 않습니다.

out 파서

parse_out은 MCP도 의존성도 없는 일반 함수입니다. out 파일은 하나의 결과가 아니라 단계의 시퀀스입니다 — vmc_opt는 주기마다 VMC 및 OPTIMIZATION 단계를 쓰고, vmc_dmc는 VMC, DMC 평형화 및 DMC 통계 누적을 씁니다 — 따라서 phases를 반환하고, result는 에너지를 포함하는 마지막 단계를 가리킵니다.

from casino_mcp.parse_out import parse_out

parsed = parse_out('./calc')
parsed['result']['energy']  # {'value': -2.861829862553, 'error': 0.000659077167, 'line': 237}

그 안의 유일한 파생 숫자는 단일 블록 실행의 표본 분산 오차로, CASINO가 출력하지 않습니다. envmc가 하는 것과 정확히 동일하게 단일 블록에서 가져오며 derived로 표시됩니다. 런타임에 envmc나 endmc를 셸로 호출하지 않습니다 — endmc는 비 C 로케일에서 숫자를 잘못 파싱합니다.

테스트

pytest                      # 102 tests, ~2 s, no CASINO needed

단위 테스트 스위트는 어디서나 실행됩니다: 파서는 tests/data/에 커밋된 다섯 개의 실제 out 파일로 검사되며, 런처, 프로세스 그룹 및 가드레일은 가짜 runqmc 셸 스크립트로 테스트됩니다.

pytest -m integration --examples-dir ~/PycharmProjects/PyCasino/examples

통합 테스트 스위트는 실제 CASINO가 필요합니다. parse_out을 CASINO 자체 envmc와 전체 예제 트리(526개 파일, ~50초)에 대해 확인하고, 실제 stdio MCP를 통해 서버를 구동하여 실제 VMC 계산을 실행하고 중지합니다.

tools/protocol_dump.py는 SDK 없이 JSON-RPC를 직접 말하며 양방향의 모든 줄을 출력합니다. 도구를 추가하기 전에 읽으세요.

라이선스

MIT.