casino-mcp

Un plano de control MCP sobre el código Fortran CASINO de Monte Carlo cuántico: iniciar ejecuciones, saber qué está en marcha, detenerlas y leer un archivo out como datos estructurados en lugar de enviar 4000 líneas de texto al contexto de un modelo.

Alfa (0.1.0). Las cuatro herramientas de control y el analizador de out están terminados y probados; la herramienta que devuelve la física al modelo aún no se ha publicado. Las interfaces pueden cambiar todavía.

Qué es y qué no es

CASINO ya tiene los primitivos — opt_plan, runqmc --auto-continue, multirun, envmc, make_E_v_dt. Lo que no tiene es la capa intermedia: resultados legibles por máquina, una memoria de lo que se ejecutó y los juicios que se sitúan entre los pasos ("¿ha alcanzado la varianza una meseta?", "¿sigue este paso de tiempo en el régimen lineal?"). Esa capa es lo que este paquete es, y tres reglas lo mantienen honesto:

1. Ningún número lo produce el modelo. Cada valor que devuelve una herramienta se lee de un archivo y lleva la línea de la que proviene. Lo que CASINO no imprimió se devuelve como null con un motivo, nunca una suposición.

2. Cada resultado es reproducible a partir de su registro. Un registro de trabajo congela el comando, el número de procesos y la ruta, tamaño y mtime del binario casino que se ejecutó.

3. Nada destructivo es implícito. Una ejecución se niega a comenzar en un directorio que ya contiene resultados, y se niega con más firmeza cuando ese out es datos de referencia confirmados.

Deliberadamente no hay una herramienta execute_shell(command). Cada herramienta es una operación CASINO con nombre y argumentos tipados.

Related MCP server: fdmnes-mcp

Instalación

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

Desde un checkout:

pip install -e '.[dev]'

El paquete no incluye, compila ni reemplaza CASINO. Controla runqmc, que sigue siendo el entorno de ejecución: la detección de arquitectura, las variantes MPI, el envío a colas de lotes y el archivo de bloqueo son su trabajo, no el nuestro.

Regístralo con Claude Code

.mcp.json, ámbito de proyecto:

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

Herramientas

El tipo de ejecución (vmc, vmc_opt, vmc_dmc, …) proviene del archivo input en workdir; no hay una herramienta por tipo de ejecución, porque eso multiplica la superficie sin añadir una capacidad.

Línea de comandos

El mismo entorno de ejecución sin un modelo en el bucle — que también es como se depura el servidor:

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

Cada subcomando imprime JSON y sale con código distinto de cero cuando ese JSON contiene un error.

Configuración

No hay archivo de configuración. Un servidor MCP se configura donde se registra — el bloque env del .mcp.json anterior — y las variables propias de CASINO conservan sus nombres, de modo que configurarlas una vez configura ambas capas:

Todo lo demás — un proceso MPI, el binario opt, veinte segundos entre SIGTERM y SIGKILL, doscientos registros de trabajo conservados — es una constante en settings.py. casino-mcp config imprime lo que el servidor usaría ahora mismo y qué variable lo dijo; ejecútalo primero cuando una llamada a una herramienta se niegue.

CASINO_MCP_FORBID es la única protección sin anulación por llamada. overwrite=true y unlock=true desbloquean las otras dos; un directorio listado aquí no se puede ejecutar en absoluto, lo que lo convierte en el lugar adecuado para un árbol de cálculos de referencia confirmados.

Cómo funciona

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

El estado vive fuera del cálculo, bajo $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`)

El directorio de cálculo solo recibe lo que CASINO pone allí.

Por qué un proceso lanzador. runqmc es un script bash que ejecuta mpirun -np N casino; señalizar su pid huérfana el árbol. El lanzador se ejecuta en su propia sesión, de modo que killpg alcanza todo, su código de salida sobrevive a un reinicio del servidor MCP, y la salida de runqmc va a un registro en lugar de al flujo JSON-RPC. Un pid reciclado no puede pasar por un trabajo vivo: se compara el tiempo de inicio de /proc/<pid>, y un zombi no cuenta como en ejecución.

El analizador de out

parse_out es una función simple sin MCP y sin dependencias. Un archivo out es una secuencia de fases, no un solo resultado — vmc_opt escribe una fase VMC y una de OPTIMIZACIÓN por ciclo, vmc_dmc escribe VMC, equilibración DMC y acumulación de estadísticas DMC — por lo que devuelve phases, y result apunta a la última fase que lleva una energía.

from casino_mcp.parse_out import parse_out

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

El único número derivado en él es el error de varianza muestral de una ejecución de un solo bloque, que CASINO no imprime; se toma del único bloque exactamente como hace envmc, y se etiqueta como derived. Nada invoca envmc o endmc en tiempo de ejecución — endmc interpreta mal los números bajo una configuración regional no C.

Pruebas

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

La suite de pruebas unitarias se ejecuta en cualquier lugar: el analizador se comprueba contra cinco archivos out reales confirmados en tests/data/, y el lanzador, el grupo de procesos y las protecciones se ejercitan contra un script runqmc falso.

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

La suite de integración necesita un CASINO real. Comprueba parse_out contra el propio envmc de CASINO sobre un árbol de ejemplos completo (526 archivos, ~50 s), y controla el servidor a través de MCP stdio real, ejecutando y deteniendo cálculos VMC reales.

tools/protocol_dump.py habla JSON-RPC a mano sin SDK e imprime cada línea en ambas direcciones. Léelo antes de añadir una herramienta.

Licencia

MIT.