llm-chess-mcp 0.5.0 → 0.7.2

package/README.md

@@ -72,8 +72,11 @@ 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.
+and `snapshotChess`. The package root is the supported public API. Deep imports
+under `dist/` are intentionally not exported and will fail with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`; use named root exports instead.
+This removes the previous `dist/*` compatibility exports and is a breaking
+change for integrations that imported internal modules.
 
 `bodyTimeoutMs` limits HTTP body upload time; it is not a whole-tool deadline.
 The deprecated `requestTimeoutMs` alias remains supported when `bodyTimeoutMs`
@@ -173,7 +176,7 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | Tool | Description |
 |---|---|
 | `create_game` | Create a game (optionally from a FEN), returns `game_id` |
-| `delete_game` | Delete a game and free its session |
+| `delete_game` | Delete a process-shared game and free game capacity |
 | `game_state` | Authoritative state: FEN, turn, revision, check/mate/draw flags, history, last move, castling (optional ASCII) |
 | `game_play_move` | Play a move (SAN or UCI) — the only mutating tool, with stale-position guard |
 | `game_legal_moves` | All legal moves with metadata |
@@ -207,9 +210,10 @@ human-readable summary and must not be parsed as data.
   `best / excellent / good / inaccuracy / mistake / blunder`.
 - `maia3Prob` is a **human-likelihood**, not move quality. A high-probability move
   can still be objectively bad.
-- Analysis continuations return `pv` in UCI and the same legal prefix in
-  `pvSan` as SAN. If an engine line contains an invalid move, `pvSan` stops
-  before it while the original `pv` remains unchanged.
+- Successful analysis continuations return corresponding `pv` and `pvSan`
+  arrays of equal length in UCI and SAN. An invalid engine continuation is
+  rejected at the internal tool boundary instead of returning a truncated
+  `pvSan`.
 
 ## Candidate structure
 
@@ -272,10 +276,11 @@ 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 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.
+  plies; stored snapshots enforce the same byte, header, token, and ply resource
+  bounds. 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. Maia runs at most two
@@ -283,13 +288,18 @@ rejected:
 - 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. 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.
+- HTTP accepts bodies up to 2 MiB under normal body-parser capacity. Once those
+  parsers are full, an overflow request receives only a small, up-to-8 KiB
+  probe; only a complete MCP cancellation notification can proceed, and no
+  accepted parser is preempted. The listener's connection limit bounds overflow
+  probes. 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 prioritizes MCP cancellation when normal
+  dispatch capacity is full. If an existing-session POST response closes before
+  it finishes, its session is closed and its work is aborted; an uncooperative
+  downstream operation still holds capacity 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.
 
 Programmatic users can override the HTTP limits through `HttpServerOptions`.
 These safeguards do not replace public-edge quotas: a public deployment must
@@ -302,7 +312,9 @@ its UCI queue boundary, drains queued work during shutdown, and rejects new
 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.
+response disconnect for an existing-session POST closes that session and aborts
+its work. Reconnect with a new session, then re-read the process-shared game
+state before retrying a move.
 
 ## Intents
 

package/dist/analysis-boundary.d.ts

@@ -0,0 +1,2 @@
+import type { SfLine } from "./domain.js";
+export declare function validateAnalysisLines(lines: readonly SfLine[], requestedMultipv: number): void;

package/dist/analysis-boundary.js

@@ -0,0 +1,49 @@
+import { MAX_MULTIPV, WDL_TOTAL } from "./domain.js";
+function validScore(value) {
+    return value === null || (typeof value === "number" && Number.isFinite(value));
+}
+function validWdl(value) {
+    return value === null ||
+        (Array.isArray(value) &&
+            value.length === 3 &&
+            value.every((count) => typeof count === "number" &&
+                Number.isSafeInteger(count) &&
+                count >= 0 &&
+                count <= WDL_TOTAL) &&
+            value[0] + value[1] + value[2] === WDL_TOTAL);
+}
+export function validateAnalysisLines(lines, requestedMultipv) {
+    if (!Number.isSafeInteger(requestedMultipv) ||
+        requestedMultipv < 1 ||
+        requestedMultipv > MAX_MULTIPV) {
+        throw new RangeError("invalid requested analysis multipv");
+    }
+    if (!Array.isArray(lines) || lines.length > requestedMultipv) {
+        throw new RangeError("analysis returned too many lines");
+    }
+    const ranks = new Set();
+    for (const line of lines) {
+        if (typeof line !== "object" ||
+            line === null ||
+            Array.isArray(line) ||
+            !Number.isSafeInteger(line.multipv) ||
+            line.multipv < 1 ||
+            line.multipv > requestedMultipv ||
+            ranks.has(line.multipv)) {
+            throw new RangeError("invalid analysis multipv rank");
+        }
+        ranks.add(line.multipv);
+        if (!validScore(line.scoreCp) || !validScore(line.scoreMate)) {
+            throw new RangeError("analysis line has an invalid score");
+        }
+        if (line.scoreCp !== null && line.scoreMate !== null) {
+            throw new RangeError("analysis line has conflicting scores");
+        }
+        if (!validWdl(line.wdl))
+            throw new RangeError("analysis line has invalid WDL");
+        if (!Array.isArray(line.pv) ||
+            !Array.from(line.pv).every((move) => typeof move === "string" && move.length > 0)) {
+            throw new RangeError("analysis line has invalid PV");
+        }
+    }
+}

package/dist/chess-copy.d.ts

@@ -1,4 +1,7 @@
 import { Chess } from "chess.js";
-export declare function assertSafeFenCounters(fen: string): void;
-export declare function assertLegalPosition(chess: Chess): void;
+export { assertLegalPosition, assertSafeFenCounters, } from "./position-validation.js";
+export declare function snapshotChessWithPgn(chess: Chess): {
+    chess: Chess;
+    pgn: string;
+};
 export declare function snapshotChess(chess: Chess): Chess;

package/dist/chess-copy.js

@@ -1,45 +1,11 @@
 import { Chess } from "chess.js";
+import { materializeMove } from "./chess-move.js";
 import { ChessError } from "./errors.js";
-import { assertPgnPlyLimit, replacePgnHeaders } from "./pgn-shared.js";
-const ORIGINAL_PIECES = {
-    q: 1,
-    r: 2,
-    n: 2,
-};
+import { assertPgnPlyLimit, pgnHeaderIndex, pgnSetupHeaders, replacePgnHeaders, terminalPgnResult, } from "./pgn-shared.js";
+import { serializePgn } from "./pgn-serialize.js";
+import { assertLegalPosition, assertSafeFenCounters, } from "./position-validation.js";
+export { assertLegalPosition, assertSafeFenCounters, } from "./position-validation.js";
 const CHESS_STATE_KEYS = Reflect.ownKeys(new Chess());
-function squareColor(square) {
-    return ((square.charCodeAt(0) - 97 + Number(square[1])) % 2);
-}
-function minimumPawnCaptures(chess, color) {
-    const pawns = chess
-        .findPiece({ type: "p", color })
-        .map((square) => ({
-        advances: color === "w" ? Number(square[1]) - 2 : 7 - Number(square[1]),
-        file: square.charCodeAt(0) - 97,
-    }))
-        .sort((left, right) => left.file - right.file);
-    let costs = new Map([[0, 0]]);
-    for (const pawn of pawns) {
-        const next = new Map();
-        for (const [mask, cost] of costs) {
-            for (let original = 0; original < 8; original += 1) {
-                const bit = 1 << original;
-                if (mask & bit)
-                    continue;
-                const captures = Math.abs(original - pawn.file);
-                if (captures > pawn.advances)
-                    continue;
-                const nextMask = mask | bit;
-                next.set(nextMask, Math.min(next.get(nextMask) ?? Infinity, cost + captures));
-            }
-        }
-        costs = next;
-    }
-    return Math.min(...costs.values());
-}
-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) {
@@ -66,132 +32,8 @@ function clonedChess(chess) {
 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;
-}
-function assertCastlingPosition(chess, color) {
-    const rank = color === "w" ? "1" : "8";
-    const rights = chess.getCastlingRights(color);
-    if ((rights.k || rights.q) &&
-        !hasPiece(chess, `e${rank}`, "k", color)) {
-        throw new ChessError("INVALID_FEN", "FEN castling rights require a home king");
-    }
-    if (rights.k && !hasPiece(chess, `h${rank}`, "r", color)) {
-        throw new ChessError("INVALID_FEN", "FEN kingside castling rights require a home rook");
-    }
-    if (rights.q && !hasPiece(chess, `a${rank}`, "r", color)) {
-        throw new ChessError("INVALID_FEN", "FEN queenside castling rights require a home rook");
-    }
-}
-function assertEnPassantPosition(chess) {
-    const fields = chess.fen({ forceEnpassantSquare: true }).split(" ");
-    const target = fields[3];
-    if (!target || target === "-")
-        return;
-    const turn = chess.turn();
-    const file = target[0];
-    const targetRank = turn === "w" ? "6" : "3";
-    const pawnRank = turn === "w" ? "5" : "4";
-    const originRank = turn === "w" ? "7" : "2";
-    const pawnColor = turn === "w" ? "b" : "w";
-    const targetSquare = target;
-    const pawnSquare = `${file}${pawnRank}`;
-    const originSquare = `${file}${originRank}`;
-    if (target[1] !== targetRank ||
-        chess.get(targetSquare) !== undefined ||
-        !hasPiece(chess, pawnSquare, "p", pawnColor) ||
-        chess.get(originSquare) !== undefined ||
-        fields[4] !== "0" ||
-        (turn === "w" && fields[5] === "1")) {
-        throw new ChessError("INVALID_FEN", "FEN en passant target does not match a double pawn move");
-    }
-}
-function moveDescriptor(move) {
-    const base = { from: move.from, to: move.to };
-    return move.promotion ? { ...base, promotion: move.promotion } : base;
-}
-function isSafeDecimal(value, minimum) {
-    return (/^(?:0|[1-9]\d*)$/.test(value) &&
-        Number.isSafeInteger(Number(value)) &&
-        Number(value) >= minimum);
-}
-export function assertSafeFenCounters(fen) {
-    const fields = fen.split(/\s+/);
-    if (fields.length >= 5 && !isSafeDecimal(fields[4] ?? "", 0)) {
-        throw new ChessError("INVALID_FEN", "FEN halfmove clock must be a non-negative safe decimal integer");
-    }
-    if (fields.length >= 6 && !isSafeDecimal(fields[5] ?? "", 1)) {
-        throw new ChessError("INVALID_FEN", "FEN fullmove number must be a positive safe decimal integer");
-    }
-}
-export function assertLegalPosition(chess) {
-    for (const color of ["w", "b"]) {
-        if (chess.findPiece({ type: "k", color }).length !== 1) {
-            throw new ChessError("INVALID_FEN", "FEN must contain exactly one king per side");
-        }
-        const pawns = chess.findPiece({ type: "p", color });
-        if (pawns.some((square) => square[1] === "1" || square[1] === "8")) {
-            throw new ChessError("INVALID_FEN", "FEN pawns cannot occupy the first or eighth rank");
-        }
-        if (pawns.length > 8) {
-            throw new ChessError("INVALID_FEN", "FEN cannot contain more than eight pawns per side");
-        }
-        const promotedPieces = Object.entries(ORIGINAL_PIECES).reduce((total, [type, original]) => total +
-            Math.max(0, chess.findPiece({ type: type, color }).length -
-                original), 0);
-        const promotedBishops = [0, 1].reduce((total, squareColorValue) => total +
-            Math.max(0, chess
-                .findPiece({ type: "b", color })
-                .filter((square) => squareColor(square) === squareColorValue)
-                .length - 1), 0);
-        const promoted = promotedPieces + promotedBishops;
-        if (promoted > 8 - pawns.length) {
-            throw new ChessError("INVALID_FEN", "FEN contains more promoted material than missing pawns allow");
-        }
-        assertCastlingPosition(chess, color);
-        const opponent = color === "w" ? "b" : "w";
-        const missingOpponentMaterial = 15 - nonKingMaterial(chess, opponent);
-        if (minimumPawnCaptures(chess, color) > missingOpponentMaterial) {
-            throw new ChessError("INVALID_FEN", "FEN pawn files require more captures than opposing material allows");
-        }
-    }
-    assertEnPassantPosition(chess);
-    const turn = chess.turn();
-    const previous = turn === "w" ? "b" : "w";
-    const previousKing = chess.findPiece({ type: "k", color: previous })[0];
-    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");
-    }
+    const { fen } = pgnSetupHeaders(pgnHeaderIndex(headers));
     if (fen === undefined)
         return exactFen(new Chess());
     assertSafeFenCounters(fen);
@@ -226,21 +68,69 @@ function validatedHistory(chess) {
     }
     return { history, initialFen, shadow, sourceHeaders };
 }
-export function snapshotChess(chess) {
-    assertLegalPosition(chess);
-    const { history, initialFen, shadow, sourceHeaders } = validatedHistory(chess);
-    assertPgnPlyLimit(history.length);
-    assertSafeFenCounters(initialFen);
-    const snapshot = new Chess(initialFen);
-    assertLegalPosition(snapshot);
+function commentsByFen(chess, shadow) {
     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 }) => [
+    return new Map(sourceComments.map(({ fen, comment }) => [
         fen,
         /[{}]/.test(comment) ? comment.replace(/[\r\n]+/g, " ") : comment,
     ]));
+}
+function replayHistory(chess, history, restoreComment) {
+    restoreComment();
+    for (const move of history) {
+        chess.move(materializeMove(move));
+        restoreComment();
+    }
+}
+function snapshotPgn(chess) {
+    const result = terminalPgnResult(chess);
+    const originalResult = chess.getHeaders().Result;
+    if (result !== undefined)
+        chess.setHeader("Result", result);
+    try {
+        const headers = Object.entries(chess.getHeaders());
+        return serializePgn(() => Chess.prototype.pgn.call(chess), headers, Chess.prototype.getComments.call(chess).map(({ comment }) => comment));
+    }
+    finally {
+        if (result !== undefined) {
+            if (originalResult === undefined)
+                chess.removeHeader("Result");
+            else
+                chess.setHeader("Result", originalResult);
+        }
+    }
+}
+function restoreUnsafeComments(snapshot, comments, markerPrefix, markerComments, sourceHeaders) {
+    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()) { }
+    replayHistory(restored, restoredHistory, () => {
+        const comment = comments.get(restored.fen());
+        if (comment !== undefined && !/[{}]/.test(comment)) {
+            restored.setComment(comment);
+        }
+    });
+    replacePgnHeaders(restored, sourceHeaders, { removeMissing: true });
+    assertSafeFenCounters(restored.fen());
+    return restored;
+}
+export function snapshotChessWithPgn(chess) {
+    assertLegalPosition(chess);
+    const { history, initialFen, shadow, sourceHeaders } = validatedHistory(chess);
+    assertPgnPlyLimit(history.length);
+    assertSafeFenCounters(initialFen);
+    const snapshot = new Chess(initialFen);
+    assertLegalPosition(snapshot);
+    const comments = commentsByFen(chess, shadow);
     const unsafeComments = [...comments.values()].some((comment) => /[{}]/.test(comment));
     let markerPrefix = "\uE000";
     if (unsafeComments) {
@@ -249,7 +139,7 @@ export function snapshotChess(chess) {
             markerPrefix += "\uE001";
     }
     const markerComments = [];
-    const restoreComment = () => {
+    replayHistory(snapshot, history, () => {
         const comment = comments.get(snapshot.fen());
         if (comment === undefined)
             return;
@@ -260,38 +150,15 @@ export function snapshotChess(chess) {
         const marker = `${markerPrefix}${markerComments.length}${markerPrefix}`;
         markerComments.push(comment);
         snapshot.setComment(marker);
-    };
-    restoreComment();
-    for (const move of history) {
-        snapshot.move(moveDescriptor(move));
-        restoreComment();
-    }
+    });
     assertSafeFenCounters(snapshot.fen());
     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();
+        return { chess: snapshot, pgn: snapshotPgn(snapshot) };
     }
-    replacePgnHeaders(restored, sourceHeaders, { removeMissing: true });
-    assertSafeFenCounters(restored.fen());
-    return restored;
+    const restored = restoreUnsafeComments(snapshot, comments, markerPrefix, markerComments, sourceHeaders);
+    return { chess: restored, pgn: snapshotPgn(restored) };
+}
+export function snapshotChess(chess) {
+    return snapshotChessWithPgn(chess).chess;
 }

package/dist/chess-move.d.ts

@@ -0,0 +1,7 @@
+import type { PieceSymbol, Square } from "chess.js";
+export type MoveDescriptor = {
+    from: Square;
+    to: Square;
+    promotion?: PieceSymbol;
+};
+export declare function materializeMove(move: MoveDescriptor): MoveDescriptor;

package/dist/chess-move.js

@@ -0,0 +1,4 @@
+export function materializeMove(move) {
+    const { from, to, promotion } = move;
+    return promotion ? { from, to, promotion } : { from, to };
+}

package/dist/chess.d.ts

@@ -3,11 +3,12 @@ import type { Move } from "chess.js";
 export { assertLegalPosition, assertSafeFenCounters, snapshotChess, } from "./chess-copy.js";
 export { MAX_PGN_BYTES, MAX_PGN_HEADERS, MAX_PGN_PLIES, MAX_PGN_TOKEN_BYTES, parseImportedPgn, pgnOf, } from "./pgn.js";
 import type { ChessState, DrawResult } from "./domain.js";
+import { type MoveDescriptor } from "./chess-move.js";
 export declare const MAX_EVALUATED_MOVES = 10;
 export declare function drawResult(chess: Chess): DrawResult | null;
 export declare function stateOf<Revision extends number>(chess: Chess, revision: Revision): ChessState & {
     revision: Revision;
 };
 export declare function parseMove(chess: Chess, move: string): Move;
-export declare function playParsedMove(chess: Chess, move: Move): Move;
+export declare function playParsedMove(chess: Chess, move: MoveDescriptor): Move;
 export declare function pvToSan(chess: Chess, pv: readonly string[]): string[];

package/dist/chess.js

@@ -2,11 +2,8 @@ import { Chess } from "chess.js";
 export { assertLegalPosition, assertSafeFenCounters, snapshotChess, } from "./chess-copy.js";
 export { MAX_PGN_BYTES, MAX_PGN_HEADERS, MAX_PGN_PLIES, MAX_PGN_TOKEN_BYTES, parseImportedPgn, pgnOf, } from "./pgn.js";
 import { ChessError } from "./errors.js";
+import { materializeMove } from "./chess-move.js";
 export const MAX_EVALUATED_MOVES = 10;
-function moveDescriptor(move) {
-    const base = { from: move.from, to: move.to };
-    return move.promotion ? { ...base, promotion: move.promotion } : base;
-}
 export function drawResult(chess) {
     if (chess.isCheckmate() || !chess.isDraw())
         return null;
@@ -21,7 +18,8 @@ export function drawResult(chess) {
     return "draw";
 }
 export function stateOf(chess, revision) {
-    const last = chess.history({ verbose: true }).at(-1);
+    const history = chess.history({ verbose: true });
+    const last = history.at(-1);
     const isCheckmate = chess.isCheckmate();
     return {
         fen: chess.fen(),
@@ -36,7 +34,7 @@ export function stateOf(chess, revision) {
         isThreefoldRepetition: !isCheckmate && chess.isThreefoldRepetition(),
         isDrawByFiftyMoves: !isCheckmate && chess.isDrawByFiftyMoves(),
         moveNumber: chess.moveNumber(),
-        history: chess.history(),
+        history: history.map((move) => move.san),
         lastMove: last ? { san: last.san, uci: last.lan } : null,
         castling: {
             whiteKingside: chess.getCastlingRights("w").k,
@@ -58,7 +56,7 @@ export function parseMove(chess, move) {
     return found;
 }
 export function playParsedMove(chess, move) {
-    return chess.move(moveDescriptor(move));
+    return chess.move(materializeMove(move));
 }
 export function pvToSan(chess, pv) {
     const copy = new Chess(chess.fen());

package/dist/cli.d.ts

@@ -7,5 +7,5 @@ export type CliOptions = {
     allowedHosts: string[];
     help: boolean;
 };
-export declare const HELP = "Usage: llm-chess-mcp [options]\n\nOptions:\n  --transport <stdio|http>  Transport to use (default: stdio)\n  --http                    Shortcut for --transport http\n  --host <host>             HTTP bind host (default: 127.0.0.1)\n  --port <port>             HTTP listen port (default: 3000)\n  --path <path>             HTTP endpoint path (default: /mcp)\n  --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)\n  -h, --help                Show this help\n";
+export declare const HELP = "Usage: llm-chess-mcp [options]\n\nOptions:\n  --transport <stdio|http>  Transport to use (default: stdio)\n  --http                    Shortcut for --transport http\n  --host <host>             HTTP bind host (default: 127.0.0.1)\n  --port <port>             HTTP listen port; 0 selects an available port (default: 3000)\n  --path <path>             HTTP endpoint path (default: /mcp)\n  --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)\n  -h, --help                Show this help\n";
 export declare function parseCli(args: string[]): CliOptions;

package/dist/cli.js

@@ -5,7 +5,7 @@ Options:
   --transport <stdio|http>  Transport to use (default: stdio)
   --http                    Shortcut for --transport http
   --host <host>             HTTP bind host (default: 127.0.0.1)
-  --port <port>             HTTP listen port (default: 3000)
+  --port <port>             HTTP listen port; 0 selects an available port (default: 3000)
   --path <path>             HTTP endpoint path (default: /mcp)
   --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)
   -h, --help                Show this help
@@ -90,8 +90,8 @@ export function parseCli(args) {
                 throw new Error(`unknown option: ${option}`);
         }
     }
-    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-        throw new Error("--port must be between 1 and 65535");
+    if (!Number.isInteger(port) || port < 0 || port > 65_535) {
+        throw new Error("--port must be between 0 and 65535");
     }
     if (!isCanonicalHttpPath(path)) {
         throw new Error("--path must be an absolute URL path without query or fragment");

package/dist/domain.d.ts

@@ -13,6 +13,12 @@ export declare const MOVE_EVALUATION_RESULTS: readonly ["ongoing", "checkmate",
 export type MoveEvaluationResult = (typeof MOVE_EVALUATION_RESULTS)[number];
 export declare const ANALYSIS_LEVELS: readonly ["fast", "normal", "deep"];
 export type AnalysisLevel = (typeof ANALYSIS_LEVELS)[number];
+export declare const MAX_ANALYSIS_DEPTH = 30;
+export declare const MAX_MULTIPV = 10;
+export declare const MAX_HUMAN_MOVES = 20;
+export declare const HUMAN_PROBABILITY_TOLERANCE = 0.00001;
+export declare const GAME_ID_MAX_LENGTH = 256;
+export declare const WDL_TOTAL = 1000;
 export declare const MOVE_CLASSIFICATIONS: readonly ["best", "excellent", "good", "inaccuracy", "mistake", "blunder"];
 export type MoveClassification = (typeof MOVE_CLASSIFICATIONS)[number];
 export declare const INTENTS: readonly ["best", "strong", "natural", "balanced", "ease_off", "give_chance"];
@@ -49,13 +55,21 @@ export interface ChessState {
     };
 }
 export type Wdl = [number, number, number];
-export interface SfLine {
+type SfScore = {
+    scoreCp: number;
+    scoreMate: null;
+} | {
+    scoreCp: null;
+    scoreMate: number;
+} | {
+    scoreCp: null;
+    scoreMate: null;
+};
+export type SfLine = {
     multipv: number;
-    scoreCp: number | null;
-    scoreMate: number | null;
     wdl: Wdl | null;
     pv: string[];
-}
+} & SfScore;
 export interface Maia3Move {
     uci: string;
     san: string;

package/dist/domain.js

@@ -25,6 +25,12 @@ export const MOVE_EVALUATION_RESULTS = [
     ...DRAW_RESULTS,
 ];
 export const ANALYSIS_LEVELS = ["fast", "normal", "deep"];
+export const MAX_ANALYSIS_DEPTH = 30;
+export const MAX_MULTIPV = 10;
+export const MAX_HUMAN_MOVES = 20;
+export const HUMAN_PROBABILITY_TOLERANCE = 1e-5;
+export const GAME_ID_MAX_LENGTH = 256;
+export const WDL_TOTAL = 1_000;
 export const MOVE_CLASSIFICATIONS = [
     "best",
     "excellent",