llm-chess-mcp

Un runtime de ajedrez MCP que permite a los LLM jugar, analizar y ajustar su fuerza sin externalizar cada decisión a un motor.

En lugar de devolver una única jugada, expone la fuerza objetiva (Stockfish), la probabilidad de jugada humana (Maia3) y las estadísticas de partidas reales (Lichess) para que el LLM elija cómo quiere jugar. El LLM se encarga de la estrategia y el juicio; el servidor MCP hace todo el cálculo.

Motores

Todo se ejecuta dentro del proceso de Node: nada de motor externo ni runtime de Python en el momento del despliegue. El paquete publicado incluye el modelo Maia3 5M; las demás variantes de exportación no son opciones de ejecución a menos que sus archivos ONNX se proporcionen por separado.

Related MCP server: Chess MCP

Instalación

Requiere Node.js 20 o más reciente.

No necesita instalación — ejecútalo directamente con npx:

npx -y llm-chess-mcp

El modelo Maia3 ya viene incluido, así que no hay que instalar Python, torch ni binarios de motor. npx descarga el paquete en la primera ejecución y lo guarda en caché.

Para instalarlo permanentemente en su lugar:

npm install -g llm-chess-mcp

Compilar desde el código fuente

pnpm install
pnpm build
pnpm test

pnpm test:unit ejecuta la suite de pruebas unitarias. pnpm test:e2e compila primero y luego ejecuta las pruebas de transporte de MCP. pnpm check ejecuta todo el control local; usa pnpm release:check antes de publicar.

Mantenedores

Arquitectura describe los límites del runtime y de los servicios.

Comandos locales de calidad:

pnpm typecheck
pnpm test:coverage
pnpm contract:check
pnpm check
pnpm test:package

pnpm test:stress ejecuta la comprobación corta de concurrencia con el motor real. pnpm test:live consulta Lichess solo cuando LICHESS_TOKEN está definido; si no, se omite sin hacer ninguna petición de red.

Exportar Maia3 a ONNX (solo en tiempo de compilación)

Este paso necesita Python y PyTorch una sola vez. Descarga el checkpoint de Maia3, comprueba la reimplementación frente a la original y exporta models/maia3-5m.onnx.

uv venv .venv-maia3 --python 3.13
uv pip install --python .venv-maia3/bin/python -r scripts/requirements.txt
uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
pnpm export:maia3            # -> models/maia3-5m.onnx

El .onnx resultante se commitea o se incluye en el paquete; los usuarios finales nunca necesitan Python ni torch.

Token de Lichess (opcional)

El explorador de aperturas ahora requiere autenticación. Genera un token de acceso personal en https://lichess.org/account/oauth/token/create y configúralo en .env:

cp .env.example .env
# set LICHESS_TOKEN=...

Sin token, opening_explorer devuelve un aviso de desactivación; todas las demás herramientas funcionan.

Los filtros del explorador son estrictos. Las velocidades son ultraBullet, bullet, blitz, rapid, classical y correspondence; los segmentos de rating son 0, 1000, 1200, 1400, 1600, 1800, 2000, 2200 y 2500. masters no acepta ninguno de los filtros. Los filtros no válidos fallan localmente. Los fallos transitorios (red, timeout, 429 y 5xx) se reintentan una vez dentro de un presupuesto total de 12 segundos; las peticiones no válidas y el resto de respuestas 4xx no se reintentan.

Configuración en tu cliente MCP

opencode

Añádelo a opencode.json (proyecto) o ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "llm-chess-mcp": {
      "type": "local",
      "command": ["npx", "-y", "llm-chess-mcp"],
      "enabled": true,
      "environment": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

Añádelo a .mcp.json (proyecto) o ~/.claude.json (global), o ejecuta:

claude mcp add llm-chess-mcp -- npx -y llm-chess-mcp

{
  "mcpServers": {
    "llm-chess-mcp": {
      "command": "npx",
      "args": ["-y", "llm-chess-mcp"],
      "env": {
        "LICHESS_TOKEN": "your-token"
      }
    }
  }
}

Codex CLI

Añádelo a ~/.codex/config.toml:

[mcp_servers.llm-chess-mcp]
command = "npx"
args = ["-y", "llm-chess-mcp"]

[mcp_servers.llm-chess-mcp.env]
LICHESS_TOKEN = "your-token"

O mediante la CLI:

codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_TOKEN=your-token

Herramientas

Formato de resultado

structuredContent es el resultado de éxito canónico. Los fallos a nivel de gestor establecen isError y proporcionan structuredContent.error. Los fallos de validación de entrada los genera el SDK de MCP antes del gestor y usan su isError estándar de texto, sin structuredContent. En cualquier otro caso, content es solo un resumen breve legible y no debe interpretarse como datos.

Convenciones de puntuación

• Las puntuaciones de Stockfish son desde la perspectiva del bando que mueve: cp positivo = el bando a mover está mejor; mate N = el bando que mueve da mate en N. wdles[win, draw, loss]` en permille para el bando que mueve.

• move_candidates da moverCp (la perspectiva del que mueve: más alto = mejor para el jugador que elige la jugada) y whiteCp (perspectiva fija de las baby White) para que el signo no se dé la vuelta.

• move_evaluate muestra la puntuación desde la perspectiva del que mueve, más cpLoss (milesimas de peón perdidas con respecto a la mejor jugada) y la clasificación: best / excellent / good / inaccuracy / mistake / blunder.

• maia3Prob es una probabilidad humana, no la calidad de la jugada. Una jugada con probabilidad alta puede ser objetivamente mala.

Estructura de las candidatas

move_candidates devuelve cada candidata con tres facetas independientes:

{
  "uci": "g1f3",
  "san": "Nf3",
  "objective": { "rank": 1, "moverCp": 55, "whiteCp": 55, "cpLoss": 0, "moverMate": null, "wdl": [153, 844, 3] },
  "human": { "maia3Prob": 0.62, "selfElo": 1500, "opponentElo": 1500 },
  "opening": { "status": "available", "games": 18421, "frequency": 0.31 }
}

• objective — Stockfish: fuerza del motor, nunca mezclada con la probabilidad humana. moverCp está en la perspectiva del que mueve (más alto = mejor para quien elige).

• human — Probabilidad condicional de Maia3 a un Elo objetivo.

• opening — Frecuencia empírica de Lichess (señal distinta de la de Maia3).

opening.status puede ser available, no_data (la API devuelve OK pero no hay partidas en esta posición), unavailable (timeout/429/401) o disabled (no token). La salida de Stockfish y de Maia3 siempre se devuelve en todos los casos.

move_candidates también devuelve moveSensitivity:

{ "moveSensitivity": { "level": "high", "topMoveSpreadCp": 245 } }

level es low (<80cp de dispersión), medium (80–200cp) o high (≥200cp). La sensibilidad alta significa que elegir entre opciones plausibles puede cambiar materialmente la evaluación, lo que sirve para decidir si aflojar o jugar con precisión.

Niveles de análisis

Las herramientas de Stockfish aceptan un preset como analysis_level en lugar de parámetros UCI brutos:

Para uso avanzado se pueden seguir anulando con depth y multipv explícitos.

Protección de posición obsoleta

Cada lectura de estado devuelve una revision. game_play_move requiere expected_revision; si la partida ha avanzado desde tu última lectura, la jugada se rechaza:

{ "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }

Límites del runtime

A. Se mantienen hasta 1.000 sesiones de partida; las sesiones inactivas caducan después de una hora. B. move_evaluate admite como máximo 10 jugadas por llamada. C. Los PGN importados están limitados a 1 MiB y 4.096 pliegas (moves).

Intenciones

move_candidates_by_intent ordena candidatas para una intención elegida. Es una capa de comodidad por encima de move_candidates; los umbrales fijos de abajo son valores por defecto heurísticos, no una verdad absoluta:

Esta herramienta ordena los candidatos pero no decide la jugada. Depende del contexto conversacional para la decisión final; no asignes de forma automática nivel de usuario a una intención.

Ejemplo de flujo

El bucle de juego normal hace tres llamadas:

1. create_game → game_id

2. move_candidates → elegir jugada

3. game_play_move (con expected_revision) → asignar la jugada

Aumenta solo cuando sea necesario:

• position_analyze — líneas buenas objetivamente

• human_move_distribution — lo que un humano de ese Elo juega

• opening_explorer — estadísticas de partidas reales

• move_evaluate — puntuar una jugada específica (o comparar varias)

Verificación ONNX de Maia3

El modelo ONNX exportado se va a probar con regresión contra la implementación original de Maia3 en posiciones fijas y pares de Elo:

.venv-maia3/bin/python scripts/verify_maia3.py --model 5m

Comprueba el acuerdo en la jugada top1/topk y el error máximo de probabilidad para detectar regresiones de exportación/runtime. El maia3-5m.onnx incluido pasa con un 100% de acuerdo top-1 y top-5 y un error máximo de probabilidad <1e-4.

Verificación del paquete

Los artefactos del paquete se verifican localmente; este proyecto deliberadamente no tiene CI cloud.

Ejecuta pnpm check como gate determinista de offline. Usa pnpm test:package para empacar el proyecto, instala el tarball en un directorio temporal limpio y ejecuta el binario llm-chess-mcp instalado contra runtimes real de Stockfish y Maia. pnpm release:check ejecuta ambas comprobaciones junto con la auditoría de dependencias y el dry run del manifiesto.

Licencia y atribución

Este proyecto se distribuye bajo AGPL-3.0 (ver LICENSE).

Este paquete incluye y depende de componentes de terceros:

El modelo Maia3 incluido (models/maia3-5m.onnx) se deriva de UofTCSSLab/Maia3-5M en b6559de2398d7140b985f28fd2c19fb5e47ddabe. La exportación ONNX es un paso de compilación (scripts/export_maia3.py); el tiempo de ejecución no ejecuta ningún código Python de Maia3.