llm-chess-mcp 0.4.9 → 0.5.0

package/README.md

@@ -13,13 +13,14 @@ judgment; the MCP server handles all the computation.
 | Engine | Role | Runtime |
 |---|---|---|
 | **Stockfish 18** (WASM) | Objective evaluation, best moves, multipv | In-process (npm `stockfish`) |
-| **Maia3 5M** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
+| **Maia3 5M** (ONNX) | Human-like move probabilities conditioned on Elo | Dedicated Node child processes (`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. The published package bundles the Maia3 5M
-model; other export variants are not runtime options unless their ONNX files are
-provided separately.
+No external engine executable or Python runtime is required at deploy time.
+Stockfish runs in the server process, while Maia inference runs in dedicated
+Node child processes. The published package bundles the Maia3 5M model; other
+export variants are not runtime options unless their ONNX files are provided
+separately.
 
 ## Build from source
 
@@ -68,6 +69,12 @@ const server = await serveHttp({ port: 3000, bodyTimeoutMs: 15_000 });
 await server.close();
 ```
 
+The root API also exports `buildServer`, `GameStore`, `ChessError`,
+`ExplorerError`, the service/domain types needed to provide custom
+`AppServices`, and safe chess helpers including `parseImportedPgn`, `pgnOf`,
+and `snapshotChess`. New integrations should use the package root. Legacy
+`dist/` subpath imports remain available for compatibility.
+
 `bodyTimeoutMs` limits HTTP body upload time; it is not a whole-tool deadline.
 The deprecated `requestTimeoutMs` alias remains supported when `bodyTimeoutMs`
 is omitted.
@@ -264,20 +271,23 @@ rejected:
 
 - Up to 1,000 games are retained per process; idle games expire after one hour.
 - `move_evaluate` accepts at most 10 moves per call.
-- Imported PGNs are limited to 1 MiB, 256 headers, and 4,096 plies across the
-  mainline and variations, plus 32,768 structural elements and 16 KiB per
-  lexical token. Every variation is legality-checked; game state retains the
-  mainline. UTF-8 BOMs and standard escaped header values are supported.
+- Imported and exported PGNs are limited to 1 MiB, 256 headers, and 4,096
+  plies; stored game histories use the same ply limit. Imports also cap the
+  mainline and variations together at 32,768 structural elements and 16 KiB
+  per lexical token. Every variation is legality-checked; game state retains
+  the mainline. UTF-8 BOMs and standard escaped header values are supported.
 - Custom FENs reject inconsistent castling/en-passant metadata and impossible
   pawn or promotion material.
-- Stockfish accepts up to 32 active or queued analyses.
+- Stockfish accepts up to 32 active or queued analyses. Maia runs at most two
+  inferences concurrently and queues up to 32 more.
 - Lichess Explorer requests run one at a time and share 429 cooldowns.
 - HTTP retains at most 64 MCP sessions; sessions with no active request expire
   after 30 minutes. An open GET/SSE stream keeps its session active.
-- HTTP accepts bodies up to 2 MiB. It permits 16 concurrent POSTs and downstream
-  compute/network jobs process-wide, with two of each per session. A separately
-  bounded control lane keeps MCP cancellation available when normal POST slots
-  are full. Work keeps its slot after a raw disconnect until it settles. HTTP
+- HTTP accepts bodies up to 2 MiB. After body parsing, it permits 16 concurrent
+  POST dispatches and downstream compute/network jobs process-wide, with two of
+  each per session. A separate bounded control lane keeps MCP cancellation
+  available when normal POST slots are full. Work keeps its slot after a raw
+  disconnect until it settles. HTTP
   also caps connections at 128 and applies a 15-second body upload deadline
   plus bounded header, socket, and keep-alive timeouts.
 
@@ -289,10 +299,10 @@ proxy.
 MCP cancellation notifications, session deletion, and server shutdown propagate
 to body uploads and Stockfish, Maia, and Lichess work. Stockfish stops safely at
 its UCI queue boundary, drains queued work during shutdown, and rejects new
-analysis until teardown completes. Lichess fetch and retry waits abort immediately. ONNX
-Runtime cannot interrupt an inference already executing, so Maia discards its
-result after the native call returns. A raw HTTP disconnect alone is not a
-cancellation signal.
+analysis until teardown completes. Lichess fetch and retry waits abort
+immediately. Maia runs native inference in dedicated child processes; cancelling
+active work terminates its child, while queued cancellation is immediate. A raw
+HTTP disconnect alone is not a cancellation signal.
 
 ## Intents
 

package/dist/chess-copy.js

@@ -1,10 +1,12 @@
 import { Chess } from "chess.js";
 import { ChessError } from "./errors.js";
+import { assertPgnPlyLimit, replacePgnHeaders } from "./pgn-shared.js";
 const ORIGINAL_PIECES = {
     q: 1,
     r: 2,
     n: 2,
 };
+const CHESS_STATE_KEYS = Reflect.ownKeys(new Chess());
 function squareColor(square) {
     return ((square.charCodeAt(0) - 97 + Number(square[1])) % 2);
 }
@@ -38,6 +40,32 @@ function minimumPawnCaptures(chess, color) {
 function nonKingMaterial(chess, color) {
     return ["p", "q", "r", "b", "n"].reduce((total, type) => total + chess.findPiece({ type, color }).length, 0);
 }
+function clonedChess(chess) {
+    const state = Object.create(null);
+    for (const key of CHESS_STATE_KEYS) {
+        const descriptor = Object.getOwnPropertyDescriptor(chess, key);
+        if (!descriptor || !("value" in descriptor)) {
+            throw new ChessError("INVALID_FEN", "chess state cannot be cloned");
+        }
+        Object.defineProperty(state, key, {
+            configurable: true,
+            enumerable: true,
+            value: descriptor.value,
+            writable: true,
+        });
+    }
+    try {
+        const clone = structuredClone(state);
+        Object.setPrototypeOf(clone, Chess.prototype);
+        return clone;
+    }
+    catch {
+        throw new ChessError("INVALID_FEN", "chess state cannot be cloned");
+    }
+}
+function exactFen(chess) {
+    return chess.fen({ forceEnpassantSquare: true });
+}
 function hasPiece(chess, square, type, color) {
     const piece = chess.get(square);
     return piece?.type === type && piece.color === color;
@@ -123,11 +151,8 @@ export function assertLegalPosition(chess) {
         }
         assertCastlingPosition(chess, color);
         const opponent = color === "w" ? "b" : "w";
-        const opponentPawns = chess.findPiece({ type: "p", color: opponent }).length;
         const missingOpponentMaterial = 15 - nonKingMaterial(chess, opponent);
-        const possibleOpponentPromotions = 8 - opponentPawns;
-        if (minimumPawnCaptures(chess, color) >
-            missingOpponentMaterial + possibleOpponentPromotions) {
+        if (minimumPawnCaptures(chess, color) > missingOpponentMaterial) {
             throw new ChessError("INVALID_FEN", "FEN pawn files require more captures than opposing material allows");
         }
     }
@@ -138,22 +163,103 @@ export function assertLegalPosition(chess) {
     if (previousKing && chess.isAttacked(previousKing, turn)) {
         throw new ChessError("INVALID_FEN", "FEN cannot leave the side that just moved in check");
     }
+    const king = chess.findPiece({ type: "k", color: turn })[0];
+    if (king) {
+        const checkers = chess.attackers(king, previous);
+        const leapers = checkers.filter((square) => {
+            const type = chess.get(square)?.type;
+            return type === "k" || type === "n" || type === "p";
+        });
+        if (checkers.length > 2 || leapers.length > 1) {
+            throw new ChessError("INVALID_FEN", "FEN contains an impossible check topology");
+        }
+    }
+}
+function expectedInitialFen(headers) {
+    const values = new Map();
+    for (const [name, value] of headers) {
+        const key = name.toLowerCase();
+        if (values.has(key)) {
+            throw new ChessError("INVALID_PGN", `PGN must not repeat ${name} headers`);
+        }
+        values.set(key, value);
+    }
+    const setup = values.get("setup");
+    const fen = values.get("fen");
+    if (setup !== undefined && setup !== "0" && setup !== "1") {
+        throw new ChessError("INVALID_PGN", "PGN SetUp must be 0 or 1");
+    }
+    if ((setup === "1") !== (fen !== undefined)) {
+        throw new ChessError("INVALID_PGN", "PGN SetUp 1 and FEN headers must appear together");
+    }
+    if (fen === undefined)
+        return exactFen(new Chess());
+    assertSafeFenCounters(fen);
+    let initial;
+    try {
+        initial = new Chess(fen);
+    }
+    catch {
+        throw new ChessError("INVALID_FEN", "invalid FEN");
+    }
+    assertLegalPosition(initial);
+    return exactFen(initial);
+}
+function validatedHistory(chess) {
+    const sourceFen = exactFen(chess);
+    const sourceHeaders = Object.entries(chess.getHeaders());
+    const shadow = clonedChess(chess);
+    const history = Chess.prototype.history.call(shadow, {
+        verbose: true,
+    });
+    if (history.some((move) => move.from === move.to)) {
+        throw new ChessError("INVALID_PGN", "null moves are not supported");
+    }
+    if (exactFen(shadow) !== sourceFen) {
+        throw new ChessError("INVALID_FEN", "current position does not match move history");
+    }
+    const initial = clonedChess(chess);
+    while (Chess.prototype.undo.call(initial)) { }
+    const initialFen = exactFen(initial);
+    if (initialFen !== expectedInitialFen(sourceHeaders)) {
+        throw new ChessError("INVALID_PGN", "move history does not match PGN setup headers");
+    }
+    return { history, initialFen, shadow, sourceHeaders };
 }
 export function snapshotChess(chess) {
     assertLegalPosition(chess);
-    const history = chess.history({ verbose: true });
-    const initialFen = history[0]?.before ?? chess.fen();
+    const { history, initialFen, shadow, sourceHeaders } = validatedHistory(chess);
+    assertPgnPlyLimit(history.length);
     assertSafeFenCounters(initialFen);
     const snapshot = new Chess(initialFen);
     assertLegalPosition(snapshot);
-    const comments = new Map(chess.getComments().map(({ fen, comment }) => [fen, comment]));
-    for (const [key, value] of Object.entries(chess.getHeaders())) {
-        snapshot.setHeader(key, value);
+    const getComments = chess.getComments;
+    const sourceComments = getComments === Chess.prototype.getComments
+        ? Chess.prototype.getComments.call(shadow)
+        : getComments.call(chess);
+    const comments = new Map(sourceComments.map(({ fen, comment }) => [
+        fen,
+        /[{}]/.test(comment) ? comment.replace(/[\r\n]+/g, " ") : comment,
+    ]));
+    const unsafeComments = [...comments.values()].some((comment) => /[{}]/.test(comment));
+    let markerPrefix = "\uE000";
+    if (unsafeComments) {
+        const occupied = [...sourceHeaders.flat(), ...comments.values()].join("\u0000");
+        while (occupied.includes(markerPrefix))
+            markerPrefix += "\uE001";
     }
+    const markerComments = [];
     const restoreComment = () => {
         const comment = comments.get(snapshot.fen());
-        if (comment !== undefined)
+        if (comment === undefined)
+            return;
+        if (!unsafeComments || !/[{}]/.test(comment)) {
             snapshot.setComment(comment);
+            return;
+        }
+        const marker = `${markerPrefix}${markerComments.length}${markerPrefix}`;
+        markerComments.push(comment);
+        snapshot.setComment(marker);
     };
     restoreComment();
     for (const move of history) {
@@ -161,5 +267,31 @@ export function snapshotChess(chess) {
         restoreComment();
     }
     assertSafeFenCounters(snapshot.fen());
-    return snapshot;
+    if (!unsafeComments) {
+        replacePgnHeaders(snapshot, sourceHeaders, { removeMissing: true });
+        return snapshot;
+    }
+    const escapedPrefix = markerPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const marker = new RegExp(`\\{${escapedPrefix}(\\d+)${escapedPrefix}\\}`, "g");
+    const pgn = snapshot.pgn().replace(marker, (_match, index) => {
+        return `;${markerComments[Number(index)]}\n`;
+    });
+    const restored = new Chess();
+    restored.loadPgn(pgn);
+    const restoredHistory = restored.history({ verbose: true });
+    while (restored.undo()) { }
+    const restoreSafeComment = () => {
+        const comment = comments.get(restored.fen());
+        if (comment !== undefined && !/[{}]/.test(comment)) {
+            restored.setComment(comment);
+        }
+    };
+    restoreSafeComment();
+    for (const move of restoredHistory) {
+        restored.move(moveDescriptor(move));
+        restoreSafeComment();
+    }
+    replacePgnHeaders(restored, sourceHeaders, { removeMissing: true });
+    assertSafeFenCounters(restored.fen());
+    return restored;
 }

package/dist/cli.js

@@ -29,6 +29,9 @@ export function parseCli(args) {
     let help = false;
     let hasHttpOption = false;
     const allowedHosts = [];
+    if (args.includes("-h") || args.includes("--help")) {
+        return { transport, host, port, path, allowedHosts, help: true };
+    }
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === undefined)
@@ -93,21 +96,23 @@ export function parseCli(args) {
     if (!isCanonicalHttpPath(path)) {
         throw new Error("--path must be an absolute URL path without query or fragment");
     }
+    const canonicalHost = canonicalHttpHostname(host);
     const canonicalAllowedHosts = allowedHosts.map(canonicalHttpHostname);
-    if (!host || canonicalAllowedHosts.some((value) => value === null)) {
+    if (canonicalHost === null ||
+        canonicalAllowedHosts.some((value) => value === null)) {
         throw new Error("HTTP hostnames must be non-empty hostnames");
     }
     if (transport === "stdio" && hasHttpOption) {
         throw new Error("HTTP options require --transport http");
     }
     if (transport === "http" &&
-        isWildcardHttpBindHost(host) &&
+        isWildcardHttpBindHost(canonicalHost) &&
         canonicalAllowedHosts.length === 0) {
         throw new Error("wildcard HTTP binding requires at least one --allowed-host");
     }
     return {
         transport,
-        host,
+        host: canonicalHost,
         port,
         path,
         allowedHosts: canonicalAllowedHosts,

package/dist/domain.d.ts

@@ -84,22 +84,30 @@ export interface HumanModel {
     selfElo: number;
     opponentElo: number;
 }
-type OpeningStatsValues = {
-    games: number | null;
-    frequency: number | null;
-    white: number | null;
-    draws: number | null;
-    black: number | null;
+type EmptyOpeningStats = {
+    games: null;
+    frequency: null;
+    white: null;
+    draws: null;
+    black: null;
+    averageRating: null;
+};
+type AvailableOpeningStats = {
+    games: number;
+    frequency: number;
+    white: number;
+    draws: number;
+    black: number;
     averageRating: number | null;
 };
 export type OpeningStats = ({
-    status: "available" | "no_data";
-} & OpeningStatsValues) | ({
+    status: "available";
+} & (EmptyOpeningStats | AvailableOpeningStats)) | ({
+    status: "no_data" | "disabled";
+} & EmptyOpeningStats) | ({
     status: "unavailable";
     reason: ExplorerErrorKind;
-} & OpeningStatsValues) | ({
-    status: "disabled";
-} & OpeningStatsValues);
+} & EmptyOpeningStats);
 export interface Candidate {
     uci: string;
     san: string;

package/dist/engines/stockfish.d.ts

@@ -38,6 +38,9 @@ export declare class Stockfish {
     private readonly maxQueue;
     private readonly timeouts;
     constructor(options?: StockfishOptions);
+    private disposeInitEngine;
+    private adoptInitEngine;
+    private completeInit;
     private init;
     private handshake;
     private registerInvalidator;