@chessceo/mcp 0.44.0 → 0.48.2

package/dist/pgn/exporter.js

@@ -25,9 +25,20 @@ export function exportPGN(file) {
         parts.push(`[${k} "${escapeTagValue(v)}"]`);
     }
     parts.push(""); // blank line between headers and movetext
-    // Movetext.
+    // Movetext. Root can carry a text comment AND visual annotations
+    // AND a stored eval — all rendered in a single {…} block before the
+    // first move so the parser's regexes pick them all up on re-parse.
+    // (v0.46 fix: previously only the visual/eval annotation was emitted
+    // and it went out unbraced — a plain comment set on the root via
+    // set_comment silently disappeared during export.)
+    const rootPreludeBits = [];
+    if (file.root.comment && file.root.comment.trim().length > 0) {
+        rootPreludeBits.push(file.root.comment.trim());
+    }
     const rootAnnotation = renderNodeAnnotation(file.root);
-    const rootPrelude = rootAnnotation ? `${rootAnnotation} ` : "";
+    if (rootAnnotation)
+        rootPreludeBits.push(rootAnnotation);
+    const rootPrelude = rootPreludeBits.length > 0 ? `{${rootPreludeBits.join(" ")}} ` : "";
     const movetext = rootPrelude + renderChildren(file.root.children, file.root.ply + 1, /* forceMoveNumber */ true);
     const result = file.tags.Result ?? "*";
     parts.push(`${movetext.trim()} ${result}`);

package/dist/pgn/parser.js

@@ -15,7 +15,15 @@ import { deriveNodeId, ROOT_ID } from "./paths.js";
 const CAL_RE = /\[%cal\s+([^\]]+)\]/g;
 const CSL_RE = /\[%csl\s+([^\]]+)\]/g;
 const CEO_EVAL_RE = /\[%ceo-eval\s+([^\]]+)\]/g;
-const ANY_CMD_RE = /\[%[a-z-]+\s+[^\]]+\]/g;
+// Only strip the three escape commands we structurally parse (into
+// annotations + ceoEval). Everything else — [%eval], [%wdl], [%clk],
+// [%emt], and any future/unknown [%foo] — is preserved verbatim in
+// the comment text so a parse → export round-trip is lossless.
+// v0.46 fix: previously ANY_CMD_RE matched `\[%[a-z-]+\s+[^\]]+\]`
+// and silently dropped every unknown escape (real report: a
+// `{[%eval] [%wdl]}` comment on an imported Lichess PGN got stripped
+// on a set_tag save cycle).
+const KNOWN_CMD_RE = /\[%(?:cal|csl|ceo-eval)\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.
@@ -85,16 +93,41 @@ export function parseCommentAnnotations(comment) {
         if (ev.sf || ev.lc0 || ev.nag)
             ceoEval = ev;
     }
-    const text = comment.replace(ANY_CMD_RE, "").replace(/\s+/g, " ").trim();
+    const text = comment.replace(KNOWN_CMD_RE, "").replace(/\s+/g, " ").trim();
     const annotations = arrows.length || highlights.length ? { arrows, highlights } : undefined;
     return { text, annotations, ceoEval };
 }
+// chessops' parsePgn silently drops any {…} block that sits BEFORE
+// the first move — we've verified this: `{root note} 1. e4` parses
+// with the "root note" nowhere in the resulting tree. That broke
+// set_comment(node_id: "r") round-trips (v0.46 bug report). Extract
+// the leading root-level comment ourselves before handing the rest
+// to chessops. Anything past the leading `{…}` is left untouched so
+// chessops can do its normal job.
+function extractRootComment(pgn) {
+    const sepMatch = /\r?\n\r?\n/.exec(pgn);
+    if (!sepMatch)
+        return { pgn, rootComment: null };
+    const headerEnd = sepMatch.index + sepMatch[0].length;
+    const body = pgn.slice(headerEnd);
+    // Leading whitespace, then a {…} block. Non-greedy so we stop at
+    // the first `}` even if the file has more comments later.
+    const m = /^\s*\{([\s\S]*?)\}\s*/.exec(body);
+    if (!m)
+        return { pgn, rootComment: null };
+    const rest = body.slice(m[0].length);
+    return {
+        pgn: pgn.slice(0, headerEnd) + rest,
+        rootComment: m[1],
+    };
+}
 // Parse full PGN → PrepFile. Throws on unrecoverable errors (no games,
 // invalid starting FEN). Illegal SAN moves in the movetext are skipped
 // silently — matches the frontend's tolerant behaviour so a game with
 // one typo doesn't nuke the whole tree.
 export function parsePGN(pgn) {
-    const games = parsePgn(pgn);
+    const { pgn: cleanPgn, rootComment: preComment } = extractRootComment(pgn);
+    const games = parsePgn(cleanPgn);
     if (games.length === 0)
         throw new Error("no games in PGN");
     const game = games[0];
@@ -107,10 +140,16 @@ export function parsePGN(pgn) {
     const startPos = startResult.value;
     const rootFen = makeFen(startPos.toSetup());
     const root = { id: ROOT_ID, san: null, fen: rootFen, ply: 0, children: [] };
-    // Root-level comment on the game (rare, but supported).
-    const gameComments = game.moves.comments;
-    if (gameComments && gameComments.length > 0) {
-        const parsed = parseCommentAnnotations(gameComments.join(" "));
+    // Root-level comment on the game. Two sources:
+    //   1. `game.moves.comments` — kept as a fallback in case chessops
+    //      ever populates it (currently doesn't for pre-move-1 blocks).
+    //   2. `preComment` — the {…} we pre-extracted above.
+    const gameCommentsRaw = game.moves.comments ?? [];
+    const rootCommentBits = [...gameCommentsRaw];
+    if (preComment)
+        rootCommentBits.push(preComment);
+    if (rootCommentBits.length > 0) {
+        const parsed = parseCommentAnnotations(rootCommentBits.join(" "));
         if (parsed.text)
             root.comment = parsed.text;
         if (parsed.annotations)

package/dist/pgn/paths.js

@@ -13,21 +13,28 @@
 import { createHash } from "node:crypto";
 // Special ID for the root position (starting FEN, no move played).
 export const ROOT_ID = "r";
-// 8-hex-char (32-bit) content hash. Root is "r". Every other node's
+// 12-hex-char (48-bit) content hash. Root is "r". Every other node's
 // id is derived from (parent.id, san). Two children of the same parent
 // with the same SAN are impossible in real chess — same SAN from the
 // same position IS the same move — so within-parent same-id events
 // mean the caller tried to duplicate a move that already exists;
 // `addMove` handles that by joining to the existing child rather than
-// appending a duplicate (see mutations.ts). Cross-tree birthday
-// collisions in 32 bits at 1000 nodes are ~10^-4 — rare, and thrown
-// at parse time rather than silently masked.
+// appending a duplicate (see mutations.ts).
+//
+// v0.46: widened from 32 → 48 bit. At the 32-bit width birthday
+// collisions in real prep files ran ~10^-4 at 1000 nodes and were
+// hit in practice, throwing at buildIdIndex time and rendering the
+// whole file unreadable. 48 bits drops that to ~10^-9 at 1000 nodes
+// (~10^-7 at 10k). If a collision still lands, buildIdIndex now
+// keeps the first occurrence and logs rather than throwing, so
+// reads survive; only mutations against the collided id go to the
+// first-found node.
 export function deriveNodeId(parentId, san) {
     const h = createHash("sha256");
     h.update(parentId);
     h.update("|");
     h.update(san);
-    return h.digest("hex").slice(0, 8);
+    return h.digest("hex").slice(0, 12);
 }
 // Bad-node-id errors so the LLM sees exactly what went wrong. Message
 // carries the offending id, which is often a copy-paste bug (missing
@@ -46,19 +53,35 @@ export class PathError extends Error {
         this.path = path;
     }
 }
-// Build the id → path index for a whole tree. Also detects the rare
-// collision (two nodes with the same 32-bit id) and throws so the
-// caller can surface a clear message.
+// Build the id → path index for a whole tree.
+//
+// v0.46: collisions no longer throw. At 48-bit width they're
+// statistically improbable (~10^-9 at 1000 nodes), but if one does
+// land — e.g. a persisted PGN whose IDs were derived by an older
+// 32-bit build — throwing would render the whole file unreadable
+// via the MCP surface. Instead, we keep the FIRST occurrence in the
+// index and emit a stderr line naming both nodes. Reads survive
+// (`read_prep_file` returns the full tree; the collided IDs both
+// appear in the tree even though only one is addressable via
+// `resolveNodeId`). Mutations against the collided id hit the
+// first-found node deterministically. Downstream tools that care —
+// `list_nodes`, `find_position_in_files`, engine calls that don't
+// need a node handle — keep working normally.
 export function buildIdIndex(root) {
     const index = new Map();
     const walk = (node, path) => {
-        if (index.has(node.id)) {
-            throw new Error(`node id collision on "${node.id}" — two distinct nodes in the tree ` +
-                `hash to the same 32-bit id. This is statistically rare (~10^-4 at ` +
-                `1000 nodes); if you see this, please report the file so we can ` +
-                `widen the hash.`);
+        const existing = index.get(node.id);
+        if (existing !== undefined) {
+            // Keep the earlier occurrence; log so operators can widen further
+            // if this recurs. Message names both nodes' SAN + ply so the file
+            // is identifiable.
+            console.error(`[mcp] node id collision on "${node.id}" — first at path ${JSON.stringify(existing)}, ` +
+                `now at path ${JSON.stringify(path)} (san=${node.san}, ply=${node.ply}). ` +
+                `Keeping the first; mutations against this id will hit that node.`);
+        }
+        else {
+            index.set(node.id, path);
         }
-        index.set(node.id, path);
         for (let i = 0; i < node.children.length; i++) {
             walk(node.children[i], [...path, i]);
         }

package/dist/pgn/types.js

@@ -2,7 +2,7 @@
 //
 // Nodes are addressed by a stable, content-derived `id`:
 //   root.id = "r"
-//   node.id = first 8 hex chars of sha256(parent.id + "|" + san)
+//   node.id = first 12 hex chars of sha256(parent.id + "|" + san)
 //
 // The derivation is a pure function of the tree structure, so IDs
 // survive parse → mutate → export → reparse without needing to be
@@ -12,10 +12,13 @@
 // op inserts a sibling) simply cannot happen. See src/pgn/paths.ts
 // for the id → path resolution used to power mutation calls.
 //
-// 32-bit width (8 hex chars) means birthday-collision probability
-// is ~10^-4 even at 1000 nodes — the largest prep files we see are
-// well under that. On the rare parse-time collision we throw a clear
-// error rather than persisting anything ambiguous.
+// v0.46: 48-bit width (12 hex chars) means birthday-collision
+// probability is ~10^-9 at 1000 nodes and ~10^-7 at 10k. Was 32-bit
+// (8 hex chars) through v0.45; collisions hit ~10^-4 there and were
+// observed in live prep files. If a collision still lands at the new
+// width, buildIdIndex keeps the first occurrence and logs to stderr
+// rather than throwing — the file stays readable, only mutations
+// against the collided id are ambiguous.
 // Named colours as they appear in the parsed tree. The wire format uses
 // single-letter codes (G, R, Y, C, B, O); the tree uses these longer
 // names to match how the frontend represents them.

package/dist/prep/library.js

@@ -0,0 +1,92 @@
+// Discovery + creation over the user's full PGN library. v0.43 removed
+// the hidden `/mcp`-folder scoping; every function here now reaches
+// across every non-encrypted collection the user owns.
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { authedRequest, createGame, makeFileId, PGN_BASE, unwrap, } from "../http.js";
+import { resolveFromNodeOrFen } from "../analysis/file_handle.js";
+export async function listCollections(_args) {
+    const raw = await authedRequest("GET", PGN_BASE);
+    const collections = unwrap(raw) ?? [];
+    return {
+        collections: collections.map(c => ({
+            id: c.id,
+            title: c.title,
+            icon: c.icon,
+            folder_path: c.folderPath,
+            game_count: c.gameCount,
+            position_search_enabled: c.positionSearchEnabled,
+            updated_at: c.updatedAt,
+        })),
+    };
+}
+// Convert a browser-returned game list row into the LLM shape (composite
+// id, cleaned field names).
+function projectGameRow(row) {
+    const collId = row.collectionId ?? "";
+    return {
+        id: collId ? makeFileId(collId, row.id) : row.id,
+        collection_id: collId,
+        collection_title: row.collectionTitle,
+        event: row.event,
+        white: row.white_player,
+        black: row.black_player,
+        eco: row.eco,
+        opening: row.opening,
+        updated_at: row.updated_at,
+        ply: row.ply,
+    };
+}
+export async function listPrepFiles(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to see your options, or search across collections with search_prep_files / find_position_in_files");
+    }
+    // Browser handler at GET /me/pgns/{id}/games returns a paginated list.
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games?page=1&limit=200`);
+    const data = unwrap(raw);
+    const games = data?.games ?? (Array.isArray(data) ? data : []);
+    return { collection_id: collectionId, prep_files: games.map(projectGameRow) };
+}
+export async function searchPrepFiles(args) {
+    const q = typeof args.query === "string" ? args.query.trim() : "";
+    if (!q)
+        throw new Error("query required");
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?q=${encodeURIComponent(q)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return { query: q, prep_files: games.map(projectGameRow) };
+}
+export async function findPositionInFiles(args) {
+    // FEN can come from a node handle OR a direct fen/moves/line. Reuse
+    // the same resolver everything else uses.
+    const resolved = await resolveFromNodeOrFen(args);
+    const fen = resolved.fen;
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?position=${encodeURIComponent(fen)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return {
+        fen,
+        match_count: games.length,
+        prep_files: games.map(projectGameRow),
+    };
+}
+export async function createPrepFile(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to pick where the new file lives. There is no default landing folder any more (v0.43: the old hidden /mcp collection was removed).");
+    }
+    const name = String(args.name || "").trim();
+    if (!name)
+        throw new Error("name is required");
+    // Seed with a PGN carrying the LLM-chosen name as the Event tag so
+    // subsequent list_prep_files calls display something useful.
+    const seedPgn = `[Event "${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n\n*\n`;
+    const game = await createGame(collectionId, seedPgn);
+    return {
+        ok: true,
+        id: makeFileId(game.collectionId ?? collectionId, game.id),
+        collection_id: game.collectionId ?? collectionId,
+        version: game.version,
+    };
+}

package/dist/prep/mutations.js

@@ -0,0 +1,176 @@
+// Mutation orchestration for prep files.
+//
+// Every mutation tool goes through one of two entry points:
+//   - `applyMutation(args, mutator)` — the standard case handler wrapper.
+//     Fetches the file, runs the mutator, saves. Auto-saves so every
+//     tool call is atomic; the LLM never sees intermediate state.
+//   - `applyBatchMutations(args)` — the `apply_mutations` tool. Loads
+//     once, runs N ops in order via `dispatchMutation`, saves once.
+//     All-or-nothing.
+//
+// `dispatchMutation` is the switch that maps `op` names to the actual
+// mutation helpers from `pgn/mutations` plus the anti-pattern warning
+// scanners.
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { fetchGame, saveGame } from "../http.js";
+import { parsePGN } from "../pgn/parser.js";
+import { exportPGN } from "../pgn/exporter.js";
+import { buildIdIndex, NodeIdError, PathError, resolveNodeId, ROOT_ID, } from "../pgn/paths.js";
+import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "../pgn/mutations.js";
+import { getNodeByPath } from "../analysis/file_handle.js";
+import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, } from "../warnings.js";
+// Extract a node id from the args. Accepts either `node_id` or a
+// `parent_id` alias for the add-style tools. Throws with a helpful
+// message if malformed.
+export function argNodeId(args, key = "node_id") {
+    const raw = args[key];
+    if (typeof raw !== "string" || raw.length === 0) {
+        throw new Error(`\`${key}\` is required (call read_prep_file to get valid node ids)`);
+    }
+    return raw.trim();
+}
+// Dispatch table for the batch tool: name → mutator that returns
+// { file, id } where id is the node the mutation touched. The batch
+// caller rebuilds the id → path index between ops so newly-created
+// nodes are addressable within the same batch.
+export function dispatchMutation(file, idIndex, op) {
+    const kind = String(op.op);
+    // Small local helper — resolves a node_id (or parent_id) op field to
+    // a path against the CURRENT tree state.
+    const nodeIdField = (key) => {
+        const raw = op[key];
+        if (typeof raw !== "string" || raw.length === 0) {
+            throw new Error(`\`${key}\` required on op ${kind}`);
+        }
+        return raw.trim();
+    };
+    const resolve = (id) => resolveNodeId(idIndex, id);
+    switch (kind) {
+        case "add_move": {
+            const parentPath = resolve(nodeIdField("parent_id"));
+            const parent = getNodeByPath(file.root, parentPath);
+            const noStatsWarn = noStatsCheckWarning(parent);
+            const step = addMove(file, parentPath, String(op.san));
+            return { ...step, ...(noStatsWarn ? { warning: noStatsWarn } : {}) };
+        }
+        case "add_line": {
+            const sans = Array.isArray(op.sans) ? op.sans.map(String) : [];
+            const parentPath = resolve(nodeIdField("parent_id"));
+            const parent = getNodeByPath(file.root, parentPath);
+            const step = addLine(file, parentPath, sans);
+            const lastId = step.line.length > 0 ? step.line[step.line.length - 1].id : nodeIdField("parent_id");
+            // Same anti-pattern warnings as the standalone add_line case —
+            // long unbranched line + no-stats-check parent are both bugs
+            // whether they land solo or inside a batch.
+            const longLineWarn = longLineWarning(sans.length);
+            const noStatsWarn = noStatsCheckWarning(parent);
+            const warnings = [longLineWarn, noStatsWarn].filter((s) => !!s);
+            return { file: step.file, id: lastId, results: step.line, ...(warnings.length > 0 ? { warnings } : {}) };
+        }
+        case "set_comment": {
+            const commentStr = typeof op.comment === "string" ? op.comment : "";
+            const commentWarns = commentAntiPatterns(commentStr);
+            const targetPath = resolve(nodeIdField("node_id"));
+            const targetNode = getNodeByPath(file.root, targetPath);
+            const describeWarn = noDescribeWarning(targetNode, commentStr);
+            const step = setComment(file, targetPath, commentStr);
+            const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
+            return { ...step, ...(all.length > 0 ? { warnings: all } : {}) };
+        }
+        case "set_nags": {
+            const nagsArr = Array.isArray(op.nags) ? op.nags.map(String) : [];
+            const targetPath = resolve(nodeIdField("node_id"));
+            const targetNode = getNodeByPath(file.root, targetPath);
+            const nagWarn = positionalNagOnIntermediateWarning(targetNode, nagsArr);
+            const step = setNags(file, targetPath, nagsArr);
+            return { ...step, ...(nagWarn ? { warning: nagWarn } : {}) };
+        }
+        case "set_annotations": {
+            const arrows = Array.isArray(op.arrows) ? op.arrows : [];
+            const highlights = Array.isArray(op.highlights) ? op.highlights : [];
+            const ann = arrows.length === 0 && highlights.length === 0 ? null : { arrows, highlights };
+            return setAnnotations(file, resolve(nodeIdField("node_id")), ann);
+        }
+        case "set_ceo_eval": {
+            const ev = op.ceoEval;
+            return setCeoEval(file, resolve(nodeIdField("node_id")), ev ?? null);
+        }
+        case "delete_subtree":
+            return deleteSubtree(file, resolve(nodeIdField("node_id")));
+        case "promote_variation":
+            return promoteVariation(file, resolve(nodeIdField("node_id")));
+        case "set_tag":
+            return { file: setTag(file, String(op.key), String(op.value ?? "")), id: ROOT_ID };
+        default:
+            throw new Error(`unknown mutation op: ${kind}`);
+    }
+}
+// Batch: load, parse, apply N mutations in order, export, save.
+// All-or-nothing — any error aborts and nothing is saved. The id index
+// is rebuilt after each op so nodes created earlier in the batch can be
+// addressed by later ops via their newly-derived node_id.
+export async function applyBatchMutations(args) {
+    const id = String(args.id);
+    const mutations = Array.isArray(args.mutations) ? args.mutations : [];
+    if (mutations.length === 0)
+        throw new Error("mutations array required");
+    const g = await fetchGame(id);
+    let file = parsePGN(g.pgnContent);
+    let idIndex = buildIdIndex(file.root);
+    const results = [];
+    for (let i = 0; i < mutations.length; i++) {
+        const op = mutations[i];
+        try {
+            const step = dispatchMutation(file, idIndex, op);
+            file = step.file;
+            idIndex = buildIdIndex(file.root);
+            results.push({
+                node_id: step.id,
+                ...(step.results !== undefined ? { line: step.results } : {}),
+                ...(step.warning ? { warning: step.warning } : {}),
+                ...(step.warnings && step.warnings.length > 0 ? { warnings: step.warnings } : {}),
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`mutation #${i} (${String(op.op)}) failed: ${msg}`);
+        }
+    }
+    const newPgn = exportPGN(file);
+    const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
+    const saved = await saveGame(id, newPgn, expected);
+    return { ok: true, results, version: saved.version };
+}
+// Load-mutate-save: fetch current PGN, parse, apply mutation, re-export,
+// save with optimistic lock. Auto-saves so every tool call is atomic;
+// the LLM never sees intermediate state. The mutator is called with
+// both the parsed file and its id → path index, so the mutation can
+// resolve node_ids without rebuilding the index itself.
+export async function applyMutation(args, mutator) {
+    const id = String(args.id);
+    const g = await fetchGame(id);
+    const file = parsePGN(g.pgnContent);
+    const idIndex = buildIdIndex(file.root);
+    let result;
+    try {
+        result = mutator(file, idIndex);
+    }
+    catch (err) {
+        if (err instanceof MutationError || err instanceof PathError || err instanceof NodeIdError) {
+            throw new Error(`mutation rejected: ${err.message}`);
+        }
+        throw err;
+    }
+    const newPgn = exportPGN(result.file);
+    const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
+    const saved = await saveGame(id, newPgn, expected);
+    return {
+        ok: true,
+        node_id: result.id,
+        ...(result.results !== undefined ? { line: result.results } : {}),
+        ...(result.warning ? { warning: result.warning } : {}),
+        ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        version: saved.version,
+    };
+}