llm-chess-mcp 0.4.1 → 0.4.4

package/README.md

@@ -279,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) |
@@ -307,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
 
@@ -370,8 +373,8 @@ 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.
+- 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

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/explorer.js

@@ -128,7 +128,7 @@ async function sleepWithSignal(sleep, ms, signal) {
         });
     });
 }
-export async function openingExplorer(chess, db, speeds, ratings, options = {}) {
+function setupExplorerRequest(chess, db, speeds, ratings, options) {
     const callerSignal = options.signal;
     throwIfAborted(callerSignal);
     const token = options.token ?? process.env.LICHESS_TOKEN ?? "";
@@ -145,120 +145,149 @@ export async function openingExplorer(chess, db, speeds, ratings, options = {})
     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 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 now = options.now ?? Date.now;
+    return {
+        callerSignal,
+        db,
+        deadline: now() + EXPLORER_TOTAL_TIMEOUT_MS,
+        legalMoves: new Map(chess.moves({ verbose: true }).map((move) => [move.lan, move.san])),
+        now,
+        request: options.fetch ?? globalThis.fetch,
+        sleep: options.sleep ??
+            ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        timeout: options.timeout ?? ((ms) => AbortSignal.timeout(ms)),
+        token,
+        url: `${BASE}/${db}?${params}`,
+    };
+}
+async function attemptRequest(setup) {
+    const { callerSignal, deadline, now, request, timeout, token, url } = setup;
+    throwIfAborted(callerSignal);
+    const remaining = deadline - now();
+    if (remaining <= 0)
+        throw error("timeout");
+    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, {
+            headers: { Authorization: `Bearer ${token}` },
+            signal,
+        });
+    }
+    catch {
         throwIfAborted(callerSignal);
-        const remaining = deadline - now();
-        if (remaining <= 0)
-            throw error("timeout");
-        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, {
-                headers: { Authorization: `Bearer ${token}` },
-                signal,
-            });
+        return { error: error(signal.aborted ? "timeout" : "network") };
+    }
+    throwIfAborted(callerSignal);
+    if (response.ok)
+        return { response, signal };
+    const kind = response.status === 401 || response.status === 403
+        ? "auth"
+        : response.status === 429
+            ? "rate_limited"
+            : response.status >= 500 && response.status <= 599
+                ? "upstream"
+                : "http";
+    return {
+        error: error(kind, response.status),
+        retryAfter: response.headers.get("retry-after"),
+    };
+}
+async function normalizeSuccessfulResponse(response, signal, setup) {
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (cause) {
+        throwIfAborted(setup.callerSignal);
+        if (signal.aborted || cause instanceof TypeError) {
+            throw error(signal.aborted ? "timeout" : "network");
         }
-        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 sleepWithSignal(sleep, delay, callerSignal);
-            continue;
+        throw error("invalid_response");
+    }
+    throwIfAborted(setup.callerSignal);
+    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) || setup.legalMoves.get(move.uci) !== move.san) {
+            throw error("invalid_response");
         }
-        throwIfAborted(callerSignal);
-        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) {
+        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: setup.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,
+    };
+}
+async function retryAfterNetworkFailure(setup) {
+    const delay = Math.min(EXPLORER_DEFAULT_RETRY_DELAY_MS, Math.max(0, setup.deadline - setup.now()));
+    await sleepWithSignal(setup.sleep, delay, setup.callerSignal);
+}
+export async function openingExplorer(chess, db, speeds, ratings, options = {}) {
+    const setup = setupExplorerRequest(chess, db, speeds, ratings, options);
+    let lastError = error("network");
+    for (let attempt = 0; attempt < EXPLORER_MAX_ATTEMPTS; attempt += 1) {
+        const attemptResult = await attemptRequest(setup);
+        if ("error" in attemptResult) {
+            lastError = attemptResult.error;
+            if (!isRetryable(lastError.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 (attemptResult.retryAfter === undefined) {
+                await retryAfterNetworkFailure(setup);
+                continue;
+            }
+            const delay = retryAfterMs(attemptResult.retryAfter, setup.now());
+            const retryBudget = Math.max(0, setup.deadline - setup.now());
             if (delay > EXPLORER_MAX_RETRY_DELAY_MS || delay >= retryBudget) {
                 throw lastError;
             }
-            await sleepWithSignal(sleep, delay, callerSignal);
+            await sleepWithSignal(setup.sleep, delay, setup.callerSignal);
             continue;
         }
-        let body;
         try {
-            body = await response.json();
+            return await normalizeSuccessfulResponse(attemptResult.response, attemptResult.signal, setup);
         }
         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 sleepWithSignal(sleep, delay, callerSignal);
-                    continue;
-                }
-                throw lastError;
+            if (!(cause instanceof ExplorerError) || !isRetryable(cause.kind)) {
+                throw cause;
             }
-            throw error("invalid_response");
-        }
-        throwIfAborted(callerSignal);
-        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");
+            lastError = cause;
+            if (attempt + 1 >= EXPLORER_MAX_ATTEMPTS)
+                throw lastError;
+            await retryAfterNetworkFailure(setup);
         }
-        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,
-        };
     }
     throw lastError;
 }

package/dist/games.js

@@ -1,8 +1,29 @@
 import { randomUUID } from "node:crypto";
 import { Chess } from "chess.js";
+import { playParsedMove, snapshotChess } from "./chess.js";
 import { ChessError } from "./errors.js";
 export const MAX_GAMES = 1_000;
 export const GAME_TTL_MS = 60 * 60 * 1_000;
+function cloneChess(chess) {
+    const copy = snapshotChess(chess);
+    for (const [key, value] of Object.entries(chess.getHeaders())) {
+        copy.setHeader(key, value);
+    }
+    const comments = new Map(chess.getComments().map(({ fen, comment }) => [fen, comment]));
+    const reversed = [];
+    while (true) {
+        const comment = comments.get(copy.fen());
+        if (comment !== undefined)
+            copy.setComment(comment);
+        const move = copy.undo();
+        if (!move)
+            break;
+        reversed.push(move);
+    }
+    for (const move of reversed.reverse())
+        playParsedMove(copy, move);
+    return copy;
+}
 export class GameStore {
     maxGames;
     idleTtlMs;
@@ -44,10 +65,28 @@ export class GameStore {
         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 });
+        this.games.set(id, {
+            chess: cloneChess(chess),
+            createdAt: now,
+            lastAccessedAt: now,
+            revision: 0,
+        });
         return id;
     }
-    getGame(id) {
+    getSnapshot(id) {
+        const game = this.getLiveGame(id);
+        return { chess: cloneChess(game.chess), revision: game.revision };
+    }
+    applyMove(id, expectedRevision, move) {
+        const game = this.getLiveGame(id);
+        if (expectedRevision !== game.revision) {
+            throw new ChessError("STALE_POSITION", `position changed: expected revision ${expectedRevision}, current ${game.revision}`);
+        }
+        playParsedMove(game.chess, move);
+        game.revision += 1;
+        return { chess: cloneChess(game.chess), revision: game.revision };
+    }
+    getLiveGame(id) {
         const game = this.games.get(id);
         if (!game)
             throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
@@ -59,11 +98,6 @@ export class GameStore {
         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);
@@ -81,11 +115,3 @@ export class GameStore {
     }
 }
 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();

package/dist/http.js

@@ -166,6 +166,18 @@ function hasUnsupportedContentEncoding(req) {
     return (contentEncoding !== undefined &&
         (typeof contentEncoding !== "string" || contentEncoding.trim().toLowerCase() !== "identity"));
 }
+async function parsePostBody(req, limit, timeoutMs) {
+    const body = await readPostBody(req, limit, timeoutMs);
+    if (!body.ok)
+        return body;
+    if (!isJsonContentType(req)) {
+        return { ok: false, status: 415, message: "Content-Type must be application/json" };
+    }
+    if (hasUnsupportedContentEncoding(req)) {
+        return { ok: false, status: 415, message: "Content-Encoding must be identity" };
+    }
+    return body;
+}
 const UNABORTABLE_SIGNAL = new AbortController().signal;
 function scopedServices(services, run) {
     return {
@@ -222,6 +234,17 @@ export async function serveHttp(options = {}, services = defaultAppServices) {
             .filter(([, session]) => session.activeRequests === 0 && now - session.lastUsedAt >= limits.sessionIdleTtlMs)
             .map(([id, session]) => closeSession(id, session)));
     };
+    const withActiveSession = async (session, work) => {
+        session.activeRequests += 1;
+        session.lastUsedAt = Date.now();
+        try {
+            return await work();
+        }
+        finally {
+            session.activeRequests -= 1;
+            session.lastUsedAt = Date.now();
+        }
+    };
     const releasePost = (session) => {
         activePosts -= 1;
         if (session)
@@ -290,33 +313,22 @@ export async function serveHttp(options = {}, services = defaultAppServices) {
                     closeWithError(req, res, 503, "server request limit reached", { "retry-after": "1" });
                     return;
                 }
-                session.activeRequests += 1;
-                session.lastUsedAt = Date.now();
                 try {
-                    const body = await readPostBody(req, limits.maxRequestBodyBytes, limits.requestTimeoutMs);
-                    if (!body.ok) {
-                        closeWithError(req, res, body.status, body.message);
-                        return;
-                    }
-                    if (!isJsonContentType(req)) {
-                        closeWithError(req, res, 415, "Content-Type must be application/json");
-                        return;
-                    }
-                    if (hasUnsupportedContentEncoding(req)) {
-                        closeWithError(req, res, 415, "Content-Encoding must be identity");
-                        return;
-                    }
-                    await session.transport.handleRequest(req, res, body.value);
+                    await withActiveSession(session, async () => {
+                        const body = await parsePostBody(req, limits.maxRequestBodyBytes, limits.requestTimeoutMs);
+                        if (!body.ok) {
+                            closeWithError(req, res, body.status, body.message);
+                            return;
+                        }
+                        await session.transport.handleRequest(req, res, body.value);
+                    });
                 }
                 finally {
-                    session.activeRequests -= 1;
-                    session.lastUsedAt = Date.now();
                     releasePost(session);
                 }
                 return;
             }
-            session.lastUsedAt = Date.now();
-            await session.transport.handleRequest(req, res);
+            await withActiveSession(session, () => session.transport.handleRequest(req, res));
             return;
         }
         if (req.method !== "POST") {
@@ -328,90 +340,80 @@ export async function serveHttp(options = {}, services = defaultAppServices) {
             closeWithError(req, res, 503, "server request limit reached", { "retry-after": "1" });
             return;
         }
-        const body = await readPostBody(req, limits.maxRequestBodyBytes, limits.requestTimeoutMs);
-        if (!body.ok) {
-            releasePost(undefined);
-            closeWithError(req, res, body.status, body.message);
-            return;
-        }
-        if (!isJsonContentType(req)) {
-            releasePost(undefined);
-            closeWithError(req, res, 415, "Content-Type must be application/json");
-            return;
-        }
-        if (hasUnsupportedContentEncoding(req)) {
-            releasePost(undefined);
-            closeWithError(req, res, 415, "Content-Encoding must be identity");
-            return;
-        }
-        if (!isInitializeRequest(body.value)) {
-            releasePost(undefined);
-            closeWithError(req, res, 400, "MCP session initialization required");
-            return;
-        }
-        await reapExpiredSessions();
-        if (closing) {
-            releasePost(undefined);
-            closeWithError(req, res, 503, "server is shutting down", { "retry-after": "1" });
-            return;
-        }
-        if (sessions.size + pendingInitializations >= limits.maxSessions) {
-            releasePost(undefined);
-            closeWithError(req, res, 503, "MCP session limit reached", { "retry-after": "1" });
-            return;
-        }
-        pendingInitializations += 1;
-        let initializedId;
-        let session;
-        let hasReservation = true;
-        const transport = new NodeStreamableHTTPServerTransport({
-            sessionIdGenerator: randomUUID,
-            onsessioninitialized: (newId) => {
-                initializedId = newId;
+        try {
+            const body = await parsePostBody(req, limits.maxRequestBodyBytes, limits.requestTimeoutMs);
+            if (!body.ok) {
+                closeWithError(req, res, body.status, body.message);
+                return;
+            }
+            if (!isInitializeRequest(body.value)) {
+                closeWithError(req, res, 400, "MCP session initialization required");
+                return;
+            }
+            await reapExpiredSessions();
+            if (closing) {
+                closeWithError(req, res, 503, "server is shutting down", { "retry-after": "1" });
+                return;
+            }
+            if (sessions.size + pendingInitializations >= limits.maxSessions) {
+                closeWithError(req, res, 503, "MCP session limit reached", { "retry-after": "1" });
+                return;
+            }
+            pendingInitializations += 1;
+            let initializedId;
+            let session;
+            let hasReservation = true;
+            const transport = new NodeStreamableHTTPServerTransport({
+                sessionIdGenerator: randomUUID,
+                onsessioninitialized: (newId) => {
+                    initializedId = newId;
+                    initializing.delete(session);
+                    if (hasReservation) {
+                        hasReservation = false;
+                        pendingInitializations -= 1;
+                    }
+                    session.lastUsedAt = Date.now();
+                    sessions.set(newId, session);
+                },
+                onsessionclosed: (closedId) => {
+                    const current = sessions.get(closedId);
+                    if (current === session)
+                        sessions.delete(closedId);
+                },
+            });
+            const abort = new AbortController();
+            const mcp = buildServer(scopedServices(services, workAdmission.session(abort.signal)));
+            session = {
+                server: mcp,
+                transport,
+                abort,
+                lastUsedAt: Date.now(),
+                activeRequests: 0,
+                activePosts: 0,
+            };
+            initializing.add(session);
+            transport.onclose = () => {
+                session.abort.abort(new DOMException("MCP session closed", "AbortError"));
+                if (initializedId && sessions.get(initializedId) === session) {
+                    sessions.delete(initializedId);
+                }
+            };
+            try {
+                await withActiveSession(session, async () => {
+                    await mcp.connect(transport);
+                    await transport.handleRequest(req, res, body.value);
+                });
+            }
+            finally {
                 initializing.delete(session);
-                if (hasReservation) {
-                    hasReservation = false;
+                if (hasReservation)
                     pendingInitializations -= 1;
-                }
-                session.lastUsedAt = Date.now();
-                sessions.set(newId, session);
-            },
-            onsessionclosed: (closedId) => {
-                const current = sessions.get(closedId);
-                if (current === session)
-                    sessions.delete(closedId);
-            },
-        });
-        const abort = new AbortController();
-        const mcp = buildServer(scopedServices(services, workAdmission.session(abort.signal)));
-        session = {
-            server: mcp,
-            transport,
-            abort,
-            lastUsedAt: Date.now(),
-            activeRequests: 1,
-            activePosts: 0,
-        };
-        initializing.add(session);
-        transport.onclose = () => {
-            session.abort.abort(new DOMException("MCP session closed", "AbortError"));
-            if (initializedId && sessions.get(initializedId) === session) {
-                sessions.delete(initializedId);
+                if (!initializedId)
+                    await mcp.close();
             }
-        };
-        try {
-            await mcp.connect(transport);
-            await transport.handleRequest(req, res, body.value);
         }
         finally {
-            session.activeRequests -= 1;
-            session.lastUsedAt = Date.now();
-            initializing.delete(session);
             releasePost(undefined);
-            if (hasReservation)
-                pendingInitializations -= 1;
-            if (!initializedId)
-                await mcp.close();
         }
     };
     const headerTimers = new WeakMap();

package/dist/intents.js

@@ -1,6 +1,3 @@
-import { stockfish } from "./engines/stockfish.js";
-import { humanMoveDistribution } from "./maia3/inference.js";
-import { ExplorerError, openingExplorer, explorerEnabled } from "./explorer.js";
 import { toEval, evalToCp } from "./eval.js";
 function softmax(values, temperature) {
     const scaled = values.map((v) => v / temperature);
@@ -122,31 +119,34 @@ export function candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResu
         moveSensitivity: computeMoveSensitivity(normalizedSfLines.map(({ line }) => line)),
     };
 }
-export async function computeCandidates(chess, elo, sfDepth, sfMultipv, maiaTopN, lichess, signal) {
-    const [sfLines, maiaMoves, lichessResult] = await Promise.all([
-        stockfish.analyze(chess.fen(), sfDepth, sfMultipv, signal),
-        humanMoveDistribution(chess, elo, elo, maiaTopN, signal),
-        lichess && explorerEnabled()
-            ? openingExplorer(chess, lichess.db, lichess.speeds, lichess.ratings, {
-                ...(signal ? { signal } : {}),
-            })
-                .then(explorerCandidateData)
-                .catch((e) => {
-                signal?.throwIfAborted();
-                return {
-                    status: "unavailable",
-                    reason: e instanceof ExplorerError ? e.reason : "upstream",
-                    totalGames: null,
-                    moves: [],
-                };
-            })
-            : Promise.resolve({
-                status: "disabled",
-                totalGames: null,
-                moves: [],
-            }),
-    ]);
-    return candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResult);
+export function createCandidateComputation(dependencies) {
+    return {
+        computeCandidates: async (chess, elo, sfDepth, sfMultipv, maiaTopN, lichess, signal) => {
+            const [sfLines, maiaMoves, lichessResult] = await Promise.all([
+                dependencies.analyze(chess.fen(), sfDepth, sfMultipv, signal),
+                dependencies.humanMoveDistribution(chess, elo, elo, maiaTopN, signal),
+                lichess && dependencies.explorerEnabled()
+                    ? dependencies
+                        .openingExplorer(chess, lichess.db, lichess.speeds, lichess.ratings, signal)
+                        .then(explorerCandidateData)
+                        .catch((error) => {
+                        signal?.throwIfAborted();
+                        return {
+                            status: "unavailable",
+                            reason: dependencies.explorerFailureReason(error),
+                            totalGames: null,
+                            moves: [],
+                        };
+                    })
+                    : Promise.resolve({
+                        status: "disabled",
+                        totalGames: null,
+                        moves: [],
+                    }),
+            ]);
+            return candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResult);
+        },
+    };
 }
 function winMargin(c) {
     const wdl = c.objective.wdl;

package/dist/services.js

@@ -1,15 +1,24 @@
 import { stockfish } from "./engines/stockfish.js";
-import { explorerEnabled, openingExplorer, } from "./explorer.js";
+import { ExplorerError, explorerEnabled, openingExplorer, } from "./explorer.js";
 import { defaultGameStore } from "./games.js";
-import { computeCandidates, rankByIntent } from "./intents.js";
+import { createCandidateComputation, rankByIntent } from "./intents.js";
 import { humanMoveDistribution } from "./maia3/inference.js";
+const analyze = (fen, depth, multipv, signal) => stockfish.analyze(fen, depth, multipv, signal);
+const openExplorer = (chess, db, speeds, ratings, signal) => openingExplorer(chess, db, speeds, ratings, signal === undefined ? {} : { signal });
+const candidateComputation = createCandidateComputation({
+    analyze,
+    humanMoveDistribution,
+    explorerEnabled,
+    openingExplorer: openExplorer,
+    explorerFailureReason: (error) => error instanceof ExplorerError ? error.reason : "upstream",
+});
 export const defaultAppServices = {
     games: defaultGameStore,
-    analyze: (fen, depth, multipv, signal) => stockfish.analyze(fen, depth, multipv, signal),
+    analyze,
     quit: () => stockfish.quit(),
     humanMoveDistribution,
     explorerEnabled,
-    openingExplorer: (chess, db, speeds, ratings, signal) => openingExplorer(chess, db, speeds, ratings, signal === undefined ? {} : { signal }),
-    computeCandidates,
+    openingExplorer: openExplorer,
+    computeCandidates: candidateComputation.computeCandidates,
     rankByIntent,
 };

package/dist/tool-meta.js

@@ -46,7 +46,7 @@ export const TOOL_META = {
     },
     position_analyze: {
         title: "Analyze Chess Position",
-        description: "Run Stockfish on the current position and return the top engine lines (multipv). Scores are from the side-to-move perspective: positive cp = side to move is better; mate N = side to move mates in N. wdl is [win, draw, loss] in permille for the side to move. Use analysis_level (fast/normal/deep) or explicit depth/multipv. Does NOT mutate the game.",
+        description: "Run Stockfish on the current position and return the top engine lines (multipv) as UCI pv and SAN pvSan. Scores are from the side-to-move perspective: positive cp = side to move is better; mate N = side to move mates in N. wdl is [win, draw, loss] in permille for the side to move. Use analysis_level (fast/normal/deep) or explicit depth/multipv. Does NOT mutate the game.",
         annotations: readOnly(),
     },
     human_move_distribution: {
@@ -56,7 +56,7 @@ export const TOOL_META = {
     },
     move_evaluate: {
         title: "Evaluate Chess Moves",
-        description: "Evaluate one or more moves with Stockfish without mutating the game. Pass a single move string or an array of moves to compare. Returns, for each move, the score after the move (from the mover's perspective), cpLoss vs the best move, and a classification (best/excellent/good/inaccuracy/mistake/blunder).",
+        description: "Evaluate one or more moves with Stockfish without mutating the game. Pass a single move string or an array of moves to compare. Returns, for each move, the score after the move (from the mover's perspective), cpLoss vs the best move, a classification (best/excellent/good/inaccuracy/mistake/blunder), and the continuation as UCI pv and SAN pvSan.",
         annotations: readOnly(),
     },
     move_candidates: {

package/dist/tool-names.js

@@ -0,0 +1,15 @@
+export const TOOL_NAMES = [
+    "create_game",
+    "delete_game",
+    "game_import_pgn",
+    "game_legal_moves",
+    "game_pgn",
+    "game_play_move",
+    "game_state",
+    "human_move_distribution",
+    "move_candidates",
+    "move_candidates_by_intent",
+    "move_evaluate",
+    "opening_explorer",
+    "position_analyze",
+];

package/dist/tool-schemas.js

@@ -45,6 +45,10 @@ export const SfLineSchema = z.strictObject({
     wdl: wdl.nullable(),
     pv: z.array(z.string()),
 });
+export const AnalysisLineSchema = z.strictObject({
+    ...SfLineSchema.shape,
+    pvSan: z.array(z.string()),
+});
 export const OpeningStatsSchema = z.strictObject({
     status: z.enum(["available", "no_data", "unavailable", "disabled"]),
     reason: z.enum(EXPLORER_ERROR_KINDS).optional(),
@@ -121,7 +125,7 @@ export const PositionAnalyzeOutputSchema = z.strictObject({
     turn: color,
     revision,
     analysis_level: z.enum(["fast", "normal", "deep"]),
-    lines: z.array(SfLineSchema),
+    lines: z.array(AnalysisLineSchema),
 });
 export const Maia3MoveSchema = z.strictObject({
     uci: z.string(),
@@ -155,6 +159,7 @@ const moveEvaluation = z.strictObject({
         .enum(["best", "excellent", "good", "inaccuracy", "mistake", "blunder"])
         .nullable(),
     pv: z.array(z.string()),
+    pvSan: z.array(z.string()),
 });
 export const MoveEvaluateOutputSchema = z.strictObject({
     game_id: z.string(),

package/dist/tools/analysis.js

@@ -1,4 +1,4 @@
-import { drawResult, parseMove, playParsedMove, snapshotChess, } from "../chess.js";
+import { drawResult, parseMove, playParsedMove, pvToSan, snapshotChess, } from "../chess.js";
 import { ANALYSIS_PRESETS, classifyCpLoss, evalToCp, negateEval, toEval, } from "../eval.js";
 import { TOOL_INPUT_SCHEMAS } from "../tool-inputs.js";
 import { TOOL_META } from "../tool-meta.js";
@@ -10,8 +10,7 @@ export function registerAnalysisTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.position_analyze,
         outputSchema: TOOL_OUTPUT_SCHEMAS.position_analyze,
     }, safeHandler(TOOL_INPUT_SCHEMAS.position_analyze, async ({ game_id, analysis_level, depth, multipv }, signal) => {
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const preset = ANALYSIS_PRESETS[analysis_level];
         const d = depth ?? preset.depth;
         const mpv = multipv ?? preset.multipv;
@@ -28,6 +27,7 @@ export function registerAnalysisTools(server, services) {
                 scoreMate: line.scoreMate,
                 wdl: line.wdl,
                 pv: line.pv,
+                pvSan: pvToSan(chess, line.pv),
             })),
         };
         return toolResult(payload, `Analyzed game ${game_id} at revision ${revision}; ${payload.lines.length} lines`);
@@ -37,8 +37,7 @@ export function registerAnalysisTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.human_move_distribution,
         outputSchema: TOOL_OUTPUT_SCHEMAS.human_move_distribution,
     }, safeHandler(TOOL_INPUT_SCHEMAS.human_move_distribution, async ({ game_id, elo, oppo_elo, top_n }, signal) => {
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const opponentElo = oppo_elo ?? elo;
         const moves = await services.humanMoveDistribution(chess, elo, opponentElo, top_n, signal);
         const payload = {
@@ -55,8 +54,7 @@ export function registerAnalysisTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.move_evaluate,
         outputSchema: TOOL_OUTPUT_SCHEMAS.move_evaluate,
     }, safeHandler(TOOL_INPUT_SCHEMAS.move_evaluate, async ({ game_id, move, depth }, signal) => {
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const moves = Array.isArray(move) ? move : [move];
         const beforeLines = await services.analyze(chess.fen(), depth, 1, signal);
         signal.throwIfAborted();
@@ -80,6 +78,7 @@ export function registerAnalysisTools(server, services) {
                     cpLoss: null,
                     classification: "best",
                     pv: [],
+                    pvSan: [],
                 });
                 continue;
             }
@@ -98,6 +97,7 @@ export function registerAnalysisTools(server, services) {
                         ? classifyCpLoss(cpLoss)
                         : null,
                     pv: [],
+                    pvSan: [],
                 });
                 continue;
             }
@@ -108,6 +108,7 @@ export function registerAnalysisTools(server, services) {
             const moverEval = afterEval ? negateEval(afterEval) : null;
             const afterCp = moverEval ? evalToCp(moverEval) : null;
             const cpLoss = afterCp !== null && beforeCp !== null ? beforeCp - afterCp : null;
+            const pv = after?.pv ?? [];
             results.push({
                 move: parsed.san,
                 uci: parsed.lan,
@@ -119,7 +120,8 @@ export function registerAnalysisTools(server, services) {
                 classification: cpLoss !== null
                     ? classifyCpLoss(cpLoss)
                     : null,
-                pv: after?.pv ?? [],
+                pv,
+                pvSan: pvToSan(copy, pv),
             });
         }
         return toolResult({ game_id, revision, results }, `Evaluated ${results.length} move${results.length === 1 ? "" : "s"} in game ${game_id}`);

package/dist/tools/candidates.js

@@ -1,66 +1,50 @@
-import { snapshotChess } from "../chess.js";
 import { ANALYSIS_PRESETS } from "../eval.js";
 import { TOOL_INPUT_SCHEMAS } from "../tool-inputs.js";
 import { TOOL_META } from "../tool-meta.js";
 import { safeHandler, toolResult } from "../tool-result.js";
 import { TOOL_OUTPUT_SCHEMAS } from "../tool-schemas.js";
+async function candidatePayload(services, { game_id, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }, signal) {
+    const { chess, revision } = services.games.getSnapshot(game_id);
+    const preset = ANALYSIS_PRESETS[analysis_level];
+    const { candidates, moveSensitivity } = await services.computeCandidates(chess, elo, sf_depth ?? preset.depth, sf_multipv ?? preset.multipv, maia_top_n, {
+        db: lichess_db,
+        speeds: lichess_speeds,
+        ratings: lichess_ratings,
+    }, signal);
+    signal.throwIfAborted();
+    return {
+        game_id,
+        revision,
+        fen: chess.fen(),
+        turn: chess.turn(),
+        elo,
+        analysis_level,
+        moveSensitivity,
+        candidates,
+    };
+}
 export function registerCandidateTools(server, services) {
     const moveCandidatesSchema = TOOL_INPUT_SCHEMAS.move_candidates;
     server.registerTool("move_candidates", {
         ...TOOL_META.move_candidates,
         inputSchema: moveCandidatesSchema,
         outputSchema: TOOL_OUTPUT_SCHEMAS.move_candidates,
-    }, safeHandler(moveCandidatesSchema, async ({ game_id, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }, signal) => {
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
-        const preset = ANALYSIS_PRESETS[analysis_level];
-        const depth = sf_depth ?? preset.depth;
-        const multipv = sf_multipv ?? preset.multipv;
-        const { candidates, moveSensitivity } = await services.computeCandidates(chess, elo, depth, multipv, maia_top_n, {
-            db: lichess_db,
-            speeds: lichess_speeds,
-            ratings: lichess_ratings,
-        }, signal);
-        signal.throwIfAborted();
-        return toolResult({
-            game_id,
-            revision,
-            fen: chess.fen(),
-            turn: chess.turn(),
-            elo,
-            analysis_level,
-            moveSensitivity,
-            candidates,
-        }, `${candidates.length} candidates for game ${game_id} at revision ${revision}`);
+    }, safeHandler(moveCandidatesSchema, async (input, signal) => {
+        const payload = await candidatePayload(services, input, signal);
+        return toolResult(payload, `${payload.candidates.length} candidates for game ${payload.game_id} at revision ${payload.revision}`);
     }));
     const byIntentSchema = TOOL_INPUT_SCHEMAS.move_candidates_by_intent;
     server.registerTool("move_candidates_by_intent", {
         ...TOOL_META.move_candidates_by_intent,
         inputSchema: byIntentSchema,
         outputSchema: TOOL_OUTPUT_SCHEMAS.move_candidates_by_intent,
-    }, safeHandler(byIntentSchema, async ({ game_id, intent, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }, signal) => {
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
-        const preset = ANALYSIS_PRESETS[analysis_level];
-        const depth = sf_depth ?? preset.depth;
-        const multipv = sf_multipv ?? preset.multipv;
-        const { candidates, moveSensitivity } = await services.computeCandidates(chess, elo, depth, multipv, maia_top_n, {
-            db: lichess_db,
-            speeds: lichess_speeds,
-            ratings: lichess_ratings,
-        }, signal);
-        signal.throwIfAborted();
-        const ranked = services.rankByIntent(candidates, intent);
+    }, safeHandler(byIntentSchema, async ({ intent, ...input }, signal) => {
+        const payload = await candidatePayload(services, input, signal);
+        const candidates = services.rankByIntent(payload.candidates, intent);
         return toolResult({
-            game_id,
-            revision,
-            fen: chess.fen(),
-            turn: chess.turn(),
+            ...payload,
             intent,
-            elo,
-            analysis_level,
-            moveSensitivity,
-            candidates: ranked,
-        }, `${ranked.length} ${intent} candidates for game ${game_id} at revision ${revision}`);
+            candidates,
+        }, `${candidates.length} ${intent} candidates for game ${payload.game_id} at revision ${payload.revision}`);
     }));
 }

package/dist/tools/explorer.js

@@ -1,4 +1,3 @@
-import { snapshotChess } from "../chess.js";
 import { ChessError } from "../errors.js";
 import { OpeningExplorerInputSchema } from "../tool-inputs.js";
 import { TOOL_META } from "../tool-meta.js";
@@ -13,8 +12,7 @@ export function registerExplorerTool(server, services) {
         if (!services.explorerEnabled()) {
             throw new ChessError("LICHESS_DISABLED", "LICHESS_TOKEN not set; opening explorer is disabled");
         }
-        const { chess: live, revision } = services.games.getGame(game_id);
-        const chess = snapshotChess(live);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const result = await services.openingExplorer(chess, db, speeds, ratings, signal);
         return toolResult({ game_id, revision, ...result }, `Lichess ${db} returned ${result.moves.length} moves for game ${game_id}`);
     }));

package/dist/tools/game.js

@@ -1,4 +1,4 @@
-import { parseImportedPgn, parseMove, playParsedMove, stateOf } from "../chess.js";
+import { parseImportedPgn, parseMove, stateOf } from "../chess.js";
 import { ChessError } from "../errors.js";
 import { TOOL_INPUT_SCHEMAS } from "../tool-inputs.js";
 import { TOOL_META } from "../tool-meta.js";
@@ -39,7 +39,7 @@ export function registerGameTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.game_state,
         outputSchema: TOOL_OUTPUT_SCHEMAS.game_state,
     }, safeHandler(TOOL_INPUT_SCHEMAS.game_state, async ({ game_id, include_ascii }) => {
-        const { chess, revision } = services.games.getGame(game_id);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const state = stateOf(chess, revision);
         return toolResult({
             game_id,
@@ -52,7 +52,7 @@ export function registerGameTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.game_play_move,
         outputSchema: TOOL_OUTPUT_SCHEMAS.game_play_move,
     }, safeHandler(TOOL_INPUT_SCHEMAS.game_play_move, async ({ game_id, move, expected_revision }, signal) => {
-        const { chess, revision } = services.games.getGame(game_id);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         if (expected_revision !== revision) {
             throw new ChessError("STALE_POSITION", `position changed: expected revision ${expected_revision}, current ${revision}`);
         }
@@ -61,16 +61,15 @@ export function registerGameTools(server, services) {
         }
         const parsed = parseMove(chess, move);
         signal.throwIfAborted();
-        playParsedMove(chess, parsed);
-        const newRevision = services.games.bumpRevision(game_id);
-        return toolResult({ game_id, move: parsed.san, ...stateOf(chess, newRevision) }, `Played ${parsed.san} in game ${game_id}; revision ${newRevision}`);
+        const { chess: next, revision: newRevision } = services.games.applyMove(game_id, expected_revision, parsed);
+        return toolResult({ game_id, move: parsed.san, ...stateOf(next, newRevision) }, `Played ${parsed.san} in game ${game_id}; revision ${newRevision}`);
     }));
     server.registerTool("game_legal_moves", {
         ...TOOL_META.game_legal_moves,
         inputSchema: TOOL_INPUT_SCHEMAS.game_legal_moves,
         outputSchema: TOOL_OUTPUT_SCHEMAS.game_legal_moves,
     }, safeHandler(TOOL_INPUT_SCHEMAS.game_legal_moves, async ({ game_id }, signal) => {
-        const { chess, revision } = services.games.getGame(game_id);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         const moves = [];
         for (const move of chess.moves({ verbose: true })) {
             signal.throwIfAborted();
@@ -93,7 +92,7 @@ export function registerGameTools(server, services) {
         inputSchema: TOOL_INPUT_SCHEMAS.game_pgn,
         outputSchema: TOOL_OUTPUT_SCHEMAS.game_pgn,
     }, safeHandler(TOOL_INPUT_SCHEMAS.game_pgn, async ({ game_id }) => {
-        const { chess, revision } = services.games.getGame(game_id);
+        const { chess, revision } = services.games.getSnapshot(game_id);
         return toolResult({ game_id, revision, pgn: chess.pgn() }, `Exported PGN for game ${game_id} at revision ${revision}`);
     }));
     server.registerTool("game_import_pgn", {

package/docs/architecture.md

@@ -112,10 +112,10 @@ a 2 MiB byte cap, initialization reserves one of 64 session slots atomically,
 and only 16 POSTs process-wide or two per session may run concurrently. The same
 limits independently bound downstream compute and network jobs. A job retains
 its slot after the HTTP response or socket closes and releases it only when the
-service promise settles. Idle sessions expire after 30 minutes without deleting
-their process-shared games. GET SSE streams do not consume POST permits and are
-closed when their session expires. Header, upload, connection, socket, and
-keep-alive limits are enforced by the Node listener.
+service promise settles. Sessions with no active request expire after 30 minutes
+without deleting their process-shared games. Open GET SSE streams keep their
+session active without consuming POST permits. Header, upload, connection,
+socket, and keep-alive limits are enforced by the Node listener.
 
 The server has no MCP OAuth endpoints, OAuth discovery metadata, bearer-token
 validation, or browser CORS support. A reverse proxy may implement its own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-chess-mcp",
-  "version": "0.4.1",
+  "version": "0.4.4",
   "description": "MCP server that lets an LLM analyze, judge, and choose chess moves (Stockfish + Maia3 + Lichess)",
   "type": "module",
   "license": "AGPL-3.0",