@chessceo/mcp 0.24.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";
@@ -188,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" +
@@ -229,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: {
@@ -669,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: {
@@ -740,6 +743,17 @@ function uciMoveToSAN(startFen, uci) {
         return uci;
     }
 }
+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;
+    }
+}
 // 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) {
@@ -794,6 +808,10 @@ function dispatchMutation(file, op) {
             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":
@@ -839,8 +857,10 @@ async function applyBatchMutations(args) {
     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.
+// 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 : [];
@@ -854,7 +874,7 @@ async function autoEvaluate(args) {
     const targets = [];
     const walk = (node, path) => {
         if (path.length > 0) {
-            if (!onlyMissing || !(node.nags && node.nags.length > 0)) {
+            if (!onlyMissing || !node.ceoEval) {
                 targets.push({ path, fen: node.fen });
             }
         }
@@ -866,8 +886,8 @@ async function autoEvaluate(args) {
     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 = [];
+    // over-saturate the engine-ws connection cap (single-client per port).
+    const stored = [];
     const CONCURRENCY = 4;
     let cursor = 0;
     async function worker() {
@@ -876,23 +896,27 @@ async function autoEvaluate(args) {
             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 });
+                const ev = analysisToStoredEval(analysis, t.fen);
+                if (ev)
+                    stored.push({ path: t.path, ev });
             }
             catch {
-                // ignore per-node failures — best-effort auto-annotation
+                // best-effort — a single failed node shouldn't kill the batch
             }
         }
     }
     await Promise.all(Array.from({ length: CONCURRENCY }, () => worker()));
-    if (nags.length === 0)
+    if (stored.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 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: nags.length, skipped: targets.length - nags.length, version: sr.version };
+    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) {
@@ -905,39 +929,81 @@ function pathIntoTree(root, path) {
     }
     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) {
+// 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 line = r.stockfish?.lines?.[0];
-    if (!line)
+    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;
-    // 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 {
+    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;
-    }
-    if (!whiteToMove)
-        cp = -cp;
-    const abs = Math.abs(cp);
+    const abs = Math.abs(effective);
     if (abs < 25)
         return "$10";
     if (abs < 60)
-        return cp > 0 ? "$14" : "$15";
+        return effective > 0 ? "$14" : "$15";
     if (abs < 130)
-        return cp > 0 ? "$16" : "$17";
-    return cp > 0 ? "$18" : "$19";
+        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;
@@ -1082,17 +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);
+            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);
@@ -1241,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

@@ -124,6 +124,8 @@ Engine numbers go into the NAG, not into prose. Convert the eval to the correct
 
 **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.24.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": {