casino-mcp
casino-mcp
Fortran으로 작성된 CASINO 양자 몬테카를로 코드를 위한 MCP 컨트롤 플레인: 실행을 시작하고, 무엇이 실행 중인지 확인하고, 실행을 중지하고, 모델 컨텍스트에 4000줄의 텍스트를 보내는 대신 out 파일을 구조화된 데이터로 읽습니다.
베타(0.2.0). 네 가지 제어 도구와
out파서는 완성되어 실제 CASINO로 테스트했습니다. 모델에 물리 결과를 반환하는 도구는 아직 제공되지 않습니다. 인터페이스는 1.0 이전에 변경될 수 있습니다.
무엇이며, 무엇이 아닌가
CASINO에는 이미 기본 요소들(opt_plan, runqmc --auto-continue, multirun, envmc, make_E_v_dt)이 있습니다. 그러나 그 사이의 계층이 들어갈 자리는 없습니다. 기계가 읽을 수 있는 결과, 실행된 내용에 대한 기록, 그리고 단계 사이에 필요한 판단("분산이 평탄해졌는가?", "이 타임스텝이 여전히 선형 영역인가?") 같은 것이 그것입니다. 이 계층이 바로 이 패키지가 하는 일이며, 세 가지 규칙이 신뢰성을 지켜줍니다.
모델이 숫자를 만들지 않습니다. 도구가 반환하는 모든 값은 파일에서 읽은 것이며 출처 줄을 함께 담습니다. CASINO가 출력하지 않은 것은 추측이 아니라 이유와 함께
null로 반환됩니다.모든 결과는 해당 기록에서 재현할 수 있습니다. 작업 기록에는 명령, 프로세스 수, 그리고 실행된
casino바이너리의 경로·크기·수정 시간이 고정되어 있습니다.파괴적인 작업은 암시적으로 수행되지 않습니다. 실행은 이미 결과가 있는 디렉터리에서 시작을 거부하며, 해당
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를 교체하지 않고 덧붙입니다. 따라서 한 디렉터리에서 두 번 실행하면 두 실행이 이어진 파일이 생성됩니다. 기본적으로 이를 거부하며, 우회 방법은 두 가지입니다. 서로 반대이므로 하나만 전달하십시오:
| 이전 실행이 남긴 것을 삭제하고 처음부터 시작합니다. |
| 중단된 실행을 멈춘 지점에서 이어갑니다. CASINO의 두 가지 계속 경로 중 어느 것을 사용할지는 여기서 선택하지 않고 |
명령줄에서는 각각 --restart와 --resume이며, 후자의 경우 runqmc가 사용하는 이름인 --continue도 허용됩니다. 도구 매개변수는 그렇게 쓸 수 없습니다. continue는 Python 키워드이기 때문입니다.
실행 중지 및 계속
casino_stop는 해당 작업의 casino 프로세스에만 SIGTERM을 보내고 다른 곳에는 보내지 않습니다. 이는 haltqmc -k가 보내는 신호와 같지만, haltqmc의 신호는 전체 계정에 pkill -x casino를 수행하여 머신의 다른 모든 작업을 중단시킵니다. mpirun은 각 rank를 고유한 프로세스 그룹에 넣으므로 rank는 세션 ID로 찾습니다. 세션은 런처의 것이며 전체 트리가 이를 공유합니다. runqmc 자체는 종료 절차를 마칠 수 있도록 남겨두며, timeout 후에도 여전히 실행 중인 작업만 프로세스 그룹에 신호를 보낸 다음 종료합니다.
그런 다음 디렉터리에서 haltqmc -f -u를 실행합니다. 이는 중지된 실행을 계속 가능하게 만드는 단계입니다. config.out이 config.in이 되고, 잠금 및 마커 파일은 사라지며, 남은 작업에 맞게 input이 다시 쓰입니다. newrun : F, 완료된 블록은 차감되고, 런타입은 다음 단계로 진행됩니다. 응답에는 halt 아래에 수행한 내용이 포함됩니다. 그 이전의 input은 작업 디렉터리에 복사되며, halt.input_saved가 그 위치를 알려줍니다.
resume=true가 그 다음에 사용할 계속 경로는 out의 마지막 실행에 따라 결정됩니다:
|
|
해당 블록이 없음 | haltqmc가 다시 쓴 |
실행이 스스로 끝까지 도달함 | 거부됨: 계속할 것이 없습니다. |
input에 newrun : F라고 되어 있는 디렉터리에서는 restart=true가 거부됩니다. 다시 시작하면 CASINO가 요구하는 config.in이 삭제되기 때문입니다. 먼저 저장된 입력 파일을 복원하십시오.
명령줄
모델 없이 동일한 런타임을 실행합니다. 이는 서버를 디버깅하는 방법이기도 합니다:
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가 있으면 0이 아닌 코드로 종료됩니다.
구성
구성 파일은 없습니다. 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는 다른 두 보호 장치를 해제합니다. 여기에 나열된 디렉터리에서는 아예 실행할 수 없으므로, 커밋된 참조 계산 트리를 두기에 적절한 곳입니다.
작동 방식
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 스크립트입니다. 여기에 신호를 보내면 트리가 고아가 됩니다. 런처는 자체 세션에서 실행되며, 이것이 트리를 식별 가능하게 합니다. killpg는 runqmc와 mpirun에 도달하고, 세션 ID는 mpirun이 각자의 프로세스 그룹에 넣은 rank들을 찾아냅니다. 또한 런처의 종료 코드는 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 # 158 tests, ~5 s, no CASINO needed단위 테스트 묶음은 어디서든 실행됩니다. 파서는 tests/data/ 아래의 실제 out 파일 5개(각각을 생성한 input 포함)와 examples/ 아래의 18개 계산 전체를 대상으로 필드별로 검증됩니다. 런처, 프로세스 그룹, 보호 장치는 가짜 runqmc 셸 스크립트로 테스트됩니다.
pytest -m integration통합 테스트 스위트는 실제 CASINO가 필요하지만, 이 저장소 밖의 어떤 것도 필요하지 않습니다. parse_out이 examples/의 모든 out에 대해 CASINO 자체의 envmc와 일치하는지 확인하고, 설치된 바이너리로 전체 트리를 다시 실행하며, 실제 stdio MCP를 통해 서버를 구동하여 실제 VMC 계산을 시작하고 중지합니다.
examples/에는 CASINO를 실행할 수 있는 설정을 망라하도록 선택된 열여덟 개의 계산이 들어 있습니다. 모든 runtype, basis type, optimiser 및 wavefunction 옵션이 최소 한 번씩 등장하며, 파서가 조용히 잘못 읽는 두 파일, 즉 에너지를 출력한 적이 없는 실행과 최적화 주기 사이에 중단된 실행도 등장합니다. 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
- AlicenseAqualityBmaintenanceA 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