@chessceo/mcp 0.19.0 → 0.24.0

package/dist/index.js

@@ -12,6 +12,10 @@ import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 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 { PathError } from "./pgn/paths.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -36,6 +40,7 @@ function loadBundledDoc(filename, fallbackLabel) {
 const ENGINE_USAGE_DOC = loadBundledDoc("engine-usage.md", "Engine usage guide");
 const PREP_STRATEGY_DOC = loadBundledDoc("prep-strategy.md", "Prep strategy guide");
 const PREP_FILES_DOC = loadBundledDoc("prep-files-guide.md", "Prep files guide");
+const PGN_AUTHORING_DOC = loadBundledDoc("pgn-authoring.md", "PGN authoring guide");
 // ── HTTP ────────────────────────────────────────────────────────────
 //
 // Two auth flavours coexist:
@@ -63,8 +68,16 @@ const AUTHED_TOOLS = new Set([
     "search_prep_files",
     "read_prep_file",
     "create_prep_file",
-    "save_prep_file",
     "delete_prep_file",
+    "add_move",
+    "set_comment",
+    "set_nags",
+    "set_annotations",
+    "delete_subtree",
+    "promote_variation",
+    "set_tag",
+    "apply_mutations",
+    "auto_evaluate",
     "predict_human_move",
 ]);
 function isAuthedToolCall(body) {
@@ -241,35 +254,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" +
@@ -457,7 +441,8 @@ const TOOLS = [
     },
     {
         name: "read_prep_file",
-        description: "Read one prep file. Returns the full PGN text and a compact tree JSON of the mainline (SAN + FEN per move) for programmatic reasoning. Also carries the `version` field you need to pass back to save_prep_file for the optimistic-lock check.",
+        description: "Read one prep file. Returns a compact tree (path-addressable, one node per move) plus tags and the `version` for optimistic locking on subsequent mutations. NO raw PGN — all edits go through the mutation tools (add_move / set_comment / set_nags / set_annotations / delete_subtree / promote_variation / set_tag), which validate SAN and structure for you.\n\n" +
+            "Path addressing: paths are arrays of child indices. `[]` = root position. `[0]` = the first mainline move. `[0, 1]` = the second variation branching after the first move. `[0, 0, 0]` = three plies deep on the mainline. Every mutation returns the effective path it landed at.",
         inputSchema: {
             type: "object",
             properties: {
@@ -468,55 +453,200 @@ const TOOLS = [
     },
     {
         name: "create_prep_file",
-        description: "Create a new prep file. `name` becomes the Event PGN tag (user-facing label). Optional `pgn` seeds the file — if omitted, a minimal empty PGN is written and you can save_prep_file into it later.\n\n" +
-            "ALWAYS run list_prep_files (or search_prep_files with the opponent / opening keyword) BEFORE creating, so you don't duplicate an existing file. If a file already exists that fits, extend it via save_prep_file instead.",
+        description: "Create a new (empty) prep file. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
+            "ALWAYS call list_prep_files (or search_prep_files with the opponent / opening keyword) FIRST — creating a duplicate 'Prep vs Firouzja' when one exists is the #1 LLM failure mode. If a file already covers the topic, add moves to that one instead.",
         inputSchema: {
             type: "object",
             properties: {
                 name: {
                     type: "string",
-                    description: "User-facing name for the file — becomes the [Event] tag in the PGN. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
-                },
-                pgn: {
-                    type: "string",
-                    description: "Optional initial PGN content. Supports full PGN with headers and parenthesised variations. If omitted, an empty PGN is created.",
+                    description: "User-facing name — becomes the [Event] tag. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
                 },
             },
             required: ["name"],
         },
     },
     {
-        name: "save_prep_file",
-        description: "Save (replace) a prep file's PGN content. Optimistic-lock via `expected_version` — pass the `version` you got from read_prep_file. If someone else (user in the app, or another agent session) updated the file since you read it, save returns 409 with the current version — re-read and merge.\n\n" +
-            "PGN structure guidance:\n" +
-            "- Keep the mainline clean (your top recommendation).\n" +
-            "- Alternative candidates go in parenthesised variations at the branching move.\n" +
-            "- Attach one-sentence commentary at key branch points using PGN {curly-brace comments}. Cite the actual tool output ('Lc0 gives +0.15 in this line') — don't dress the file up with unsourced chess prose.\n" +
-            "- Use PGN NAGs for evaluations: $1 !, $2 ?, $3 !!, $4 ??, $6 =, $10 = (equal), $14 +/= (slight edge), etc. Optional but nice.",
+        name: "delete_prep_file",
+        description: "Soft-delete a prep file. User can restore from the app's recycle bin. Rare — usually you extend or edit instead.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id." },
-                pgn: { type: "string", description: "Full replacement PGN (headers + moves)." },
-                expected_version: {
-                    type: "integer",
-                    description: "The `version` you got from read_prep_file. If omitted, no optimistic check runs (last-write-wins — riskier).",
-                },
             },
-            required: ["id", "pgn"],
+            required: ["id"],
         },
     },
     {
-        name: "delete_prep_file",
-        description: "Soft-delete a prep file. The user can restore it from the chess.ceo app's recycle bin if you deleted something valuable. Rare — usually you extend or replace instead.",
+        name: "add_move",
+        description: "Append a move as a new child of the node at `path`. If the node already has children, the new move becomes a variation (appended at the end). Use promote_variation afterwards if you want it to be the mainline. SAN is validated against the position — illegal moves are rejected with a clear error.\n\n" +
+            "Auto-saves. Returns `{path, version}` — the effective path the new node landed at (which you pass to follow-up set_comment / set_nags / etc.) and the new file version for optimistic locking on your next mutation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+                path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Path to the parent node the move is played FROM." },
+                san: { type: "string", description: "The move in SAN notation (e.g. 'Nf3', 'exd5', 'O-O', 'Qxf7+')." },
+                expected_version: { type: "integer", description: "Optimistic-lock check; pass the `version` from your last read." },
+            },
+            required: ["id", "path", "san"],
+        },
+    },
+    {
+        name: "set_comment",
+        description: "Set (or clear, with empty string) the text comment on the node at `path`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id." },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                comment: { type: "string", description: "New comment text. Empty string clears." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path", "comment"],
+        },
+    },
+    {
+        name: "set_nags",
+        description: "Replace the list of NAGs on the node at `path`. Empty array clears them. See read_pgn_authoring_guide for the full NAG table and eval→NAG thresholds (|eval|<0.25 → $10; <0.6 → $14/$15; <1.3 → $16/$17; ≥1.3 → $18/$19). Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                nags: { type: "array", items: { type: "string", pattern: "^\\$\\d+$" }, description: "NAG list, e.g. ['$14'] or ['$146', '$44']." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path", "nags"],
+        },
+    },
+    {
+        name: "set_annotations",
+        description: "Replace the visual annotations (arrows + coloured squares) on the node at `path`. Passing empty arrays clears them.\n\n" +
+            "Colours: green, red, yellow, light-blue, dark-blue, orange. Keep it LIGHT: 1-3 arrows and 2-3 squares per move maximum. Twenty arrows is noise, not signal. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                arrows: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            color: { type: "string", enum: ["green", "red", "yellow", "light-blue", "dark-blue", "orange"] },
+                            from: { type: "string", pattern: "^[a-h][1-8]$" },
+                            to: { type: "string", pattern: "^[a-h][1-8]$" },
+                        },
+                        required: ["color", "from", "to"],
+                    },
+                },
+                highlights: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            color: { type: "string", enum: ["green", "red", "yellow", "light-blue", "dark-blue", "orange"] },
+                            square: { type: "string", pattern: "^[a-h][1-8]$" },
+                        },
+                        required: ["color", "square"],
+                    },
+                },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path"],
+        },
+    },
+    {
+        name: "delete_subtree",
+        description: "Delete the node at `path` and all its descendants. Refuses to delete the root. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 } },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "path"],
+        },
+    },
+    {
+        name: "promote_variation",
+        description: "Make the node at `path` its parent's mainline (children[0]), demoting the current mainline (and any other siblings) into variation order. Silently no-op if already the mainline. Auto-saves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                path: { type: "array", items: { type: "integer", minimum: 0 }, description: "Path to the node to promote. Length ≥ 1." },
+                expected_version: { type: "integer" },
+            },
+            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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                key: { type: "string", description: "Tag key, e.g. 'Event', 'White', 'Date'." },
+                value: { type: "string", description: "Tag value. Empty string removes the tag." },
+                expected_version: { type: "integer" },
+            },
+            required: ["id", "key", "value"],
+        },
+    },
     {
         name: "read_engine_usage_guide",
         description: "Returns the full chess.ceo engine-usage guide: when to trust Stockfish (objective truth) vs Lc0 (practical eval), how to read disagreements between them, and how to use Lc0 contempt to find non-objective 'practical' ideas. Call this ONCE per session before running expensive `cloud_analyse` calls or when the user asks WHY the engines gave certain scores. Same content is also available as the `engine_usage_primer` prompt (for clients that surface prompts as slash commands), but many clients do not expose prompts to the model — this tool works everywhere.",
@@ -529,7 +659,12 @@ const TOOLS = [
     },
     {
         name: "read_prep_files_guide",
-        description: "Returns the full guide on how to store prep in the user's chess.ceo account via list_prep_files / read_prep_file / create_prep_file / save_prep_file / delete_prep_file. Covers: how to structure a repertoire PGN (mainline + variations + comments + NAGs), the critical 'search-before-create' habit to avoid duplicates, optimistic-locking with `version`, and how to write comments that cite tool output instead of inventing chess prose. Call this ONCE per session before your first create_prep_file / save_prep_file call.",
+        description: "Returns the guide to the prep-files FEATURE — how the storage works, when to list vs search vs create, optimistic locking with `version`, and naming conventions for the [Event] tag. Call this ONCE per session before your first create_prep_file. For how to actually WRITE PGN (mainline, variations, NAGs, arrows, comments) call read_pgn_authoring_guide instead — separate concern.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "read_pgn_authoring_guide",
+        description: "Returns the guide on how to write correct, useful PGN — mainline discipline, variations as moves (never prose describing moves), NAG symbols including novelty ($146), unclear ($13), compensation ($44) and the standard set, ChessBase arrow/coloured-square syntax ([%cal] / [%csl]), and common pitfalls the parser will reject. Call this ONCE per session before any save_prep_file call, or any time you're producing PGN output for the user.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -605,20 +740,6 @@ 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);
-        }
-    }
-    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.
 function convertCloudSnapshotResponse(raw, startFen) {
@@ -639,23 +760,217 @@ function convertCloudSnapshotResponse(raw, startFen) {
     }
     return raw;
 }
-function pgnToTree(pgn) {
-    try {
-        const board = new Chess();
-        // chess.js loadPgn accepts full PGN incl. tags; loadPgn returns true on
-        // success or throws on newer versions. Wrap defensively.
-        board.loadPgn(pgn);
-        // history({verbose:true}) walks the mainline only; variations aren't
-        // exposed by chess.js's built-in PGN loader at time of writing. If the
-        // PGN carries parenthesised variations they get flattened.
-        const hist = board.history({ verbose: true });
-        if (hist.length === 0)
-            return [];
-        return hist.map(h => ({ san: h.san, fen: h.after }));
+// Path arg parsing for the mutation tools. Rejects malformed input
+// with a clear message the LLM can act on.
+function argPath(args) {
+    const raw = args.path;
+    if (!Array.isArray(raw))
+        throw new Error("`path` must be an array of non-negative integers");
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const n = raw[i];
+        if (typeof n !== "number" || !Number.isInteger(n) || n < 0) {
+            throw new Error(`path[${i}] must be a non-negative integer (got ${JSON.stringify(n)})`);
+        }
+        out.push(n);
     }
-    catch {
+    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 "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,
+// convert the SF score to a NAG per the standard thresholds, and apply
+// everything in one batch mutation. Uses batching to avoid N saves.
+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.nags && node.nags.length > 0)) {
+                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's WS connection cap (single-client per port).
+    const nags = [];
+    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 nag = analysisToNag(analysis);
+                if (nag)
+                    nags.push({ path: t.path, nag });
+            }
+            catch {
+                // ignore per-node failures — best-effort auto-annotation
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
+    if (nags.length === 0)
+        return { ok: true, evaluated: 0, skipped: targets.length, version: g.version };
+    // Apply all NAGs as a single batch.
+    const batchMutations = nags.map(n => ({ op: "set_nags", path: n.path, nags: [n.nag] }));
+    const saveResult = await applyBatchMutations({ id, mutations: batchMutations, expected_version: g.version });
+    const sr = saveResult;
+    return { ok: true, evaluated: nags.length, skipped: targets.length - nags.length, version: sr.version };
+}
+// 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 Stockfish's rank-1 line, convert to White-POV centipawns, and
+// bucket into a NAG per the standard threshold table. Returns null if
+// the response shape doesn't carry a usable score.
+function analysisToNag(analysis) {
+    if (!analysis || typeof analysis !== "object")
         return null;
+    const r = analysis;
+    const line = r.stockfish?.lines?.[0];
+    if (!line)
+        return null;
+    // Determine side to move from the FEN so we can convert side-to-move
+    // POV score to White POV.
+    const whiteToMove = typeof r.fen === "string" && / w /.test(r.fen);
+    let cp;
+    if (typeof line.mate === "number") {
+        cp = line.mate > 0 ? 10000 : -10000;
+    }
+    else if (typeof line.scoreCp === "number") {
+        cp = line.scoreCp;
+    }
+    else {
+        return null;
+    }
+    if (!whiteToMove)
+        cp = -cp;
+    const abs = Math.abs(cp);
+    if (abs < 25)
+        return "$10";
+    if (abs < 60)
+        return cp > 0 ? "$14" : "$15";
+    if (abs < 130)
+        return cp > 0 ? "$16" : "$17";
+    return cp > 0 ? "$18" : "$19";
+}
+// 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.
+async function applyMutation(args, mutator) {
+    const id = String(args.id);
+    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);
+    let result;
+    try {
+        result = mutator(file);
+    }
+    catch (err) {
+        if (err instanceof MutationError || err instanceof PathError) {
+            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 authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
+        pgn: newPgn,
+        expected_version: expected,
+    });
+    const savedRow = saved;
+    return {
+        ok: true,
+        path: result.path,
+        version: savedRow.version,
+    };
 }
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
@@ -779,16 +1094,6 @@ async function callToolInner(name, args) {
             });
             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);
-        }
         case "predict_human_move": {
             const fen = resolveFenFromArgs(args);
             const qs = new URLSearchParams();
@@ -849,35 +1154,58 @@ async function callToolInner(name, args) {
             return authedRequest("GET", `/api/agent/prep-files/search?q=${encodeURIComponent(String(args.query))}`);
         case "read_prep_file": {
             const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
-            // MCP layer adds the tree JSON view — backend stays pure PGN in/out.
-            // If parse fails the LLM still has the raw PGN text to work with.
-            if (raw && typeof raw === "object") {
-                const g = raw;
-                if (typeof g.pgnContent === "string") {
-                    const tree = pgnToTree(g.pgnContent);
-                    return { ...raw, tree };
-                }
-            }
-            return raw;
+            const g = raw;
+            if (typeof g.pgnContent !== "string")
+                throw new Error("prep file missing pgnContent");
+            const file = parsePGN(g.pgnContent);
+            return {
+                id: g.id,
+                version: g.version,
+                tags: file.tags,
+                tree: file.root,
+            };
         }
         case "create_prep_file":
             return authedRequest("POST", "/api/agent/prep-files", {
                 name: String(args.name),
-                pgn: typeof args.pgn === "string" ? args.pgn : undefined,
-            });
-        case "save_prep_file":
-            return authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`, {
-                pgn: String(args.pgn),
-                expected_version: typeof args.expected_version === "number" ? args.expected_version : undefined,
             });
         case "delete_prep_file":
             return authedRequest("DELETE", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
+        case "add_move":
+            return applyMutation(args, file => addMove(file, argPath(args), String(args.san)));
+        case "set_comment":
+            return applyMutation(args, file => setComment(file, argPath(args), typeof args.comment === "string" ? args.comment : ""));
+        case "set_nags":
+            return applyMutation(args, file => setNags(file, argPath(args), Array.isArray(args.nags) ? args.nags.map(String) : []));
+        case "set_annotations": {
+            const arrowsRaw = Array.isArray(args.arrows) ? args.arrows : [];
+            const highlightsRaw = Array.isArray(args.highlights) ? args.highlights : [];
+            const ann = (arrowsRaw.length === 0 && highlightsRaw.length === 0)
+                ? null
+                : { arrows: arrowsRaw, highlights: highlightsRaw };
+            return applyMutation(args, file => setAnnotations(file, argPath(args), ann));
+        }
+        case "delete_subtree":
+            return applyMutation(args, file => deleteSubtree(file, argPath(args)));
+        case "promote_variation":
+            return applyMutation(args, file => promoteVariation(file, argPath(args)));
+        case "set_tag":
+            return applyMutation(args, file => ({
+                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":
             return { guide: PREP_STRATEGY_DOC };
         case "read_prep_files_guide":
             return { guide: PREP_FILES_DOC };
+        case "read_pgn_authoring_guide":
+            return { guide: PGN_AUTHORING_DOC };
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);