casino-mcp

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

Alpha (0.1.0)。 四个控制工具和 out 解析器已完成并测试；将物理结果返回给模型的工具尚未发布。接口可能仍会变动。

它是什么，以及它不是什么

CASINO 已经拥有这些原语——opt_plan、runqmc --auto-continue、multirun、envmc、make_E_v_dt。它没有位置的是它们之间的层：机器可读的结果、对已运行内容的记忆，以及步骤之间的判断调用（“方差是否已经趋于平稳？”、“这个时间步是否仍处于线性区域？”）。这个层就是这个包的作用，三条规则使其保持诚实：

1. 模型不产生任何数字。 工具返回的每个值都从文件中读取，并带有其来源行。CASINO 未打印的内容以 null 返回并附有原因，绝不猜测。

2. 每个结果都可以从其记录中重现。 作业记录冻结了命令、进程数以及运行的 casino 二进制的路径、大小和修改时间。

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

工具

运行类型（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 自己的变量保持其名称，因此设置一次即可配置两层：

其他所有内容——一个 MPI 进程、opt 二进制、SIGTERM 和 SIGKILL 之间的二十秒、保留两百条作业记录——都是 settings.py 中的常量。casino-mcp config 会打印服务器当前将使用的内容以及是哪个变量决定的；当工具调用被拒绝时，先运行它。

CASINO_MCP_FORBID 是唯一没有每次调用覆盖的防护。overwrite=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`)

计算目录只会获得 CASINO 放入其中的内容。

为什么需要启动器进程。 runqmc 是一个 bash 脚本，它执行 mpirun -np N casino；向其 pid 发送信号会使进程树成为孤儿。启动器在自己的会话中运行，因此 killpg 可以触及所有内容，其退出代码在 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                      # 102 tests, ~2 s, no CASINO needed

单元测试套件可在任何地方运行：解析器针对 tests/data/ 下提交的五个真实 out 文件进行检查，启动器、进程组和防护措施则针对一个假的 runqmc shell 脚本进行测试。

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

集成测试套件需要真实的 CASINO。它会在整个示例树（526 个文件，约 50 秒）上，将 parse_out 与 CASINO 自己的 envmc 进行比较，并通过真实的 stdio MCP 驱动服务器，运行和停止实际的 VMC 计算。

tools/protocol_dump.py 手动使用 JSON-RPC，无需 SDK，并打印双向的每一行。在添加工具之前请阅读它。

许可证

MIT。