llm-chess-mcp 0.1.3 → 0.3.0

package/README.md

@@ -48,6 +48,24 @@ pnpm build
 pnpm test
 ```
 
+`pnpm test:unit` runs the unit suite. `pnpm test:e2e` builds first, then runs
+the MCP transport tests. `pnpm check` runs the full local gate; use
+`pnpm release:check` before publishing.
+
+### Maintainers
+
+[Architecture](docs/architecture.md) describes runtime and service boundaries;
+[the changelog](CHANGELOG.md) records client-visible changes.
+
+Local quality commands:
+
+```bash
+pnpm typecheck
+pnpm test:coverage
+pnpm contract:check
+pnpm check
+```
+
 ### Export Maia3 to ONNX (build-time only)
 
 This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
@@ -74,6 +92,13 @@ cp .env.example .env
 
 Without a token, `opening_explorer` returns a disabled notice; all other tools work.
 
+Explorer filters are strict. Speeds are `ultraBullet`, `bullet`, `blitz`,
+`rapid`, `classical`, and `correspondence`; rating buckets are `0`, `1000`,
+`1200`, `1400`, `1600`, `1800`, `2000`, `2200`, and `2500`. `masters` accepts
+neither filter. Invalid filters fail locally. Transient failures (network,
+timeout, 429, and 5xx) are retried once within a 12-second total budget;
+invalid requests and other 4xx responses are not retried.
+
 ## Configure in your MCP client
 
 ### opencode
@@ -155,6 +180,20 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `move_candidates_by_intent` | Convenience layer: candidates ranked for a strategic intent |
 | `opening_explorer` | Lichess human game statistics |
 
+## Result format and 0.1.x migration
+
+`structuredContent` is the canonical successful result. Handler-level failures
+set `isError` and provide `structuredContent.error`. Input-schema failures are
+generated by the MCP SDK before the handler and use its standard `isError` text
+result without `structuredContent`. Otherwise, `content` is only a short
+human-readable summary and must not be parsed as data.
+
+Clients upgrading from 0.1.x should stop parsing `content` and consume
+`structuredContent` instead. Check `isError` and the structured error code when
+a tool fails. `move_evaluate` now always returns
+`{ game_id, revision, results }`; its former single-move top-level duplicates
+are removed.
+
 ## Score conventions
 
 - Stockfish scores are **side-to-move perspective**: positive cp = side to move is
@@ -279,6 +318,16 @@ It checks top-1/top-k move agreement and max probability error to detect
 export/runtime regressions. The bundled `maia3-5m.onnx` passes with 100% top-1
 and top-5 agreement and max probability error < 1e-4.
 
+## Releases
+
+Releases are verified locally; this project intentionally has no hosted CI
+release workflow.
+
+For `0.2.0`, run `pnpm release:check`, pack the tarball, and smoke-test a clean
+install of that tarball with `llm-chess-mcp`. Publish only after that succeeds.
+Use the same local gate and clean-install smoke test before promoting the proven
+`0.2.x` release process to `1.0.0`.
+
 ## License & attribution
 
 This project is licensed under the **AGPL-3.0** (see `LICENSE`).

package/dist/chess.js

@@ -0,0 +1,83 @@
+import { Chess } from "chess.js";
+import { ChessError } from "./errors.js";
+export const MAX_EVALUATED_MOVES = 10;
+export const MAX_PGN_BYTES = 1024 * 1024;
+export const MAX_PGN_PLIES = 4096;
+function moveDescriptor(move) {
+    const base = { from: move.from, to: move.to };
+    return move.promotion ? { ...base, promotion: move.promotion } : base;
+}
+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(moveDescriptor(move));
+    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;
+}
+export function stateOf(chess, revision) {
+    const last = chess.history({ verbose: true }).at(-1);
+    return {
+        fen: chess.fen(),
+        turn: chess.turn(),
+        revision,
+        isCheck: chess.isCheck(),
+        isCheckmate: chess.isCheckmate(),
+        isStalemate: chess.isStalemate(),
+        isDraw: chess.isDraw(),
+        isGameOver: chess.isGameOver(),
+        isInsufficientMaterial: chess.isInsufficientMaterial(),
+        isThreefoldRepetition: chess.isThreefoldRepetition(),
+        isDrawByFiftyMoves: chess.isDrawByFiftyMoves(),
+        moveNumber: chess.moveNumber(),
+        history: chess.history(),
+        lastMove: last ? { san: last.san, uci: last.lan } : null,
+        castling: {
+            whiteKingside: chess.getCastlingRights("w").k,
+            whiteQueenside: chess.getCastlingRights("w").q,
+            blackKingside: chess.getCastlingRights("b").k,
+            blackQueenside: chess.getCastlingRights("b").q,
+        },
+    };
+}
+export function parseMove(chess, move) {
+    const legal = chess.moves({ verbose: true });
+    const san = move.replace(/[+#]$/, "");
+    const found = legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === san) ??
+        legal.find((candidate) => candidate.lan === move);
+    if (!found)
+        throw new ChessError("ILLEGAL_MOVE", `illegal move: ${move}`);
+    return found;
+}
+export function playParsedMove(chess, move) {
+    return chess.move(moveDescriptor(move));
+}

package/dist/engines/stockfish.js

@@ -38,10 +38,10 @@ function parseScore(token) {
     return { cp: null, mate: null };
 }
 function parseWdl(line) {
-    const m = line.match(/ wdl (\d+) (\d+) (\d+)/);
-    if (!m)
+    const groups = line.match(/ wdl (?<wins>\d+) (?<draws>\d+) (?<losses>\d+)/)?.groups;
+    if (!groups)
         return null;
-    return [Number(m[1]), Number(m[2]), Number(m[3])];
+    return [Number(groups.wins), Number(groups.draws), Number(groups.losses)];
 }
 export class Stockfish {
     session = null;
@@ -246,19 +246,21 @@ export class Stockfish {
             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+)/);
-                    const pv = line.match(/ pv (.+)$/);
-                    if (!m)
+                    const multipv = line.match(/multipv (?<value>\d+)/)?.groups?.value;
+                    if (!multipv)
                         return;
-                    const n = Number(m[1]);
-                    const score = s ? parseScore(s[1]) : { cp: null, mate: null };
+                    const scoreToken = line.match(/ score (?<value>cp -?\d+|mate -?\d+)/)?.groups?.value;
+                    const pv = line.match(/ pv (?<value>.+)$/)?.groups?.value;
+                    const n = Number(multipv);
+                    const score = scoreToken
+                        ? parseScore(scoreToken)
+                        : { cp: null, mate: null };
                     byPv.set(n, {
                         multipv: n,
                         scoreCp: score.cp,
                         scoreMate: score.mate,
                         wdl: parseWdl(line),
-                        pv: pv ? pv[1].split(" ") : [],
+                        pv: pv ? pv.split(" ") : [],
                     });
                 }
                 else if (line.startsWith("bestmove")) {

package/dist/errors.js

@@ -1,7 +1,7 @@
 export class ChessError extends Error {
     code;
     constructor(code, message) {
-        super(`${code}: ${message}`);
+        super(message);
         this.code = code;
         this.name = "ChessError";
     }

package/dist/explorer.js

@@ -1,38 +1,233 @@
+import { z } from "zod/v4";
 const BASE = "https://explorer.lichess.org";
+export const LICHESS_SPEEDS = [
+    "ultraBullet",
+    "bullet",
+    "blitz",
+    "rapid",
+    "classical",
+    "correspondence",
+];
+export const LICHESS_RATINGS = [
+    0, 1000, 1200, 1400, 1600, 1800, 2000, 2200, 2500,
+];
+export const lichessSpeedSchema = z.enum(LICHESS_SPEEDS);
+export const lichessRatingSchema = z.union([
+    z.literal(0),
+    z.literal(1000),
+    z.literal(1200),
+    z.literal(1400),
+    z.literal(1600),
+    z.literal(1800),
+    z.literal(2000),
+    z.literal(2200),
+    z.literal(2500),
+]);
+export const EXPLORER_ATTEMPT_TIMEOUT_MS = 5_000;
+export const EXPLORER_MAX_ATTEMPTS = 2;
+export const EXPLORER_MAX_RETRY_DELAY_MS = 2_000;
+export const EXPLORER_DEFAULT_RETRY_DELAY_MS = 250;
+export const EXPLORER_TOTAL_TIMEOUT_MS = 12_000;
+export const EXPLORER_ERROR_KINDS = [
+    "disabled",
+    "invalid_input",
+    "timeout",
+    "network",
+    "auth",
+    "rate_limited",
+    "upstream",
+    "http",
+    "invalid_response",
+];
+export class ExplorerError extends Error {
+    kind;
+    status;
+    reason;
+    constructor(kind, message, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+        this.name = "ExplorerError";
+        this.reason = kind;
+    }
+}
+const countSchema = z.number().int().nonnegative();
+const responseSchema = z.object({
+    white: countSchema,
+    draws: countSchema,
+    black: countSchema,
+    moves: z.array(z.object({
+        uci: z.string().min(1),
+        san: z.string().min(1),
+        white: countSchema,
+        draws: countSchema,
+        black: countSchema,
+        averageRating: z.number().nonnegative().optional(),
+    })),
+    opening: z
+        .object({ eco: z.string().min(1), name: z.string().min(1) })
+        .nullable()
+        .optional(),
+});
+const speedSet = new Set(LICHESS_SPEEDS);
+const ratingSet = new Set(LICHESS_RATINGS);
 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");
+function error(kind, status) {
+    const message = {
+        disabled: "Lichess opening explorer is disabled",
+        invalid_input: "Invalid Lichess opening explorer filters",
+        timeout: "Lichess opening explorer timed out",
+        network: "Lichess opening explorer network failure",
+        auth: "Lichess opening explorer authentication failed",
+        rate_limited: "Lichess opening explorer rate limited the request",
+        upstream: "Lichess opening explorer service failure",
+        http: "Lichess opening explorer rejected the request",
+        invalid_response: "Lichess opening explorer returned an invalid response",
+    };
+    return new ExplorerError(kind, message[kind], status);
+}
+function retryAfterMs(value, now) {
+    if (!value)
+        return EXPLORER_DEFAULT_RETRY_DELAY_MS;
+    const seconds = Number(value);
+    const delay = Number.isFinite(seconds)
+        ? seconds * 1_000
+        : Date.parse(value) - now;
+    if (!Number.isFinite(delay))
+        return EXPLORER_DEFAULT_RETRY_DELAY_MS;
+    return Math.max(0, delay);
+}
+function isRetryable(kind) {
+    return (kind === "timeout" ||
+        kind === "network" ||
+        kind === "rate_limited" ||
+        kind === "upstream");
+}
+export async function openingExplorer(chess, db, speeds, ratings, options = {}) {
+    const token = options.token ?? process.env.LICHESS_TOKEN ?? "";
+    if (!token)
+        throw error("disabled");
+    if (!speeds.every((speed) => speedSet.has(speed)) ||
+        new Set(speeds).size !== speeds.length) {
+        throw error("invalid_input");
+    }
+    if (!ratings.every((rating) => ratingSet.has(rating)) ||
+        new Set(ratings).size !== ratings.length) {
+        throw error("invalid_input");
     }
+    if (db === "masters" && (speeds.length > 0 || ratings.length > 0)) {
+        throw error("invalid_input");
+    }
+    const request = options.fetch ?? globalThis.fetch;
+    const sleep = options.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const timeout = options.timeout ?? ((ms) => AbortSignal.timeout(ms));
+    const now = options.now ?? Date.now;
+    const deadline = now() + EXPLORER_TOTAL_TIMEOUT_MS;
     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 url = `${BASE}/${db}?${params}`;
+    const legalMoves = new Map(chess.moves({ verbose: true }).map((move) => [move.lan, move.san]));
+    let lastError = error("network");
+    for (let attempt = 0; attempt < EXPLORER_MAX_ATTEMPTS; attempt += 1) {
+        const remaining = deadline - now();
+        if (remaining <= 0)
+            throw error("timeout");
+        const signal = timeout(Math.max(1, Math.min(EXPLORER_ATTEMPT_TIMEOUT_MS, remaining)));
+        let response;
+        try {
+            response = await request(url, {
+                headers: { Authorization: `Bearer ${token}` },
+                signal,
+            });
+        }
+        catch {
+            lastError = error(signal.aborted ? "timeout" : "network");
+            if (attempt + 1 >= EXPLORER_MAX_ATTEMPTS)
+                throw lastError;
+            const delay = Math.min(EXPLORER_DEFAULT_RETRY_DELAY_MS, Math.max(0, deadline - now()));
+            await sleep(delay);
+            continue;
+        }
+        if (!response.ok) {
+            const kind = response.status === 401 || response.status === 403
+                ? "auth"
+                : response.status === 429
+                    ? "rate_limited"
+                    : response.status >= 500 && response.status <= 599
+                        ? "upstream"
+                        : "http";
+            lastError = error(kind, response.status);
+            if (!isRetryable(kind) || attempt + 1 >= EXPLORER_MAX_ATTEMPTS) {
+                throw lastError;
+            }
+            const delay = retryAfterMs(response.headers.get("retry-after"), now());
+            const retryBudget = Math.max(0, deadline - now());
+            if (delay > EXPLORER_MAX_RETRY_DELAY_MS || delay >= retryBudget) {
+                throw lastError;
+            }
+            await sleep(delay);
+            continue;
+        }
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch (cause) {
+            if (signal.aborted || cause instanceof TypeError) {
+                lastError = error(signal.aborted ? "timeout" : "network");
+                if (attempt + 1 < EXPLORER_MAX_ATTEMPTS) {
+                    const delay = Math.min(EXPLORER_DEFAULT_RETRY_DELAY_MS, Math.max(0, deadline - now()));
+                    await sleep(delay);
+                    continue;
+                }
+                throw lastError;
+            }
+            throw error("invalid_response");
+        }
+        const parsed = responseSchema.safeParse(body);
+        if (!parsed.success)
+            throw error("invalid_response");
+        const data = parsed.data;
+        const ucis = new Set();
+        let white = 0;
+        let draws = 0;
+        let black = 0;
+        for (const move of data.moves) {
+            if (ucis.has(move.uci) ||
+                legalMoves.get(move.uci) !== move.san) {
+                throw error("invalid_response");
+            }
+            ucis.add(move.uci);
+            white += move.white;
+            draws += move.draws;
+            black += move.black;
+        }
+        if (white > data.white || draws > data.draws || black > data.black) {
+            throw error("invalid_response");
+        }
+        return {
+            db,
+            white: data.white,
+            draws: data.draws,
+            black: data.black,
+            moves: data.moves.map((move) => ({
+                uci: move.uci,
+                san: move.san,
+                white: move.white,
+                draws: move.draws,
+                black: move.black,
+                count: move.white + move.draws + move.black,
+                averageRating: move.averageRating ?? null,
+            })),
+            opening: data.opening ?? null,
+        };
     }
-    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,
-    };
+    throw lastError;
 }

package/dist/games.js

@@ -1,64 +1,91 @@
-import { Chess } from "chess.js";
 import { randomUUID } from "node:crypto";
+import { Chess } from "chess.js";
 import { ChessError } from "./errors.js";
-const games = new Map();
 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;
+export class GameStore {
+    maxGames;
+    idleTtlMs;
+    games = new Map();
+    clock;
+    createId;
+    constructor(options = {}) {
+        this.maxGames = options.maxGames ?? MAX_GAMES;
+        this.idleTtlMs = options.idleTtlMs ?? GAME_TTL_MS;
+        this.clock = options.clock ?? Date.now;
+        this.createId = options.createId ?? randomUUID;
+        if (!Number.isInteger(this.maxGames) || this.maxGames < 1) {
+            throw new RangeError("maxGames must be a positive integer");
+        }
+        if (!Number.isFinite(this.idleTtlMs) || this.idleTtlMs < 0) {
+            throw new RangeError("idleTtlMs must be a non-negative number");
+        }
     }
-    return removed;
-}
-function storeGame(chess) {
-    cleanupGames();
-    if (games.size >= MAX_GAMES) {
-        throw new ChessError("GAME_LIMIT_REACHED", `game session limit reached: ${MAX_GAMES}`);
+    cleanupGames(now = this.clock()) {
+        let removed = 0;
+        for (const [id, game] of this.games) {
+            if (!this.isExpired(game, now))
+                continue;
+            this.games.delete(id);
+            removed += 1;
+        }
+        return removed;
     }
-    const id = randomUUID();
-    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) {
-    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}`);
+    createGame(fen) {
+        return this.createGameFromChess(fen === undefined ? new Chess() : new Chess(fen));
+    }
+    createGameFromChess(chess) {
+        const now = this.clock();
+        this.cleanupGames(now);
+        if (this.games.size >= this.maxGames) {
+            throw new ChessError("GAME_LIMIT_REACHED", `game session limit reached: ${this.maxGames}`);
+        }
+        const id = this.createId();
+        if (this.games.has(id)) {
+            throw new ChessError("GAME_ID_COLLISION", `game ID already exists: ${id}`);
+        }
+        this.games.set(id, { chess, createdAt: now, lastAccessedAt: now, revision: 0 });
+        return id;
+    }
+    getGame(id) {
+        const game = this.games.get(id);
+        if (!game)
+            throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
+        const now = this.clock();
+        if (this.isExpired(game, now)) {
+            this.games.delete(id);
+            throw new ChessError("GAME_EXPIRED", `game expired: ${id}`);
+        }
+        game.lastAccessedAt = now;
+        return game;
+    }
+    bumpRevision(id) {
+        const game = this.getGame(id);
+        game.revision += 1;
+        return game.revision;
+    }
+    deleteGame(id) {
+        this.cleanupGames();
+        return this.games.delete(id);
+    }
+    listGames() {
+        this.cleanupGames();
+        return [...this.games.keys()];
+    }
+    gameCount() {
+        this.cleanupGames();
+        return this.games.size;
+    }
+    isExpired(game, now) {
+        return now - game.lastAccessedAt >= this.idleTtlMs;
     }
-    g.lastAccessedAt = Date.now();
-    return g;
-}
-export function bumpRevision(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;
 }
+export const defaultGameStore = new GameStore();
+export const cleanupGames = (now) => defaultGameStore.cleanupGames(now);
+export const createGame = (fen) => defaultGameStore.createGame(fen);
+export const createGameFromChess = (chess) => defaultGameStore.createGameFromChess(chess);
+export const getGame = (id) => defaultGameStore.getGame(id);
+export const bumpRevision = (id) => defaultGameStore.bumpRevision(id);
+export const deleteGame = (id) => defaultGameStore.deleteGame(id);
+export const listGames = () => defaultGameStore.listGames();
+export const gameCount = () => defaultGameStore.gameCount();