casino-mcp
casino-mcp
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つのルールがそれを正直に保つ:
モデルによって生成される数値はない。 ツールが返すすべての値はファイルから読み取らレ、その出所の行を伴う。CASINO が出力しなかったものは、推測ではなく理由付きで
nullとして返る。すべての結果はその記録から再現できる。 ジョブ記録は、コマンド、プロセス数、実行された
casinoバイナリのパス、サイズ、mtime を固定する。破壊的な操作は暗黙には行われない。 実行は、すでに結果が存在するディレクトリでは開始を拒否し、その
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"
}
}
}
}ツール
ツール | 戻り値 |
| job_id、pid、workdir、command、バイナリスタンプ、 |
| running / finished / failed / stopped / unknown、pid、実行時間、終了コード |
| シグナルを送ったもの、最終ステータス、 |
| 既知のすべてのジョブ(新しい順) |
ラんタイプ(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つを渡す:
| 以前の実行が残したものを削除してやり直す。 |
| 中断した実行を停止した場所から続行する。CASINO の2つの継続経路のどちらを取るかは |
コマンドライン上ではこれらは --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 内の最後の実行によって決まる:
|
|
そのようなブロックがない場合 | haltqmc が書き換えた |
実行が自然に終了した場合 | 拒否される: 継続するものは何もない。 |
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 インストールのルート(デフォルトは |
| ビルドタゲット。 |
|
|
|
|
| ジョブレジストリ。それ以外は |
| 実行が決して触れてはならないディレクトリ。 |
その他すべて——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 outputtools/protocol_dump.py はSDKを使わずにJSON-RPCを手動で処理し、双方向のすべての行を出力します。ツールを追加する前にそれを読んでください。
ライセンス
MIT.
Available Tools
6 toolscasino_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Run isolated code and manage apps, databases and deployments on Lizard (lizard.build).
Dispatch and track Alchemist Cloud tickets, watch deploys, read logs, and query your project DB.
Manage servers through SSH.
Related MCP Servers
- AlicenseAqualityCmaintenanceA unified CLI, web dashboard, and Python API for SLURM job management.1547 PyPI23Apache 2.0
- AlicenseNot gradedqualityDmaintenanceConverts Quantum ESPRESSO output files to structured JSON and serves them via an HTTP API for use with MCP clients.MIT
- AlicenseAqualityCmaintenanceDurable 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.1117 PyPI1MIT
- AlicenseBqualityBmaintenanceEnables natural-language preparation, submission, monitoring, and diagnosis of Slurm jobs on the ROMEO HPC cluster via SSH.471MIT