@chessceo/mcp 0.49.10 → 0.50.0

package/dist/index.js

@@ -22,10 +22,11 @@ import { TOOLS } from "./tools.js";
 import { PROMPTS } from "./prompts.js";
 import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
 import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, restoreGame, } from "./http.js";
-import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, mergeRentalAnalyses, } from "./analysis/response.js";
+import { fetchCompactEval, } from "./analysis/response.js";
+import { cloudAnalyse, ensureEngines } from "./analysis/cloud.js";
 import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
 import { deepAnalyseCancel, deepAnalyseStart, deepAnalyseStatus, } from "./analysis/deep.js";
-import { analyseRouting, getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysis/file_handle.js";
+import { getNodeByPath, resolveFromNodeOrFen, } from "./analysis/file_handle.js";
 import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
 import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
 import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
@@ -41,6 +42,8 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "ensure_engines",
+    "list_cloud_machine_options",
     "list_collections",
     "create_collection",
     "rename_collection",
@@ -125,11 +128,22 @@ const ENGINE_GUIDE = {
     stockfish: "Objective calculation, the default cloud engine at about 100 million nodes per second. A few seconds gives a very strong view of the position. Use it on every position, including when steering by lc0 or human. Its score is the objective value with best defense: 0.00 means objectively a draw with best play, not that nothing is happening or that neither side has chances. Many positions that are very hard to play for a human score 0.00. Scores drift toward 0.00 as the search deepens, especially in drawn positions. Use it to check whether a tactic is real, whether a defense holds, and whether a move loses material or the game.",
     lc0: "Neural-net engine trained on self-play games, not human games. It is better than Stockfish at long-term ideas and at judging which side is practically on top. Never gives 0.00: it always says which side prefers the position, at least a little. Use it when Stockfish gives 0.00 to see who still has the practical edge, and to find where the long-term ideas are. Contempt changes how it values a draw and which side it plays for: contempt at -20 makes Black play for a win, which is useful for finding ideas, including in openings. It is much weaker tactically than Stockfish, so confirm any concrete line with Stockfish.",
     human: "Neural net trained only on human games, about 11 million rated games. Its moves and evaluations are practical, not objective: the moves it suggests are the ones a human would find and play. It punishes dubious moves less than Stockfish, because human games contain many imperfect moves that still work in practice, so a move with a sound idea behind it can score well here. Use it to predict how a person will respond to an idea, to find ideas (it may like a move that only fails to a refutation no human would find; Stockfish shows whether that refutation exists), and to see how a human would evaluate a position, especially positional or unclear ones. Like lc0 it is weaker in very unusual positions, and its evaluations there can be trusted much less. Stockfish remains the check on tactics and on whether a practical idea is objectively sound.",
-    combo: "Runs Stockfish and Lc0 together — use when you want both the objective read and the practical/human-feel read on the same position.",
 };
 // Modern engines give equality very often, so small numbers are not "equal".
 // Rough guide, not exact thresholds. Shown alongside ENGINE_GUIDE above.
 const ENGINE_EVAL_SCALE = "Small numbers are not equality. ±0.00 to ±0.10 is equal in practice (+0.10 is '=' or '+=' at most). +0.20 to +0.40 is real pressure, not 'a bit better'. +0.50 and up is a clear advantage. Stockfish 0.00 with a plus from Lc0 is a practical edge, not equality. Check both engines before calling a position equal.";
+// How to run analysis end to end. Authed response only, with ENGINE_GUIDE.
+const ENGINE_WORKFLOW = [
+    "1. Plan: ensure_engines({engines, positions}) shows what is running, what to start, the price and an estimate. It starts nothing.",
+    "2. Ask: show the user the price of anything you would start and get a yes. Rentals bill per minute until stopped.",
+    "3. Start: start_cloud_engine({machine_type}) per missing engine. Each SKU runs one engine; the engine comes from the SKU. Wait until list_cloud_engines shows it running (static engines are instant, others ~1-5 min).",
+    "4. Analyse: cloud_analyse({fens | lines | file_id+node_ids, engines}) for up to 10 positions, each engine on its own rental, in parallel. auto_evaluate({id, engines}) for a whole file or subtree: fills only the engines each node is missing and saves as it goes. deep_analyse({engine, ...}) for one long think.",
+    "5. Read back: quote_engine_eval gives the stored sf (cp/mate), lc0 and human (win/draw/loss %) per node.",
+    "6. Stop: stop_cloud_engine when the work is done, unless the user wants it kept running.",
+].join("\n");
+// Eval symbols are the writer's call, not the engine's. Recommendation
+// only; nothing in the MCP sets a symbol automatically.
+const EVAL_SYMBOL_GUIDE = "The eval symbol (=, +=, ±, +-) is your call, written for a human reader. The engines inform it; no tool sets it for you. Stockfish 0.00 can still be += when Lc0 or the human engine clearly prefer one side, because the symbol describes the practical picture, not only the objective one. Look at all engines you ran before choosing, and don't put a symbol on a position nobody analysed.";
 // v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
 // tools into ONE `read_docs`. LLM lists what it wants; we return them
 // in a single response. Also cleaner: enumerating available docs in one
@@ -390,77 +404,26 @@ async function callToolInner(name, args) {
                 ...(resp && typeof resp === "object" ? resp : { options: [] }),
                 engine_guide: ENGINE_GUIDE,
                 eval_scale: ENGINE_EVAL_SCALE,
+                eval_symbols: EVAL_SYMBOL_GUIDE,
+                workflow: ENGINE_WORKFLOW,
             };
         }
+        case "ensure_engines":
+            return {
+                ...await ensureEngines(args),
+                engine_guide: ENGINE_GUIDE,
+                workflow: ENGINE_WORKFLOW,
+            };
         case "start_cloud_engine":
             return authedRequest("POST", "/api/agent/cloud-engines", {
                 machineType: String(args.machine_type),
-                ...(typeof args.engine_type === "string" ? { engineType: args.engine_type } : {}),
             });
         case "list_cloud_engines":
             return authedRequest("GET", "/api/agent/cloud-engines");
         case "stop_cloud_engine":
             return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
-        case "cloud_analyse": {
-            const resolved = await resolveFromNodeOrFen(args);
-            const fen = resolved.fen;
-            const body = { fen };
-            if (typeof args.movetime_ms === "number")
-                body.movetime_ms = args.movetime_ms;
-            if (typeof args.stockfish_multipv === "number")
-                body.stockfish_multipv = args.stockfish_multipv;
-            if (typeof args.lc0_multipv === "number")
-                body.lc0_multipv = args.lc0_multipv;
-            if (typeof args.contempt === "number")
-                body.contempt = args.contempt;
-            Object.assign(body, analyseRouting(args));
-            // Fan-out: several rentals analyse the same FEN in parallel, each
-            // returning the engines it runs; the results are merged into one
-            // object (first rental wins per engine field). One call, one
-            // position, any mix of rentals.
-            const fanOutIds = Array.isArray(args.contract_ids)
-                ? args.contract_ids.filter((id) => typeof id === "string" && id.trim() !== "").map((id) => id.trim())
-                : [];
-            const raw = fanOutIds.length > 1
-                ? mergeRentalAnalyses(await Promise.all(fanOutIds.map((id) => authedRequest("POST", "/api/agent/cloud-engines/analyse", { ...body, contract_id: id }))))
-                : await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
-            const converted = convertCloudSnapshotResponse(raw, fen);
-            // PV cap: engine PVs beyond ~6 plies are speculative (the tail is
-            // where the search's confidence collapses — SF at depth 24 has
-            // seen the first few plies solidly and hedged everything after).
-            // More importantly, LLMs paste long PVs into `add_line` as if
-            // they were prepared repertoire. A 15-move PV pasted as a
-            // variation is one line of engine output through positions
-            // where both sides had real choices — not a repertoire. Cap the
-            // affordance: return only what's load-bearing (3 full moves for
-            // understanding the point), let the caller re-analyse the
-            // resulting position if they want to see further. Override via
-            // `pv_max_plies` for the rare case (deep tactics verification).
-            const pvMaxPlies = typeof args.pv_max_plies === "number" && args.pv_max_plies > 0
-                ? Math.min(args.pv_max_plies, 40)
-                : 6;
-            capPvsInResponse(converted, pvMaxPlies);
-            // Node-addressed calls: persist the result on the node's ceoEval
-            // so a later quote_engine_eval can cite this measurement. This is
-            // the anti-hallucination hinge — prose that says "engines say X
-            // on node Y" can only trace back to a call actually made against
-            // node_id=Y, because the store only fires when file_id+node_id
-            // was supplied and the eval survives via the [%ceo-eval] escape.
-            if (resolved.file) {
-                const ev = analysisToStoredEval(converted);
-                if (ev) {
-                    const stamped = await storeEvalOnNode(resolved.file, ev);
-                    if (stamped.length > 1) {
-                        // Surface the propagation so the LLM sees exactly which
-                        // other nodes now carry this eval (and can skip them for
-                        // re-analysis).
-                        converted.also_stored_on = stamped.slice(1);
-                    }
-                }
-            }
-            converted.eval_scale = ENGINE_EVAL_SCALE;
-            return converted;
-        }
+        case "cloud_analyse":
+            return cloudAnalyse(args, ENGINE_EVAL_SCALE);
         case "deep_analyse":
             return deepAnalyseStart(args);
         case "deep_analyse_status":
@@ -571,7 +534,7 @@ async function callToolInner(name, args) {
         case "apply_mutations":
             return applyBatchMutations(args);
         case "auto_evaluate":
-            return autoEvaluate(args, applyBatchMutations);
+            return autoEvaluate(args);
         case "auto_evaluate_status":
             return autoEvaluateStatus(args);
         case "auto_evaluate_cancel":

package/dist/pgn/exporter.js

@@ -1,7 +1,7 @@
 // PrepFile → PGN text. Deterministic — same tree always exports to the
 // same PGN modulo whitespace, so paths stay stable across
 // export→reparse cycles.
-import { codeFromColor } from "./types.js";
+import { codeFromColor, STORED_EVAL_KEYS } from "./types.js";
 // Standard PGN "seven tag roster" order. We emit these first (in the
 // order they appear in tags), then any extra tags in insertion order.
 const STR_ORDER = ["Event", "Site", "Date", "Round", "White", "Black", "Result"];
@@ -142,22 +142,24 @@ function renderNodeAnnotation(node) {
     }
     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`.
+// Serialise a stored eval as `[%ceo-eval sf=+0.20/38 lc0=W38D45L17/24
+// human=W30D50L20/20]`. Compact: no PVs (regenerable), decimal cp for
+// readability, mate as `MN`/`-MN`, WDL as `W<w>D<d>L<l>`, 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}`);
+    for (const k of STORED_EVAL_KEYS) {
+        const e = ev[k];
+        if (e)
+            bits.push(`${k}=${formatEngineEval(e)}`);
+    }
     return bits.length > 0 ? `[%ceo-eval ${bits.join(" ")}]` : "";
 }
 function formatEngineEval(e) {
     let body;
-    if (typeof e.mate === "number") {
+    if (typeof e.w === "number" && typeof e.d === "number" && typeof e.l === "number") {
+        body = `W${e.w}D${e.d}L${e.l}`;
+    }
+    else if (typeof e.mate === "number") {
         body = e.mate >= 0 ? `+M${e.mate}` : `M${e.mate}`; // "+M5" / "M-5"
     }
     else if (typeof e.cp === "number") {

package/dist/pgn/mutations.js

@@ -12,6 +12,7 @@ import { Chess } from "chessops/chess";
 import { parseSan } from "chessops/san";
 import { makeFen } from "chessops/fen";
 import { cloneOnPath, deriveNodeId, getNode, PathError } from "./paths.js";
+import { STORED_EVAL_KEYS } from "./types.js";
 export class MutationError extends Error {
 }
 // Add a SAN move as a new child under `parentPath`. **Idempotent on
@@ -162,14 +163,26 @@ export function promoteVariation(file, path) {
     parent.children = [promoted, ...rest];
     return { file: { tags: file.tags, root: newRoot }, id: promoted.id };
 }
-// Replace the stored ceoEval on the node at `path`. Passing null clears.
-// This is what auto_evaluate / cloud_analyse(node_id) calls per-node.
+// Merge engine evals into the stored ceoEval on the node at `path`: only
+// the engines present in `ev` are replaced, the others are kept, so a
+// Stockfish deep think never wipes a stored human or Lc0 read. Passing null
+// clears every engine.
 export function setCeoEval(file, path, ev) {
     const { root: newRoot, target } = cloneOnPath(file.root, path);
-    if (ev === null || (!ev.sf && !ev.lc0 && !ev.nag))
+    if (ev === null) {
         delete target.ceoEval;
-    else
-        target.ceoEval = ev;
+    }
+    else {
+        const merged = { ...(target.ceoEval ?? {}) };
+        for (const k of STORED_EVAL_KEYS) {
+            if (ev[k])
+                merged[k] = ev[k];
+        }
+        if (merged.sf || merged.lc0 || merged.human)
+            target.ceoEval = merged;
+        else
+            delete target.ceoEval;
+    }
     return { file: { tags: file.tags, root: newRoot }, id: target.id };
 }
 // Set the same ceoEval on every path in `paths`. One clone-and-return

package/dist/pgn/parser.js

@@ -24,10 +24,17 @@ const CEO_EVAL_RE = /\[%ceo-eval\s+([^\]]+)\]/g;
 // `{[%eval] [%wdl]}` comment on an imported Lichess PGN got stripped
 // on a set_tag save cycle).
 const KNOWN_CMD_RE = /\[%(?:cal|csl|ceo-eval)\s+[^\]]+\]/g;
-// Parse a `sf=+0.20/38` or `lc0=M-5/22` fragment into its numeric parts.
-// Returns null if the value doesn't parse; the parser tolerates missing
-// depth and mate notation.
+// Parse a `sf=+0.20/38`, `sf=M-5/22` or `lc0=W38D45L17/24` fragment into
+// its numeric parts. Returns null if the value doesn't parse; depth is
+// optional.
 function parseEngineEvalFragment(raw) {
+    const wdl = raw.match(/^W(\d+)D(\d+)L(\d+)(?:\/(\d+))?$/i);
+    if (wdl) {
+        const out = { w: parseInt(wdl[1], 10), d: parseInt(wdl[2], 10), l: parseInt(wdl[3], 10) };
+        if (wdl[4] !== undefined)
+            out.depth = parseInt(wdl[4], 10);
+        return out;
+    }
     const m = raw.match(/^([+-]?)(?:M(-?\d+)|(\d+(?:\.\d+)?))(?:\/(\d+))?$/i);
     if (!m)
         return null;
@@ -75,22 +82,14 @@ export function parseCommentAnnotations(comment) {
                 continue;
             const k = entry.slice(0, eq).toLowerCase();
             const v = entry.slice(eq + 1);
-            if (k === "sf") {
+            if (k === "sf" || k === "lc0" || k === "human") {
                 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;
+                    ev[k] = parsed;
             }
+            // Anything else (incl. the pre-0.50 `nag=`) is dropped.
         }
-        if (ev.sf || ev.lc0 || ev.nag)
+        if (ev.sf || ev.lc0 || ev.human)
             ceoEval = ev;
     }
     const text = comment.replace(KNOWN_CMD_RE, "").replace(/\s+/g, " ").trim();

package/dist/pgn/types.js

@@ -19,6 +19,8 @@
 // width, buildIdIndex keeps the first occurrence and logs to stderr
 // rather than throwing — the file stays readable, only mutations
 // against the collided id are ambiguous.
+// Keys of StoredEval in canonical order.
+export const STORED_EVAL_KEYS = ["sf", "lc0", "human"];
 // Named colours as they appear in the parsed tree. The wire format uses
 // single-letter codes (G, R, Y, C, B, O); the tree uses these longer
 // names to match how the frontend represents them.