@chessceo/mcp 0.23.0 → 0.24.0

package/dist/index.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) {
@@ -252,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" +
@@ -610,6 +583,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.",
@@ -717,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) {
@@ -767,6 +776,169 @@ 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 "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.
@@ -922,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();
@@ -1032,6 +1194,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":

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).
+
+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.
 
-Every step returns the new `version`; carry it forward.
+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,14 @@ 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).
+
+**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.24.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {