casino-mcp

Fortran 製 CASINO 量子モンテカルロコードに対する MCP コントロールプレーンです。実行の開始、実行中のジョブの把握、停止、そして out ファイルを 4000 行のテキストをモデルのコンテキストに送る代わりに構造化データとして読み取ります。

アルファ版 (0.1.0)。 4 つの制御ツールと out パーサーは完成しテスト済みです。モデルに物理量を返すツールはまだリリースされていません。インターフェースは今後変更される可能性があります。

これは何か、何でないか

CASINO にはすでにプリミティブがあります — opt_plan、runqmc --auto-continue、multirun、envmc、make_E_v_dt。しかし、それらの間の層、つまり機械可読な結果、実行履歴の記憶、そしてステップ間の判断（「分散はプラトーに達したか？」「このタイムステップはまだ線形領域か？」）を置く場所はありません。このパッケージがその層であり、次の 3 つのルールが誠実さを保ちます。

1. モデルが数値を生成することはありません。 ツールが返すすべての値はファイルから読み取られ、その出典行を保持します。CASINO が出力しなかったものは、推測ではなく理由付きで null として返されます。

2. すべての結果はその記録から再現可能です。 ジョブレコードは、コマンド、プロセス数、実行された casino バイナリのパス・サイズ・mtime を固定します。

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 を駆動します。runqmc はランタイムのままです。アーキテクチャ検出、MPI バリアント、バッチキューへの投入、ロックファイルは、私たちではなく runqmc の仕事です。

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 を含む場合は非ゼロで終了します。

設定

設定ファイルはありません。MCP サーバーは登録された場所で設定されます — 上記の .mcp.json の env ブロック — そして CASINO 自身の変数は名前を維持するため、一度設定すれば両方の層が設定されます:

その他すべて — 1 MPI プロセス、opt バイナリ、SIGTERM と SIGKILL の間の 20 秒、保持する 200 件のジョブレコード — は settings.py の定数です。casino-mcp config は、サーバーが現在使用する値と、どの変数がそれを指定したかを出力します。ツール呼び出しが拒否された場合は、最初にこれを実行してください。

CASINO_MCP_FORBID は、呼び出しごとのオーバーライドがない唯一のガードです。overwrite=true と unlock=true は他の 2 つを解除します。ここにリストされたディレクトリでは実行自体ができません。そのため、コミット済みの参照計算のツリーに適した場所です。

仕組み

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 ファイルは 1 つの結果ではなく フェーズのシーケンス です — 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 が行うのとまったく同じように 1 つのブロックから取得され、derived とラベル付けされます。実行時に envmc や endmc にシェルアウトすることはありません — endmc は非 C ロケールで数値を誤って解析します。

テスト

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

ユニットスイートはどこでも実行できます。パーサーは tests/data/ にコミットされた 5 つの実際の out ファイルに対してチェックされ、ランチャー、プロセスグループ、ガードレールは偽の runqmc シェルスクリプトに対してテストされます。

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

統合スイートには実際の CASINO が必要です。parse_out を CASINO 自身の envmc と、examples ツリー全体（526 ファイル、約 50 秒）に対してチェックし、実際の stdio MCP を介してサーバーを駆動し、実際の VMC 計算を実行・停止します。

tools/protocol_dump.py は SDK なしで JSON-RPC を手動で話し、双方向のすべての行を出力します。ツールを追加する前にこれを読んでください。

ライセンス

MIT。