Skip to main content
Glama
casino-mcp

casino-mcp

casino-mcp

PyPI Python CI Licence

基于 Fortran CASINO 量子蒙特卡洛代码的 MCP 控制平面:启动运行、了解正在运行的内容、停止它们,并将 out 文件作为结构化数据读取,而不是将 4000 行文本塞进模型的上下文中。

Beta(0.2.0)。 四个控制工具和 out 解析器已完成,并已针对真实 CASINO 进行测试;将物理量返回给模型的工具尚未发布。在 1.0 之前,接口仍可能变动。

它是什么,以及它不是什么

CASINO 已经有这些原语——opt_plan、runqmc --auto-continue、multirun、envmc、make_E_v_dt。它没有位置容纳的是它们之间的那一层:机器可读的结果、对已运行内容的记忆,以及位于各步骤之间的判断(“方差是否已趋于平稳?”“这个时间步是否仍处于线性区间?”)。这一层就是这个包所提供的内容,而且有三条规则让它保持诚实:

  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,后者仍然是运行时:架构检测、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"
      }
    }
  }
}

工具

工具

返回内容

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

job_id、pid、workdir、command、二进制标记、restart 移除了什么

casino_status(job_id)

运行中 / 已完成 / 已失败 / 已停止 / 未知、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,而不是替换它们,因此在一个目录中运行两次会产生两次运行拼接在一起的文件。默认情况下这会遭到拒绝;有两条绕过它的途径——彼此相反,所以只能传一个:

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 的两种继续路线中走哪一条是从 out 中读出的,而不是在这里选择的——见下文。

在命令行中,它们分别是 --restart 和 --resume;后者也接受 --continue,也就是 runqmc 所用的名称。工具参数不能那样拼写:continue 是一个 Python 关键字。

停止运行并继续它

casino_stop 向该作业的 casino 进程发送 SIGTERM,而不向其他任何进程发送——这与 haltqmc -k 发送的信号相同,只不过 haltqmc 的信号是对整个账户执行 pkill -x casino,这会杀死机器上的所有其他作业。mpirun 将每个 rank 放入各自的进程组,因此通过会话 ID 找到这些 rank:会话属于启动器,整个进程树共享它。runqmc 本身被保留下来以完成其收尾工作;只有在 timeout 之后仍在运行的作业,其进程组才会被发信号然后被杀死。

然后该目录交给 haltqmc -f -u,正是这一步让已停止的运行可以继续:config.out 变成 config.in,锁文件和标记文件被移除,input 会针对剩余工作重写——newrun : F、减去已完成的块、运行类型前进到下一阶段。回复会在 halt 下报告它所做的操作。此前的 input 会被复制到作业目录中,halt.input_saved 会说明其位置。

resume=true 随后走哪条继续路线,由 out 中的最后一次运行决定:

out 中有 CONTINUATION INFO:

runqmc --continue。CASINO 仅在因 max_cpu_time 或 max_real_time 自行停止时才会写入该块;runqmc 会应用它并将已完成段归档到 saved_part_N/。

没有这样的块

对 haltqmc 重写后的 input 执行普通 runqmc。被中断的运行就是这样继续的——--continue 只会因为缺少继续信息而 errstop 报错终止。

运行已到达自身终点

拒绝:没有可继续的内容。

如果目录的 input 中写着 newrun : F,则 restart=true 会被拒绝,因为重启会删除 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 进程、opt 二进制文件、已停止作业自行结束的二十秒、haltqmc 清理的一分钟、保留两百条作业记录——都是 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 是一个 bash 脚本,它执行 mpirun -np N casino;向它的 pid 发送信号会使进程树变成孤儿。启动器在自己的会话中运行,这正是让进程树可被识别的原因——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 locale 下会错误解析数字。

测试

pytest                      # 158 tests, ~5 s, no CASINO needed

单元测试套件可在任何地方运行:解析器会针对 tests/data/ 下的五个真实 out 文件逐字段检查——每个文件都附有生成它的 input——并覆盖 examples/ 下全部十八个计算;同时,启动器、进程组和防护措施会用一个假的 runqmc shell 脚本进行测试。

pytest -m integration

集成测试套件需要一个真实的 CASINO,但除此之外不需要本仓库之外的任何东西。它会针对 examples/ 中的每个 out,用 parse_out 与 CASINO 自带的 envmc 进行比对;会用已安装的二进制文件重新运行整棵目录树,并通过真实的 stdio MCP 驱动服务器,实际启动和停止 VMC 计算。

examples/ 中包含十八个计算,它们被挑选出来覆盖 CASINO 可运行的各种设置——每种运行类型、基组类型、优化器和波函数选项至少出现一次;两个会让解析器静默出错的文件也在此列:一个从未打印能量的运行,以及一个在优化周期之间被中断的运行。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
      1
      MIT