llm-chess-mcp 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# llm-chess-mcp
+
+An MCP server for truly enjoying chess games with your LLM. It adds a feature that, rather than simply making the best move, allows it to think and judge on its own and make moves. the MCP server handles all the computation (Stockfish evaluation, Maia3 human-move prediction, Lichess opening statistics).
+
+## Engines
+
+| Engine | Role | Runtime |
+|---|---|---|
+| **Stockfish 18** (WASM) | Objective evaluation, best moves, multipv | In-process (npm `stockfish`) |
+| **Maia3** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
+| **Lichess explorer** | Real human game statistics | HTTP (needs token) |
+
+Everything runs inside the Node process — no separate engine binaries or Python
+runtime needed at deploy time. Maia3 is exported to ONNX once at build time.
+
+## Install
+
+```bash
+pnpm install
+pnpm build
+```
+
+### Export Maia3 to ONNX (build-time only)
+
+This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
+the reimplementation against the original, and exports `models/maia3-5m.onnx`.
+
+```bash
+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"
+pnpm export:maia3            # -> models/maia3-5m.onnx
+```
+
+The resulting `.onnx` is committed/bundled; end users never need Python or torch.
+
+### Lichess token (optional)
+
+The opening explorer now requires authentication. Generate a personal access token
+at <https://lichess.org/account/oauth/token/create> and set it in `.env`:
+
+```bash
+cp .env.example .env
+# set LICHESS_TOKEN=...
+```
+
+Without a token, `opening_explorer` returns a disabled notice; all other tools work.
+
+## Configure in your MCP client
+
+### opencode
+
+Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "llm-chess-mcp": {
+      "type": "local",
+      "command": ["node", "/path/to/llm-chess-mcp/dist/index.js"],
+      "enabled": true,
+      "environment": {
+        "LICHESS_TOKEN": "your-token",
+        "MAIA3_MODEL": "5m"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` (project) or `~/.claude.json` (global), or run:
+
+```bash
+claude mcp add llm-chess-mcp -- node /path/to/llm-chess-mcp/dist/index.js
+```
+
+```json
+{
+  "mcpServers": {
+    "llm-chess-mcp": {
+      "command": "node",
+      "args": ["/path/to/llm-chess-mcp/dist/index.js"],
+      "env": {
+        "LICHESS_TOKEN": "your-token",
+        "MAIA3_MODEL": "5m"
+      }
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.llm-chess-mcp]
+command = "node"
+args = ["/path/to/llm-chess-mcp/dist/index.js"]
+
+[mcp_servers.llm-chess-mcp.env]
+LICHESS_TOKEN = "your-token"
+MAIA3_MODEL = "5m"
+```
+
+Or via the CLI:
+
+```bash
+codex mcp add llm-chess-mcp --command node --args /path/to/llm-chess-mcp/dist/index.js --env LICHESS_TOKEN=your-token
+```
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `create_game` | Create a game (optionally from a FEN), returns `game_id` |
+| `delete_game` | Delete a game and free its session |
+| `game_state` | Authoritative state: FEN, turn, check/mate/draw flags, history, last move, castling |
+| `game_state_ascii` | ASCII board diagram |
+| `game_play_move` | Play a move (SAN or UCI) — the only mutating tool |
+| `game_legal_moves` | All legal moves with metadata |
+| `game_pgn` | Export the game as PGN |
+| `game_import_pgn` | Import a PGN into a new game |
+| `position_analyze` | Stockfish multipv lines (cp/mate + PV) |
+| `human_move_distribution` | Maia3 human-move probabilities at a target Elo |
+| `move_evaluate` | Score a move + cpLoss + classification |
+| `move_candidates` | Unified candidates (SF eval + cpLoss + Maia3 prob + Lichess stats) |
+| `move_candidates_by_intent` | Candidates ranked for a strategic intent |
+| `opening_explorer` | Lichess human game statistics |
+
+## Score conventions
+
+- Stockfish scores are **side-to-move perspective**: positive cp = side to move is
+  better; `mate N` = side to move mates in N.
+- `move_evaluate` reports the score **from the mover's perspective** (negated after
+  the move), plus `cpLoss` (centipawns lost vs the best move) and a classification:
+  `best / excellent / good / inaccuracy / mistake / blunder`.
+- `maia3Prob` is a **human-likelihood**, not move quality. A high-probability move
+  can still be objectively bad.
+
+## Intents
+
+`move_candidates_by_intent` ranks candidates for a chosen intent:
+
+| Intent | Meaning |
+|---|---|
+| `best` | Strongest engine move |
+| `strong` | Engine-strong but human-plausible |
+| `natural` | Most human-typical at the target Elo |
+| `balanced` | Blend of strength and human-likeness |
+| `ease_off` | Slightly weaker (−30..−80cp) but human |
+| `give_chance` | Clearly weaker (−80..−150cp), gives the opponent chances |
+
+## Example flow
+
+1. `create_game` → `game_id`
+2. `position_analyze` to see the objective best lines
+3. `human_move_distribution` to see what a human of a given Elo would play
+4. `move_candidates_by_intent` with the intent that fits the situation
+5. `game_play_move` to commit the chosen move
+
+## License & attribution
+
+This project is licensed under the **AGPL-3.0** (see `LICENSE`).
+
+It bundles and depends on third-party components:
+
+| Component | License | Source |
+|---|---|---|
+| [Maia3](https://github.com/CSSLab/maia3) (Chessformer) | AGPL-3.0 | UofT CSSLab — Monroe et al., *Chessformer: A Unified Architecture for Chess Modeling* (ICLR 2026) |
+| [Stockfish](https://github.com/official-stockfish/Stockfish) (via npm `stockfish`) | GPL-3.0 | The Stockfish developers |
+| [onnxruntime-node](https://github.com/microsoft/onnxruntime) | MIT | Microsoft |
+| [chess.js](https://github.com/jhlywa/chess.js) | BSD-2-Clause | Jeff Hlywa |
+
+The Maia3 model weights (`models/maia3-5m.onnx`) are derived from the
+`UofTCSSLab/Maia3-5M` checkpoint. The ONNX export is a build-time step
+(`scripts/export_maia3.py`); the runtime does not execute any Maia3 Python code.

package/dist/engines/stockfish.js

@@ -0,0 +1,125 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+function flavor() {
+    return process.env.STOCKFISH_FLAVOR || "lite-single";
+}
+function parseScore(token) {
+    if (token.startsWith("cp"))
+        return { cp: Number(token.slice(2)), mate: null };
+    if (token.startsWith("mate"))
+        return { cp: null, mate: Number(token.slice(4)) };
+    return { cp: null, mate: null };
+}
+export class Stockfish {
+    engine = null;
+    ready = null;
+    queue = Promise.resolve();
+    init() {
+        if (this.ready)
+            return this.ready;
+        this.ready = new Promise((resolve, reject) => {
+            const init = require("stockfish");
+            const engine = init(flavor(), (err) => {
+                if (err)
+                    return reject(err);
+                this.handshake().then(resolve, reject);
+            });
+            this.engine = engine;
+            engine.listener = () => { };
+        });
+        return this.ready;
+    }
+    handshake() {
+        return new Promise((resolve, reject) => {
+            const engine = this.engine;
+            let stage = 0;
+            const timer = setTimeout(() => reject(new Error("stockfish handshake timeout")), 15000);
+            engine.listener = (line) => {
+                if (stage === 0 && line === "uciok") {
+                    stage = 1;
+                    engine.sendCommand("isready");
+                }
+                else if (stage === 1 && line === "readyok") {
+                    clearTimeout(timer);
+                    engine.listener = null;
+                    resolve();
+                }
+            };
+            engine.sendCommand("uci");
+        });
+    }
+    enqueue(fn) {
+        const run = this.queue.then(fn, fn);
+        this.queue = run.catch(() => { });
+        return run;
+    }
+    async analyze(fen, depth, multipv) {
+        await this.init();
+        return this.enqueue(() => this.doAnalyze(fen, depth, multipv));
+    }
+    doAnalyze(fen, depth, multipv) {
+        return new Promise((resolve, reject) => {
+            const engine = this.engine;
+            const byPv = new Map();
+            let stopTimer = null;
+            let failTimer = null;
+            const cleanup = () => {
+                if (stopTimer)
+                    clearTimeout(stopTimer);
+                if (failTimer)
+                    clearTimeout(failTimer);
+                stopTimer = null;
+                failTimer = null;
+            };
+            engine.listener = (line) => {
+                if (line.startsWith("info") && line.includes(" multipv ")) {
+                    const m = line.match(/multipv (\d+)/);
+                    const s = line.match(/ score (cp -?\d+|mate -?\d+)/);
+                    const pv = line.match(/ pv (.+)$/);
+                    if (!m)
+                        return;
+                    const n = Number(m[1]);
+                    const score = s ? parseScore(s[1]) : { cp: null, mate: null };
+                    byPv.set(n, {
+                        multipv: n,
+                        scoreCp: score.cp,
+                        scoreMate: score.mate,
+                        pv: pv ? pv[1].split(" ") : [],
+                    });
+                }
+                else if (line.startsWith("bestmove")) {
+                    cleanup();
+                    engine.listener = null;
+                    resolve([...byPv.values()].sort((a, b) => a.multipv - b.multipv));
+                }
+            };
+            engine.sendCommand("position fen " + fen);
+            engine.sendCommand(`setoption name MultiPV value ${multipv}`);
+            engine.sendCommand(`go depth ${depth}`);
+            stopTimer = setTimeout(() => {
+                engine.sendCommand("stop");
+                failTimer = setTimeout(() => {
+                    if (engine.listener) {
+                        engine.listener = null;
+                        this.reset();
+                        reject(new Error("stockfish analyze timeout"));
+                    }
+                }, 2000);
+            }, 30000);
+        });
+    }
+    reset() {
+        if (this.engine) {
+            try {
+                this.engine.terminate();
+            }
+            catch { }
+        }
+        this.engine = null;
+        this.ready = null;
+    }
+    async quit() {
+        this.reset();
+    }
+}
+export const stockfish = new Stockfish();

package/dist/env.js

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+export function loadEnv(path = ".env") {
+    let text;
+    try {
+        text = readFileSync(resolve(process.cwd(), path), "utf8");
+    }
+    catch {
+        return;
+    }
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq).trim();
+        const value = trimmed.slice(eq + 1).trim();
+        if (key && process.env[key] === undefined) {
+            process.env[key] = value.replace(/^["']|["']$/g, "");
+        }
+    }
+}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class ChessError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "ChessError";
+    }
+}
+export function fail(code, message) {
+    throw new ChessError(code, message);
+}

package/dist/eval.js

@@ -0,0 +1,27 @@
+export function scoreToCp(line) {
+    if (line.scoreMate !== null) {
+        const sign = line.scoreMate >= 0 ? 1 : -1;
+        return sign * (10000 - Math.abs(line.scoreMate) * 100);
+    }
+    return line.scoreCp ?? 0;
+}
+export const CLASSIFICATION = {
+    best: 0,
+    excellent: 30,
+    good: 80,
+    inaccuracy: 150,
+    mistake: 300,
+};
+export function classifyCpLoss(cpLoss) {
+    if (cpLoss <= CLASSIFICATION.best)
+        return "best";
+    if (cpLoss < CLASSIFICATION.excellent)
+        return "excellent";
+    if (cpLoss < CLASSIFICATION.good)
+        return "good";
+    if (cpLoss < CLASSIFICATION.inaccuracy)
+        return "inaccuracy";
+    if (cpLoss < CLASSIFICATION.mistake)
+        return "mistake";
+    return "blunder";
+}

package/dist/explorer.js

@@ -0,0 +1,38 @@
+const BASE = "https://explorer.lichess.org";
+export function explorerEnabled() {
+    return (process.env.LICHESS_TOKEN || "").length > 0;
+}
+export async function openingExplorer(chess, db, speeds, ratings) {
+    if (!explorerEnabled()) {
+        throw new Error("LICHESS_TOKEN not set; opening explorer is disabled");
+    }
+    const params = new URLSearchParams();
+    params.set("fen", chess.fen());
+    if (speeds.length)
+        params.set("speeds", speeds.join(","));
+    if (ratings.length)
+        params.set("ratings", ratings.join(","));
+    const res = await fetch(`${BASE}/${db}?${params}`, {
+        headers: { Authorization: `Bearer ${process.env.LICHESS_TOKEN}` },
+    });
+    if (!res.ok) {
+        throw new Error(`lichess explorer ${db} failed: HTTP ${res.status}`);
+    }
+    const data = (await res.json());
+    return {
+        db,
+        white: data.white,
+        draws: data.draws,
+        black: data.black,
+        moves: data.moves.map((m) => ({
+            uci: m.uci,
+            san: m.san,
+            white: m.white,
+            draws: m.draws,
+            black: m.black,
+            count: m.white + m.draws + m.black,
+            averageRating: m.averageRating ?? null,
+        })),
+        opening: data.opening ?? null,
+    };
+}

package/dist/games.js

@@ -0,0 +1,30 @@
+import { Chess } from "chess.js";
+import { randomUUID } from "node:crypto";
+import { ChessError } from "./errors.js";
+const games = new Map();
+export function createGame(fen) {
+    const id = randomUUID();
+    const chess = fen ? new Chess(fen) : new Chess();
+    games.set(id, { chess, createdAt: Date.now() });
+    return id;
+}
+export function createGameFromChess(chess) {
+    const id = randomUUID();
+    games.set(id, { chess, createdAt: Date.now() });
+    return id;
+}
+export function getGame(id) {
+    const g = games.get(id);
+    if (!g)
+        throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
+    return g;
+}
+export function deleteGame(id) {
+    return games.delete(id);
+}
+export function listGames() {
+    return [...games.keys()];
+}
+export function gameCount() {
+    return games.size;
+}