llm-chess-mcp 0.1.2 → 0.1.3

package/.env.example

@@ -0,0 +1,9 @@
+# Lichess opening explorer (optional; explorer tools disabled if unset)
+# Generate at https://lichess.org/account/oauth/token/create
+LICHESS_TOKEN=
+
+# The published package bundles only Maia3 5m (~20 MB). Leave at 5m.
+MAIA3_MODEL=5m
+
+# Stockfish flavor: lite-single (default, ~7MB) | lite | single | full
+STOCKFISH_FLAVOR=lite-single

package/README.md

@@ -13,14 +13,18 @@ judgment; the MCP server handles all the computation.
 | 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`) |
+| **Maia3 5M** (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 external engine process or Python
-runtime is required at deploy time. Maia3 is exported to ONNX once at build time.
+runtime is required at deploy time. The published package bundles the Maia3 5M
+model; other export variants are not runtime options unless their ONNX files are
+provided separately.
 
 ## Install
 
+Requires Node.js 20 or newer.
+
 No install needed — run it directly with `npx`:
 
 ```bash
@@ -41,6 +45,7 @@ npm install -g llm-chess-mcp
 ```bash
 pnpm install
 pnpm build
+pnpm test
 ```
 
 ### Export Maia3 to ONNX (build-time only)
@@ -51,7 +56,7 @@ 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"
+uv pip install --python .venv-maia3/bin/python "maia3 @ git+https://github.com/CSSLab/maia3.git@1e13597c42d4858b7cfd7cfdae01e297263364b2"
 pnpm export:maia3            # -> models/maia3-5m.onnx
 ```
 
@@ -84,8 +89,7 @@ Add to `opencode.json` (project) or `~/.config/opencode/opencode.json` (global):
       "command": ["npx", "-y", "llm-chess-mcp"],
       "enabled": true,
       "environment": {
-        "LICHESS_TOKEN": "your-token",
-        "MAIA3_MODEL": "5m"
+        "LICHESS_TOKEN": "your-token"
       }
     }
   }
@@ -107,8 +111,7 @@ claude mcp add llm-chess-mcp -- npx -y llm-chess-mcp
       "command": "npx",
       "args": ["-y", "llm-chess-mcp"],
       "env": {
-        "LICHESS_TOKEN": "your-token",
-        "MAIA3_MODEL": "5m"
+        "LICHESS_TOKEN": "your-token"
       }
     }
   }
@@ -126,7 +129,6 @@ args = ["-y", "llm-chess-mcp"]
 
 [mcp_servers.llm-chess-mcp.env]
 LICHESS_TOKEN = "your-token"
-MAIA3_MODEL = "5m"
 ```
 
 Or via the CLI:
@@ -223,6 +225,13 @@ rejected:
 { "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }
 ```
 
+## Runtime limits
+
+- Up to 1,000 game sessions are retained; idle sessions expire after one hour.
+- `move_evaluate` accepts at most 10 moves per call.
+- Imported PGNs are limited to 1 MiB and 4,096 plies.
+- Stockfish accepts up to 32 active or queued analyses.
+
 ## Intents
 
 `move_candidates_by_intent` ranks candidates for a chosen intent. It is a
@@ -283,6 +292,7 @@ It bundles and depends on third-party components:
 | [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.
+The bundled Maia3 model (`models/maia3-5m.onnx`) is derived from
+[`UofTCSSLab/Maia3-5M` at `b6559de2398d7140b985f28fd2c19fb5e47ddabe`](https://huggingface.co/UofTCSSLab/Maia3-5M/tree/b6559de2398d7140b985f28fd2c19fb5e47ddabe).
+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

@@ -1,7 +1,34 @@
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
-function flavor() {
-    return process.env.STOCKFISH_FLAVOR || "lite-single";
+export const STOCKFISH_FLAVORS = [
+    "full",
+    "lite",
+    "single",
+    "lite-single",
+    "single-lite",
+    "asm",
+];
+const DEFAULT_FLAVOR = "lite-single";
+const FLAVORS = new Set(STOCKFISH_FLAVORS);
+const DEFAULT_TIMEOUTS = {
+    init: 15000,
+    handshake: 15000,
+    analyze: 30000,
+    stopGrace: 2000,
+};
+const DEFAULT_MAX_QUEUE = 32;
+export function resolveStockfishFlavor(value) {
+    const normalized = (value || DEFAULT_FLAVOR).toLowerCase();
+    if (!FLAVORS.has(normalized)) {
+        throw new Error(`invalid STOCKFISH_FLAVOR: ${JSON.stringify(value)}; expected one of ${STOCKFISH_FLAVORS.join(", ")}`);
+    }
+    return normalized;
+}
+function loadStockfish() {
+    return require("stockfish");
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
 }
 function parseScore(token) {
     if (token.startsWith("cp"))
@@ -17,56 +44,176 @@ function parseWdl(line) {
     return [Number(m[1]), Number(m[2]), Number(m[3])];
 }
 export class Stockfish {
-    engine = null;
-    ready = null;
+    session = null;
     queue = Promise.resolve();
+    queued = 0;
+    quitGeneration = 0;
+    terminated = new WeakSet();
+    initEngine;
+    configuredFlavor;
+    maxQueue;
+    timeouts;
+    constructor(options = {}) {
+        this.initEngine = options.init;
+        this.configuredFlavor = options.flavor;
+        this.maxQueue = options.maxQueue ?? DEFAULT_MAX_QUEUE;
+        this.timeouts = { ...DEFAULT_TIMEOUTS, ...options.timeouts };
+        if (!Number.isInteger(this.maxQueue) || this.maxQueue < 1) {
+            throw new Error("stockfish maxQueue must be a positive integer");
+        }
+        for (const [name, timeout] of Object.entries(this.timeouts)) {
+            if (!Number.isFinite(timeout) || timeout < 1) {
+                throw new Error(`stockfish ${name} timeout must be positive`);
+            }
+        }
+    }
     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 = () => { };
+        if (this.session)
+            return this.session.ready;
+        let resolve;
+        let reject;
+        const ready = new Promise((res, rej) => {
+            resolve = res;
+            reject = rej;
         });
-        return this.ready;
+        const session = {
+            engine: null,
+            ready,
+            initSettled: false,
+            initTimer: null,
+            resolve,
+            reject,
+            aborts: new Set(),
+        };
+        this.session = session;
+        session.initTimer = setTimeout(() => this.failSession(session, new Error("stockfish init timeout")), this.timeouts.init);
+        let callbackCalled = false;
+        try {
+            const selectedFlavor = resolveStockfishFlavor(this.configuredFlavor ?? process.env.STOCKFISH_FLAVOR);
+            const engine = (this.initEngine ?? loadStockfish())(selectedFlavor, (error, initializedEngine) => {
+                callbackCalled = true;
+                if (this.session !== session) {
+                    this.terminate(initializedEngine);
+                    return;
+                }
+                if (session.initSettled) {
+                    if (initializedEngine !== session.engine)
+                        this.terminate(initializedEngine);
+                    return;
+                }
+                if (session.engine && session.engine !== initializedEngine) {
+                    this.terminate(session.engine);
+                }
+                session.engine = initializedEngine;
+                if (error) {
+                    this.failSession(session, asError(error));
+                    return;
+                }
+                initializedEngine.listener = () => { };
+                if (session.initTimer)
+                    clearTimeout(session.initTimer);
+                session.initTimer = null;
+                this.handshake(session).then(() => {
+                    if (this.session !== session || session.initSettled)
+                        return;
+                    session.initSettled = true;
+                    session.resolve();
+                }, (handshakeError) => this.failSession(session, asError(handshakeError)));
+            });
+            if (!callbackCalled && this.session === session && !session.initSettled) {
+                session.engine = engine;
+                engine.listener = () => { };
+            }
+        }
+        catch (error) {
+            this.failSession(session, asError(error));
+        }
+        return ready;
     }
-    handshake() {
+    handshake(session) {
         return new Promise((resolve, reject) => {
-            const engine = this.engine;
+            const engine = session.engine;
+            if (!engine) {
+                reject(new Error("stockfish initialized without an engine"));
+                return;
+            }
             let stage = 0;
-            const timer = setTimeout(() => reject(new Error("stockfish handshake timeout")), 15000);
-            engine.listener = (line) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                session.aborts.delete(abort);
+                if (engine.listener === listener)
+                    engine.listener = null;
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const abort = (error) => finish(error);
+            const listener = (line) => {
                 if (stage === 0 && line === "uciok") {
                     stage = 1;
-                    engine.sendCommand("isready");
+                    try {
+                        engine.sendCommand("isready");
+                    }
+                    catch (error) {
+                        finish(asError(error));
+                    }
                 }
                 else if (stage === 1 && line === "readyok") {
-                    clearTimeout(timer);
-                    engine.listener = null;
-                    resolve();
+                    finish();
                 }
             };
-            engine.sendCommand("uci");
+            const timer = setTimeout(() => finish(new Error("stockfish handshake timeout")), this.timeouts.handshake);
+            session.aborts.add(abort);
+            engine.listener = listener;
+            try {
+                engine.sendCommand("uci");
+            }
+            catch (error) {
+                finish(asError(error));
+            }
         });
     }
     enqueue(fn) {
-        const run = this.queue.then(fn, fn);
-        this.queue = run.catch(() => { });
-        return run;
+        if (this.queued >= this.maxQueue) {
+            return Promise.reject(new Error("stockfish queue full"));
+        }
+        this.queued++;
+        const run = this.queue.then(fn);
+        this.queue = run.then(() => { }, () => { });
+        return run.finally(() => {
+            this.queued--;
+        });
     }
-    async analyze(fen, depth, multipv) {
-        await this.init();
-        return this.enqueue(() => this.doAnalyze(fen, depth, multipv));
+    analyze(fen, depth, multipv) {
+        const quitGeneration = this.quitGeneration;
+        return this.enqueue(async () => {
+            if (quitGeneration !== this.quitGeneration) {
+                throw new Error("stockfish request cancelled");
+            }
+            await this.init();
+            if (quitGeneration !== this.quitGeneration) {
+                throw new Error("stockfish request cancelled");
+            }
+            const session = this.session;
+            if (!session)
+                throw new Error("stockfish unavailable after initialization");
+            return this.doAnalyze(session, fen, depth, multipv);
+        });
     }
-    doAnalyze(fen, depth, multipv) {
+    doAnalyze(session, fen, depth, multipv) {
         return new Promise((resolve, reject) => {
-            const engine = this.engine;
+            const engine = session.engine;
+            if (!engine) {
+                reject(new Error("stockfish engine unavailable"));
+                return;
+            }
             const byPv = new Map();
+            let settled = false;
             let stopTimer = null;
             let failTimer = null;
             const cleanup = () => {
@@ -76,8 +223,28 @@ export class Stockfish {
                     clearTimeout(failTimer);
                 stopTimer = null;
                 failTimer = null;
+                session.aborts.delete(abort);
+                if (engine.listener === listener)
+                    engine.listener = null;
             };
-            engine.listener = (line) => {
+            const succeed = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve([...byPv.values()].sort((a, b) => a.multipv - b.multipv));
+            };
+            const fail = (error, reset) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                if (reset)
+                    this.invalidateSession(session, error);
+                reject(error);
+            };
+            const abort = (error) => fail(error, false);
+            const listener = (line) => {
                 if (line.startsWith("info") && line.includes(" multipv ")) {
                     const m = line.match(/multipv (\d+)/);
                     const s = line.match(/ score (cp -?\d+|mate -?\d+)/);
@@ -95,39 +262,77 @@ export class Stockfish {
                     });
                 }
                 else if (line.startsWith("bestmove")) {
-                    cleanup();
-                    engine.listener = null;
-                    resolve([...byPv.values()].sort((a, b) => a.multipv - b.multipv));
+                    succeed();
                 }
             };
-            engine.sendCommand("position fen " + fen);
-            engine.sendCommand(`setoption name MultiPV value ${multipv}`);
-            engine.sendCommand("setoption name UCI_ShowWDL value true");
-            engine.sendCommand(`go depth ${depth}`);
+            session.aborts.add(abort);
+            engine.listener = listener;
             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) {
+                failTimer = setTimeout(() => fail(new Error("stockfish analyze timeout"), true), this.timeouts.stopGrace);
+                try {
+                    engine.sendCommand("stop");
+                }
+                catch (error) {
+                    fail(asError(error), true);
+                }
+            }, this.timeouts.analyze);
             try {
-                this.engine.terminate();
+                engine.sendCommand("position fen " + fen);
+                engine.sendCommand(`setoption name MultiPV value ${multipv}`);
+                engine.sendCommand("setoption name UCI_ShowWDL value true");
+                engine.sendCommand(`go depth ${depth}`);
+            }
+            catch (error) {
+                fail(asError(error), true);
+                return;
             }
-            catch { }
+        });
+    }
+    failSession(session, error) {
+        if (session.initSettled)
+            return;
+        session.initSettled = true;
+        if (session.initTimer)
+            clearTimeout(session.initTimer);
+        session.initTimer = null;
+        this.invalidateSession(session, error);
+        session.reject(error);
+    }
+    invalidateSession(session, error) {
+        if (this.session !== session)
+            return;
+        this.session = null;
+        if (session.initTimer)
+            clearTimeout(session.initTimer);
+        session.initTimer = null;
+        if (!session.initSettled) {
+            session.initSettled = true;
+            session.reject(error);
+        }
+        const aborts = [...session.aborts];
+        session.aborts.clear();
+        if (session.engine) {
+            session.engine.listener = null;
+            this.terminate(session.engine);
+        }
+        for (const abort of aborts)
+            abort(error);
+    }
+    terminate(engine) {
+        if (this.terminated.has(engine))
+            return;
+        this.terminated.add(engine);
+        engine.listener = null;
+        try {
+            engine.terminate();
         }
-        this.engine = null;
-        this.ready = null;
+        catch { }
     }
     async quit() {
-        this.reset();
+        this.quitGeneration++;
+        const session = this.session;
+        if (session)
+            this.invalidateSession(session, new Error("stockfish quit"));
     }
 }
 export const stockfish = new Stockfish();

package/dist/env.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+const ALLOWED_KEYS = new Set(["LICHESS_TOKEN", "MAIA3_MODEL", "STOCKFISH_FLAVOR"]);
 export function loadEnv(path = ".env") {
     let text;
     try {
@@ -17,7 +18,7 @@ export function loadEnv(path = ".env") {
             continue;
         const key = trimmed.slice(0, eq).trim();
         const value = trimmed.slice(eq + 1).trim();
-        if (key && process.env[key] === undefined) {
+        if (ALLOWED_KEYS.has(key) && process.env[key] === undefined) {
             process.env[key] = value.replace(/^["']|["']$/g, "");
         }
     }

package/dist/games.js

@@ -2,36 +2,63 @@ import { Chess } from "chess.js";
 import { randomUUID } from "node:crypto";
 import { ChessError } from "./errors.js";
 const games = new Map();
-export function createGame(fen) {
+export const MAX_GAMES = 1_000;
+export const GAME_TTL_MS = 60 * 60 * 1_000;
+function isExpired(game, now) {
+    return now - game.lastAccessedAt >= GAME_TTL_MS;
+}
+export function cleanupGames(now = Date.now()) {
+    let removed = 0;
+    for (const [id, game] of games) {
+        if (!isExpired(game, now))
+            continue;
+        games.delete(id);
+        removed += 1;
+    }
+    return removed;
+}
+function storeGame(chess) {
+    cleanupGames();
+    if (games.size >= MAX_GAMES) {
+        throw new ChessError("GAME_LIMIT_REACHED", `game session limit reached: ${MAX_GAMES}`);
+    }
     const id = randomUUID();
-    const chess = fen ? new Chess(fen) : new Chess();
-    games.set(id, { chess, createdAt: Date.now(), revision: 0 });
+    const now = Date.now();
+    games.set(id, { chess, createdAt: now, lastAccessedAt: now, revision: 0 });
     return id;
 }
+export function createGame(fen) {
+    const chess = fen ? new Chess(fen) : new Chess();
+    return storeGame(chess);
+}
 export function createGameFromChess(chess) {
-    const id = randomUUID();
-    games.set(id, { chess, createdAt: Date.now(), revision: 0 });
-    return id;
+    return storeGame(chess);
 }
 export function getGame(id) {
     const g = games.get(id);
     if (!g)
         throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
+    if (isExpired(g, Date.now())) {
+        games.delete(id);
+        throw new ChessError("GAME_EXPIRED", `game expired: ${id}`);
+    }
+    g.lastAccessedAt = Date.now();
     return g;
 }
 export function bumpRevision(id) {
-    const g = games.get(id);
-    if (!g)
-        throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
+    const g = getGame(id);
     g.revision += 1;
     return g.revision;
 }
 export function deleteGame(id) {
+    cleanupGames();
     return games.delete(id);
 }
 export function listGames() {
+    cleanupGames();
     return [...games.keys()];
 }
 export function gameCount() {
+    cleanupGames();
     return games.size;
 }

package/dist/index.js

@@ -3,6 +3,9 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
 import { Chess } from "chess.js";
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
 import { loadEnv } from "./env.js";
 import { createGame, createGameFromChess, getGame, deleteGame, bumpRevision, } from "./games.js";
 import { stockfish } from "./engines/stockfish.js";
@@ -19,9 +22,54 @@ const INTENTS = [
     "ease_off",
     "give_chance",
 ];
+const { version: SERVER_VERSION } = createRequire(import.meta.url)("../package.json");
+export const MAX_EVALUATED_MOVES = 10;
+export const MAX_PGN_BYTES = 1024 * 1024;
+export const MAX_PGN_PLIES = 4096;
 function text(data) {
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
+function errorText(data) {
+    return { ...text(data), isError: true };
+}
+export function snapshotChess(chess) {
+    const history = chess.history({ verbose: true });
+    const snapshot = new Chess(history[0]?.before ?? chess.fen());
+    for (const move of history) {
+        snapshot.move({ from: move.from, to: move.to, promotion: move.promotion });
+    }
+    return snapshot;
+}
+export function drawResult(chess) {
+    if (!chess.isDraw())
+        return null;
+    if (chess.isStalemate())
+        return "stalemate";
+    if (chess.isInsufficientMaterial())
+        return "insufficient_material";
+    if (chess.isThreefoldRepetition())
+        return "threefold_repetition";
+    if (chess.isDrawByFiftyMoves())
+        return "fifty_move_rule";
+    return "draw";
+}
+export function parseImportedPgn(pgn) {
+    if (Buffer.byteLength(pgn, "utf8") > MAX_PGN_BYTES) {
+        throw new ChessError("PGN_TOO_LARGE", `PGN exceeds the ${MAX_PGN_BYTES}-byte limit`);
+    }
+    let chess;
+    try {
+        chess = new Chess();
+        chess.loadPgn(pgn);
+    }
+    catch {
+        throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
+    }
+    if (chess.history().length > MAX_PGN_PLIES) {
+        throw new ChessError("PGN_TOO_MANY_MOVES", `PGN exceeds the ${MAX_PGN_PLIES}-ply limit`);
+    }
+    return chess;
+}
 function stateOf(chess, revision) {
     const last = chess.history({ verbose: true }).at(-1);
     return {
@@ -65,15 +113,15 @@ function wrap(handler) {
         }
         catch (e) {
             if (e instanceof ChessError) {
-                return text({ error: { code: e.code, message: e.message } });
+                return errorText({ error: { code: e.code, message: e.message } });
             }
             const msg = e instanceof Error ? e.message : String(e);
-            return text({ error: { code: "INTERNAL", message: msg } });
+            return errorText({ error: { code: "INTERNAL", message: msg } });
         }
     };
 }
 export function buildServer() {
-    const server = new McpServer({ name: "llm-chess-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: "llm-chess-mcp", version: SERVER_VERSION }, { capabilities: { tools: {} } });
     server.registerTool("create_game", {
         description: "Create a new chess game and return its game_id. The server is the authoritative source of board state — never track the board yourself. Optionally pass a FEN to start from a custom position.",
         inputSchema: z.object({
@@ -84,7 +132,9 @@ export function buildServer() {
         try {
             id = createGame(fen);
         }
-        catch {
+        catch (e) {
+            if (e instanceof ChessError)
+                throw e;
             throw new ChessError("INVALID_FEN", "invalid FEN");
         }
         return text({ game_id: id, revision: 0 });
@@ -137,7 +187,7 @@ export function buildServer() {
         description: "List all legal moves in the current position (SAN, UCI, piece, capture, promotion).",
         inputSchema: z.object({ game_id: z.string() }),
     }, wrap(async ({ game_id }) => {
-        const { chess } = getGame(game_id);
+        const { chess, revision } = getGame(game_id);
         const moves = chess.moves({ verbose: true }).map((m) => ({
             san: m.san,
             uci: m.lan,
@@ -149,7 +199,7 @@ export function buildServer() {
             isCapture: m.flags.includes("c"),
             isCheck: m.san.includes("+") || m.san.includes("#"),
         }));
-        return text({ game_id, count: moves.length, moves });
+        return text({ game_id, revision, count: moves.length, moves });
     }));
     server.registerTool("position_analyze", {
         description: "Run Stockfish on the current position and return the top engine lines (multipv). Scores are from the side-to-move perspective: positive cp = side to move is better; mate N = side to move mates in N. wdl is [win, draw, loss] in permille for the side to move. Use analysis_level (fast/normal/deep) or explicit depth/multipv. Does NOT mutate the game.",
@@ -160,7 +210,8 @@ export function buildServer() {
             multipv: z.number().int().min(1).max(10).optional(),
         }),
     }, wrap(async ({ game_id, analysis_level, depth, multipv }) => {
-        const { chess, revision } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const preset = ANALYSIS_PRESETS[analysis_level];
         const d = depth ?? preset.depth;
         const mpv = multipv ?? preset.multipv;
@@ -189,7 +240,8 @@ export function buildServer() {
             top_n: z.number().int().min(1).max(20).default(5),
         }),
     }, wrap(async ({ game_id, elo, oppo_elo, top_n }) => {
-        const { chess, revision } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const moves = await humanMoveDistribution(chess, elo, oppo_elo ?? elo, top_n);
         return text({ game_id, elo, oppo_elo: oppo_elo ?? elo, revision, moves });
     }));
@@ -197,11 +249,15 @@ export function buildServer() {
         description: "Evaluate one or more moves with Stockfish without mutating the game. Pass a single move string or an array of moves to compare. Returns, for each move, the score after the move (from the mover's perspective), cpLoss vs the best move, and a classification (best/excellent/good/inaccuracy/mistake/blunder).",
         inputSchema: z.object({
             game_id: z.string(),
-            move: z.union([z.string(), z.array(z.string())]),
+            move: z.union([
+                z.string(),
+                z.array(z.string()).min(1).max(MAX_EVALUATED_MOVES),
+            ]),
             depth: z.number().int().min(1).max(30).default(15),
         }),
     }, wrap(async ({ game_id, move, depth }) => {
-        const { chess, revision } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const moves = Array.isArray(move) ? move : [move];
         const beforeLines = await stockfish.analyze(chess.fen(), depth, 1);
         const before = beforeLines[0];
@@ -210,7 +266,7 @@ export function buildServer() {
         const results = [];
         for (const mv of moves) {
             const m = parseMove(chess, mv);
-            const copy = new Chess(chess.fen());
+            const copy = snapshotChess(chess);
             copy.move({ from: m.from, to: m.to, promotion: m.promotion });
             if (copy.isCheckmate()) {
                 results.push({
@@ -226,11 +282,12 @@ export function buildServer() {
                 });
                 continue;
             }
-            if (copy.isStalemate()) {
+            const result = drawResult(copy);
+            if (result) {
                 results.push({
                     move: m.san,
                     uci: m.lan,
-                    result: "stalemate",
+                    result,
                     scoreCp: 0,
                     scoreMate: null,
                     bestCp: beforeCp,
@@ -275,7 +332,8 @@ export function buildServer() {
             lichess_ratings: z.array(z.number().int()).default([]),
         }),
     }, wrap(async ({ game_id, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
-        const { chess, revision } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const preset = ANALYSIS_PRESETS[analysis_level];
         const d = sf_depth ?? preset.depth;
         const mpv = sf_multipv ?? preset.multipv;
@@ -306,7 +364,8 @@ export function buildServer() {
             lichess_ratings: z.array(z.number().int()).default([]),
         }),
     }, wrap(async ({ game_id, intent, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
-        const { chess, revision } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const preset = ANALYSIS_PRESETS[analysis_level];
         const d = sf_depth ?? preset.depth;
         const mpv = sf_multipv ?? preset.multipv;
@@ -336,33 +395,37 @@ export function buildServer() {
         if (!explorerEnabled()) {
             throw new ChessError("LICHESS_DISABLED", "LICHESS_TOKEN not set; opening explorer is disabled");
         }
-        const { chess } = getGame(game_id);
+        const { chess: live, revision } = getGame(game_id);
+        const chess = snapshotChess(live);
         const result = await openingExplorer(chess, db, speeds, ratings);
-        return text({ game_id, ...result });
+        return text({ game_id, revision, ...result });
     }));
     server.registerTool("game_pgn", {
         description: "Export the current game as PGN.",
         inputSchema: z.object({ game_id: z.string() }),
     }, wrap(async ({ game_id }) => {
-        const { chess } = getGame(game_id);
-        return text({ game_id, pgn: chess.pgn() });
+        const { chess, revision } = getGame(game_id);
+        return text({ game_id, revision, pgn: chess.pgn() });
     }));
     server.registerTool("game_import_pgn", {
         description: "Import a PGN into a new game. Returns a new game_id with the position after all PGN moves. Rejects malformed or illegal PGN.",
         inputSchema: z.object({ pgn: z.string() }),
     }, wrap(async ({ pgn }) => {
-        let chess;
-        try {
-            chess = new Chess();
-            chess.loadPgn(pgn);
-        }
-        catch {
-            throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
-        }
+        const chess = parseImportedPgn(pgn);
         const id = createGameFromChess(chess);
         return text({ game_id: id, ...stateOf(chess, 0) });
     }));
     return server;
 }
 loadEnv();
-serveStdio(() => buildServer());
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+    const handle = serveStdio(() => buildServer());
+    let shutdown = null;
+    const close = () => (shutdown ??= Promise.all([stockfish.quit(), handle.close()]).then(() => { }));
+    const onClose = () => {
+        void close().catch((error) => console.error("shutdown failed", error));
+    };
+    process.stdin.once("end", onClose);
+    process.stdin.once("close", onClose);
+}

package/dist/intents.js

@@ -186,11 +186,5 @@ export function rankByIntent(candidates, intent) {
         .filter((x) => x.score !== -Infinity)
         .sort((a, b) => b.score - a.score)
         .map((x) => x.c);
-    if (ranked.length === 0 && (intent === "ease_off" || intent === "give_chance")) {
-        const human = candidates.filter((c) => c.human.maia3Prob !== null && c.objective.moverCp !== null);
-        return human
-            .sort((a, b) => (a.objective.moverCp ?? -Infinity) - (b.objective.moverCp ?? -Infinity))
-            .slice(0, 5);
-    }
     return ranked;
 }

package/dist/maia3/inference.js

@@ -5,29 +5,37 @@ import { dirname, resolve } from "node:path";
 import { buildInput } from "./tokenize.js";
 import { vocabIndex } from "./vocab.js";
 import { mirrorMove } from "./mirror.js";
-const MODEL_KEY = process.env.MAIA3_MODEL || "5m";
 let session = null;
 let sessionPromise = null;
+const MODEL_KEYS = new Set(["3m", "5m", "23m", "79m"]);
 function modelPath() {
+    const modelKey = process.env.MAIA3_MODEL || "5m";
+    if (!MODEL_KEYS.has(modelKey))
+        throw new Error(`unsupported Maia3 model: ${modelKey}`);
     const here = dirname(fileURLToPath(import.meta.url));
     const candidates = [
-        resolve(here, "../../models", `maia3-${MODEL_KEY}.onnx`),
-        resolve(process.cwd(), "models", `maia3-${MODEL_KEY}.onnx`),
+        resolve(here, "../../models", `maia3-${modelKey}.onnx`),
+        resolve(process.cwd(), "models", `maia3-${modelKey}.onnx`),
     ];
     for (const c of candidates) {
         if (existsSync(c))
             return c;
     }
-    throw new Error(`maia3 model not found (models/maia3-${MODEL_KEY}.onnx). Run \`pnpm export:maia3\` first.`);
+    throw new Error(`maia3 model not found (models/maia3-${modelKey}.onnx). Run \`pnpm export:maia3\` first.`);
 }
 async function getSession() {
     if (session)
         return session;
     if (sessionPromise)
         return sessionPromise;
-    sessionPromise = ort.InferenceSession.create(modelPath()).then((s) => {
+    sessionPromise = ort.InferenceSession.create(modelPath())
+        .then((s) => {
         session = s;
         return s;
+    })
+        .catch((error) => {
+        sessionPromise = null;
+        throw error;
     });
     return sessionPromise;
 }

package/dist/maia3/tokenize.js

@@ -28,13 +28,13 @@ function tokenizeBoard(chess) {
 }
 function historyPositions(chess) {
     const moves = chess.history({ verbose: true });
-    const positions = [new Chess()];
-    const replay = new Chess();
-    for (const m of moves) {
-        replay.move({ from: m.from, to: m.to, promotion: m.promotion });
-        positions.push(new Chess(replay.fen()));
-    }
-    return positions;
+    if (moves.length >= HISTORY)
+        return moves.slice(-HISTORY).map((move) => new Chess(move.after));
+    if (moves.length)
+        return [new Chess(moves[0].before), ...moves.map((move) => new Chess(move.after))];
+    const headers = chess.getHeaders();
+    const initialFen = headers.SetUp === "1" && headers.FEN ? headers.FEN : chess.fen();
+    return [new Chess(initialFen)];
 }
 export function buildInput(chess) {
     const positions = historyPositions(chess);

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "llm-chess-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "MCP server that lets an LLM analyze, judge, and choose chess moves (Stockfish + Maia3 + Lichess)",
   "type": "module",
   "license": "AGPL-3.0",
+  "engines": {
+    "node": ">=20"
+  },
   "bin": {
     "llm-chess-mcp": "dist/index.js"
   },
@@ -11,12 +14,14 @@
     "dist",
     "models",
     "LICENSE",
-    "README.md"
+    "README.md",
+    ".env.example"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
+    "test": "tsx --test tests/*.test.ts",
     "export:maia3": "python scripts/export_maia3.py"
   },
   "dependencies": {