@chessceo/mcp 0.33.1 → 0.34.0

package/dist/index.js

@@ -89,6 +89,9 @@ const AUTHED_TOOLS = new Set([
     "auto_evaluate",
     "auto_evaluate_status",
     "auto_evaluate_cancel",
+    "deep_analyse",
+    "deep_analyse_status",
+    "deep_analyse_cancel",
     "quote_engine_eval",
     "predict_human_move",
     "prepare_opponent",
@@ -508,6 +511,11 @@ const TOOLS = [
                     maximum: 100,
                     description: "Lc0 contempt bias. Signed 0-100 strength (same scale as the web UI's ContemptStrength slider — server multiplies by 8 to get the internal cp bias). 0 = objective (default). Positive favours White, negative favours Black. Typical: ±15 light nudge, ±30-60 real fighting play, ±80-100 maximum steer. Not applied to Stockfish. See engine_usage_primer for when to use.",
                 },
+                engines: {
+                    type: "array",
+                    items: { type: "string", enum: ["stockfish", "lc0"] },
+                    description: "Which engines to run. Default = both. Use `[\"lc0\"]` to skip Stockfish (e.g. while a deep_analyse job is holding the SF slot on the same combo). Use `[\"stockfish\"]` when only the objective read matters. The skipped engine's field is omitted from the response.",
+                },
             },
         },
     },
@@ -763,6 +771,56 @@ const TOOLS = [
             required: ["job_id"],
         },
     },
+    {
+        name: "deep_analyse",
+        description: "Start a long Stockfish think on a single position (up to 5 min movetime). Returns a `job_id` immediately; poll `deep_analyse_status(job_id)` for the result, cancel with `deep_analyse_cancel(job_id)`. Runs SF only — Lc0 doesn't benefit from long thinks past a handful of seconds — and **holds only the SF engine slot on the combo, so `cloud_analyse(..., engines: [\"lc0\"])` stays available for other work in parallel**.\n\n" +
+            "Use this when a specific critical position deserves depth — a novelty candidate, a hairy tactical shot, a difficult endgame — and you want Stockfish at depth 35+ rather than the ~depth 22 you get from a 2s cloud_analyse. Movetime is in ms; typical: 30_000-60_000 for 'careful check', 120_000-300_000 for 'find the truth'.\n\n" +
+            "Result shape when done matches cloud_analyse's Stockfish leg (depth, top-N candidates with scoreCp/mate, best move, PV). Auto-stores the eval on `file_id`+`node_id` when both are supplied, same as cloud_analyse.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_id: { type: "string", description: "Prep file id. Combine with `node_id` to derive FEN from the tree AND persist the result on the node's ceoEval." },
+                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`/`moves`." },
+                fen: { type: "string", description: "Position as FEN. Only used if `node_id` is not set." },
+                moves: { type: "string", description: "Optional SAN moves on top of `fen`. Only used if `node_id` is not set." },
+                movetime_ms: {
+                    type: "integer",
+                    minimum: 5_000,
+                    maximum: 300_000,
+                    description: "Think time in ms. Default 60_000 (1 min). Max 300_000 (5 min).",
+                },
+                multipv: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Number of candidate lines (default 3).",
+                },
+            },
+        },
+    },
+    {
+        name: "deep_analyse_status",
+        description: "Poll a deep_analyse job. Response: `{ status: 'running' | 'done' | 'cancelled' | 'error' | 'not_found', elapsed_ms, movetime_ms, result?, error? }`. `result` shape when done: `{ engine, depth, timeMs, bestMove, lines: [{rank, depth, scoreCp?, mate?, pv, nodes?}] }` — the SF leg of a cloud_analyse response.\n\n" +
+            "Poll cadence: every ~15-30s for long thinks; there's no penalty for polling more often but the engine progresses at its own pace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from `deep_analyse`." },
+            },
+            required: ["job_id"],
+        },
+    },
+    {
+        name: "deep_analyse_cancel",
+        description: "Ask a running deep_analyse job to stop early. The engine returns whatever it's found so far as the final result. Useful when a partial result at depth 25 is enough and you don't want to wait for depth 40. Idempotent for already-finished jobs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                job_id: { type: "string", description: "Job id from `deep_analyse`." },
+            },
+            required: ["job_id"],
+        },
+    },
     {
         name: "quote_engine_eval",
         description: "Return the stored engine eval for a node, or null if that node was never analysed. **Call this before writing prose or NAGs that quote engine numbers** — if it returns null, you have no measurement to cite. Do NOT infer an eval for the node from siblings or children; either analyse it (cloud_analyse with node_id) or omit the number from your prose.\n\n" +
@@ -1230,6 +1288,141 @@ function autoEvaluateCancel(args) {
     // inside runEvalJob, after the final flush persists progress.
     return { status: "cancelling", evaluated_so_far: job.evaluated };
 }
+const deepJobs = new Map();
+const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
+function newDeepJobId() {
+    const rand = Math.random().toString(16).slice(2, 8);
+    return `deep_${Date.now().toString(16)}${rand}`;
+}
+function reapExpiredDeepJobs() {
+    const now = Date.now();
+    for (const [k, j] of deepJobs) {
+        if (j.finishedAt && now - j.finishedAt > DEEP_JOB_TTL_MS) {
+            deepJobs.delete(k);
+        }
+    }
+}
+async function deepAnalyseStart(args) {
+    reapExpiredDeepJobs();
+    const resolved = await resolveFromNodeOrFen(args);
+    const fen = resolved.fen;
+    const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 60_000;
+    const multipv = typeof args.multipv === "number" ? args.multipv : 3;
+    const jobId = newDeepJobId();
+    const job = {
+        id: jobId,
+        status: "running",
+        fileHandle: resolved.file,
+        fen,
+        movetimeMs,
+        multipv,
+        startedAt: Date.now(),
+        cancelController: new AbortController(),
+    };
+    deepJobs.set(jobId, job);
+    // Kick off the long HTTP call unawaited — resolves when the backend
+    // returns the SF snapshot. authedRequest is a plain fetch under the
+    // hood; abort signal flows via cancelController.
+    void runDeepJob(job).catch(err => {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+    });
+    return {
+        job_id: jobId,
+        status: "running",
+        movetime_ms: movetimeMs,
+        fen,
+    };
+}
+async function runDeepJob(job) {
+    const body = {
+        fen: job.fen,
+        movetime_ms: job.movetimeMs,
+        multipv: job.multipv,
+        engines: ["stockfish"],
+    };
+    let raw;
+    try {
+        // TODO(future): plumb an AbortSignal through authedRequest for
+        // real mid-flight cancellation. For now, cancel just marks the
+        // job so the caller stops polling; the backend still runs the
+        // engine to completion and the result is stored on the job
+        // record but flagged cancelled.
+        raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+    }
+    catch (err) {
+        job.status = "error";
+        job.error = err instanceof Error ? err.message : String(err);
+        job.finishedAt = Date.now();
+        return;
+    }
+    const converted = convertCloudSnapshotResponse(raw, job.fen);
+    const sf = converted.stockfish;
+    if (job.cancelController.signal.aborted) {
+        job.status = "cancelled";
+    }
+    else {
+        job.status = "done";
+    }
+    job.result = sf ?? null;
+    job.finishedAt = Date.now();
+    // Same node-persistence as cloud_analyse: if the caller anchored on
+    // file_id+node_id, store the SF-only eval as the node's ceoEval so
+    // quote_engine_eval can cite it later. We build a StoredEval that has
+    // only the sf leg — no Lc0 was run.
+    if (job.fileHandle && sf) {
+        const ev = analysisToStoredEval({ stockfish: sf }, job.fen);
+        if (ev) {
+            try {
+                await storeEvalOnNode(job.fileHandle, ev);
+            }
+            catch {
+                // best-effort — the analysis result is what the LLM asked for
+            }
+        }
+    }
+}
+function deepAnalyseStatus(args) {
+    reapExpiredDeepJobs();
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job) {
+        return {
+            status: "not_found",
+            note: "Job unknown — expired (kept ~15 min after completion), never existed, or the MCP process restarted.",
+        };
+    }
+    return {
+        job_id: job.id,
+        status: job.status,
+        movetime_ms: job.movetimeMs,
+        elapsed_ms: (job.finishedAt ?? Date.now()) - job.startedAt,
+        fen: job.fen,
+        result: job.result,
+        error: job.error,
+        started_at_ms: job.startedAt,
+        finished_at_ms: job.finishedAt,
+    };
+}
+function deepAnalyseCancel(args) {
+    const jobId = String(args.job_id || "").trim();
+    if (!jobId)
+        throw new Error("`job_id` is required");
+    const job = deepJobs.get(jobId);
+    if (!job)
+        return { status: "not_found" };
+    if (job.status !== "running") {
+        return { status: job.status, note: "Job already finished; nothing to cancel." };
+    }
+    job.cancelController.abort();
+    // Status flips to "cancelled" when runDeepJob observes the abort on
+    // completion. Backend keeps churning until movetime elapses (mid-
+    // flight abort of the HTTP call is a follow-up).
+    return { status: "cancelling", elapsed_ms: Date.now() - job.startedAt };
+}
 // Walk chess.js-free: resolve a path against a tree, throw if invalid.
 function pathIntoTree(root, path) {
     let cur = root;
@@ -1756,6 +1949,8 @@ async function callToolInner(name, args) {
                 body.multipv = args.multipv;
             if (typeof args.contempt === "number")
                 body.contempt = args.contempt;
+            if (Array.isArray(args.engines))
+                body.engines = args.engines;
             const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
             const converted = convertCloudSnapshotResponse(raw, fen);
             // Node-addressed calls: persist the result on the node's ceoEval
@@ -1771,6 +1966,12 @@ async function callToolInner(name, args) {
             }
             return converted;
         }
+        case "deep_analyse":
+            return deepAnalyseStart(args);
+        case "deep_analyse_status":
+            return deepAnalyseStatus(args);
+        case "deep_analyse_cancel":
+            return deepAnalyseCancel(args);
         case "list_prep_files":
             return authedRequest("GET", "/api/agent/prep-files");
         case "search_prep_files":

package/docs/engine-usage.md

@@ -103,6 +103,31 @@ The gap (1.4 - 0.2 = 1.2) is roughly the value of the tempo Black has to spend d
 
 **Gotcha:** flipping side-to-move invalidates the en passant target field (if the last move was a two-square pawn push, the ep square is now stale). Also, both sides are counted as still having whichever castling rights are in the FEN — don't do this in the middle of a castling sequence. For opening / middlegame threat-checking it's a very useful idiom.
 
+## Deep Stockfish thinks: `deep_analyse`
+
+`cloud_analyse` runs both engines with a movetime cap of 10 s — deliberately fast because most opening-tree questions are answered in 2–3 s. For **one specific critical position** where you want depth 35+ instead of the usual depth 22, use `deep_analyse`:
+
+- SF-only (Lc0 saturates in a handful of seconds — no benefit past ~5 s of movetime).
+- Movetime up to 5 min.
+- Async: returns a `job_id` immediately, poll `deep_analyse_status(job_id)`, cancel with `deep_analyse_cancel(job_id)` if you decide partial depth is enough.
+- **Holds only the Stockfish slot on the combo.** Lc0 remains callable for other positions via `cloud_analyse({ engines: ["lc0"], … })` while the deep think runs. Use that during the wait — walk other branches, sanity-check candidates.
+
+Typical movetimes:
+- `30_000 – 60_000` (30–60 s) — careful check on a candidate move
+- `120_000 – 300_000` (2–5 min) — "find the truth" on a novelty, tactical shot, or difficult endgame
+
+Only use it when you actually need the depth. Regular `cloud_analyse` handles the ~5–10 branches of a typical prep walk perfectly well.
+
+## Splitting engines on `cloud_analyse`
+
+`cloud_analyse` accepts an `engines` list to run only one leg:
+
+- `engines: ["lc0"]` — Lc0 only, useful while a `deep_analyse` is holding the Stockfish slot.
+- `engines: ["stockfish"]` — SF only, when only the objective read matters and you want to skip the Lc0 latency.
+- Default (omitted) — both engines. This is what you want for real prep decisions.
+
+The skipped engine's field is omitted from the response (not present as an empty object).
+
 ## Worked example
 
 User is preparing Black against a 2600 opponent who plays 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e5. You want to know if 7.Nb3 or 7.Nf3 is more testing.

package/package.json

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