llm-chess-mcp 0.4.0 → 0.4.3

package/README.md

@@ -98,6 +98,80 @@ does not provide authentication or TLS; use a trusted network or an
 authenticated reverse proxy when exposing it beyond localhost. Origin values
 are validated when present, but the server does not emit browser CORS headers.
 
+### Reverse-proxy deployment
+
+The HTTP server is intended to run behind a reverse proxy for any non-local
+deployment. The proxy owns TLS termination, client authentication, external
+rate/connection limits, and any future CORS policy. Bind this process to
+localhost only; never expose its port directly through a firewall, container
+port mapping, or load balancer.
+
+For example, start the backend with the public hostname that Nginx will pass
+through as `Host`:
+
+```bash
+node dist/index.js --transport http --host 127.0.0.1 --port 3000 \
+  --allowed-host chess-mcp.example.com
+```
+
+This is a minimal Nginx layout. It assumes an identity-aware auth service is
+available only on localhost at `127.0.0.1:4180`; configure that service and
+the certificate paths for the deployment. The limits are examples, not a
+substitute for capacity planning.
+
+```nginx
+limit_req_zone $binary_remote_addr zone=mcp_req:10m rate=5r/s;
+limit_conn_zone $binary_remote_addr zone=mcp_conn:10m;
+
+server {
+    listen 443 ssl;
+    server_name chess-mcp.example.com;
+    ssl_certificate     /etc/ssl/certs/chess-mcp.pem;
+    ssl_certificate_key /etc/ssl/private/chess-mcp.key;
+
+    location = /_mcp_auth {
+        internal;
+        proxy_pass http://127.0.0.1:4180/auth;
+        proxy_pass_request_body off;
+        proxy_set_header Content-Length "";
+        proxy_set_header X-Original-Method $request_method;
+        proxy_set_header X-Original-URI $request_uri;
+    }
+
+    location = /mcp {
+        auth_request /_mcp_auth;
+        limit_req zone=mcp_req burst=20 nodelay;
+        limit_conn mcp_conn 10;
+        client_max_body_size 2m;
+
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Connection "";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-User "";
+        proxy_set_header X-Forwarded-Email "";
+        proxy_buffering off;
+        proxy_read_timeout 90s;
+
+        # Intentionally no Access-Control-Allow-* headers: browser CORS is unsupported.
+    }
+}
+```
+
+The application does not trust forwarded identity headers and does not assign
+games to authenticated users. All games in one process share one `GameStore`;
+the opaque `game_id` is the capability to operate a game within the trusted
+deployment, not an OAuth token or user identity. Do not disclose it across
+trust boundaries.
+
+This server does not implement MCP OAuth discovery, bearer-token validation,
+or browser CORS. A proxy may authenticate access to the endpoint, but that is
+deployment policy rather than an application-level identity or ownership
+model. Browser clients are unsupported unless a proxy deliberately adds and
+maintains the required CORS policy.
+
 ### Export Maia3 to ONNX (build-time only)
 
 This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
@@ -205,7 +279,7 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `game_legal_moves` | All legal moves with metadata |
 | `game_pgn` | Export the game as PGN |
 | `game_import_pgn` | Import a PGN into a new game |
-| `position_analyze` | Stockfish multipv lines (cp/mate/WDL + PV), `analysis_level` preset |
+| `position_analyze` | Stockfish multipv lines (cp/mate/WDL + UCI/SAN PV), `analysis_level` preset |
 | `human_move_distribution` | Maia3 human-move probabilities at a target Elo |
 | `move_evaluate` | Score one or more moves + cpLoss + classification |
 | `move_candidates` | **Primary tool**: unified candidates (objective + human + opening) |
@@ -233,6 +307,9 @@ 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.
 
 ## Candidate structure
 
@@ -292,10 +369,27 @@ rejected:
 
 ## Runtime limits
 
-- Up to 1,000 game sessions are retained; idle sessions expire after one hour.
+- 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 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.
+- 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.
+
+Programmatic users can override the HTTP limits through `HttpServerOptions`.
+These safeguards do not replace public-edge quotas: a public deployment must
+still enforce request, connection, and authentication limits at the reverse
+proxy.
+
+MCP cancellation notifications, session deletion, and server shutdown propagate
+to Stockfish, Maia, and Lichess work. Stockfish stops safely at its UCI queue
+boundary; 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.
 
 ## Intents
 

package/dist/chess.js

@@ -81,3 +81,20 @@ export function parseMove(chess, move) {
 export function playParsedMove(chess, move) {
     return chess.move(moveDescriptor(move));
 }
+export function pvToSan(chess, pv) {
+    const copy = new Chess(chess.fen());
+    const san = [];
+    for (const uci of pv) {
+        try {
+            const move = parseMove(copy, uci);
+            san.push(move.san);
+            playParsedMove(copy, move);
+        }
+        catch (error) {
+            if (!(error instanceof ChessError))
+                throw error;
+            break;
+        }
+    }
+    return san;
+}

package/dist/engines/stockfish.js

@@ -30,6 +30,9 @@ function loadStockfish() {
 function asError(error) {
     return error instanceof Error ? error : new Error(String(error));
 }
+function abortError(signal) {
+    return asError(signal.reason ?? "stockfish request cancelled");
+}
 function parseScore(token) {
     if (token.startsWith("cp"))
         return { cp: Number(token.slice(2)), mate: null };
@@ -178,34 +181,104 @@ export class Stockfish {
             }
         });
     }
-    enqueue(fn) {
+    release(request) {
+        if (request.released)
+            return;
+        request.released = true;
+        this.queued--;
+        if (request.signal && request.abortListener) {
+            request.signal.removeEventListener("abort", request.abortListener);
+        }
+        request.abortListener = null;
+    }
+    enqueue(request, fn) {
         if (this.queued >= this.maxQueue) {
-            return Promise.reject(new Error("stockfish queue full"));
+            return false;
         }
         this.queued++;
         const run = this.queue.then(fn);
         this.queue = run.then(() => { }, () => { });
-        return run.finally(() => {
-            this.queued--;
-        });
+        void run.finally(() => this.release(request));
+        return true;
     }
-    analyze(fen, depth, multipv) {
+    analyze(fen, depth, multipv, signal) {
+        if (signal?.aborted) {
+            return Promise.reject(abortError(signal));
+        }
         const quitGeneration = this.quitGeneration;
-        return this.enqueue(async () => {
-            if (quitGeneration !== this.quitGeneration) {
-                throw new Error("stockfish request cancelled");
+        let request;
+        const result = new Promise((resolve, reject) => {
+            request = {
+                cancelled: false,
+                cancellation: null,
+                started: false,
+                released: false,
+                signal,
+                abortListener: null,
+                stop: null,
+                resolve,
+                reject,
+            };
+        });
+        const cancel = () => {
+            if (request.cancelled)
+                return;
+            const error = request.signal
+                ? abortError(request.signal)
+                : new Error("stockfish request cancelled");
+            request.cancelled = true;
+            request.cancellation = error;
+            if (request.started) {
+                request.stop?.(error);
             }
-            await this.init();
-            if (quitGeneration !== this.quitGeneration) {
-                throw new Error("stockfish request cancelled");
+            else {
+                request.reject(error);
+                this.release(request);
             }
-            const session = this.session;
-            if (!session)
-                throw new Error("stockfish unavailable after initialization");
-            return this.doAnalyze(session, fen, depth, multipv);
-        });
+        };
+        request.abortListener = cancel;
+        if (!this.enqueue(request, async () => {
+            if (request.cancelled)
+                return;
+            request.started = true;
+            try {
+                if (quitGeneration !== this.quitGeneration) {
+                    throw new Error("stockfish request cancelled");
+                }
+                await this.init();
+                if (request.cancelled || quitGeneration !== this.quitGeneration) {
+                    if (!request.cancelled) {
+                        throw new Error("stockfish request cancelled");
+                    }
+                    return;
+                }
+                const session = this.session;
+                if (!session)
+                    throw new Error("stockfish unavailable after initialization");
+                const lines = await this.doAnalyze(session, fen, depth, multipv, (stop) => {
+                    request.stop = stop;
+                });
+                if (!request.cancelled)
+                    request.resolve(lines);
+            }
+            catch (error) {
+                if (!request.cancelled)
+                    request.reject(asError(error));
+            }
+            finally {
+                request.stop = null;
+                if (request.cancellation)
+                    request.reject(request.cancellation);
+            }
+        })) {
+            return Promise.reject(new Error("stockfish queue full"));
+        }
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted)
+            cancel();
+        return result;
     }
-    doAnalyze(session, fen, depth, multipv) {
+    doAnalyze(session, fen, depth, multipv, setStop) {
         return new Promise((resolve, reject) => {
             const engine = session.engine;
             if (!engine) {
@@ -214,6 +287,8 @@ export class Stockfish {
             }
             const byPv = new Map();
             let settled = false;
+            let cancellation = null;
+            let stopSent = false;
             let stopTimer = null;
             let failTimer = null;
             const cleanup = () => {
@@ -223,6 +298,7 @@ export class Stockfish {
                     clearTimeout(failTimer);
                 stopTimer = null;
                 failTimer = null;
+                setStop(null);
                 session.aborts.delete(abort);
                 if (engine.listener === listener)
                     engine.listener = null;
@@ -244,6 +320,23 @@ export class Stockfish {
                 reject(error);
             };
             const abort = (error) => fail(error, false);
+            const stop = (error, cancelled) => {
+                if (cancelled)
+                    cancellation ??= error;
+                if (stopSent)
+                    return;
+                stopSent = true;
+                if (stopTimer)
+                    clearTimeout(stopTimer);
+                stopTimer = null;
+                failTimer = setTimeout(() => fail(cancellation ?? error, true), this.timeouts.stopGrace);
+                try {
+                    engine.sendCommand("stop");
+                }
+                catch (sendError) {
+                    fail(asError(sendError), true);
+                }
+            };
             const listener = (line) => {
                 if (line.startsWith("info") && line.includes(" multipv ")) {
                     const multipv = line.match(/multipv (?<value>\d+)/)?.groups?.value;
@@ -268,19 +361,17 @@ export class Stockfish {
                     });
                 }
                 else if (line.startsWith("bestmove")) {
-                    succeed();
+                    if (cancellation)
+                        fail(cancellation, false);
+                    else
+                        succeed();
                 }
             };
             session.aborts.add(abort);
             engine.listener = listener;
+            setStop((error) => stop(error, true));
             stopTimer = setTimeout(() => {
-                failTimer = setTimeout(() => fail(new Error("stockfish analyze timeout"), true), this.timeouts.stopGrace);
-                try {
-                    engine.sendCommand("stop");
-                }
-                catch (error) {
-                    fail(asError(error), true);
-                }
+                stop(new Error("stockfish analyze timeout"), false);
             }, this.timeouts.analyze);
             try {
                 engine.sendCommand("position fen " + fen);

package/dist/explorer.js

@@ -105,7 +105,32 @@ function isRetryable(kind) {
         kind === "rate_limited" ||
         kind === "upstream");
 }
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+async function sleepWithSignal(sleep, ms, signal) {
+    throwIfAborted(signal);
+    if (!signal)
+        return sleep(ms);
+    await new Promise((resolve, reject) => {
+        const onAbort = () => {
+            cleanup();
+            reject(signal.reason);
+        };
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        signal.addEventListener("abort", onAbort, { once: true });
+        sleep(ms).then(() => {
+            cleanup();
+            resolve();
+        }, (cause) => {
+            cleanup();
+            reject(cause);
+        });
+    });
+}
 export async function openingExplorer(chess, db, speeds, ratings, options = {}) {
+    const callerSignal = options.signal;
+    throwIfAborted(callerSignal);
     const token = options.token ?? process.env.LICHESS_TOKEN ?? "";
     if (!token)
         throw error("disabled");
@@ -136,10 +161,12 @@ export async function openingExplorer(chess, db, speeds, ratings, options = {})
     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) {
+        throwIfAborted(callerSignal);
         const remaining = deadline - now();
         if (remaining <= 0)
             throw error("timeout");
-        const signal = timeout(Math.max(1, Math.min(EXPLORER_ATTEMPT_TIMEOUT_MS, remaining)));
+        const attemptSignal = timeout(Math.max(1, Math.min(EXPLORER_ATTEMPT_TIMEOUT_MS, remaining)));
+        const signal = AbortSignal.any(callerSignal ? [callerSignal, attemptSignal] : [attemptSignal]);
         let response;
         try {
             response = await request(url, {
@@ -148,13 +175,15 @@ export async function openingExplorer(chess, db, speeds, ratings, options = {})
             });
         }
         catch {
+            throwIfAborted(callerSignal);
             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);
+            await sleepWithSignal(sleep, delay, callerSignal);
             continue;
         }
+        throwIfAborted(callerSignal);
         if (!response.ok) {
             const kind = response.status === 401 || response.status === 403
                 ? "auth"
@@ -172,7 +201,7 @@ export async function openingExplorer(chess, db, speeds, ratings, options = {})
             if (delay > EXPLORER_MAX_RETRY_DELAY_MS || delay >= retryBudget) {
                 throw lastError;
             }
-            await sleep(delay);
+            await sleepWithSignal(sleep, delay, callerSignal);
             continue;
         }
         let body;
@@ -180,17 +209,19 @@ export async function openingExplorer(chess, db, speeds, ratings, options = {})
             body = await response.json();
         }
         catch (cause) {
+            throwIfAborted(callerSignal);
             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);
+                    await sleepWithSignal(sleep, delay, callerSignal);
                     continue;
                 }
                 throw lastError;
             }
             throw error("invalid_response");
         }
+        throwIfAborted(callerSignal);
         const parsed = responseSchema.safeParse(body);
         if (!parsed.success)
             throw error("invalid_response");

package/dist/http-work.js

@@ -0,0 +1,34 @@
+import { ChessError } from "./errors.js";
+export class HttpWorkAdmission {
+    max;
+    maxPerSession;
+    #active = 0;
+    constructor(max, maxPerSession) {
+        this.max = max;
+        this.maxPerSession = maxPerSession;
+    }
+    session(lifecycle) {
+        let active = 0;
+        return async (request, work) => {
+            const signal = AbortSignal.any([request, lifecycle]);
+            signal.throwIfAborted();
+            if (active >= this.maxPerSession) {
+                throw new ChessError("SERVER_BUSY", "MCP session work limit reached");
+            }
+            if (this.#active >= this.max) {
+                throw new ChessError("SERVER_BUSY", "server work limit reached");
+            }
+            active += 1;
+            this.#active += 1;
+            try {
+                const result = await work(signal);
+                signal.throwIfAborted();
+                return result;
+            }
+            finally {
+                active -= 1;
+                this.#active -= 1;
+            }
+        };
+    }
+}