@chessceo/mcp 0.26.0 → 0.29.0

package/dist/index.js

@@ -14,6 +14,7 @@ import { dirname, join } from "node:path";
 import { Chess } from "chess.js";
 import { parsePGN } from "./pgn/parser.js";
 import { exportPGN } from "./pgn/exporter.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";
@@ -230,8 +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'.\n\n" +
-            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read (top move + score + PV) and the corresponding NAG. Do NOT fire a separate cloud_analyse for the same FEN — the eval is right there.",
+        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: {
@@ -251,11 +256,30 @@ 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`." },
+            },
+        },
+    },
     {
         name: "predict_human_move",
         description: "Predicts what a HUMAN of the given rating will most likely play from a position. Rating-conditioned neural net (ResNet-20x256) — you get the top-N most likely moves with their probabilities and a WDL value head (White POV).\n\n" +
@@ -1038,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
@@ -1154,25 +1234,36 @@ async function callToolInner(name, args) {
                 fetchCompactEval(effectiveFen),
             ]);
             const converted = convertAvailableMovesToSAN(raw, effectiveFen);
-            if (ev && converted && typeof converted === "object")
-                converted.eval = ev;
+            if (converted && typeof converted === "object") {
+                trimGamesMovetext(converted);
+                if (ev)
+                    converted.eval = ev;
+            }
             return converted;
         }
         case "get_position_stats": {
             const fen = resolveFenFromArgs(args);
+            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/main", {
+                get(`/api/chess/database/${source}`, {
                     fen,
-                    limit: typeof args.limit === "number" ? args.limit : 20,
+                    limit: typeof args.limit === "number" ? args.limit : 10,
                     sort: "relevance",
                 }),
                 fetchCompactEval(fen),
             ]);
             const converted = convertAvailableMovesToSAN(raw, fen);
-            if (ev && converted && typeof converted === "object")
-                converted.eval = ev;
+            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();

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

@@ -144,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/docs/pgn-authoring.md

@@ -133,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.26.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": {