llm-chess-mcp

Eine MCP-Schach-Laufzeit, die es LLMs ermöglicht, zu spielen, zu analysieren und ihre Stärke anzupassen, ohne jede Entscheidung an eine Engine auszulagern.

Statt einen einzelnen besten Zug zurückzugeben, stellt sie objektive Stärke (Stockfish), menschliche Zugwahrscheinlichkeit (Maia3) und Statistiken aus echten Partien (Lichess) bereit, sodass das LLM wählen kann, wie es spielen möchte. Das LLM übernimmt Strategie und Urteilsvermögen; der MCP-Server erledigt die gesamte Berechnung.

Engines

Alles läuft innerhalb des Node-Prozesses – es ist weder ein externer Engine-Prozess noch eine Python-Laufzeit zur Bereitstellungszeit erforderlich. Das veröffentlichte Paket enthält das Maia3-5M-Modell; andere Exportvarianten sind keine Laufzeitoptionen, sofern ihre ONNX-Dateien nicht separat bereitgestellt werden.

Related MCP server: Chess MCP

Installation

Erfordert Node.js 20 oder neuer.

Keine Installation erforderlich – direkt mit npx ausführen:

npx -y llm-chess-mcp

Das Maia3-Modell ist bereits enthalten, daher müssen weder Python, torch noch Engine-Binärdateien installiert werden. npx lädt das Paket beim ersten Lauf und speichert es im Cache.

Um es stattdessen dauerhaft zu installieren:

npm install -g llm-chess-mcp

Aus dem Quellcode erstellen

pnpm install
pnpm build
pnpm test

pnpm test:unit führt die Unit-Tests aus. pnpm test:e2e erstellt zuerst und führt dann die MCP-Transporttests aus. pnpm check führt die vollständige lokale Prüfung durch; verwenden Sie pnpm release:check vor der Veröffentlichung.

Betreuer

Architektur beschreibt Laufzeit- und Dienstgrenzen.

Lokale Qualitätsbefehle:

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

pnpm test:stress führt die kurze Echt-Engine-Konkurrenzprüfung durch. pnpm test:live fragt Lichess nur ab, wenn LICHESS_TOKEN gesetzt ist; andernfalls überspringt es ohne Netzwerkanfrage.

Maia3 nach ONNX exportieren (nur zur Build-Zeit)

Dieser Schritt benötigt einmalig Python + PyTorch. Er lädt den Maia3-Checkpoint herunter, verifiziert die Neuimplementierung gegen das Original und exportiert 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

Die resultierende .onnx-Datei wird eingecheckt/gebündelt; Endbenutzer benötigen niemals Python oder torch.

Lichess-Token (optional)

Der Eröffnungs-Explorer erfordert jetzt eine Authentifizierung. Generieren Sie ein persönliches Zugriffstoken unter https://lichess.org/account/oauth/token/create und setzen Sie es in .env:

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

Ohne Token gibt opening_explorer einen Hinweis auf Deaktivierung zurück; alle anderen Tools funktionieren.

Explorer-Filter sind streng. Geschwindigkeiten sind ultraBullet, bullet, blitz, rapid, classical und correspondence; Rating-Stufen sind 0, 1000, 1200, 1400, 1600, 1800, 2000, 2200 und 2500. masters akzeptiert keinen der Filter. Ungültige Filter schlagen lokal fehl. Vorübergehende Fehler (Netzwerk, Timeout, 429 und 5xx) werden einmal innerhalb eines Gesamtbudgets von 12 Sekunden wiederholt; ungültige Anfragen und andere 4xx-Antworten werden nicht wiederholt.

In Ihrem MCP-Client konfigurieren

opencode

Fügen Sie zu opencode.json (Projekt) oder ~/.config/opencode/opencode.json (global) hinzu:

{
  "$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

Fügen Sie zu .mcp.json (Projekt) oder ~/.claude.json (global) hinzu, oder führen Sie aus:

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

Fügen Sie zu ~/.codex/config.toml hinzu:

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

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

Oder über die CLI:

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

Tools

Ergebnisformat

structuredContent ist das kanonische erfolgreiche Ergebnis. Fehler auf Handler-Ebene setzen isError und liefern structuredContent.error. Fehler im Eingabeschema werden vom MCP-SDK vor dem Handler generiert und verwenden dessen standardmäßiges isError-Textergebnis ohne structuredContent. Andernfalls ist content nur eine kurze, für Menschen lesbare Zusammenfassung und darf nicht als Daten geparst werden.

Bewertungskonventionen

• Stockfish-Werte sind aus der Perspektive der am Zug befindlichen Seite: positives cp = die am Zug befindliche Seite ist besser; mate N = die am Zug befindliche Seite setzt in N Zügen matt. wdl ist [Sieg, Remis, Niederlage] in Promille für die am Zug befindliche Seite.

• move_candidates liefert moverCp (Perspektive des Zugspielers – höher ist besser für den Spieler, der den Zug wählt) und whiteCp (feste weiße Perspektive), sodass das Vorzeichen nie wechselt.

• move_evaluate meldet die Bewertung aus der Perspektive des Zugspielers, plus cpLoss (verlorene Centibauern gegenüber dem besten Zug) und eine Klassifizierung: best / excellent / good / inaccuracy / mistake / blunder.

• maia3Prob ist eine Menschlichkeitswahrscheinlichkeit, keine Zugqualität. Ein Zug mit hoher Wahrscheinlichkeit kann objektiv schlecht sein.

Kandidatenstruktur

move_candidates gibt jeden Kandidaten mit drei unabhängigen Facetten zurück:

{
  "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: Engine-Stärke, niemals mit Menschlichkeit verwechselt. moverCp ist aus der Perspektive des Zugspielers (höher = besser für den Wählenden).

• human — Maia3-bedingte Wahrscheinlichkeit bei einem Ziel-Elo.

• opening — Lichess-empirische Häufigkeit (ein anderes Signal als Maia3).

opening.status ist available, no_data (API ok, aber keine Partien in dieser Stellung), unavailable (Timeout/429/401) oder disabled (kein Token). Stockfish- und Maia3-Ergebnisse werden unabhängig davon immer zurückgegeben.

move_candidates gibt auch moveSensitivity zurück, das beschreibt, wie stark sich die Bewertung über die besten Engine-Linien ändert:

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

level ist low (<80cp-Spanne), medium (80–200cp) oder high (≥200cp). Hohe Sensitivität bedeutet, dass die Wahl unter plausiblen Alternativen die Bewertung wesentlich verändern kann – nützlich, um zu entscheiden, ob man nachlassen oder präzise spielen sollte.

Analyse-Stufen

Stockfish-Tools akzeptieren eine analysis_level-Voreinstellung anstelle roher UCI-Regler:

Explizite depth/multipv-Überschreibungen sind für fortgeschrittene Verwendung weiterhin verfügbar.

Schutz vor veralteten Stellungen

Jeder Zustandslesevorgang gibt eine revision zurück. game_play_move erfordert expected_revision; wenn sich die Partie seit Ihrem letzten Lesen weiterentwickelt hat, wird der Zug abgelehnt:

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

Laufzeitgrenzen

• Bis zu 1.000 Partie-Sitzungen werden aufbewahrt; inaktive Sitzungen laufen nach einer Stunde ab.

• move_evaluate akzeptiert höchstens 10 Züge pro Aufruf.

• Importierte PGNs sind auf 1 MiB und 4.096 Halbzüge begrenzt.

• Stockfish akzeptiert bis zu 32 aktive oder in der Warteschlange befindliche Analysen.

Absichten

move_candidates_by_intent sortiert Kandidaten für eine gewählte Absicht. Es ist eine Komfortschicht über move_candidates; die festen Schwellenwerte unten sind heuristische Standardwerte, nicht die Quelle der Wahrheit:

Dieses Tool sortiert Kandidaten, wählt aber keinen Zug. Verwenden Sie die zurückgegebenen Signale und den Gesprächskontext, um die endgültige Entscheidung zu treffen – bilden Sie das Können des Benutzers nicht mechanisch auf eine Absicht ab.

Beispielablauf

Die normale Spielschleife besteht aus drei Aufrufen:

1. create_game → game_id

2. move_candidates → einen Zug wählen

3. game_play_move (mit expected_revision) → ihn ausführen

Gehen Sie nur dann tiefer, wenn Sie es brauchen:

• position_analyze — objektive beste Linien

• human_move_distribution — was ein Mensch eines bestimmten Elo spielen würde

• opening_explorer — Statistiken aus echten Partien

• move_evaluate — einen bestimmten Zug bewerten (oder mehrere vergleichen)

Maia3-ONNX-Verifizierung

Das exportierte ONNX-Modell wird gegen die Upstream-Maia3-Implementierung über feste Stellungen und Elo-Paare regressionstestet:

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

Es prüft die Übereinstimmung der Top-1/Top-k-Züge und den maximalen Wahrscheinlichkeitsfehler, um Export-/Laufzeitregressionen zu erkennen. Das gebündelte maia3-5m.onnx besteht mit 100% Top-1- und Top-5-Übereinstimmung und einem maximalen Wahrscheinlichkeitsfehler < 1e-4.

Paketverifizierung

Paketartefakte werden lokal verifiziert; dieses Projekt hat bewusst keinen gehosteten CI-Workflow.

Führen Sie pnpm check für die deterministische Offline-Prüfung aus. Verwenden Sie pnpm test:package, um das Projekt zu packen, das Tarball in einem sauberen temporären Verzeichnis zu installieren und die installierte llm-chess-mcp-Binärdatei gegen die echten Stockfish- und Maia-Laufzeiten auszuführen. pnpm release:check führt beide Prüfungen plus das Produktionsabhängigkeits-Audit und den Paketmanifest-Trockenlauf aus.

Lizenz & Namensnennung

Dieses Projekt ist unter der AGPL-3.0 lizenziert (siehe LICENSE).

Es bündelt und hängt von Komponenten Dritter ab:

Das gebündelte Maia3-Modell (models/maia3-5m.onnx) ist abgeleitet von UofTCSSLab/Maia3-5M bei b6559de2398d7140b985f28fd2c19fb5e47ddabe. Der ONNX-Export ist ein Schritt zur Build-Zeit (scripts/export_maia3.py); die Laufzeitumgebung führt keinen Maia3-Python-Code aus.