Skip to main content
Glama
casino-mcp

casino-mcp

casino-mcp

PyPI Python CI Licence

Fortran CASINO 量子モンテカルロ・コードに対する MCP コントロールプレーン: 実行を開始し、何が実行中かを把握し、停止し、out ファイルを構造化データとして読む。4000行のテキストをモデルのコンテキストに送り込む代わりに。

Beta (0.2.0). 4つのコントロールツールと out パーサーは完成し、実際の CASINO に対してテスト済みである。物理をモデルに返すツールはまだ公開されていない。インターフェースは 1.0 より前に変わる可能性がある。

これが何であるか、何でないか

CASINO にはすでにプリミティブがある——opt_plan、runqmc --auto-continue、multirun、envmc、make_E_v_dt。CASINO に居場所がないのは、それらの間のレイヤーである: マシン読み取リ可能な結果、何が実行されたかの記憶、そしてステップ間にある判断(「分散は頭打ちになったか?」「このタイムステップはまだ線形領域か?」)。そのレイヤーこそがこのパッケージであり、3つのルールがそれを正直に保つ:

  1. モデルによって生成される数値はない。 ツールが返すすべての値はファイルから読み取らレ、その出所の行を伴う。CASINO が出力しなかったものは、推測ではなく理由付きで null として返る。

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

  3. 破壊的な操作は暗黙には行われない。 実行は、すでに結果が存在するディレクトリでは開始を拒否し、その out が確定済みの参照データである場合はさらに強く拒否する。

意図的に execute_shell(command) ツールは存在しない。すべてのツールは、型付き引数を持つ名前付き CASINO 操作である。

Related MCP server: qe2mcp

インストール

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"
      }
    }
  }
}

ツール

ツール

戻り値

casino_run(workdir, nproc, version, restart, resume, unlock)

job_id、pid、workdir、command、バイナリスタンプ、restart が削除したもの

casino_status(job_id)

running / finished / failed / stopped / unknown、pid、実行時間、終了コード

casino_stop(job_id, timeout)

シグナルを送ったもの、最終ステータス、haltqmc が行ったこと

casino_list_jobs(limit)

既知のすべてのジョブ(新しい順)

ラんタイプ(vmc、vmc_opt、vmc_dmc、…)は workdir 内の input ファイルから決まる。ラんタイプごとのツールは存在しない。それは、能力を追加せずに表面積を増やすだけだからである。

計算の開始、停止、継続はすべて CASINO 自身のスクリプトを通じてのみ行われる: runqmc が開始し、haltqmc が終了と後始末を行い、runqmc --continue または haltqmc -u が書き換えた input に対する素の runqmc が継続する。ここでは設定ファイルを移動したリ、input を編集したり、途中までの計算が次に何をすべきかを判断したリすることは一切ない。

すでに out があるディレクトリ

runqmc は out、vmc.hist、dmc.hist を置き換えるのではなく追記する。そのため、1つのディレクトリで2回実行すると、2つの実行が貼り合わされたファイルが生成される。これはデフォルトで拒否され、回避方法は2つある——正反対なので、どちらか1つを渡す:

restart=true

以前の実行が残したものを削除してやり直す。out、out_part.N、.hist ファイル群、config.in/config.out、correlation.out.N、parameters.N.casl、saved_part_N/ を削除する。入力は残る: input、波動関数、擬ポテンシャル、correlation.data、parameters.casl。削除された名前はすべて応答の removed の下に返される。

resume=true

中断した実行を停止した場所から続行する。CASINO の2つの継続経路のどちらを取るかは out から読み取られ、ここでは選択されない——下記参照。

コマンドライン上ではこれらは --restart と --resume であり、後者には --continue も受け入れられる。runqmc がそう呼ぶからである。ツール引数はそのように綴ることはできない: continue は Python のキーワードである。

実行の停止と継続

casino_stop は、そのジョブの casino プロセスに対してのみ SIGTERM を送り、それ以外には送らない——これは haltqmc -k が送る信号と同じだが、haltqmc の方はアカウント全体に対する pkill -x casino であり、マシン上の他のすべてのジョブを落としてしまう。mpirun は各ランクを独自のプロセスグループに置く。そのため、ランクはセッション ID で見つかる: セッションはランチャーのものであり、ツリー全体がそれを共有する。runqmc 自体はエピローグを完了するために生かしておかれる。timeout 後もまだ実行中のジョブだけが、そのプロセスグループにシグナルを送られ、その後 kill される。

次にディレクトリは haltqmc -f -u に渡される。これが、停止した実行を継続可能にする部分である: config.out は config.in になり、ロックファイルとマーカーファイルはなくなり、input は残りの作業用に書き換えられる——newrun : F、完了したブロックを差し引く、ラんタイプを次のステージへ進める。応答は halt の下に、それが行ったことを載せる。その前の input はジョブディレクトリにコピーされ、halt.input_saved がその場所を示す。

その後に resume=true が取る継続経路は、out 内の最後の実行によって決まる:

CONTINUATION INFO:(out 内)

runqmc --continue。CASINO は max_cpu_time または max_real_time で自ら停止したときだけそのブロックを書く。runqmc がそれを適用し、完了したセグメントを saved_part_N/ にアーカイブする。

そのようなブロックがない場合

haltqmc が書き換えた input に対する素の runqmc。これが中断された実行の継続方法である——--continue は継続情報がないとエラー停止するだけである。

実行が自然に終了した場合

拒否される: 継続するものは何もない。

restart=true は、input が newrun : F と書かれているディレクトリでは拒否される。再開すると、CASINO がその後要求する config.in が削除されるからである。保存した input を先に戻せ。

コマンドライン

モデルを介さない同じラんタイム——これはサーバーをデバッグする方法でもある:

casino-mcp config                  # the resolved configuration, and the files it came from
casino-mcp run ./calc -p 4         # start a calculation
casino-mcp run ./calc --restart    # ... after deleting what an earlier run left there
casino-mcp run ./calc --continue   # ... or carrying that run on instead
casino-mcp status 20260823-164511-qobn
casino-mcp stop   20260823-164511-qobn   # stop the run, then hand the directory to haltqmc
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 自身の変数は名前を保持するので、一度設定すれば両方のレイヤーが設定される:

変数

CASINO_HOME

CASINO インストールのルート(デフォルトは ~/bin/CASINO)

CASINO_ARCH

ビルドタゲット。bin_qmc 配下のディレクトリ。ジョブが実行したバイナリをスタンプするために使う

CASINO_RUNQMC

runqmc への明示的なパス。それ以外は PATH、次に $CASINO_HOME/bin_qmc/runqmc

CASINO_HALTQMC

haltqmc への明示的なパス。それ以外は PATH、次に $CASINO_HOME/bin_qmc/haltqmc

CASINO_MCP_STATE_DIR

ジョブレジストリ。それ以外は $XDG_STATE_HOME/casino-mcp

CASINO_MCP_FORBID

実行が決して触れてはならないディレクトリ。PATH のように : 区切り

その他すべて——MPI プロセス1つ、opt バイナリ、停止したジョブが自ら終了するまでの20秒、haltqmc の後始末の1分、保持するジョブ記録200件——は settings.py 内の定数である。casino-mcp config は、サーバーが現在使おうとする設定と、どの変数がそう言ったのかを出力する。ツール呼び出しが拒否されたら、まずこれを実行する。

CASINO_MCP_FORBID は、呼び出しごとの上書き換えができない唯一のガードである。restart=true/resume=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`)
jobs/<job_id>/input.before_halt   the input as it was, kept when a stop rewrites it

計算ディレクトリには、CASINO がそこに置くものだけが常に置かれる。

なぜランチャープロセスなのか。 runqmc は mpirun -np N casino を exec する bash スクリプトである。その pid にシグナルを送るとツリーが孤児化する。ランチャーは自らのセッションで実行される。これがツリーを識別可能にする——killpg は runqmc と mpirun に届き、セッション ID は mpirun が独自のプロセスグループに置いたランクを見つける——その終了コードは 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                      # 158 tests, ~5 s, no CASINO needed

ユニットスイートはどこでも実行できる: パーサーは tests/data/ 下の5つの実在の out ファイルに対してフィールドごとに検証され、exampes/ 下の全18の計算に対しても検証される。一方、ランチャー、プロセスグループ、ガードレールは、偽の runqmc シェルスクリプトに対して試される。

pytest -m integration

統合スイートには実際のCASINOが必要ですが、このリポジトリの外部には何も必要ありません。examples/ 内のすべての out について parse_out をCASINO自身の envmc と照合し、インストール済みバイナリに対してツリー全体を再実行し、実際のstdio MCP経由でサーバーを駆動して、実際のVMC計算を開始および停止します。

examples/ には、CASINO を実行する際の設定をカバーするように選ばれた18個の計算が含まれています。すべての runtype、basis type、optimiser、wavefunction オプションが少なくとも1回は登場し、パーサーが静かに誤る2つのファイル(エネルギーを出力しなかった実行と、最適化サイクルの途中で中断された実行)も同様に含まれます。examples/README.md にそれぞれの目的が記載されています。

これらは短く、シードが設定されているため、ツリーはCASINO自体のチェックも兼ねます。新しいリリースで再実行すると、パーサーが読み取る行のうち名前が変更されたり削除されたりしたものは、黙って None になるのではなく、その名前が明示されます。アサートされるのはそれだけです。移動した数値は人間が判断するために報告されます。

python tools/refresh_examples.py --nproc 4     # run the tree, report, touch nothing
python tools/refresh_examples.py --nproc 4 --write   # adopt the new output

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

ライセンス

MIT.

Available Tools

6 tools
casino_list_jobsC

Every known job, newest first, with its current state.

Inputs: limit. Returns: object

casino_prepareA

Copy a calculation into a new directory and write the input for the next run in it.

This is how a calculation becomes the next one: optimise a wave function, then prepare a vmc_dmc directory beside it; halve the timestep into another; change the target weight into a third. A copy rather than an edit, because a number whose input was overwritten in place can no longer be reproduced, and because casino_run refuses a directory that already holds a run -- rightly.

What is copied is what a calculation is given and never what a run produced: input, the orbital file, correlation.data, parameters.casl, the pseudopotentials, and config.in (which a dmc-only or opt runtype reads as an input). Not out, not the .hist files, not config.out. A symlinked orbital file is copied by content, so the new directory stands on its own.

runtype: the runtype the new directory is for -- vmc, vmc_opt, opt, vmc_dmc, vmc_dmc_equil, dmc_dmc, dmc_equil, dmc_stats. Every keyword that runtype needs and the source input does not set is filled from a working default; every keyword the source does set is kept, so the electron count, the basis and any hand tuning survive. Leave it empty to keep the source's runtype and only apply overrides. overrides: keywords to set, as {name: value}, and they win over both the source and the defaults. A null value deletes the keyword; a value containing newlines is written as a %block (that is how opt_plan and npcell are set). Values are written verbatim, so booleans are 'T' and 'F' as CASINO spells them. jastrow: the terms of a blank Jastrow factor to write into the new directory -- ['u', 'chi', 'f'] for the usual one, ['u'] for a system with no atoms. This is for the first calculation of a chain, the one whose directory holds an orbital file and nothing else: use_jastrow : T needs a correlation.data, no CASINO utility writes one, and the manual's own instruction is to copy an example and delete its numbers by hand. Every coefficient starts at zero, which is what the first optimisation cycle is for. Leave it unset when the source already has a correlation.data; asking for both is refused, because a blank Jastrow would discard an optimised one. Finite systems only so far: a periodic Jastrow wants a P term, whose stars come from CASINO's own make_p_stars. backflow: the terms of a blank backflow function, in the same file -- ['eta', 'mu', 'phi'] for the usual one. It goes with backflow : T in the input, and the two blocks are written together for a calculation that wants both. The electron-nucleus cusp type of each set is not a setting: it is read off the pseudopotentials in the directory, 1 for a bare nucleus and 0 behind a pseudopotential, because CASINO believes the flag without checking it. No AE CUTOFFS section is written -- it is optional, and CASINO chooses the lengths itself. jastrow_settings: the shape of both blocks, where the defaults are not wanted. Jastrow: trunc_order (3), n_u (8), n_chi (8), n_f_en (3), n_f_ee (3), spin_dep_u (1), spin_dep_chi (0), spin_dep_f (1), cusp_chi (0), cutoff_u / cutoff_chi / cutoff_f (0, which CASINO reads as "use your own default"), no_dup_u (0), no_dup_chi (0), optimizable (1, the cutoffs). Backflow: bf_trunc_order (3), n_eta (9), n_mu (9), n_phi_en (3), n_phi_ee (3), spin_dep_eta (1), spin_dep_mu (0), spin_dep_phi (1), cutoff_eta / cutoff_mu / cutoff_phi (0), irrotational (0), cusp_bf (-1, meaning derive it from the pseudopotentials).

Nothing is written unless the result would actually run: the keyword combinations CASINO only rejects at run time are checked first (an optimisation sample smaller than the DMC target weight, opt_backflow without backflow, a missing mandatory keyword), and so is the presence of every file the input tells CASINO to read. A refusal names the problems and creates no directory. What is legal but probably unintended -- a dtdmc still at CASINO's placeholder default, dmc_stats_nstep not divisible by its block count, keywords left over from the runtype this was copied from -- comes back in warnings and does not stop it.

Inputs: dest (required), source (required), jastrow, runtype, +3 more. Returns: object

casino_resultsA

Physics out of a job's files: energies, error bars, variance, per-block numbers.

Reads out and returns it as phases, because a CASINO run is a sequence of them and not one result: vmc_opt writes a VMC and an optimization phase per cycle, vmc_dmc writes VMC, DMC equilibration and DMC statistics accumulation. result points at the number that is this run's answer, and every value carries the file and line it was read from. Nothing is computed here that CASINO did not print, and a value it did not print comes back as null with the reason.

A DMC run that has not ended is readable too, and this is the only way to read one: CASINO writes the mixed estimators into out at the very end, and until then the current estimate lives in dmc.status, which it rewrites after every statistics block and deletes when the run finishes. When that file is there it is parsed into dmc_status and result points at it, so a running job answers with the estimate as of its last block -- and never with the VMC energy of the configuration-generation phase, which is the trial wave function's and not the calculation's. A run stopped by casino_stop keeps its dmc.status, so the last estimate it reached survives the stop.

While the run is still equilibrating there is no DMC energy anywhere yet, and result then says so rather than answering with an earlier phase.

Inputs: job_id (required). Returns: object

casino_runA

Start a CASINO calculation in workdir and return immediately.

The runtype (vmc, vmc_opt, vmc_dmc, ...) comes from the input file in workdir; this tool only decides how the binary is launched. The calculation keeps running after the call returns and after this server is restarted.

A directory that already holds an out is refused, because runqmc appends to it and the result is two runs in one file. restart and resume are the two ways past that, and they are opposites -- pass one.

workdir: directory holding input and the wave function files. nproc: number of MPI processes (vmc_nstep in input is the total over all of them). version: binary flavour, 'opt' or 'debug'. restart: delete out and everything else the earlier run left -- .hist files, configs, optimisation output -- and start the calculation over. Inputs are kept. Destructive: config.in goes too, so what could have been continued no longer can be. Refused on a directory whose input haltqmc has set up to continue (NEWRUN : F), because CASINO then wants the config.in this would delete; casino_stop keeps a copy of the input as it was, and the reply to the stop says where. resume: carry the interrupted run on, keeping the work already done. Which of CASINO's two continuation routes that takes is read out of out, not chosen here: a run that CASINO stopped on max_cpu_time / max_real_time is continued by runqmc --continue, and a run that casino_stop halted is continued by a plain runqmc over the input that haltqmc -u rewrote. The reply says which one under resume. A run that reached its own end is refused -- there is nothing to continue. unlock: clear a stale .runqmc.lock left by a runqmc instance that died.

Inputs: workdir (required), nproc, resume, unlock, +2 more. Returns: object

casino_statusA

State of one job: running / finished / failed / stopped, pid, runtime in seconds, exit code.

Inputs: job_id (required). Returns: object

casino_stopA

Stop a running calculation and leave its directory ready to be continued.

SIGTERM goes to this job's casino processes, as haltqmc -k does for the whole account, so runqmc stays alive to finish writing out. CASINO has no graceful-halt signal: the blocks it had finished stay in out, vmc.hist and dmc.hist, the current block is lost. Then haltqmc -f -u tidies the directory -- config.out to config.in, the lock file, and input rewritten for the work that is left -- so casino_run(workdir, resume=true) carries this calculation on.

timeout: seconds the job gets to end on its own before the process group is killed.

Inputs: job_id (required), timeout. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool addresses a distinct lifecycle stage: preparing a directory, launching/interrupting a run, listing/checking jobs, and extracting physics results. Status and list_jobs are adjacent, but one is explicitly per-job detail while the other is an overview, so there is no real ambiguity.

    Naming Consistency4/5

    All tools share the casino_ prefix and use snake_case, but the pattern mixes simple verbs (run, prepare, stop), a verb-object phrase (list_jobs), and bare nouns (status, results). This is readable and predictable, though not a uniform verb_noun convention.

    Tool Count5/5

    Six tools is a well-scoped set for a job-management server. Each tool covers a necessary action without redundancy, and the count sits comfortably in the ideal 3-15 range.

    Completeness5/5

    The tool surface covers the full CASINO workflow: prepare a calculation, run or restart it, monitor it, stop it, and retrieve physics results. Missing cleanup or job-forgetting operations are not essential to the stated purpose.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Converts Quantum ESPRESSO output files to structured JSON and serves them via an HTTP API for use with MCP clients.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Durable MCP server for managing long-running jobs locally, over SSH, or on Slurm clusters. Jobs survive client disconnects and return exit codes, bounded logs, and JSON artifacts.
      11
      17 PyPI
      1
      MIT