casino-mcp

Управляющая плоскость MCP над кодом квантового Монте-Карло CASINO на Fortran: запускать расчёты, знать, что выполняется, останавливать их и читать файл out как структурированные данные вместо отправки 4000 строк текста в контекст модели.

Альфа (0.1.0). Четыре управляющих инструмента и парсер out готовы и протестированы; инструмент, возвращающий физику модели, ещё не выпущен. Интерфейсы могут ещё меняться.

Что это такое и чем не является

У CASINO уже есть примитивы — opt_plan, runqmc --auto-continue, multirun, envmc, make_E_v_dt. Но в нём нет места для слоя между ними: машиночитаемых результатов, памяти о том, что было запущено, и оценочных суждений, которые находятся между шагами («достигла ли дисперсия плато?», «всё ли ещё этот временной шаг в линейном режиме?»). Этот слой и есть данный пакет, и три правила сохраняют его честность:

1. Ни одно число не создаётся моделью. Каждое значение, возвращаемое инструментом, читается из файла и несёт строку, из которой оно получено. То, что CASINO не напечатал, возвращается как null с причиной, а не догадкой.

2. Каждый результат воспроизводим из его записи. Запись задания фиксирует команду, количество процессов, а также путь, размер и mtime исполняемого файла 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, …) берётся из файла input в workdir; нет отдельного инструмента для каждого типа запуска, потому что это умножает поверхность без добавления возможности.

Командная строка

Та же среда выполнения без модели в цикле — это также способ отладки сервера:

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-сервер настраивается там, где он зарегистрирован — в блоке env файла .mcp.json выше — а собственные переменные 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

Модульный набор тестов работает где угодно: парсер проверяется на пяти реальных файлах out, сохранённых в tests/data/, а запускатель, группа процессов и защитные механизмы проверяются на поддельном shell-скрипте runqmc.

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

Интеграционный набор требует настоящий CASINO. Он проверяет parse_out против собственного envmc CASINO по всему дереву примеров (526 файлов, ~50 с) и управляет сервером через реальный stdio MCP, запуская и останавливая настоящие расчёты VMC.

tools/protocol_dump.py вручную говорит на JSON-RPC без SDK и выводит каждую строку в обоих направлениях. Прочтите его перед добавлением инструмента.

Лицензия

MIT.