@chessceo/mcp 0.44.0 → 0.46.0

package/dist/prep/read.js

@@ -0,0 +1,242 @@
+// Prep-file reads and list-queries. Everything the LLM calls to inspect
+// a file WITHOUT mutating it:
+//   - readPrepFile (with four view modes: compact / full / spine / pgn)
+//   - listNodes (cheap filter-based node queries)
+//   - listTranspositions (positions occurring 2+ times in the file)
+//
+// Extracted from index.ts in v0.44 as part of the file split. Was
+// originally split off the read-case handler because both readPrepFile
+// and listNodes need the same load-parse pipeline and share the
+// compact / spine / pgn view logic.
+import { fetchGame } from "../http.js";
+import { parsePGN } from "../pgn/parser.js";
+import { exportPGN } from "../pgn/exporter.js";
+import { buildFenIndex, buildIdIndex, positionKey, resolveNodeId, ROOT_ID, } from "../pgn/paths.js";
+import { getNodeByPath } from "../analysis/file_handle.js";
+export async function loadPrepFile(id) {
+    const g = await fetchGame(id);
+    // Echo the composite id back so read_prep_file responses match the
+    // exact id the LLM passed in. The backend returns the raw game_id;
+    // recompose so the LLM never sees the split form.
+    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: id, pgn: g.pgnContent };
+}
+// Recursively project a PrepNode into the requested view. `depthLeft`
+// null → unlimited; 0 → just the node without children.
+//
+// `fenIndex` (optional) enables the `transposes_to` field — for each
+// node whose position also appears elsewhere in the SAME file, we
+// annotate it with the OTHER occurrences' ids. Pass null (the default)
+// to skip the annotation entirely; passing the map costs one lookup
+// per node projected.
+export function projectNode(node, view, depthLeft, fenIndex = null) {
+    const base = {
+        id: node.id,
+        san: node.san,
+        ply: node.ply,
+    };
+    if (node.nags && node.nags.length > 0)
+        base.nags = node.nags;
+    if (node.comment)
+        base.comment = node.comment;
+    if (node.ceoEval)
+        base.ceoEval = node.ceoEval;
+    if (view === "full") {
+        base.fen = node.fen;
+        if (node.annotations)
+            base.annotations = node.annotations;
+    }
+    if (fenIndex && node.id !== ROOT_ID) {
+        const group = fenIndex.get(positionKey(node.fen));
+        if (group && group.length > 1) {
+            const others = group.filter(n => n.id !== node.id).map(n => n.id);
+            if (others.length > 0)
+                base.transposes_to = others;
+        }
+    }
+    // Children handling depends on view + depth budget.
+    const showChildren = depthLeft === null || depthLeft > 0;
+    const childDepth = depthLeft === null ? null : depthLeft - 1;
+    if (showChildren && node.children.length > 0) {
+        if (view === "spine") {
+            // Only follow children[0] — collapses the tree to the mainline.
+            base.children = [projectNode(node.children[0], view, childDepth, fenIndex)];
+        }
+        else {
+            base.children = node.children.map(c => projectNode(c, view, childDepth, fenIndex));
+        }
+    }
+    else {
+        base.children = [];
+    }
+    return base;
+}
+export async function readPrepFile(args) {
+    const id = String(args.id);
+    const view = (typeof args.view === "string" && ["compact", "full", "spine", "pgn"].includes(args.view))
+        ? args.view
+        : "compact";
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file, version, fileIdEcho, pgn } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const fenIndex = buildFenIndex(file.root);
+    // How many DISTINCT positions in the file appear more than once,
+    // and how many nodes are involved. Shown in the header so the LLM
+    // sees at a glance whether transpositions matter here before diving
+    // into the tree.
+    let transGroups = 0;
+    let transNodes = 0;
+    for (const arr of fenIndex.values()) {
+        if (arr.length > 1) {
+            transGroups++;
+            transNodes += arr.length;
+        }
+    }
+    const header = {
+        id: fileIdEcho ?? id,
+        version,
+        tags: file.tags,
+        view,
+        node_id: startNodeId,
+        max_depth: maxDepth,
+        transposition_groups: transGroups,
+        transposition_nodes: transNodes,
+    };
+    if (view === "pgn") {
+        // For the root, just return the file's actual PGN as-is. For a
+        // subtree, build a mini-Game from the anchor and export it. Keeps
+        // formatting identical to what the app renders.
+        if (startNodeId === ROOT_ID && (maxDepth === null || maxDepth >= 999)) {
+            return { ...header, pgn };
+        }
+        // Truncate to a subtree with max_depth. Simple: walk the anchor's
+        // subtree, produce a synthetic PGN starting from the anchor's FEN.
+        const subtreePgn = exportSubtreePgn(file, anchor, maxDepth);
+        return { ...header, pgn: subtreePgn };
+    }
+    return { ...header, tree: projectNode(anchor, view, maxDepth, fenIndex) };
+}
+// Produce a PGN string for a subtree rooted at `anchor`, truncated
+// at `maxDepth` plies below (null = unlimited). Reuses the exporter
+// by building a synthetic PrepFile whose root is a shallow clone of
+// the anchor with its children trimmed to depth.
+function exportSubtreePgn(file, anchor, maxDepth) {
+    const trim = (n, depthLeft) => {
+        if (depthLeft !== null && depthLeft <= 0)
+            return { ...n, children: [] };
+        const next = depthLeft === null ? null : depthLeft - 1;
+        return { ...n, children: n.children.map(c => trim(c, next)) };
+    };
+    const trimmedAnchor = trim(anchor, maxDepth);
+    // If the anchor IS the root, exporter handles it. If it's an inner
+    // node, we set the root's FEN to the anchor's position and hang the
+    // trimmed subtree off it. Tags carried over.
+    if (anchor.id === ROOT_ID) {
+        return exportPGN({ tags: file.tags, root: trimmedAnchor });
+    }
+    const syntheticRoot = {
+        id: ROOT_ID,
+        san: null,
+        fen: anchor.fen,
+        ply: 0,
+        children: trimmedAnchor.children,
+    };
+    const tags = { ...file.tags, FEN: anchor.fen, SetUp: "1" };
+    return exportPGN({ tags, root: syntheticRoot });
+}
+export async function listNodes(args) {
+    const id = String(args.id);
+    const filter = String(args.filter || "");
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const fenIndex = filter === "transpositions" ? buildFenIndex(file.root) : null;
+    const hits = [];
+    const walk = (node, depthLeft, spineOnly) => {
+        // Root has no san — never emit it as a match. Everything else is fair game.
+        if (node.id !== ROOT_ID) {
+            let include = false;
+            let extra = {};
+            switch (filter) {
+                case "missing_eval":
+                    include = !node.ceoEval;
+                    break;
+                case "has_comment":
+                    include = !!(node.comment && node.comment.length > 0);
+                    if (include)
+                        extra.comment_preview = (node.comment || "").slice(0, 80);
+                    break;
+                case "has_annotations":
+                    include = !!(node.annotations && (node.annotations.arrows.length > 0 || node.annotations.highlights.length > 0));
+                    break;
+                case "novelties":
+                    include = !!(node.nags && node.nags.includes("$146"));
+                    break;
+                case "leaves":
+                    include = node.children.length === 0;
+                    break;
+                case "mainline":
+                    include = spineOnly;
+                    break;
+                case "transpositions": {
+                    const group = fenIndex.get(positionKey(node.fen));
+                    if (group && group.length > 1) {
+                        include = true;
+                        extra.transposes_to = group.filter(n => n.id !== node.id).map(n => n.id);
+                    }
+                    break;
+                }
+                case "all":
+                    include = true;
+                    break;
+                default:
+                    throw new Error(`unknown filter: ${filter}`);
+            }
+            if (include) {
+                const hit = { node_id: node.id, san: node.san, ply: node.ply };
+                Object.assign(hit, extra);
+                hits.push(hit);
+            }
+        }
+        if (depthLeft !== null && depthLeft <= 0)
+            return;
+        const nextDepth = depthLeft === null ? null : depthLeft - 1;
+        if (filter === "mainline" && spineOnly) {
+            if (node.children.length > 0)
+                walk(node.children[0], nextDepth, true);
+        }
+        else {
+            for (const c of node.children)
+                walk(c, nextDepth, filter === "mainline");
+        }
+    };
+    const rootIsSpineForFilter = filter === "mainline";
+    walk(anchor, maxDepth, rootIsSpineForFilter);
+    return { file_id: id, filter, node_id: startNodeId, max_depth: maxDepth, count: hits.length, nodes: hits };
+}
+// list_transpositions — every position that occurs 2+ times in the
+// file, so the LLM knows where its analysis / prose will double up.
+export async function listTranspositions(args) {
+    const id = String(args.id);
+    const { file } = await loadPrepFile(id);
+    const fenIndex = buildFenIndex(file.root);
+    const groups = [];
+    for (const [key, arr] of fenIndex.entries()) {
+        if (arr.length < 2)
+            continue;
+        groups.push({
+            position_key: key,
+            size: arr.length,
+            node_ids: arr.map(n => n.id),
+            sans: arr.map(n => n.san),
+        });
+    }
+    groups.sort((a, b) => b.size - a.size || a.position_key.localeCompare(b.position_key));
+    const nodeCount = groups.reduce((s, g) => s + g.size, 0);
+    return { file_id: id, group_count: groups.length, node_count: nodeCount, groups };
+}

package/dist/response_transforms.js

@@ -0,0 +1,169 @@
+// Response shape transformations applied to backend payloads before
+// they reach the LLM. Two responsibilities:
+//   - Drop internal / debug-only fields the LLM doesn't need
+//     (`hash`, `plyNumber`, `relevance`, etc.).
+//   - Rewrite backend jargon into LLM-friendly names
+//     (`transpositions` → `reachedViaTransposition`, `hotness` →
+//     `fashionScore`, UCI moves → SAN).
+//
+// Plus a couple of tool-input adapters that also live here for lack of
+// a better home:
+//   - `trimMovesToPly` (used by trimGamesMovetext, exported for reuse).
+//   - `normalizeSourceForBackend` (prepare_opponent request adapter).
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { uciMoveToSAN } from "./analysis/response.js";
+// Strip cruft the LLM doesn't need from the DB-position response.
+// Called AFTER trimGamesMovetext so plyNumber survives long enough to
+// slice each game's movetext. Also renames the `transpositions` field
+// to something the LLM can parse without knowing chess-DB jargon.
+export function stripPositionResponse(r) {
+    if (!r || typeof r !== "object")
+        return;
+    const t = r;
+    delete t.hash; // internal zobrist string
+    delete t.source; // internal "database" marker; we overwrite with our own .source
+    delete t.totalGames; // duplicates statistics.totalCount often; hasMore covers pagination
+    if (Array.isArray(t.moves)) {
+        for (const m of t.moves) {
+            if (typeof m.transpositions === "number") {
+                m.reachedViaTransposition = m.transpositions;
+                delete m.transpositions;
+            }
+            // Backend calls it "hotness" — a 0-100 time-decayed popularity score
+            // (recent + played often = high). Rename to something an LLM can read
+            // without guessing it means "on a winning streak".
+            if (typeof m.hotness === "number") {
+                m.fashionScore = m.hotness;
+                delete m.hotness;
+            }
+        }
+    }
+    if (Array.isArray(t.games)) {
+        for (const g of t.games) {
+            delete g.gameId;
+            delete g.whiteTitle;
+            delete g.blackTitle;
+            delete g.whiteTeam;
+            delete g.blackTeam;
+            delete g.round;
+            delete g.plyNumber;
+            delete g.relevance;
+            delete g.site;
+            delete g.ply;
+        }
+    }
+}
+// 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.
+export 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);
+        }
+    }
+}
+export 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
+// response through unchanged if there's no availableMoves array.
+export function convertAvailableMovesToSAN(raw, fen) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const r = raw;
+    if (!Array.isArray(r.availableMoves))
+        return raw;
+    for (const m of r.availableMoves) {
+        if (typeof m.move === "string" && m.move.length >= 4) {
+            m.move = uciMoveToSAN(fen, m.move);
+        }
+    }
+    return raw;
+}
+// Normalize one MCP `prepare_opponent` source into the shape the backend's
+// /api/chess/prep/prepare-multi expects. Handles two impedance mismatches:
+//   - snake_case → camelCase (fide_id → fideId, start_month → startMonth, etc.)
+//   - the unified `time_control` string → per-source-type filter:
+//       * fide / chesscom → timeFormats: ["Classical" | "Rapid" | "Blitz"]
+//       * lichess → perfType: "classical" | "rapid" | "blitz" | "bullet"
+// Backend validates required fields per source type, so we don't need to
+// pre-reject missing username/fideId here — it'll come back as a 400 the
+// LLM can act on.
+export function normalizeSourceForBackend(src, idx) {
+    const type = typeof src.type === "string" ? src.type : "";
+    if (type !== "fide" && type !== "chesscom" && type !== "lichess") {
+        throw new Error(`sources[${idx}].type must be one of fide|chesscom|lichess (got ${JSON.stringify(src.type)})`);
+    }
+    const out = { type };
+    if (typeof src.fide_id === "number")
+        out.fideId = src.fide_id;
+    if (typeof src.username === "string" && src.username.trim() !== "")
+        out.username = src.username.trim();
+    if (typeof src.color === "string" && (src.color === "white" || src.color === "black"))
+        out.color = src.color;
+    if (typeof src.start_month === "string" && src.start_month.trim() !== "")
+        out.startMonth = src.start_month.trim();
+    if (typeof src.end_month === "string" && src.end_month.trim() !== "")
+        out.endMonth = src.end_month.trim();
+    if (typeof src.exclude_online === "boolean")
+        out.excludeOnline = src.exclude_online;
+    const tc = typeof src.time_control === "string" ? src.time_control : "";
+    if (tc) {
+        if (type === "lichess") {
+            out.perfType = tc;
+        }
+        else {
+            // fide + chesscom take a titlecased timeFormats array.
+            const titled = tc.charAt(0).toUpperCase() + tc.slice(1);
+            out.timeFormats = [titled];
+        }
+    }
+    return out;
+}

package/package.json

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