casino-mcp

Eine MCP-Steuerungsebene für den Fortran-CASINO-Quanten-Monte-Carlo-Code: Läufe starten, wissen, was läuft, sie stoppen und eine out-Datei als strukturierte Daten lesen, anstatt 4000 Zeilen Text in den Kontext eines Modells zu schicken.

Alpha (0.1.0). Die vier Steuerungswerkzeuge und der out-Parser sind fertig und getestet; das Werkzeug, das Physik an das Modell zurückgibt, ist noch nicht ausgeliefert. Schnittstellen können sich noch ändern.

Was es ist und was es nicht ist

CASINO hat bereits die Grundbausteine — opt_plan, runqmc --auto-continue, multirun, envmc, make_E_v_dt. Was darin keinen Platz hat, ist die Ebene dazwischen: maschinenlesbare Ergebnisse, eine Erinnerung an das, was gelaufen ist, und die Ermessensentscheidungen, die zwischen den Schritten liegen („Hat die Varianz ein Plateau erreicht?“, „Ist dieser Zeitschritt noch im linearen Regime?“). Diese Ebene ist es, die dieses Paket darstellt, und drei Regeln halten es ehrlich:

1. Keine Zahl wird vom Modell erzeugt. Jeder Wert, den ein Werkzeug zurückgibt, wird aus einer Datei gelesen und trägt die Zeile, aus der er stammt. Was CASINO nicht gedruckt hat, kommt als null mit einem Grund zurück, nie als Vermutung.

2. Jedes Ergebnis ist aus seinem Datensatz reproduzierbar. Ein Job-Datensatz friert den Befehl, die Prozessanzahl sowie Pfad, Größe und mtime des ausgeführten casino-Binärs ein.

3. Nichts Destruktives ist implizit. Ein Lauf weigert sich, in einem Verzeichnis zu starten, das bereits Ergebnisse enthält, und weigert sich stärker, wenn diese out-Datei festgeschriebene Referenzdaten sind.

Es gibt bewusst kein execute_shell(command)-Werkzeug. Jedes Werkzeug ist eine benannte CASINO-Operation mit typisierten Argumenten.

Related MCP server: fdmnes-mcp

Installation

pip install casino-mcp          # needs Python 3.11+ and a working CASINO installation

Aus einem Checkout:

pip install -e '.[dev]'

Das Paket bündelt, baut oder ersetzt CASINO nicht. Es steuert runqmc, das die Laufzeit bleibt: Architekturerkennung, MPI-Varianten, Batch-Queue-Einreichung und die Sperrdatei sind dessen Aufgabe, nicht unsere.

Bei Claude Code registrieren

.mcp.json, Projektbereich:

{
  "mcpServers": {
    "casino": {
      "command": "casino-mcp",
      "args": ["serve"],
      "env": {
        "CASINO_HOME": "/home/you/bin/CASINO",
        "CASINO_ARCH": "linuxpc-gcc-parallel.openblas"
      }
    }
  }
}

Werkzeuge

Der Runtyp (vmc, vmc_opt, vmc_dmc, …) stammt aus der input-Datei in workdir; es gibt kein Werkzeug pro Runtyp, weil das die Oberfläche vervielfacht, ohne eine Fähigkeit hinzuzufügen.

Befehlszeile

Dieselbe Laufzeit ohne ein Modell in der Schleife — so debuggen Sie auch den Server:

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

Jeder Unterbefehl gibt JSON aus und beendet sich mit einem Nicht-Null-Exit-Code, wenn dieses JSON einen error enthält.

Konfiguration

Es gibt keine Konfigurationsdatei. Ein MCP-Server wird dort konfiguriert, wo er registriert ist — der env-Block der obigen .mcp.json — und CASINOs eigene Variablen behalten ihre Namen, sodass ein einmaliges Setzen beide Ebenen konfiguriert:

Alles andere — ein MPI-Prozess, das opt-Binär, zwanzig Sekunden zwischen SIGTERM und SIGKILL, zweihundert aufbewahrte Job-Datensätze — ist eine Konstante in settings.py. casino-mcp config gibt aus, was der Server gerade verwenden würde und welche Variable das gesagt hat; führen Sie es zuerst aus, wenn ein Werkzeugaufruf sich weigert.

CASINO_MCP_FORBID ist die einzige Schutzmaßnahme ohne Überschreibung pro Aufruf. overwrite=true und unlock=true entsperren die anderen beiden; ein hier aufgeführtes Verzeichnis kann überhaupt nicht ausgeführt werden, was es zum richtigen Ort für einen Baum festgeschriebener Referenzberechnungen macht.

So funktioniert es

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

Der Zustand lebt außerhalb der Berechnung, unter $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`)

Das Berechnungsverzeichnis erhält nur das, was CASINO dort ablegt.

Warum ein Launcher-Prozess. runqmc ist ein Bash-Skript, das mpirun -np N casino ausführt; das Signalisieren seiner PID verwaist den Baum. Der Launcher läuft in seiner eigenen Sitzung, sodass killpg alles erreicht, sein Exit-Code überlebt einen Neustart des MCP-Servers, und die Ausgabe von runqmc geht in ein Protokoll statt in den JSON-RPC-Stream. Eine recycelte PID kann nicht als lebender Job durchgehen: Die Startzeit von /proc/<pid> wird verglichen, und ein Zombie zählt nicht als laufend.

Der out-Parser

parse_out ist eine einfache Funktion ohne MCP und ohne Abhängigkeiten. Eine out-Datei ist eine Sequenz von Phasen, nicht ein Ergebnis — vmc_opt schreibt pro Zyklus eine VMC- und eine OPTIMIZATION-Phase, vmc_dmc schreibt VMC, DMC-Equilibrierung und DMC-Statistikakkumulation — daher gibt sie phases zurück, und result zeigt auf die letzte Phase, die eine Energie trägt.

from casino_mcp.parse_out import parse_out

parsed = parse_out('./calc')
parsed['result']['energy']  # {'value': -2.861829862553, 'error': 0.000659077167, 'line': 237}

Die eine abgeleitete Zahl darin ist der Stichprobenvarianz-Fehler eines Einzelblock-Laufs, den CASINO nicht druckt; sie wird aus dem einen Block genau so übernommen, wie envmc es tut, und als derived gekennzeichnet. Nichts ruft zur Laufzeit envmc oder endmc auf — endmc parst Zahlen unter einem Nicht-C-Locale falsch.

Tests

pytest                      # 102 tests, ~2 s, no CASINO needed

Die Unit-Testsuite läuft überall: Der Parser wird gegen fünf echte out-Dateien geprüft, die unter tests/data/ eingecheckt sind, und der Launcher, die Prozessgruppe und die Schutzmaßnahmen werden gegen ein gefälschtes runqmc-Shell-Skript getestet.

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

Die Integrationstestsuite benötigt ein echtes CASINO. Sie prüft parse_out gegen CASINOs eigenes envmc über einen gesamten Beispiele-Baum (526 Dateien, ~50 s) und steuert den Server über echtes stdio-MCP, wobei echte VMC-Berechnungen gestartet und gestoppt werden.

tools/protocol_dump.py spricht JSON-RPC von Hand ohne SDK und gibt jede Zeile in beide Richtungen aus. Lesen Sie es, bevor Sie ein Werkzeug hinzufügen.

Lizenz

MIT.