@chessceo/mcp 0.24.0 → 0.29.0

package/dist/index.js

@@ -14,7 +14,8 @@ import { dirname, join } from "node:path";
 import { Chess } from "chess.js";
 import { parsePGN } from "./pgn/parser.js";
 import { exportPGN } from "./pgn/exporter.js";
-import { addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setComment, setNags, setTag, } from "./pgn/mutations.js";
+import { describePosition } from "./pgn/describe.js";
+import { addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "./pgn/mutations.js";
 import { PathError } from "./pgn/paths.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -188,6 +189,7 @@ const TOOLS = [
         name: "get_player_preparation",
         description: "For a given player, colour and starting position, return both the moves the player actually chose (frequency + win rate) and the underlying games. Position is specified either as a move sequence in SAN (`line`) or a raw FEN. Use `line` iteratively to walk the opening tree: call once with empty `line`, pick a move, call again with `line` extended by that move, etc.\n\n" +
             "GROUNDING: every claim about the opponent's repertoire must trace back to this tool's output. Don't assert 'they play sharply' or 'they hate isolated queen pawn' without pointing at the actual game counts / win rates in the response. Don't invent 'the opponent typically plays X' — check first. Compute is cheap: run this on more branches instead of pattern-matching from a chess book.\n\n" +
+            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read at the requested position (top move + score + PV) and the corresponding NAG. Do NOT fire a separate cloud_analyse for the same FEN — the eval is right there.\n\n" +
             "Reading the response — CRITICAL:\n" +
             "• Win % is one weight, not a verdict. Recommend 1.b3 over 1.d4 because 60% > 50% is wrong. Sample size matters (3 games at 66% is noise; 300 at 55% is signal); avgWhite / avgBlack per move show the rating context (a big score often means a rating gap, not repertoire truth).\n" +
             "• Prep is symmetric information — both sides see the same history. Assume the opponent knows the weakness you spotted; a weak opponent won't patch it, a strong or improving one already has (but structural weaknesses like 'bad in Catalan structures' hold anyway).\n" +
@@ -229,7 +231,12 @@ const TOOLS = [
     },
     {
         name: "get_position_stats",
-        description: "Move statistics from all 11.7M+ indexed games at a given position — game counts, win percentages, top continuations. Answers 'from position P, how often does White play 4. O-O vs 4. d3, and which scores better'.",
+        description: "Move statistics + example games at a position. Answers 'how often is 4.O-O vs 4.d3 played here and which scores better'.\n\n" +
+            "SOURCE (default: `gm-classical`) selects a pre-aggregated database shard:\n" +
+            "- `gm-classical` — GM classical games (both players ≥2500, real thinking-time). BEST for opening prep — every move is signal, avgElo ~2600 across all listed moves.\n" +
+            "- `main` — the whole 11.7M-game DB. Widest coverage but noisiest (includes 1000-Elo blunder-fests in the move stats). Use as fallback when gm-classical's totalCount is too small to be informative.\n\n" +
+            "Game movetext is trimmed to the moves AFTER the queried position (using each game's plyNumber). Saves ~70% of the bytes vs full movetext.\n\n" +
+            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read and the corresponding NAG. Do NOT fire cloud_analyse separately for the same FEN.",
         inputSchema: {
             type: "object",
             properties: {
@@ -249,8 +256,27 @@ const TOOLS = [
                     type: "integer",
                     minimum: 1,
                     maximum: 50,
-                    description: "Number of top continuations to return.",
+                    description: "Number of example games to return (default 10).",
                 },
+                source: {
+                    type: "string",
+                    enum: ["gm-classical", "main"],
+                    description: "Which database shard to query. Default `gm-classical`. Switch to `main` only when gm-classical's totalCount is too low.",
+                },
+            },
+        },
+    },
+    {
+        name: "describe_position",
+        description: "Structured facts about a chess position: piece placements per colour (SAN-style letters), material balance in pawn units, list of every contested piece (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant square, side to move, and the full list of LEGAL MOVES for the side to move. Pure computation — no engine, ~1 ms per call.\n\n" +
+            "USE THIS BEFORE COMMENTING ON A POSITION. LLMs are not reliable at reading FEN strings — you'll misplace pieces or invent captures. This tool gives you the same board state a human sees.\n\n" +
+            "ALSO USE THIS if `add_move` rejects an illegal SAN — the `.legalMoves` array shows exactly what's playable from that position.\n\n" +
+            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves` to walk from there.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "Starting position as FEN (defaults to startpos)." },
+                moves: { type: "string", description: "Optional SAN moves to apply on top of `fen`." },
             },
         },
     },
@@ -669,7 +695,8 @@ const TOOLS = [
     },
     {
         name: "prep_snapshot",
-        description: "One call, three parallel fetches at the same position: opponent's stats on their side, your stats on your side, and the 11.7M-game general database at that position. Use this while walking the opening tree — one round trip instead of three separate calls, and you can compare the three views directly (e.g. opponent has 2 games here but the general DB has 8k → prep candidate).",
+        description: "One call, three parallel fetches at the same position: opponent's stats on their side, your stats on your side, and the 11.7M-game general database at that position. Use this while walking the opening tree — one round trip instead of three separate calls, and you can compare the three views directly (e.g. opponent has 2 games here but the general DB has 8k → prep candidate).\n\n" +
+            "AUTO-EVAL: if a cloud combo instance is running, the response includes a top-level `.eval` (Stockfish + Lc0 read at the shared position) so you get four signals in one call. Do NOT fire cloud_analyse separately for the same FEN.",
         inputSchema: {
             type: "object",
             properties: {
@@ -740,6 +767,17 @@ function uciMoveToSAN(startFen, uci) {
         return uci;
     }
 }
+async function fetchCompactEval(fen) {
+    try {
+        const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen, movetime_ms: 1500, multipv: 1 });
+        const converted = convertCloudSnapshotResponse(raw, fen);
+        const stored = analysisToStoredEval(converted, fen);
+        return storedEvalToCompact(stored, converted);
+    }
+    catch {
+        return null;
+    }
+}
 // Rewrite the /api/agent/cloud-engines/analyse response (two engines,
 // each with lines[] and a bestMove) so PVs and bestMove come back in SAN.
 function convertCloudSnapshotResponse(raw, startFen) {
@@ -794,6 +832,10 @@ function dispatchMutation(file, op) {
             const ann = arrows.length === 0 && highlights.length === 0 ? null : { arrows, highlights };
             return setAnnotations(file, path, ann);
         }
+        case "set_ceo_eval": {
+            const ev = op.ceoEval;
+            return setCeoEval(file, path, ev ?? null);
+        }
         case "delete_subtree":
             return deleteSubtree(file, path);
         case "promote_variation":
@@ -839,8 +881,10 @@ async function applyBatchMutations(args) {
     return { ok: true, results, version: savedRow.version };
 }
 // Auto-evaluate: walk the tree from `path`, run cloud_analyse on each node,
-// convert the SF score to a NAG per the standard thresholds, and apply
-// everything in one batch mutation. Uses batching to avoid N saves.
+// stash the compact per-engine eval in the node's `ceoEval` field (which
+// survives across sessions and appears on every read_prep_file), and
+// derive the NAG from the SF score. Both writes go via a single batch
+// mutation at the end so a 200-node evaluate is one save.
 async function autoEvaluate(args) {
     const id = String(args.id);
     const startPath = Array.isArray(args.path) ? args.path : [];
@@ -854,7 +898,7 @@ async function autoEvaluate(args) {
     const targets = [];
     const walk = (node, path) => {
         if (path.length > 0) {
-            if (!onlyMissing || !(node.nags && node.nags.length > 0)) {
+            if (!onlyMissing || !node.ceoEval) {
                 targets.push({ path, fen: node.fen });
             }
         }
@@ -866,8 +910,8 @@ async function autoEvaluate(args) {
     if (targets.length === 0)
         return { ok: true, evaluated: 0, skipped: 0, version: g.version };
     // Dispatch cloud_analyse in parallel with a 4-way cap so we don't
-    // over-saturate the engine's WS connection cap (single-client per port).
-    const nags = [];
+    // over-saturate the engine-ws connection cap (single-client per port).
+    const stored = [];
     const CONCURRENCY = 4;
     let cursor = 0;
     async function worker() {
@@ -876,23 +920,27 @@ async function autoEvaluate(args) {
             const t = targets[idx];
             try {
                 const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
-                const nag = analysisToNag(analysis);
-                if (nag)
-                    nags.push({ path: t.path, nag });
+                const ev = analysisToStoredEval(analysis, t.fen);
+                if (ev)
+                    stored.push({ path: t.path, ev });
             }
             catch {
-                // ignore per-node failures — best-effort auto-annotation
+                // best-effort — a single failed node shouldn't kill the batch
             }
         }
     }
     await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
-    if (nags.length === 0)
+    if (stored.length === 0)
         return { ok: true, evaluated: 0, skipped: targets.length, version: g.version };
-    // Apply all NAGs as a single batch.
-    const batchMutations = nags.map(n => ({ op: "set_nags", path: n.path, nags: [n.nag] }));
+    const batchMutations = [];
+    for (const s of stored) {
+        batchMutations.push({ op: "set_ceo_eval", path: s.path, ceoEval: s.ev });
+        if (s.ev.nag)
+            batchMutations.push({ op: "set_nags", path: s.path, nags: [s.ev.nag] });
+    }
     const saveResult = await applyBatchMutations({ id, mutations: batchMutations, expected_version: g.version });
     const sr = saveResult;
-    return { ok: true, evaluated: nags.length, skipped: targets.length - nags.length, version: sr.version };
+    return { ok: true, evaluated: stored.length, skipped: targets.length - stored.length, version: sr.version };
 }
 // Walk chess.js-free: resolve a path against a tree, throw if invalid.
 function pathIntoTree(root, path) {
@@ -905,39 +953,81 @@ function pathIntoTree(root, path) {
     }
     return cur;
 }
-// Read Stockfish's rank-1 line, convert to White-POV centipawns, and
-// bucket into a NAG per the standard threshold table. Returns null if
-// the response shape doesn't carry a usable score.
-function analysisToNag(analysis) {
+// Read the cloud analyse response and build a StoredEval (compact form —
+// no PVs, White-POV cp / mate, depth, and derived NAG). Returns null if
+// there's no usable Stockfish signal (SF is the source of truth for
+// the NAG per docs).
+function analysisToStoredEval(analysis, fen) {
     if (!analysis || typeof analysis !== "object")
         return null;
     const r = analysis;
-    const line = r.stockfish?.lines?.[0];
-    if (!line)
+    const whiteToMove = / w /.test(fen);
+    const flip = (n) => (whiteToMove ? n : -n);
+    const engineEval = (block) => {
+        const line = block?.lines?.[0];
+        if (!line)
+            return undefined;
+        const depth = line.depth ?? block?.depth;
+        if (typeof line.mate === "number")
+            return { mate: flip(line.mate), depth };
+        if (typeof line.scoreCp === "number")
+            return { cp: flip(line.scoreCp), depth };
+        return undefined;
+    };
+    const sf = engineEval(r.stockfish);
+    const lc0 = engineEval(r.lc0);
+    if (!sf && !lc0)
         return null;
-    // Determine side to move from the FEN so we can convert side-to-move
-    // POV score to White POV.
-    const whiteToMove = typeof r.fen === "string" && / w /.test(r.fen);
-    let cp;
-    if (typeof line.mate === "number") {
-        cp = line.mate > 0 ? 10000 : -10000;
-    }
-    else if (typeof line.scoreCp === "number") {
-        cp = line.scoreCp;
-    }
-    else {
+    const ev = {};
+    if (sf)
+        ev.sf = sf;
+    if (lc0)
+        ev.lc0 = lc0;
+    ev.nag = nagFromCp(sf?.cp, sf?.mate) ?? nagFromCp(lc0?.cp, lc0?.mate) ?? undefined;
+    return ev;
+}
+function nagFromCp(cp, mate) {
+    let effective;
+    if (typeof mate === "number")
+        effective = mate > 0 ? 10000 : -10000;
+    else if (typeof cp === "number")
+        effective = cp;
+    else
         return null;
-    }
-    if (!whiteToMove)
-        cp = -cp;
-    const abs = Math.abs(cp);
+    const abs = Math.abs(effective);
     if (abs < 25)
         return "$10";
     if (abs < 60)
-        return cp > 0 ? "$14" : "$15";
+        return effective > 0 ? "$14" : "$15";
     if (abs < 130)
-        return cp > 0 ? "$16" : "$17";
-    return cp > 0 ? "$18" : "$19";
+        return effective > 0 ? "$16" : "$17";
+    return effective > 0 ? "$18" : "$19";
+}
+// Adapter for the compact eval attached to live query responses. Same
+// derivation logic; different output shape (needs the .nag + summary
+// used by get_position_stats / prep_snapshot).
+function storedEvalToCompact(ev, analysis) {
+    if (!ev)
+        return null;
+    const a = analysis;
+    const compact = { nag: ev.nag ?? null };
+    if (ev.sf) {
+        compact.stockfish = {
+            cp: ev.sf.cp,
+            mate: ev.sf.mate,
+            bestMove: a.stockfish?.bestMove,
+            pv: a.stockfish?.lines?.[0]?.pv,
+        };
+    }
+    if (ev.lc0) {
+        compact.lc0 = {
+            cp: ev.lc0.cp,
+            mate: ev.lc0.mate,
+            bestMove: a.lc0?.bestMove,
+            pv: a.lc0?.lines?.[0]?.pv,
+        };
+    }
+    return compact;
 }
 // Load-mutate-save: fetch current PGN, parse, apply mutation, re-export,
 // save with optimistic lock. Auto-saves so every tool call is atomic;
@@ -972,6 +1062,62 @@ async function applyMutation(args, mutator) {
         version: savedRow.version,
     };
 }
+// Trim every game's `moves` field to just the plies AFTER the queried
+// position, using each game's `plyNumber`. Massive token save — a game
+// 80 plies long queried at ply 12 drops to ~68 plies of movetext. Ports
+// the frontend's GamesTable.getMoveDisplay() trim logic.
+function trimGamesMovetext(response) {
+    if (!response || typeof response !== "object")
+        return;
+    const r = response;
+    if (!Array.isArray(r.games))
+        return;
+    for (const g of r.games) {
+        if (typeof g.moves === "string" && typeof g.plyNumber === "number" && g.plyNumber > 0) {
+            g.moves = trimMovesToPly(g.moves, g.plyNumber);
+        }
+    }
+}
+function trimMovesToPly(moves, plyNumber) {
+    // Split into plain SAN tokens, dropping standalone move-number tokens
+    // ("1.", "12...") and any glued number prefix on a SAN token ("1.e4").
+    // Result markers ("*", "1-0", "0-1", "1/2-1/2") are stripped so they
+    // don't get counted as plies.
+    const tokens = [];
+    for (const chunk of moves.split(/\s+/)) {
+        if (!chunk)
+            continue;
+        const cleaned = chunk.replace(/^\d+\.+/, "");
+        if (!cleaned)
+            continue;
+        if (/^(1-0|0-1|1\/2-1\/2|\*)$/.test(cleaned))
+            continue;
+        tokens.push(cleaned);
+    }
+    const remaining = tokens.slice(plyNumber);
+    if (remaining.length === 0)
+        return "";
+    // Reconstruct with move numbering. First move gets "N..." if it's
+    // Black's move (starting the slice mid-move-pair), so the reader knows
+    // moves were dropped.
+    const out = [];
+    let ply = plyNumber;
+    for (let i = 0; i < remaining.length; i++) {
+        const san = remaining[i];
+        const moveNumber = Math.floor(ply / 2) + 1;
+        if (ply % 2 === 0) {
+            out.push(`${moveNumber}. ${san}`);
+        }
+        else if (i === 0) {
+            out.push(`${moveNumber}... ${san}`);
+        }
+        else {
+            out.push(san);
+        }
+        ply++;
+    }
+    return out.join(" ");
+}
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
 // concern as engine PVs, and the same wrapper-only fix. Passes the
@@ -1082,18 +1228,42 @@ async function callToolInner(name, args) {
                 params.limit = args.limit;
             if (typeof args.offset === "number")
                 params.offset = args.offset;
-            const raw = await get("/api/chess/prep/by-player", params);
-            return convertAvailableMovesToSAN(raw, resolveFenFromArgs(args));
+            const effectiveFen = resolveFenFromArgs(args);
+            const [raw, ev] = await Promise.all([
+                get("/api/chess/prep/by-player", params),
+                fetchCompactEval(effectiveFen),
+            ]);
+            const converted = convertAvailableMovesToSAN(raw, effectiveFen);
+            if (converted && typeof converted === "object") {
+                trimGamesMovetext(converted);
+                if (ev)
+                    converted.eval = ev;
+            }
+            return converted;
         }
         case "get_position_stats": {
             const fen = resolveFenFromArgs(args);
-            const raw = await get("/api/chess/database/main", {
-                fen,
-                limit: typeof args.limit === "number" ? args.limit : 20,
-                sort: "relevance",
-            });
-            return convertAvailableMovesToSAN(raw, fen);
+            const rawSource = typeof args.source === "string" ? args.source : "gm-classical";
+            const source = rawSource === "main" ? "main" : "gm-classical";
+            const [raw, ev] = await Promise.all([
+                get(`/api/chess/database/${source}`, {
+                    fen,
+                    limit: typeof args.limit === "number" ? args.limit : 10,
+                    sort: "relevance",
+                }),
+                fetchCompactEval(fen),
+            ]);
+            const converted = convertAvailableMovesToSAN(raw, fen);
+            if (converted && typeof converted === "object") {
+                trimGamesMovetext(converted);
+                converted.source = source;
+                if (ev)
+                    converted.eval = ev;
+            }
+            return converted;
         }
+        case "describe_position":
+            return describePosition(resolveFenFromArgs(args));
         case "predict_human_move": {
             const fen = resolveFenFromArgs(args);
             const qs = new URLSearchParams();
@@ -1241,13 +1411,15 @@ async function callToolInner(name, args) {
                 compact: "true",
                 ...(line.length > 0 ? { line } : { fen }),
             });
-            const [opponent, you, general] = await Promise.all([
+            const [opponent, you, general, ev] = await Promise.all([
                 get("/api/chess/prep/by-player", prepParams(opp, oppColor)),
                 get("/api/chess/prep/by-player", prepParams(me, myColor)),
                 get("/api/chess/database/main", { fen, limit: 20, sort: "relevance" }),
+                fetchCompactEval(fen),
             ]);
             return {
                 position: { line, fen, my_color: myColor },
+                eval: ev,
                 opponent: convertAvailableMovesToSAN(opponent, fen),
                 you: convertAvailableMovesToSAN(you, fen),
                 general: convertAvailableMovesToSAN(general, fen),

package/dist/pgn/describe.js

@@ -0,0 +1,221 @@
+// describe_position — structured facts about a position that LLMs can't
+// reliably read out of a FEN string on their own. Pure computation
+// (chessops); no engine needed.
+//
+// Output covers piece placements, material balance in pawn units,
+// attackers/defenders on every piece that is currently contested, a
+// hanging list (attacked and undefended), checkers if in check, and
+// castling / ep state. NOT covered: pins, discovered attacks, tactical
+// patterns — those need the engine and are already available via
+// cloud_analyse.
+import { parseFen } from "chessops/fen";
+import { Chess } from "chessops/chess";
+import { attacks } from "chessops/attacks";
+import { makeSquare, squareRank } from "chessops/util";
+import { makeSan } from "chessops/san";
+const ROLE_LETTER = {
+    pawn: "", knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K",
+};
+// SAN convention: pawn is empty prefix. For inventory listings we use "P"
+// so counts are readable.
+const ROLE_LETTER_INV = {
+    pawn: "P", knight: "N", bishop: "B", rook: "R", queen: "Q", king: "K",
+};
+const ROLE_VALUE = {
+    pawn: 1, knight: 3, bishop: 3, rook: 5, queen: 9, king: 0,
+};
+function pieceSAN(piece, sq) {
+    return `${ROLE_LETTER[piece.role]}${makeSquare(sq)}`;
+}
+export function describePosition(fen) {
+    const setup = parseFen(fen);
+    if (setup.isErr)
+        throw new Error(`bad fen: ${setup.error}`);
+    const posResult = Chess.fromSetup(setup.value);
+    if (posResult.isErr)
+        throw new Error(`bad position: ${posResult.error}`);
+    const pos = posResult.value;
+    const board = pos.board;
+    const whitePieces = [];
+    const blackPieces = [];
+    const materialW = { P: 0, N: 0, B: 0, R: 0, Q: 0, K: 0 };
+    const materialB = { P: 0, N: 0, B: 0, R: 0, Q: 0, K: 0 };
+    for (const [sq, piece] of board) {
+        const invLetter = ROLE_LETTER_INV[piece.role];
+        const entry = { piece: invLetter, square: makeSquare(sq) };
+        if (piece.color === "white") {
+            whitePieces.push(entry);
+            materialW[invLetter]++;
+        }
+        else {
+            blackPieces.push(entry);
+            materialB[invLetter]++;
+        }
+    }
+    whitePieces.sort(pieceSortKey);
+    blackPieces.sort(pieceSortKey);
+    const wValue = pieceValueSum(materialW);
+    const bValue = pieceValueSum(materialB);
+    const diff = wValue - bValue;
+    const summary = diff === 0 ? `even (both ${wValue})` :
+        diff > 0 ? `white +${diff} (${wValue} vs ${bValue})` :
+            `black +${-diff} (${wValue} vs ${bValue})`;
+    // Contested + hanging computation: for every piece, find who attacks
+    // it and who defends it. attacks() returns the squares a piece
+    // controls given the occupied board — we invert it into "attackers-of"
+    // by iterating all pieces once and testing membership.
+    const contested = [];
+    const hangingWhite = [];
+    const hangingBlack = [];
+    for (const [sq, piece] of board) {
+        const both = attackersOf(pos, sq);
+        const oppSide = piece.color === "white" ? "black" : "white";
+        const attackers = both[oppSide];
+        const defenders = both[piece.color];
+        if (attackers.length === 0)
+            continue;
+        const targetName = pieceSAN(piece, sq);
+        contested.push({
+            target: targetName,
+            color: piece.color,
+            attackers: attackers.map(a => pieceSANFromBoard(board, a)),
+            defenders: defenders.map(d => pieceSANFromBoard(board, d)),
+        });
+        if (defenders.length === 0) {
+            if (piece.color === "white")
+                hangingWhite.push(targetName);
+            else
+                hangingBlack.push(targetName);
+        }
+    }
+    // Order contested by target square for stable output the LLM can
+    // scan.
+    contested.sort((a, b) => a.target.slice(-2).localeCompare(b.target.slice(-2)));
+    // Castling rights encoded in the standard FEN letters (KQkq).
+    const castlingW = castlingLetters(pos, "white");
+    const castlingB = castlingLetters(pos, "black");
+    const checkers = [];
+    const ctx = pos.ctx();
+    for (const sq of ctx.checkers)
+        checkers.push(pieceSANFromBoard(board, sq));
+    const legalMoves = generateLegalMoves(pos);
+    return {
+        fen,
+        sideToMove: pos.turn,
+        inCheck: pos.isCheck(),
+        checkers,
+        material: {
+            white: materialW,
+            black: materialB,
+            diff,
+            summary,
+        },
+        pieces: { white: whitePieces, black: blackPieces },
+        contested,
+        hanging: { white: hangingWhite, black: hangingBlack },
+        castling: { white: castlingW, black: castlingB },
+        epSquare: typeof pos.epSquare === "number" ? makeSquare(pos.epSquare) : null,
+        legalMoves,
+    };
+}
+// All legal moves for the side to move, in SAN. Sorted for stable output.
+// Handles promotion by expanding each pawn-promotion destination into
+// the four promotion pieces (=Q, =R, =B, =N).
+function generateLegalMoves(pos) {
+    const out = [];
+    for (const [from, piece] of pos.board) {
+        if (piece.color !== pos.turn)
+            continue;
+        const dests = pos.dests(from);
+        for (const to of dests) {
+            const isPromotion = piece.role === "pawn" &&
+                ((piece.color === "white" && squareRank(to) === 7) ||
+                    (piece.color === "black" && squareRank(to) === 0));
+            if (isPromotion) {
+                for (const promo of ["queen", "rook", "bishop", "knight"]) {
+                    const san = makeSan(pos, { from, to, promotion: promo });
+                    if (san)
+                        out.push(san);
+                }
+            }
+            else {
+                const san = makeSan(pos, { from, to });
+                if (san)
+                    out.push(san);
+            }
+        }
+    }
+    return out.sort();
+}
+// Attackers-of a square, split by colour. A piece cannot attack its own
+// square, so we skip the target index. The `occupied` for sliding
+// pieces is the whole board minus nothing — chessops's `attacks()`
+// takes care of blockers.
+function attackersOf(pos, target) {
+    const white = [];
+    const black = [];
+    for (const [sq, piece] of pos.board) {
+        if (sq === target)
+            continue;
+        const set = attacks(piece, sq, pos.board.occupied);
+        if (set.has(target)) {
+            if (piece.color === "white")
+                white.push(sq);
+            else
+                black.push(sq);
+        }
+    }
+    return { white, black };
+}
+function pieceSANFromBoard(board, sq) {
+    const piece = board.get(sq);
+    if (!piece)
+        return makeSquare(sq);
+    return pieceSAN(piece, sq);
+}
+// Sort: kings first, then queens, rooks, bishops, knights, pawns; within
+// each type, by rank descending then file ascending. Matches the visual
+// scan a human does.
+const ROLE_ORDER = ["king", "queen", "rook", "bishop", "knight", "pawn"];
+function pieceSortKey(a, b) {
+    const roleA = roleOfEntry(a);
+    const roleB = roleOfEntry(b);
+    const orderA = ROLE_ORDER.indexOf(roleA);
+    const orderB = ROLE_ORDER.indexOf(roleB);
+    if (orderA !== orderB)
+        return orderA - orderB;
+    return a.square.localeCompare(b.square);
+}
+function roleOfEntry(e) {
+    switch (e.piece) {
+        case "K": return "king";
+        case "Q": return "queen";
+        case "R": return "rook";
+        case "B": return "bishop";
+        case "N": return "knight";
+        default: return "pawn";
+    }
+}
+function pieceValueSum(m) {
+    return m.P * ROLE_VALUE.pawn +
+        m.N * ROLE_VALUE.knight +
+        m.B * ROLE_VALUE.bishop +
+        m.R * ROLE_VALUE.rook +
+        m.Q * ROLE_VALUE.queen;
+}
+// Convert chessops castling representation to the standard FEN-letter
+// form for the given color: "K" (kingside), "Q" (queenside), "KQ",
+// or "" if none remain.
+function castlingLetters(pos, color) {
+    let out = "";
+    const castles = pos.castles;
+    // castles.rooksSideOf(color, 'a') and .rooksSideOf(color, 'h') return
+    // the rook square or undefined per side. Fall back to inspecting the
+    // stored castling squares — chessops's public API varies by version.
+    const rooks = castles.rook;
+    if (rooks?.[color]?.h !== undefined)
+        out += color === "white" ? "K" : "k";
+    if (rooks?.[color]?.a !== undefined)
+        out += color === "white" ? "Q" : "q";
+    return out;
+}

package/dist/pgn/exporter.js

@@ -106,23 +106,57 @@ function renderNagsAndComment(node) {
     }
     return bits.join(" ");
 }
-// Build the [%cal ...] / [%csl ...] fragments if this node has arrows
-// or highlighted squares. Returns "" if none.
+// Build the [%cal ...] / [%csl ...] / [%ceo-eval ...] fragments if
+// this node has any. Returns "" if none.
 function renderNodeAnnotation(node) {
-    if (!node.annotations)
-        return "";
     const bits = [];
-    if (node.annotations.arrows.length > 0) {
-        const entries = node.annotations.arrows
-            .map(a => `${codeFromColor(a.color)}${a.from}${a.to}`)
-            .join(",");
-        bits.push(`[%cal ${entries}]`);
+    if (node.annotations) {
+        if (node.annotations.arrows.length > 0) {
+            const entries = node.annotations.arrows
+                .map(a => `${codeFromColor(a.color)}${a.from}${a.to}`)
+                .join(",");
+            bits.push(`[%cal ${entries}]`);
+        }
+        if (node.annotations.highlights.length > 0) {
+            const entries = node.annotations.highlights
+                .map(h => `${codeFromColor(h.color)}${h.square}`)
+                .join(",");
+            bits.push(`[%csl ${entries}]`);
+        }
     }
-    if (node.annotations.highlights.length > 0) {
-        const entries = node.annotations.highlights
-            .map(h => `${codeFromColor(h.color)}${h.square}`)
-            .join(",");
-        bits.push(`[%csl ${entries}]`);
+    if (node.ceoEval) {
+        const s = renderCeoEval(node.ceoEval);
+        if (s)
+            bits.push(s);
     }
     return bits.join(" ");
 }
+// Serialise a stored eval as `[%ceo-eval sf=+0.20/38 lc0=+0.35/24 nag=$14]`.
+// Compact: no PVs (regenerable via cloud_analyse), decimal cp for
+// readability, mate as `MN`/`-MN`, depth as `/N`.
+function renderCeoEval(ev) {
+    const bits = [];
+    if (ev.sf)
+        bits.push(`sf=${formatEngineEval(ev.sf)}`);
+    if (ev.lc0)
+        bits.push(`lc0=${formatEngineEval(ev.lc0)}`);
+    if (ev.nag)
+        bits.push(`nag=${ev.nag}`);
+    return bits.length > 0 ? `[%ceo-eval ${bits.join(" ")}]` : "";
+}
+function formatEngineEval(e) {
+    let body;
+    if (typeof e.mate === "number") {
+        body = e.mate >= 0 ? `+M${e.mate}` : `M${e.mate}`; // "+M5" / "M-5"
+    }
+    else if (typeof e.cp === "number") {
+        const pawns = e.cp / 100;
+        body = pawns >= 0 ? `+${pawns.toFixed(2)}` : pawns.toFixed(2);
+    }
+    else {
+        body = "+0.00";
+    }
+    if (typeof e.depth === "number")
+        body += `/${e.depth}`;
+    return body;
+}

package/dist/pgn/mutations.js

@@ -108,6 +108,17 @@ export function promoteVariation(file, path) {
     parent.children = [promoted, ...rest];
     return { file: { tags: file.tags, root: newRoot }, path: [...parentPath, 0] };
 }
+// Replace the stored ceoEval on the node at `path`. Passing null clears.
+// This is what auto_evaluate calls per-node; also exposed as an op the
+// LLM can invoke directly if it wants to overwrite a stale eval.
+export function setCeoEval(file, path, ev) {
+    const { root: newRoot, target } = cloneOnPath(file.root, path);
+    if (ev === null || (!ev.sf && !ev.lc0 && !ev.nag))
+        delete target.ceoEval;
+    else
+        target.ceoEval = ev;
+    return { file: { tags: file.tags, root: newRoot }, path };
+}
 // Set or clear a tag. Passing null / empty removes.
 export function setTag(file, key, value) {
     const cleanedKey = key.trim();
@@ -133,7 +144,7 @@ function validateSan(fen, san) {
     const board = pos.value;
     const move = parseSan(board, san);
     if (!move) {
-        throw new MutationError(`illegal SAN "${san}" at fen "${fen}" — check the position (side to move, piece disambiguation, promotion piece) and re-check the path.`);
+        throw new MutationError(`illegal SAN "${san}" at fen "${fen}". Call describe_position on this fen to see the full list of legal moves.`);
     }
     return move;
 }

package/dist/pgn/parser.js

@@ -13,8 +13,33 @@ import { opposite } from "chessops/util";
 import { colorFromCode, } from "./types.js";
 const CAL_RE = /\[%cal\s+([^\]]+)\]/g;
 const CSL_RE = /\[%csl\s+([^\]]+)\]/g;
-const ANY_CMD_RE = /\[%[a-z]+\s+[^\]]+\]/g;
-// Parse a comment string, splitting out visual annotations from prose.
+const CEO_EVAL_RE = /\[%ceo-eval\s+([^\]]+)\]/g;
+const ANY_CMD_RE = /\[%[a-z-]+\s+[^\]]+\]/g;
+// Parse a `sf=+0.20/38` or `lc0=M-5/22` fragment into its numeric parts.
+// Returns null if the value doesn't parse; the parser tolerates missing
+// depth and mate notation.
+function parseEngineEvalFragment(raw) {
+    const m = raw.match(/^([+-]?)(?:M(-?\d+)|(\d+(?:\.\d+)?))(?:\/(\d+))?$/i);
+    if (!m)
+        return null;
+    const sign = m[1] === "-" ? -1 : 1;
+    const out = {};
+    if (m[2] !== undefined) {
+        out.mate = sign * parseInt(m[2], 10);
+    }
+    else if (m[3] !== undefined) {
+        // pawn units → centipawns
+        out.cp = Math.round(sign * parseFloat(m[3]) * 100);
+    }
+    else {
+        return null;
+    }
+    if (m[4] !== undefined)
+        out.depth = parseInt(m[4], 10);
+    return out;
+}
+// Parse a comment string, splitting out visual annotations + stored
+// evals from prose.
 export function parseCommentAnnotations(comment) {
     const arrows = [];
     const highlights = [];
@@ -32,9 +57,36 @@ export function parseCommentAnnotations(comment) {
                 highlights.push({ color: colorFromCode(e[1]), square: e[2].toLowerCase() });
         }
     }
+    let ceoEval;
+    for (const m of comment.matchAll(CEO_EVAL_RE)) {
+        const ev = ceoEval ?? {};
+        for (const entry of m[1].trim().split(/\s+/)) {
+            const eq = entry.indexOf("=");
+            if (eq < 0)
+                continue;
+            const k = entry.slice(0, eq).toLowerCase();
+            const v = entry.slice(eq + 1);
+            if (k === "sf") {
+                const parsed = parseEngineEvalFragment(v);
+                if (parsed)
+                    ev.sf = parsed;
+            }
+            else if (k === "lc0") {
+                const parsed = parseEngineEvalFragment(v);
+                if (parsed)
+                    ev.lc0 = parsed;
+            }
+            else if (k === "nag") {
+                if (/^\$\d+$/.test(v))
+                    ev.nag = v;
+            }
+        }
+        if (ev.sf || ev.lc0 || ev.nag)
+            ceoEval = ev;
+    }
     const text = comment.replace(ANY_CMD_RE, "").replace(/\s+/g, " ").trim();
     const annotations = arrows.length || highlights.length ? { arrows, highlights } : undefined;
-    return { text, annotations };
+    return { text, annotations, ceoEval };
 }
 // Parse full PGN → PrepFile. Throws on unrecoverable errors (no games,
 // invalid starting FEN). Illegal SAN moves in the movetext are skipped
@@ -62,6 +114,8 @@ export function parsePGN(pgn) {
             root.comment = parsed.text;
         if (parsed.annotations)
             root.annotations = parsed.annotations;
+        if (parsed.ceoEval)
+            root.ceoEval = parsed.ceoEval;
     }
     const build = (childNode, treeParent, pos, ply) => {
         if (!childNode.data || typeof childNode.data.san !== "string")
@@ -97,6 +151,8 @@ export function parsePGN(pgn) {
                 node.comment = parsed.text;
             if (parsed.annotations)
                 node.annotations = parsed.annotations;
+            if (parsed.ceoEval)
+                node.ceoEval = parsed.ceoEval;
         }
         if (Array.isArray(childNode.data.nags) && childNode.data.nags.length > 0) {
             node.nags = childNode.data.nags.map((n) => `$${n}`);

package/docs/pgn-authoring.md

@@ -124,6 +124,8 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 
 **Prefer auto_evaluate for the NAG.** Don't hand-write NAGs when building — call `auto_evaluate(id)` after your build and it assigns the right glyph to every node from actual engine analysis. Manual `set_nags` is for overrides (mark a novelty with $146, flag a `$5 !?` piece sac).
 
+**Persisted evals travel with the file.** Every node with an eval gets `ceoEval: { sf: {cp: 25, depth: 32}, lc0: {cp: 30, depth: 18}, nag: "$14" }` on subsequent `read_prep_file` calls. Stored as `[%ceo-eval sf=+0.25/32 lc0=+0.30/18 nag=$14]` inside the PGN comment (an escape tag the app hides from the board view, just like [%cal] / [%csl]). So a re-read after auto_evaluate gives you every position's number without re-running cloud_analyse. Query tools (get_position_stats, get_player_preparation, prep_snapshot) also auto-attach a live `eval` at the request position when a cloud engine is running.
+
 **Engine numbers in prose: brief only.** If you must reference a number, keep it compact:
 
 - Good: `{... +0.2}` — bare number at the end of a note
@@ -131,6 +133,18 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 
 **Don't name the engine unless it adds signal.** "SF: +0.15" for a routine position is noise. Name it when there's a mismatch worth flagging: `{Human predictor gives Black 47% win despite the -0.35 objective eval — Elo gap does the work.}`
 
+### Before you write any commentary: describe_position
+
+LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position(fen)`. It's pure computation (no engine, ~1ms) and returns the same board state a human sees:
+
+- All piece placements per colour (SAN-style: `Nf3`, `Bg7`, `e4`)
+- Material balance in pawn units (`"white +1 (39 vs 38)"`)
+- Every contested piece: attackers + defenders (e.g. `{target: "e5", color: "black", attackers: ["Nf3"], defenders: ["Nc6"]}`)
+- Hanging list — attacked and undefended
+- Check state + checkers, castling rights, en passant
+
+Use it whenever you're about to describe a position from memory or from your reading of a FEN. The failure mode this prevents: `{Black's queen on c7 is defended by the knight on d5.}` when actually there's no knight on d5 and the queen is on c8.
+
 ### When prose ADDS to the NAG
 
 Prose is worth writing when the NAG *understates* something the human should know:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.24.0",
+  "version": "0.29.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {