@chessceo/mcp 0.49.6 → 0.49.8

package/dist/analysis/auto.js

@@ -24,6 +24,7 @@
 // a mid-run crash / cancellation doesn't lose the whole walk.
 import { authedRequest, fetchGame } from "../http.js";
 import { analysisToStoredEval } from "./response.js";
+import { analyseRouting } from "./file_handle.js";
 import { parsePGN } from "../pgn/parser.js";
 import { buildIdIndex, positionKey, resolveNodeId, ROOT_ID } from "../pgn/paths.js";
 const evalJobs = new Map();
@@ -146,7 +147,7 @@ export async function autoEvaluate(args, applyBatchMutations) {
     // Unawaited — runs concurrently with the tool response. Any thrown
     // error gets recorded on the job so the LLM's status poll surfaces
     // it instead of the process seeing an unhandled rejection.
-    void runEvalJob(job, id, targets, movetimeMs, applyBatchMutations).catch(err => {
+    void runEvalJob(job, id, targets, movetimeMs, applyBatchMutations, analyseRouting(args)).catch(err => {
         job.status = "error";
         job.error = err instanceof Error ? err.message : String(err);
         job.finishedAt = Date.now();
@@ -167,7 +168,7 @@ export async function autoEvaluate(args, applyBatchMutations) {
 // against the per-combo semaphore in the backend anyway), checkpoints
 // every SAVE_EVERY_N successfully-evaluated nodes so partial progress
 // is durable, and re-anchors the version after each save.
-async function runEvalJob(job, fileId, targets, movetimeMs, applyBatchMutations) {
+async function runEvalJob(job, fileId, targets, movetimeMs, applyBatchMutations, routing) {
     const pending = [];
     const flush = async () => {
         if (pending.length === 0)
@@ -196,7 +197,7 @@ async function runEvalJob(job, fileId, targets, movetimeMs, applyBatchMutations)
         if (job.cancelled || aborted)
             break;
         try {
-            const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
+            const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1, ...routing });
             const ev = analysisToStoredEval(analysis);
             if (ev) {
                 pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });

package/dist/analysis/deep.js

@@ -16,7 +16,7 @@
 // Extracted from index.ts in v0.44 as part of the file split.
 import { authedRequest } from "../http.js";
 import { analysisToStoredEval, convertCloudSnapshotResponse } from "./response.js";
-import { resolveFromNodeOrFen, storeEvalOnNode, } from "./file_handle.js";
+import { analyseRouting, resolveFromNodeOrFen, storeEvalOnNode, } from "./file_handle.js";
 const deepJobs = new Map();
 const DEEP_JOB_TTL_MS = 15 * 60 * 1000;
 function newDeepJobId() {
@@ -43,6 +43,7 @@ export async function deepAnalyseStart(args) {
     const jobId = newDeepJobId();
     const job = {
         id: jobId,
+        routing: analyseRouting(args),
         status: "running",
         fileHandle: resolved.file,
         fen,
@@ -73,6 +74,7 @@ async function runDeepJob(job) {
         movetime_ms: job.movetimeMs,
         stockfish_multipv: job.multipv,
         engines: ["stockfish"],
+        ...job.routing,
     };
     let raw;
     try {

package/dist/analysis/file_handle.js

@@ -154,3 +154,14 @@ export async function storeEvalOnNode(handle, ev) {
         return [];
     }
 }
+// Routing fields for POST /api/agent/cloud-engines/analyse: which rental to
+// run on and which engine legs to run. Omitted fields let the backend pick.
+export function analyseRouting(args) {
+    const out = {};
+    if (typeof args.contract_id === "string" && args.contract_id.trim()) {
+        out.contract_id = args.contract_id.trim();
+    }
+    if (Array.isArray(args.engines))
+        out.engines = args.engines;
+    return out;
+}

package/dist/index.js

@@ -25,7 +25,7 @@ import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, res
 import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, } from "./analysis/response.js";
 import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
 import { deepAnalyseCancel, deepAnalyseStart, deepAnalyseStatus, } from "./analysis/deep.js";
-import { getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysis/file_handle.js";
+import { analyseRouting, getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } 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";
@@ -412,8 +412,7 @@ async function callToolInner(name, args) {
                 body.lc0_multipv = args.lc0_multipv;
             if (typeof args.contempt === "number")
                 body.contempt = args.contempt;
-            if (Array.isArray(args.engines))
-                body.engines = args.engines;
+            Object.assign(body, analyseRouting(args));
             const raw = 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

package/dist/tools.js

@@ -75,7 +75,7 @@ export const TOOLS = [
         name: "get_prep_position",
         description: "Query one position within a prep session created by `prepare_opponent`. Returns move statistics (frequency + win rate + last-played date per move) plus the actual games played from that position, in one call.\n\n" +
             "Position input: prefer `file_id`+`node_id` when inside a prep file (server derives FEN from the tree). Otherwise pass `fen`.\n\n" +
-            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` (Stockfish + Lc0 read at the position) so you don't need a separate cloud_analyse.\n\n" +
+            "AUTO-EVAL: if a cloud engine instance is running, the response includes `.eval` (whichever engines that rental provides — Stockfish, Lc0, or both) so you don't need a separate cloud_analyse.\n\n" +
             "Reading the response — CRITICAL:\n" +
             "• Win % is one weight, not a verdict. Sample size matters (3 games at 66% is noise; 300 at 55% is signal).\n" +
             "• Prep is symmetric information — both sides see the same history. Assume the opponent knows the weakness you spotted.\n" +
@@ -118,7 +118,7 @@ export const TOOLS = [
             "- `gm-classical` — GM classical games (both players ≥2500, real thinking-time). BEST for opening prep — every move is signal, avgElo ~2600 across all listed moves.\n" +
             "- `main` — the whole 11.7M-game DB. Widest coverage but noisiest (includes 1000-Elo blunder-fests in the move stats). Use as fallback when gm-classical's totalCount is too small to be informative.\n\n" +
             "Game movetext is trimmed to the moves AFTER the queried position (using each game's plyNumber). Saves ~70% of the bytes vs full movetext.\n\n" +
-            "AUTO-EVAL: if a cloud combo instance is running, the response includes `.eval` with a compact Stockfish + Lc0 read and the corresponding NAG. Do NOT fire cloud_analyse separately for the same FEN. When called with `file_id`+`node_id`, the eval is also auto-stored on that node's `ceoEval` — later readable via quote_engine_eval.",
+            "AUTO-EVAL: if a cloud engine instance is running, the response includes `.eval` with a compact read from the engine(s) it provides and the corresponding NAG. Do NOT fire cloud_analyse separately for the same FEN. When called with `file_id`+`node_id`, the eval is also auto-stored on that node's `ceoEval` — later readable via quote_engine_eval.",
         inputSchema: {
             type: "object",
             properties: {
@@ -284,7 +284,7 @@ export const TOOLS = [
     },
     {
         name: "list_cloud_engines",
-        description: "List the user's currently running cloud engines. Use before starting a new one, or to find the contract_id for stop_cloud_engine. `cloud_analyse` auto-picks the only running combo, so listing is only necessary when the user might have zero or several.",
+        description: "List the user's currently running cloud engines. Use before starting a new one, or to find the contract_id for stop_cloud_engine. `cloud_analyse` uses the only running rental that can serve the request unless you pass `contract_id`, so listing is only necessary when there are several.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -303,9 +303,9 @@ export const TOOLS = [
     },
     {
         name: "cloud_analyse",
-        description: "Runs a synchronous ~2s analysis on the user's running combo instance and returns both Stockfish and Lc0's final read for the FEN — depth, top-N candidate moves with scores (**scoreCp is White-POV centipawns**: +20 = White is +0.20 pawns better regardless of whose turn it is; matches the sign convention used everywhere else in this MCP, including the stored ceoEval). Mate is White-POV plies-to-mate (+5 = White mates in 5). Also returns each engine's principal variation.\n\n" +
+        description: "Runs a synchronous ~2s analysis on one of the user's running engine instances and returns the requested engines' final read for the FEN — depth, top-N candidate moves with scores (**scoreCp is White-POV centipawns**: +20 = White is +0.20 pawns better regardless of whose turn it is; matches the sign convention used everywhere else in this MCP, including the stored ceoEval). Mate is White-POV plies-to-mate (+5 = White mates in 5). Also returns each engine's principal variation.\n\n" +
             "GROUNDING: every claim you make about a position must trace back to actual engine output from a call in THIS session. Don't invent evaluations, don't name 'best moves' you haven't seen the engine list, don't fabricate variations that 'look plausible.' Compute is cheap — call this 5-10 times while walking a tree rather than pattern-matching from your training data. When you don't have data for the position, either run the tool or say so; don't fill the gap with chess prose the user can't distinguish from measured output.\n\n" +
-            "Auto-picks the caller's only running combo instance; errors clearly if there are zero (start one first with start_cloud_engine) or more than one (destroy the extras first).\n\n" +
+            "Runs on any of the caller's running rentals — combo, stockfish-only, or lc0-only. Pass `contract_id` to choose one; without it the only rental that can serve the requested engines is used, and the error lists the candidates if there are several.\n\n" +
             "How to read the response:\n" +
             "• Stockfish is objective truth — trust it for 'does this line hold?' 'is there a tactic?' 'is this endgame drawn?' A Stockfish 0.00 means 'objectively equal', NOT 'trivial draw' — one side can still be much harder to play in practice.\n" +
             "• Lc0 is practical eval — trust it for 'which side is easier?' 'which candidate is best when Stockfish shows several as equal?' Lc0 sees long-term positional factors Stockfish's fixed search can miss.\n" +
@@ -350,10 +350,11 @@ export 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.",
                 },
+                contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
                 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.",
+                    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 rental). Use `[\"stockfish\"]` when only the objective read matters. The skipped engine's field is omitted from the response.",
                 },
                 pv_max_plies: {
                     type: "integer",
@@ -721,14 +722,14 @@ export const TOOLS = [
     },
     {
         name: "auto_evaluate",
-        description: "Walk the tree from `node_id` (default `'r'` = whole file) and populate the persistent `ceoEval` on every descendant via cloud_analyse. Requires a running cloud combo instance.\n\n" +
+        description: "Walk the tree from `node_id` (default `'r'` = whole file) and populate the persistent `ceoEval` on every descendant via cloud_analyse. Requires a running cloud engine instance (any shape; pass contract_id to choose).\n\n" +
             "**Async job — returns immediately.** Response: `{ job_id, target_count, status: 'running', estimated_seconds }`. Then poll `auto_evaluate_status(job_id)` until `done: true`. Cancel a run with `auto_evaluate_cancel(job_id)` — partial progress is preserved. Do useful other work between polls (write more of the tree, walk the opponent's repertoire) — the engine runs in the background.\n\n" +
             "Progress is checkpointed to the prep file every 8 successfully-evaluated nodes, so a cancel / crash / MCP restart mid-run leaves the tree partially populated rather than losing everything. On MCP restart the job record disappears; re-run auto_evaluate and `only_missing=true` naturally skips what was already saved.\n\n" +
             "**Does NOT set visible NAGs.** NAG placement is your call, not the engine's — an opening tree full of 0.00 positions doesn't need a `$10` (=) glyph on every move. Use quote_engine_eval on individual nodes before writing prose that references engine numbers.\n\n" +
-            "Costs real money — one cloud_analyse per node. A 200-node walk at default movetime is ~5 min of engine time (calls serialise on the per-combo semaphore in the backend).",
+            "Costs real money — one cloud_analyse per node. A 200-node walk at default movetime is ~5 min of engine time (calls serialise on the per-engine semaphore in the backend).",
         inputSchema: {
             type: "object",
-            properties: {
+            properties: { contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
                 id: { type: "string" },
                 node_id: { type: "string", description: "Subtree root (default 'r' = whole file)." },
                 only_missing: { type: "boolean", description: "Skip nodes that already carry a stored ceoEval (default true)." },
@@ -762,12 +763,12 @@ export const TOOLS = [
     },
     {
         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" +
+        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 rental, 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: {
+            properties: { contract_id: { type: "string", description: "Which of your running rentals to use, from list_cloud_engines. Any engine shape works (combo, stockfish-only, lc0-only). Omit it when only one rental can serve the request; if several can, the error lists their contract ids." },
                 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." },
@@ -926,7 +927,7 @@ export 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).\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.",
+            "AUTO-EVAL: if a cloud engine instance is running, the response includes a top-level `.eval` (the engines that rental provides, 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: {

package/docs/engine-usage.md

@@ -192,6 +192,25 @@ Override the defaults with `stockfish_multipv` / `lc0_multipv` when a specific p
 
 The skipped engine's field is omitted from the response (not present as an empty object).
 
+## Renting and choosing engines
+
+Analysis needs a running rental. Start one with `start_cloud_engine`, using a `machine_type` SKU from `list_cloud_machine_options`. Each SKU provides one of three shapes, shown in its `engine` field:
+
+- **`stockfish`**: Stockfish only. Fits when the question is objective (is this tactic real, does this defense hold).
+- **`lc0`**: Lc0 only. Fits the practical, human-feel read, or running alongside a `deep_analyse` that holds the Stockfish side.
+- **`combo`**: both engines in one container. The default, and the right choice for prep decisions, where both reads are needed on the same position.
+
+Rule of thumb: start a `combo` rental unless the task only needs one engine. A single-engine rental gives one read per position, so a prep walk that needs both reads on a single-engine rental takes two passes.
+
+`list_cloud_machine_options` returns the price for each SKU. Show the user the price and get their confirmation before starting a rental; every rental bills per second until `stop_cloud_engine`.
+
+Routing to a rental:
+
+- `cloud_analyse`, `auto_evaluate`, and `deep_analyse` each take an optional `contract_id` (from `list_cloud_engines`).
+- Without `contract_id`, the call uses the only running rental that can serve the request. If several can, the error lists their contract ids, and you pick one.
+- Any shape works. With `engines` set, the rental must provide those engines: asking for `engines: ["lc0"]` on a stockfish-only rental fails.
+- Do not guess contract ids. Call `list_cloud_engines` first if more than one rental is running.
+
 ## 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.49.6",
+  "version": "0.49.8",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {