llm-chess-mcp 0.4.3 → 0.4.5

package/README.md

@@ -23,7 +23,7 @@ provided separately.
 
 ## Install
 
-Requires Node.js 20 or newer.
+Requires Node.js 20.3 or newer.
 
 No install needed — run it directly with `npx`:
 
@@ -93,6 +93,19 @@ HTTP options:
 --allowed-host <host>    Allowed Host/Origin hostname; repeat as needed
 ```
 
+The package also exposes a typed ESM API:
+
+```js
+import { serveHttp } from "llm-chess-mcp";
+
+const server = await serveHttp({ port: 3000, bodyTimeoutMs: 15_000 });
+await server.close();
+```
+
+`bodyTimeoutMs` limits HTTP body upload time; it is not a whole-tool deadline.
+The deprecated `requestTimeoutMs` alias remains supported when `bodyTimeoutMs`
+is omitted.
+
 Binding to `0.0.0.0` or `::` requires at least one `--allowed-host`. HTTP mode
 does not provide authentication or TLS; use a trusted network or an
 authenticated reverse proxy when exposing it beyond localhost. Origin values
@@ -373,12 +386,14 @@ rejected:
 - `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.
-- HTTP retains at most 64 MCP sessions; sessions with no POST activity expire
-  after 30 minutes.
+- 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. Work keeps
   its slot after a raw disconnect until it settles. HTTP also caps connections
-  at 128 and applies bounded header, upload, socket, and keep-alive timeouts.
+  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

package/dist/chess.d.ts

@@ -0,0 +1,15 @@
+import { Chess } from "chess.js";
+import type { Move } from "chess.js";
+import type { ChessState, DrawResult } from "./types.js";
+export declare const MAX_EVALUATED_MOVES = 10;
+export declare const MAX_PGN_BYTES: number;
+export declare const MAX_PGN_PLIES = 4096;
+export declare function assertSafeFenCounters(fen: string): void;
+export declare function snapshotChess(chess: Chess): Chess;
+export declare function drawResult(chess: Chess): DrawResult | null;
+export declare function pgnOf(chess: Chess): string;
+export declare function parseImportedPgn(pgn: string): Chess;
+export declare function stateOf(chess: Chess, revision: number): ChessState;
+export declare function parseMove(chess: Chess, move: string): Move;
+export declare function playParsedMove(chess: Chess, move: Move): Move;
+export declare function pvToSan(chess: Chess, pv: readonly string[]): string[];

package/dist/chess.js

@@ -3,15 +3,45 @@ import { ChessError } from "./errors.js";
 export const MAX_EVALUATED_MOVES = 10;
 export const MAX_PGN_BYTES = 1024 * 1024;
 export const MAX_PGN_PLIES = 4096;
+const PGN_RESULTS = ["1-0", "0-1", "1/2-1/2", "*"];
 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 snapshotChess(chess) {
     const history = chess.history({ verbose: true });
-    const snapshot = new Chess(history[0]?.before ?? chess.fen());
-    for (const move of history)
+    const initialFen = history[0]?.before ?? chess.fen();
+    assertSafeFenCounters(initialFen);
+    const snapshot = new Chess(initialFen);
+    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 restoreComment = () => {
+        const comment = comments.get(snapshot.fen());
+        if (comment !== undefined)
+            snapshot.setComment(comment);
+    };
+    restoreComment();
+    for (const move of history) {
         snapshot.move(moveDescriptor(move));
+        restoreComment();
+    }
+    assertSafeFenCounters(snapshot.fen());
     return snapshot;
 }
 export function drawResult(chess) {
@@ -27,10 +57,117 @@ export function drawResult(chess) {
         return "fifty_move_rule";
     return "draw";
 }
+function withoutPgnComments(pgn) {
+    let result = "";
+    let braceComment = false;
+    let lineComment = false;
+    let quoted = false;
+    let escaped = false;
+    for (const char of pgn) {
+        if (braceComment) {
+            if (char === "}")
+                braceComment = false;
+            result += char === "\n" || char === "\r" ? char : " ";
+            continue;
+        }
+        if (lineComment) {
+            if (char === "\n" || char === "\r") {
+                lineComment = false;
+                result += char;
+            }
+            else {
+                result += " ";
+            }
+            continue;
+        }
+        if (quoted) {
+            result += char;
+            if (escaped)
+                escaped = false;
+            else if (char === "\\")
+                escaped = true;
+            else if (char === '"')
+                quoted = false;
+            continue;
+        }
+        if (char === '"') {
+            quoted = true;
+            result += char;
+            continue;
+        }
+        if (char === "{") {
+            braceComment = true;
+            result += " ";
+        }
+        else if (char === ";") {
+            lineComment = true;
+            result += " ";
+        }
+        else {
+            result += char;
+        }
+    }
+    return result;
+}
+function isPgnResult(value) {
+    return PGN_RESULTS.includes(value);
+}
+function declaredPgnResult(pgn) {
+    const visiblePgn = withoutPgnComments(pgn);
+    const headerResults = [
+        ...visiblePgn.matchAll(/^\s*\[\s*Result\s+"((?:\\.|[^"\\])*)"\s*\]\s*$/gm),
+    ].map((match) => match[1] ?? "");
+    const movetext = visiblePgn.replace(/^\s*\[[^\r\n]*\]\s*$/gm, "");
+    const markers = [
+        ...movetext.matchAll(/(?:^|\s)(1-0|0-1|1\/2-1\/2|\*)(?=\s|$)/g),
+    ].map((match) => match[1] ?? "");
+    const results = [...headerResults, ...markers];
+    if (!results.every(isPgnResult)) {
+        throw new ChessError("INVALID_PGN", "invalid PGN result");
+    }
+    const result = results[0];
+    if (results.some((value) => value !== result)) {
+        throw new ChessError("INVALID_PGN", "PGN result header and marker disagree");
+    }
+    return result;
+}
+function validatePgnFenCounters(pgn) {
+    for (const match of withoutPgnComments(pgn).matchAll(/^\s*\[\s*FEN\s+"((?:\\.|[^"\\])*)"\s*\]\s*$/gim)) {
+        assertSafeFenCounters(match[1] ?? "");
+    }
+}
+function validateResultForPosition(chess, result) {
+    if (result === undefined)
+        return;
+    if (chess.isCheckmate()) {
+        const expected = chess.turn() === "w" ? "0-1" : "1-0";
+        if (result === expected)
+            return;
+        throw new ChessError("INVALID_PGN", `checkmate result must be ${expected}`);
+    }
+    if ((chess.isStalemate() || chess.isInsufficientMaterial()) &&
+        (result === "1-0" || result === "0-1")) {
+        throw new ChessError("INVALID_PGN", "a drawn position cannot have a decisive result");
+    }
+}
+export function pgnOf(chess) {
+    const result = chess.isCheckmate()
+        ? (chess.turn() === "w" ? "0-1" : "1-0")
+        : chess.isDraw() && (!chess.getHeaders().Result || chess.getHeaders().Result === "*")
+            ? "1/2-1/2"
+            : undefined;
+    if (result === undefined)
+        return chess.pgn();
+    const snapshot = snapshotChess(chess);
+    snapshot.setHeader("Result", result);
+    return snapshot.pgn();
+}
 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`);
     }
+    validatePgnFenCounters(pgn);
+    const result = declaredPgnResult(pgn);
     let chess;
     try {
         chess = new Chess();
@@ -39,9 +176,11 @@ export function parseImportedPgn(pgn) {
     catch {
         throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
     }
+    assertSafeFenCounters(chess.fen());
     if (chess.history().length > MAX_PGN_PLIES) {
         throw new ChessError("PGN_TOO_MANY_MOVES", `PGN exceeds the ${MAX_PGN_PLIES}-ply limit`);
     }
+    validateResultForPosition(chess, result);
     return chess;
 }
 export function stateOf(chess, revision) {
@@ -71,8 +210,10 @@ export function stateOf(chess, revision) {
 }
 export function parseMove(chess, move) {
     const legal = chess.moves({ verbose: true });
-    const san = move.replace(/[+#]$/, "");
-    const found = legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === san) ??
+    const found = legal.find((candidate) => candidate.san === move) ??
+        (!/[+#]$/.test(move)
+            ? legal.find((candidate) => candidate.san.replace(/[+#]$/, "") === move)
+            : undefined) ??
         legal.find((candidate) => candidate.lan === move);
     if (!found)
         throw new ChessError("ILLEGAL_MOVE", `illegal move: ${move}`);

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+export type TransportKind = "stdio" | "http";
+export type CliOptions = {
+    transport: TransportKind;
+    host: string;
+    port: number;
+    path: string;
+    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 function parseCli(args: string[]): CliOptions;

package/dist/cli.js

@@ -20,6 +20,20 @@ function splitOption(arg) {
     const index = arg.indexOf("=");
     return index === -1 ? null : [arg.slice(0, index), arg.slice(index + 1)];
 }
+function isCanonicalHttpPath(path) {
+    if (!path.startsWith("/") ||
+        path.startsWith("//") ||
+        path.includes("?") ||
+        path.includes("#")) {
+        return false;
+    }
+    try {
+        return new URL(path, "http://localhost").pathname === path;
+    }
+    catch {
+        return false;
+    }
+}
 export function parseCli(args) {
     let transport = "stdio";
     let host = "127.0.0.1";
@@ -89,11 +103,11 @@ export function parseCli(args) {
     if (!Number.isInteger(port) || port < 1 || port > 65_535) {
         throw new Error("--port must be between 1 and 65535");
     }
-    if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+    if (!isCanonicalHttpPath(path)) {
         throw new Error("--path must be an absolute URL path without query or fragment");
     }
-    if (!host || allowedHosts.some((value) => !value)) {
-        throw new Error("HTTP hostnames must not be empty");
+    if (!host || allowedHosts.some((value) => !value || /[/?#]/.test(value))) {
+        throw new Error("HTTP hostnames must be non-empty hostnames");
     }
     if (transport === "stdio" && hasHttpOption) {
         throw new Error("HTTP options require --transport http");

package/dist/engines/stockfish.d.ts

@@ -0,0 +1,50 @@
+import type { SfLine } from "../types.js";
+export declare const STOCKFISH_FLAVORS: readonly ["full", "lite", "single", "lite-single", "single-lite", "asm"];
+export type StockfishFlavor = (typeof STOCKFISH_FLAVORS)[number];
+export type StockfishEngine = {
+    listener: ((line: string) => void) | null;
+    sendCommand: (cmd: string) => void;
+    terminate: () => void;
+};
+export type StockfishInit = (enginePath: string, cb: (err: Error | null, engine: StockfishEngine) => void) => StockfishEngine;
+type Timeouts = {
+    init: number;
+    handshake: number;
+    analyze: number;
+    stopGrace: number;
+};
+export type StockfishOptions = {
+    init?: StockfishInit;
+    flavor?: string;
+    maxQueue?: number;
+    timeouts?: Partial<Timeouts>;
+};
+export declare function resolveStockfishFlavor(value?: string): StockfishFlavor;
+export declare class Stockfish {
+    private session;
+    private queue;
+    private queueRunning;
+    private queueScheduled;
+    private queued;
+    private quitGeneration;
+    private readonly terminated;
+    private readonly initEngine;
+    private readonly configuredFlavor;
+    private readonly maxQueue;
+    private readonly timeouts;
+    constructor(options?: StockfishOptions);
+    private init;
+    private handshake;
+    private release;
+    private scheduleQueue;
+    private removeQueued;
+    private enqueue;
+    analyze(fen: string, depth: number, multipv: number, signal?: AbortSignal): Promise<SfLine[]>;
+    private doAnalyze;
+    private failSession;
+    private invalidateSession;
+    private terminate;
+    quit(): Promise<void>;
+}
+export declare const stockfish: Stockfish;
+export {};

package/dist/engines/stockfish.js

@@ -48,7 +48,9 @@ function parseWdl(line) {
 }
 export class Stockfish {
     session = null;
-    queue = Promise.resolve();
+    queue = [];
+    queueRunning = false;
+    queueScheduled = false;
     queued = 0;
     quitGeneration = 0;
     terminated = new WeakSet();
@@ -191,14 +193,44 @@ export class Stockfish {
         }
         request.abortListener = null;
     }
+    scheduleQueue() {
+        if (this.queueRunning || this.queueScheduled)
+            return;
+        this.queueScheduled = true;
+        queueMicrotask(() => {
+            this.queueScheduled = false;
+            if (this.queueRunning)
+                return;
+            const next = this.queue.shift();
+            if (!next)
+                return;
+            if (next.request.cancelled) {
+                this.release(next.request);
+                this.scheduleQueue();
+                return;
+            }
+            this.queueRunning = true;
+            void next.run().finally(() => {
+                this.release(next.request);
+                this.queueRunning = false;
+                this.scheduleQueue();
+            });
+        });
+    }
+    removeQueued(request) {
+        const index = this.queue.findIndex((item) => item.request === request);
+        if (index < 0)
+            return false;
+        this.queue.splice(index, 1);
+        return true;
+    }
     enqueue(request, fn) {
         if (this.queued >= this.maxQueue) {
             return false;
         }
         this.queued++;
-        const run = this.queue.then(fn);
-        this.queue = run.then(() => { }, () => { });
-        void run.finally(() => this.release(request));
+        this.queue.push({ request, run: fn });
+        this.scheduleQueue();
         return true;
     }
     analyze(fen, depth, multipv, signal) {
@@ -229,11 +261,18 @@ export class Stockfish {
             request.cancelled = true;
             request.cancellation = error;
             if (request.started) {
-                request.stop?.(error);
+                if (request.stop)
+                    request.stop(error);
+                else {
+                    request.reject(error);
+                    this.release(request);
+                }
             }
             else {
+                this.removeQueued(request);
                 request.reject(error);
                 this.release(request);
+                this.scheduleQueue();
             }
         };
         request.abortListener = cancel;
@@ -288,6 +327,7 @@ export class Stockfish {
             const byPv = new Map();
             let settled = false;
             let cancellation = null;
+            let timeout = null;
             let stopSent = false;
             let stopTimer = null;
             let failTimer = null;
@@ -323,6 +363,8 @@ export class Stockfish {
             const stop = (error, cancelled) => {
                 if (cancelled)
                     cancellation ??= error;
+                else
+                    timeout ??= error;
                 if (stopSent)
                     return;
                 stopSent = true;
@@ -363,6 +405,8 @@ export class Stockfish {
                 else if (line.startsWith("bestmove")) {
                     if (cancellation)
                         fail(cancellation, false);
+                    else if (timeout)
+                        fail(timeout, false);
                     else
                         succeed();
                 }

package/dist/env.d.ts

@@ -0,0 +1 @@
+export declare function loadEnv(path?: string): void;

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class ChessError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function fail(code: string, message: string): never;

package/dist/eval.d.ts

@@ -0,0 +1,24 @@
+import type { SfLine } from "./types.js";
+export type Eval = {
+    type: "cp";
+    value: number;
+} | {
+    type: "mate";
+    plies: number;
+};
+export declare function toEval(line: SfLine): Eval | null;
+export declare function evalToCp(e: Eval): number;
+export declare function negateEval(e: Eval): Eval;
+export declare const CLASSIFICATION: {
+    readonly best: 0;
+    readonly excellent: 30;
+    readonly good: 80;
+    readonly inaccuracy: 150;
+    readonly mistake: 300;
+};
+export declare function classifyCpLoss(cpLoss: number): string;
+export type AnalysisLevel = "fast" | "normal" | "deep";
+export declare const ANALYSIS_PRESETS: Record<AnalysisLevel, {
+    depth: number;
+    multipv: number;
+}>;

package/dist/explorer.d.ts

@@ -0,0 +1,64 @@
+import { Chess } from "chess.js";
+import { z } from "zod/v4";
+import type { LichessMove } from "./types.js";
+export declare const LICHESS_SPEEDS: readonly ["ultraBullet", "bullet", "blitz", "rapid", "classical", "correspondence"];
+export declare const LICHESS_RATINGS: readonly [0, 1000, 1200, 1400, 1600, 1800, 2000, 2200, 2500];
+export type LichessSpeed = (typeof LICHESS_SPEEDS)[number];
+export type LichessRating = (typeof LICHESS_RATINGS)[number];
+export declare const lichessSpeedSchema: z.ZodEnum<{
+    blitz: "blitz";
+    bullet: "bullet";
+    classical: "classical";
+    correspondence: "correspondence";
+    rapid: "rapid";
+    ultraBullet: "ultraBullet";
+}>;
+export declare const lichessRatingSchema: z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1000>, z.ZodLiteral<1200>, z.ZodLiteral<1400>, z.ZodLiteral<1600>, z.ZodLiteral<1800>, z.ZodLiteral<2000>, z.ZodLiteral<2200>, z.ZodLiteral<2500>]>;
+export declare const EXPLORER_ATTEMPT_TIMEOUT_MS = 5000;
+export declare const EXPLORER_MAX_ATTEMPTS = 2;
+export declare const EXPLORER_DEFAULT_RETRY_DELAY_MS = 250;
+export declare const EXPLORER_TOTAL_TIMEOUT_MS = 12000;
+export declare const EXPLORER_RATE_LIMIT_COOLDOWN_MS = 60000;
+export declare const EXPLORER_ERROR_KINDS: readonly ["disabled", "invalid_input", "timeout", "network", "auth", "rate_limited", "upstream", "http", "invalid_response"];
+export type ExplorerErrorKind = (typeof EXPLORER_ERROR_KINDS)[number];
+export declare class ExplorerError extends Error {
+    readonly kind: ExplorerErrorKind;
+    readonly status?: number | undefined;
+    readonly reason: ExplorerErrorKind;
+    constructor(kind: ExplorerErrorKind, message: string, status?: number | undefined);
+}
+export interface ExplorerResult {
+    db: string;
+    white: number;
+    draws: number;
+    black: number;
+    moves: LichessMove[];
+    opening: {
+        eco: string;
+        name: string;
+    } | null;
+}
+export type ExplorerFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
+export interface ExplorerRequestOptions {
+    fetch?: ExplorerFetch;
+    limiter?: ExplorerLimiter;
+    sleep?: (ms: number) => Promise<void>;
+    timeout?: (ms: number) => AbortSignal;
+    signal?: AbortSignal;
+    now?: () => number;
+    token?: string;
+}
+export declare function explorerEnabled(): boolean;
+export interface ExplorerLimiterOptions {
+    callerSignal: AbortSignal | undefined;
+    deadline: number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export interface ExplorerLimiter {
+    readonly pending: number;
+    run<T>(options: ExplorerLimiterOptions, request: () => Promise<T>): Promise<T>;
+    cooldown(ms: number, now: number): void;
+}
+export declare function createExplorerLimiter(): ExplorerLimiter;
+export declare function openingExplorer(chess: Chess, db: "lichess" | "masters", speeds: readonly string[], ratings: readonly number[], options?: ExplorerRequestOptions): Promise<ExplorerResult>;