@chessceo/mcp 0.49.8 → 0.49.10

package/dist/analysis/response.js

@@ -179,3 +179,17 @@ export function storedEvalToCompact(ev, analysis) {
     }
     return compact;
 }
+// Fan-out merge: each rental returns the engines it runs. Keep the first
+// rental's block per engine field, so one object carries e.g. Stockfish from
+// one rental and Lc0 from another. Top-level fields come from the first result.
+export function mergeRentalAnalyses(results) {
+    const merged = { ...(results[0] ?? {}) };
+    for (const key of ["stockfish", "lc0"]) {
+        delete merged[key];
+        for (const r of results) {
+            if (r[key] !== undefined && merged[key] === undefined)
+                merged[key] = r[key];
+        }
+    }
+    return merged;
+}

package/dist/index.js

@@ -22,7 +22,7 @@ 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, } from "./analysis/response.js";
+import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, mergeRentalAnalyses, } from "./analysis/response.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";
@@ -122,8 +122,9 @@ const EXAMPLE_REPERTOIRE_PGN = loadBundledDoc("examples/najdorf-6-f4-white.pgn",
 // putting it there would surface this to any caller who can list tools,
 // not just ones who actually hold a token.
 const ENGINE_GUIDE = {
-    stockfish: "Objective calculation — the ground truth for whether a line is actually winning/drawn/losing with best play, whether a tactic is real, whether a defense holds. Gives 0.00 to a large share of normal positions even when one side is much harder to play for a human — that means 'drawn with best play,' not 'trivial' or 'nothing to look for.'",
-    lc0: "Neural-net engine trained on human-style play, roughly 3500-strength. Its evaluation approximates how a strong human judges the position (practical chances, initiative, structure) rather than pure objective truth — good for finding ideas and gauging which side is easier to play over the board. Has real weaknesses in unconventional/irregular positions outside its training distribution: evals there can be unstable or it can miss a deep concrete tactic. When it disagrees sharply with Stockfish, look for the tactical justification before trusting its read.",
+    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".
@@ -413,7 +414,16 @@ async function callToolInner(name, args) {
             if (typeof args.contempt === "number")
                 body.contempt = args.contempt;
             Object.assign(body, analyseRouting(args));
-            const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+            // 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

package/dist/tools.js

@@ -305,7 +305,7 @@ export const TOOLS = [
         name: "cloud_analyse",
         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" +
-            "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" +
+            "Runs on any of the caller's running rentals. 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. Pass `contract_ids` (several rentals) to analyse the same FEN on all of them in parallel: the result merges the engines, e.g. Stockfish from one rental and Lc0 from another.\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" +
@@ -351,6 +351,7 @@ export const TOOLS = [
                     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." },
+                contract_ids: { type: "array", items: { type: "string" }, description: "Several running rentals to analyse the same FEN in parallel, from list_cloud_engines. Results merge by engine. Use it to get Stockfish and Lc0 on one position from separate rentals in one call." },
                 engines: {
                     type: "array",
                     items: { type: "string", enum: ["stockfish", "lc0"] },

package/docs/engine-usage.md

@@ -34,7 +34,7 @@ Concrete failure this rule blocks: the LLM says *"9...Bb7: both engines 0.00"* a
 
 ### Stockfish — objective source of truth
 
-Stockfish is calculation. Its evaluation is objective: *"is this position a draw, a win, or a loss with best play from both sides?"*
+Stockfish is the default cloud engine, searching 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 the human engine. Its score is objective: *"is this position a draw, a win, or a loss with best play from both sides?"* 0.00 means objectively a draw with best play, not that nothing is happening.
 
 Trust Stockfish for questions like:
 - Does this defensive line actually hold?
@@ -44,11 +44,11 @@ Trust Stockfish for questions like:
 
 **Watch out for:** Stockfish gives 0.00 to a *lot* of positions in the opening and early middlegame. 0.00 does not mean "trivial draw" — it means "objectively drawn with best play." Practically, one side can still be much harder to defend for a human. Every top-level classical game past move 8 typically shows 0.00 in Stockfish's eyes, yet real players win and lose those games all the time.
 
-### Lc0 — practical eval, human-like feel
+### Lc0 — practical eval, long-term ideas
 
-Lc0 is a neural net trained on self-play games. Its evaluation is closer to how a strong human sees the position — it weighs long-term positional factors, piece activity, space, and initiative in a way Stockfish's fixed search often can't reach.
+Lc0 is a neural net 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. It never gives 0.00: it always says which side prefers the position, at least a little.
 
-Where Stockfish says 0.00, Lc0 might say +0.15 — meaning *"White still has a small but real practical edge over the board."* That's exactly the signal you want for opening prep, where 95% of positions are within the objective drawing margin and the real question is *"which side is easier to play?"*
+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.
 
 Trust Lc0 for:
 - Which side has practical chances in an opening structure
@@ -56,7 +56,20 @@ Trust Lc0 for:
 - Whether a slow positional idea has long-term venom
 - Ranking candidate moves when Stockfish sees several as equal
 
-**Watch out for:** Lc0 can miss very deep tactical shots — its search is guided by intuition, not depth. If Lc0 loves a line but Stockfish doesn't, look for a concrete tactical justification (or a refutation).
+**Watch out for:** Lc0 is much weaker tactically than Stockfish. If Lc0 loves a line but Stockfish doesn't, look for a concrete tactical justification (or a refutation). Confirm any concrete line with Stockfish.
+
+### Human engine — the practical read
+
+The human engine is a 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. 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.
+- Find ideas. It may like a move that only fails to a refutation no human would find. Stockfish shows whether that refutation exists.
+- See how a human would evaluate a position, especially positional or unclear ones.
+
+**Watch out for:** 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.
 
 ### Rule of thumb
 

package/package.json

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