llm-chess-mcp 0.3.1 → 0.4.1

package/README.md

@@ -70,6 +70,108 @@ pnpm test:package
 `pnpm test:live` queries Lichess only when `LICHESS_TOKEN` is set; otherwise it
 skips without making a network request.
 
+## Transports
+
+stdio remains the default transport and requires no flags. To expose a local
+Streamable HTTP endpoint instead:
+
+```bash
+pnpm build
+node dist/index.js --transport http
+```
+
+The server listens on `http://127.0.0.1:3000/mcp` and supports Streamable HTTP
+sessions, JSON responses, and SSE. The equivalent development command is
+`pnpm dev:http`.
+
+HTTP options:
+
+```text
+--host <host>            Bind host (default: 127.0.0.1)
+--port <port>            Listen port (default: 3000)
+--path <path>            Endpoint path (default: /mcp)
+--allowed-host <host>    Allowed Host/Origin hostname; repeat as needed
+```
+
+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
+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
@@ -264,10 +366,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/cli.js

@@ -0,0 +1,107 @@
+export const HELP = `Usage: llm-chess-mcp [options]
+
+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)
+  --path <path>             HTTP endpoint path (default: /mcp)
+  --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)
+  -h, --help                Show this help
+`;
+function optionValue(args, index, option) {
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${option} requires a value`);
+    }
+    return value;
+}
+function splitOption(arg) {
+    const index = arg.indexOf("=");
+    return index === -1 ? null : [arg.slice(0, index), arg.slice(index + 1)];
+}
+export function parseCli(args) {
+    let transport = "stdio";
+    let host = "127.0.0.1";
+    let port = 3_000;
+    let path = "/mcp";
+    let help = false;
+    let hasHttpOption = false;
+    const allowedHosts = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        const pair = splitOption(arg);
+        const option = pair?.[0] ?? arg;
+        const inlineValue = pair?.[1];
+        const value = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = optionValue(args, index, option);
+            index += 1;
+            return next;
+        };
+        switch (option) {
+            case "-h":
+            case "--help":
+                if (inlineValue !== undefined)
+                    throw new Error(`${option} takes no value`);
+                help = true;
+                break;
+            case "--http":
+                if (inlineValue !== undefined)
+                    throw new Error("--http takes no value");
+                transport = "http";
+                break;
+            case "--transport": {
+                const selected = value();
+                if (selected !== "stdio" && selected !== "http") {
+                    throw new Error("--transport must be stdio or http");
+                }
+                transport = selected;
+                break;
+            }
+            case "--host":
+                host = value();
+                hasHttpOption = true;
+                break;
+            case "--port": {
+                const selected = value();
+                if (!/^\d+$/.test(selected))
+                    throw new Error("--port must be an integer");
+                port = Number(selected);
+                hasHttpOption = true;
+                break;
+            }
+            case "--path":
+                path = value();
+                hasHttpOption = true;
+                break;
+            case "--allowed-host":
+                allowedHosts.push(value());
+                hasHttpOption = true;
+                break;
+            default:
+                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 (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+        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 (transport === "stdio" && hasHttpOption) {
+        throw new Error("HTTP options require --transport http");
+    }
+    if (transport === "http" &&
+        (host === "0.0.0.0" || host === "::" || host === "[::]") &&
+        allowedHosts.length === 0) {
+        throw new Error("wildcard HTTP binding requires at least one --allowed-host");
+    }
+    return { transport, host, port, path, allowedHosts, help };
+}

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;
+            }
+        };
+    }
+}