@chessceo/mcp 0.23.0 → 0.26.0

package/dist/index.js

@@ -14,7 +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 { addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setComment, setNags, setTag, } from "./pgn/mutations.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";
@@ -76,6 +76,8 @@ const AUTHED_TOOLS = new Set([
     "delete_subtree",
     "promote_variation",
     "set_tag",
+    "apply_mutations",
+    "auto_evaluate",
     "predict_human_move",
 ]);
 function isAuthedToolCall(body) {
@@ -186,6 +188,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" +
@@ -227,7 +230,8 @@ 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 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.",
         inputSchema: {
             type: "object",
             properties: {
@@ -252,35 +256,6 @@ const TOOLS = [
             },
         },
     },
-    {
-        name: "analyse",
-        description: "Short Stockfish evaluation at a position. Returns the top-N candidate moves with score (centipawns from side-to-move POV, positive = advantage; or mate distance) and the principal variation for each. Defaults: 2s think time, top-3 lines. PV moves come back in SAN (e4, Nf3, Bxc4 — not UCI). Free (no cloud instance needed) — use liberally.\n\n" +
-            "GROUNDING: cite this tool's actual output when you claim things about positions. Don't invent evaluations from general principles or training data — if you don't have engine output for a FEN, call this. Compute is cheap.\n\n" +
-            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves` to walk from an arbitrary position. Also see the flip-side-to-move threat check in read_engine_usage_guide.\n\n" +
-            "Use this to sanity-check candidate lines from get_position_stats or get_player_preparation — human game frequency tells you what people play, engine evaluation tells you what's actually good.",
-        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` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5'.",
-                },
-                movetime_ms: {
-                    type: "integer",
-                    minimum: 100,
-                    maximum: 10000,
-                    description: "Think time in milliseconds (default 2000).",
-                },
-                multipv: {
-                    type: "integer",
-                    minimum: 1,
-                    maximum: 10,
-                    description: "Number of candidate lines to return (default 3).",
-                },
-            },
-        },
-    },
     {
         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" +
@@ -610,6 +585,56 @@ const TOOLS = [
             required: ["id", "path"],
         },
     },
+    {
+        name: "apply_mutations",
+        description: "Batch: apply a list of mutations in one call. One load-parse-mutate-export-save cycle for N ops, so building a 100-move repertoire costs one HTTP round-trip and one save instead of 100. This is the RIGHT way to build a file — use single mutations only for surgical follow-up edits.\n\n" +
+            "Each mutation is `{op, path, ...args}` where `op` is one of: add_move, set_comment, set_nags, set_annotations, delete_subtree, promote_variation, set_tag. Same arg shape as the individual tools. Ops apply in order; `path` is resolved against the tree AFTER preceding ops in the batch — so after `{op: 'add_move', path: [0], san: 'Nc3'}` the new node's path is `[0, N]` where N is the parent's previous children count (or `[0, 0]` if it was empty).\n\n" +
+            "Any op error aborts the batch (nothing saved). Response is `{ok, results: [{path}], version}` giving the effective path each op landed at plus the new file version.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                expected_version: { type: "integer" },
+                mutations: {
+                    type: "array",
+                    minItems: 1,
+                    items: {
+                        type: "object",
+                        properties: {
+                            op: { type: "string", enum: ["add_move", "set_comment", "set_nags", "set_annotations", "delete_subtree", "promote_variation", "set_tag"] },
+                            path: { type: "array", items: { type: "integer", minimum: 0 } },
+                            san: { type: "string" },
+                            comment: { type: "string" },
+                            nags: { type: "array", items: { type: "string", pattern: "^\\$\\d+$" } },
+                            arrows: { type: "array" },
+                            highlights: { type: "array" },
+                            key: { type: "string" },
+                            value: { type: "string" },
+                        },
+                        required: ["op"],
+                    },
+                },
+            },
+            required: ["id", "mutations"],
+        },
+    },
+    {
+        name: "auto_evaluate",
+        description: "Walk the tree from `path` (default `[]` = whole file) and auto-assign NAGs to every node based on the Stockfish eval from cloud_analyse. Uses the standard eval → NAG thresholds (|eval|<0.25 → $10, <0.6 → $14/$15, <1.3 → $16/$17, ≥1.3 → $18/$19). Requires a running cloud combo instance.\n\n" +
+            "This is the automate-the-boring-part tool. Instead of hand-annotating each move with a NAG, you build the tree via apply_mutations (no NAGs needed), then call auto_evaluate once and every node gets the right glyph.\n\n" +
+            "Costs real money — hits cloud_analyse per node. A 200-node tree at 1.5s/node = ~5 min of engine time. Use `only_missing=true` (default) to skip nodes that already have a NAG on subsequent runs. Runs 4 evaluations in parallel to save wall time.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Subtree root (default = whole file)." },
+                only_missing: { type: "boolean", description: "Skip nodes that already carry a NAG (default true)." },
+                movetime_ms: { type: "integer", minimum: 500, maximum: 5000, description: "Per-node cloud_analyse think time (default 1500)." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id"],
+        },
+    },
     {
         name: "set_tag",
         description: "Set or clear a game-level PGN tag (Event, Site, Date, White, Black, Result, or any custom tag). Passing empty string removes the tag. Auto-saves.",
@@ -646,7 +671,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: {
@@ -717,19 +743,16 @@ function uciMoveToSAN(startFen, uci) {
         return uci;
     }
 }
-// Rewrite the local /chess/database/analyse response (single engine)
-// so PVs come back in SAN.
-function convertAnalyseResponse(raw, startFen) {
-    if (!raw || typeof raw !== "object")
-        return raw;
-    const r = raw;
-    if (Array.isArray(r.lines)) {
-        for (const line of r.lines) {
-            if (Array.isArray(line.pv))
-                line.pv = uciLineToSAN(startFen, line.pv);
-        }
+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;
     }
-    return raw;
 }
 // Rewrite the /api/agent/cloud-engines/analyse response (two engines,
 // each with lines[] and a bestMove) so PVs and bestMove come back in SAN.
@@ -767,6 +790,221 @@ function argPath(args) {
     }
     return out;
 }
+// Dispatch table for the batch tool: name → mutator that returns the
+// standard { file, path } shape. Reused for individual and batch calls.
+function dispatchMutation(file, op) {
+    const kind = String(op.op);
+    const path = Array.isArray(op.path) ? op.path : [];
+    switch (kind) {
+        case "add_move":
+            return addMove(file, path, String(op.san));
+        case "set_comment":
+            return setComment(file, path, typeof op.comment === "string" ? op.comment : "");
+        case "set_nags":
+            return setNags(file, path, Array.isArray(op.nags) ? op.nags.map(String) : []);
+        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, 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":
+            return promoteVariation(file, path);
+        case "set_tag":
+            return { file: setTag(file, String(op.key), String(op.value ?? "")), path: [] };
+        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.
+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 raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
+    const g = raw;
+    if (typeof g.pgnContent !== "string")
+        throw new Error("prep file missing pgnContent");
+    let file = parsePGN(g.pgnContent);
+    const results = [];
+    for (let i = 0; i < mutations.length; i++) {
+        const op = mutations[i];
+        try {
+            const step = dispatchMutation(file, op);
+            file = step.file;
+            results.push({ path: step.path });
+        }
+        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 authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
+        pgn: newPgn,
+        expected_version: expected,
+    });
+    const savedRow = saved;
+    return { ok: true, results, version: savedRow.version };
+}
+// Auto-evaluate: walk the tree from `path`, run cloud_analyse on each node,
+// 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 : [];
+    const onlyMissing = args.only_missing !== false; // default true
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 1500;
+    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
+    const g = raw;
+    if (typeof g.pgnContent !== "string")
+        throw new Error("prep file missing pgnContent");
+    const file = parsePGN(g.pgnContent);
+    const targets = [];
+    const walk = (node, path) => {
+        if (path.length > 0) {
+            if (!onlyMissing || !node.ceoEval) {
+                targets.push({ path, fen: node.fen });
+            }
+        }
+        for (let i = 0; i < node.children.length; i++)
+            walk(node.children[i], [...path, i]);
+    };
+    const startNode = pathIntoTree(file.root, startPath);
+    walk(startNode, startPath);
+    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-ws connection cap (single-client per port).
+    const stored = [];
+    const CONCURRENCY = 4;
+    let cursor = 0;
+    async function worker() {
+        while (cursor < targets.length) {
+            const idx = cursor++;
+            const t = targets[idx];
+            try {
+                const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
+                const ev = analysisToStoredEval(analysis, t.fen);
+                if (ev)
+                    stored.push({ path: t.path, ev });
+            }
+            catch {
+                // best-effort — a single failed node shouldn't kill the batch
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+    if (stored.length === 0)
+        return { ok: true, evaluated: 0, skipped: targets.length, version: g.version };
+    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: 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) {
+    let cur = root;
+    for (let i = 0; i < path.length; i++) {
+        if (path[i] < 0 || path[i] >= cur.children.length) {
+            throw new Error(`path segment ${i}=${path[i]} out of bounds`);
+        }
+        cur = cur.children[path[i]];
+    }
+    return cur;
+}
+// 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 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;
+    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;
+    const abs = Math.abs(effective);
+    if (abs < 25)
+        return "$10";
+    if (abs < 60)
+        return effective > 0 ? "$14" : "$15";
+    if (abs < 130)
+        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;
 // the LLM never sees intermediate state.
@@ -910,27 +1148,30 @@ 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 (ev && converted && typeof converted === "object")
+                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);
-        }
-        case "analyse": {
-            const fen = resolveFenFromArgs(args);
-            const params = { fen };
-            if (typeof args.movetime_ms === "number")
-                params.movetime_ms = args.movetime_ms;
-            if (typeof args.multipv === "number")
-                params.multipv = args.multipv;
-            const raw = await get("/api/chess/database/analyse", params);
-            return convertAnalyseResponse(raw, fen);
+            const [raw, ev] = await Promise.all([
+                get("/api/chess/database/main", {
+                    fen,
+                    limit: typeof args.limit === "number" ? args.limit : 20,
+                    sort: "relevance",
+                }),
+                fetchCompactEval(fen),
+            ]);
+            const converted = convertAvailableMovesToSAN(raw, fen);
+            if (ev && converted && typeof converted === "object")
+                converted.eval = ev;
+            return converted;
         }
         case "predict_human_move": {
             const fen = resolveFenFromArgs(args);
@@ -1032,6 +1273,10 @@ async function callToolInner(name, args) {
                 file: setTag(file, String(args.key), String(args.value ?? "")),
                 path: [],
             }));
+        case "apply_mutations":
+            return applyBatchMutations(args);
+        case "auto_evaluate":
+            return autoEvaluate(args);
         case "read_engine_usage_guide":
             return { guide: ENGINE_USAGE_DOC };
         case "read_prep_strategy_guide":
@@ -1075,13 +1320,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/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();

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

@@ -16,29 +16,54 @@ Nodes are addressed by **path**: an array of child indices from the root.
 
 ## Workflow
 
-The mutation tool set is:
+Reading:
 
 - `read_prep_file(id)` → returns `{version, tags, tree}`. Every node in `tree` has `san`, `fen`, `ply`, optional `comment`, `nags`, `annotations`, and `children`.
-- `add_move(id, path, san)` — appends a new child of `path`. If `path` already has children, the new node becomes a variation. Returns the effective path of the new node.
-- `set_comment(id, path, comment)` — replace comment. Empty string clears.
-- `set_nags(id, path, nags)` — replace NAG list. Empty array clears.
-- `set_annotations(id, path, {arrows, highlights})` — replace visual annotations. Empty arrays clear.
-- `delete_subtree(id, path)` — remove node + descendants. Refuses to delete the root.
+
+Building (use these — one call for many ops):
+
+- **`apply_mutations(id, mutations[])`** — batch. This is the primary build tool. Send 100 mutations in one call → one load-parse-mutate-save cycle instead of 100. When you're writing a repertoire from scratch, EVERYTHING should go through this. Individual mutation tools are for surgical follow-up edits, not for bulk work.
+- **`auto_evaluate(id, path?)`** — walk the tree from `path` and auto-assign the right NAG to every node by running cloud_analyse on each position. Standard threshold table (below). Costs real engine time but frees you from hand-annotating evals. Skip nodes that already have a NAG by default.
+
+Per-op mutation tools (single-op calls, use for edits after the bulk build):
+
+- `add_move(id, path, san)` — appends a new child. If `path` has children, new node becomes a variation.
+- `set_comment(id, path, comment)` — replace comment (empty string clears).
+- `set_nags(id, path, nags)` — replace NAGs (empty array clears).
+- `set_annotations(id, path, {arrows, highlights})` — replace visual annotations.
+- `delete_subtree(id, path)` — remove node + descendants.
 - `promote_variation(id, path)` — make the node at `path` its parent's mainline.
-- `set_tag(id, key, value)` — set/clear a game-level tag.
+- `set_tag(id, key, value)` — set/clear a game-level PGN tag.
 
-Every mutation **auto-saves** with optimistic locking. Response is `{ok: true, path, version}`. Pass the returned `version` as `expected_version` on your next mutation to catch concurrent edits.
+All mutations **auto-save** with optimistic locking. Response includes the new `version`; pass it as `expected_version` on your next call to catch concurrent edits.
 
 ## Typical build order
 
 1. `read_prep_file` — see what's there.
-2. `add_move` to extend the mainline: `add_move(id, [], "e4")` then `add_move(id, [0], "c5")` etc.
-3. `add_move` for a variation at some node: `add_move(id, [0, 0], "Nc3")` adds Nc3 as a sibling of the current mainline's move 2.
-4. `set_comment` for plans / prep-signal, `set_nags` for evaluations, `set_annotations` for arrows and squares — always on the node the annotation belongs to.
-5. `promote_variation` if a variation is more important than the current mainline.
-6. `delete_subtree` to prune.
+2. `apply_mutations([...])` — one call with your whole intended build (all `add_move` for the moves and variations, plus any `set_comment`/`set_annotations` you already know at author time). Skip `set_nags` — auto_evaluate handles that.
+3. `auto_evaluate(id)` — walk the tree, get engine evals, assign NAGs. One shot.
+4. Individual mutation tools ONLY for surgical follow-ups (fix one comment, add one arrow, promote a specific variation, prune a branch).
 
-Every step returns the new `version`; carry it forward.
+The build-cost math: a 200-move file via individual `add_move` calls is 200 saves ≈ 100+ seconds of tool overhead. The same file via one `apply_mutations` call is one save ≈ 500ms. Use batch by default.
+
+### Path math in a batch
+
+Paths in each mutation resolve against the tree AFTER previous ops in the batch. When you `add_move(path=[0], san='c5')`, the new c5 lands at `[0, 0]` if [0] had no children, or `[0, N]` if it had N. Your next mutation in the batch can address the new node directly. The tree is deterministic — you can compute all paths ahead of time.
+
+For a linear mainline build from an empty file:
+```
+{op: "add_move", path: [],        san: "e4"}   // lands at [0]
+{op: "add_move", path: [0],       san: "c5"}   // lands at [0, 0]
+{op: "add_move", path: [0, 0],    san: "Nf3"}  // lands at [0, 0, 0]
+{op: "add_move", path: [0, 0, 0], san: "d6"}   // lands at [0, 0, 0, 0]
+...
+```
+
+For a variation at some point:
+```
+{op: "add_move", path: [0, 0], san: "Nc3"}   // variation branching after move 2; lands at [0, 0, 1]
+{op: "add_move", path: [0, 0, 1], san: "d5"} // continue the variation; lands at [0, 0, 1, 0]
+```
 
 ## Variations vs prose
 
@@ -56,6 +81,7 @@ Prose is NEVER for:
 - Move sequences ("then Nf3, then Bg5, ...") — use variations.
 - Move recommendations ("here White should play h4") — add_move it.
 - Restating the eval a NAG already conveys.
+- **Describing a sibling variation you already added as a branch.** If move A has variation B added as `add_move(A, sibling)`, don't ALSO write `{if B then ...}` on A. The reader clicks B on the board — the branch is already there.
 
 ## Move-judgment symbols (NAGs)
 
@@ -96,9 +122,16 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 | `\|eval\| ≥ 1.3`          | `$18` (+−)              | `$19` (−+)              |
 | Sharp, hard to evaluate | `$13` (∞)               | `$13` (∞)               |
 
-**Don't paste raw engine numbers into comments.** `{Stockfish gives +0.35}` is noise — `$14` is the signal. Same for `{Lc0 says +0.15}`.
+**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
+- Bad: `{Stockfish depth 22 shows +0.25, Lc0 depth 18 shows +0.4, both engines agree}` — verbose noise
 
-**Don't name the engine unless it adds signal.** Naming Stockfish adds nothing to a `$14` on a routine position. Naming it makes sense when there's a mismatch worth flagging: `$14 {Human predictor gives 47% win at 2200 vs 2600 — the Elo gap does the practical work.}`
+**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.}`
 
 ### When prose ADDS to the NAG
 

package/package.json

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