@chessceo/mcp 0.35.1 → 0.36.4

package/dist/index.js

@@ -501,11 +501,17 @@ const TOOLS = [
                     maximum: 10000,
                     description: "Think time in milliseconds (default 2000).",
                 },
-                multipv: {
+                stockfish_multipv: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Stockfish candidate lines (default 2). Kept tight because each extra PV steals search bandwidth from the top choice — SF is the 'what's objectively best' leg, use a low multipv to keep it strong. Raise only when you specifically need SF's take on a wide range of candidates.",
+                },
+                lc0_multipv: {
                     type: "integer",
                     minimum: 1,
                     maximum: 10,
-                    description: "Number of candidate lines per engine (default 3).",
+                    description: "Lc0 candidate lines (default 8). Kept wide because multipv doesn't degrade Lc0's strength the way it does Stockfish's — Lc0 is the 'find inspiration / explore practical tries' leg, use a high multipv to get a full slate of ideas.",
                 },
                 contempt: {
                     type: "integer",
@@ -795,7 +801,7 @@ const TOOLS = [
                     type: "integer",
                     minimum: 1,
                     maximum: 10,
-                    description: "Number of candidate lines (default 3).",
+                    description: "Number of candidate lines (default 2). Stockfish gets weaker as multipv grows — each extra PV steals search bandwidth from the top choice — so keep this low unless you specifically want to see several candidates ranked deep.",
                 },
             },
         },
@@ -981,7 +987,7 @@ 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);
+        const stored = analysisToStoredEval(converted);
         return storedEvalToCompact(stored, converted);
     }
     catch {
@@ -1234,7 +1240,7 @@ async function runEvalJob(job, fileId, targets, movetimeMs) {
             break;
         try {
             const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
-            const ev = analysisToStoredEval(analysis, t.fen);
+            const ev = analysisToStoredEval(analysis);
             if (ev) {
                 pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
                 job.evaluated++;
@@ -1333,7 +1339,10 @@ async function deepAnalyseStart(args) {
     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;
+    // Default 2 — SF loses meaningful strength at higher multipv, so a
+    // deep think is best spent on a tight candidate list. Matches the
+    // cloud_analyse stockfish_multipv default.
+    const multipv = typeof args.multipv === "number" ? args.multipv : 2;
     const jobId = newDeepJobId();
     const job = {
         id: jobId,
@@ -1365,7 +1374,7 @@ async function runDeepJob(job) {
     const body = {
         fen: job.fen,
         movetime_ms: job.movetimeMs,
-        multipv: job.multipv,
+        stockfish_multipv: job.multipv,
         engines: ["stockfish"],
     };
     let raw;
@@ -1398,7 +1407,7 @@ async function runDeepJob(job) {
     // 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);
+        const ev = analysisToStoredEval({ stockfish: sf });
         if (ev) {
             try {
                 await storeEvalOnNode(job.fileHandle, ev);
@@ -1545,21 +1554,14 @@ function pathIntoTree(root, path) {
 // 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) {
+function analysisToStoredEval(analysis) {
     if (!analysis || typeof analysis !== "object")
         return null;
     const r = analysis;
-    // NOTE: the backend already returns White-POV cp/mate (engine-ws flips
-    // in ParseInfo based on side-to-move, then cloud_snapshot passes the
-    // number through). Previously this function ALSO flipped on
-    // black-to-move — a double flip that silently inverted every
-    // Black-to-move position's stored eval, so half of every prep tree
-    // had wrong-sign ceoEval and the auto-attached .eval on those
-    // positions reported White as better when Black was. Any ceoEval
-    // written on a Black-to-move node prior to 2026-07-26 is inverted;
-    // re-run auto_evaluate on affected files to overwrite.
-    // Unused `fen` kept as an arg for signature stability with callers.
-    void fen;
+    // Backend returns White-POV cp/mate (engine-ws flips in ParseInfo
+    // based on side-to-move, cloud_snapshot passes through). Pure
+    // pass-through here — a previous sign-flip on black-to-move was
+    // wrong and silently inverted every Black-to-move stored eval.
     const engineEval = (block) => {
         const line = block?.lines?.[0];
         if (!line)
@@ -2061,8 +2063,10 @@ async function callToolInner(name, args) {
             const body = { fen };
             if (typeof args.movetime_ms === "number")
                 body.movetime_ms = args.movetime_ms;
-            if (typeof args.multipv === "number")
-                body.multipv = args.multipv;
+            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;
             if (Array.isArray(args.engines))
@@ -2076,7 +2080,7 @@ async function callToolInner(name, args) {
             // 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, fen);
+                const ev = analysisToStoredEval(converted);
                 if (ev)
                     await storeEvalOnNode(resolved.file, ev);
             }

package/docs/engine-usage.md

@@ -118,6 +118,19 @@ Typical movetimes:
 
 Only use it when you actually need the depth. Regular `cloud_analyse` handles the ~5–10 branches of a typical prep walk perfectly well.
 
+## Per-engine `multipv` defaults
+
+`cloud_analyse` defaults to different candidate-line counts per engine because the two engines behave differently:
+
+- **Stockfish: `stockfish_multipv=2`** — SF gets weaker as multipv grows. Each extra PV steals search bandwidth from the top choice, so the "objective best move" leg is at its strongest with a tight list. Raise only when you specifically need SF's read on a wide range of candidates (e.g. sanity-checking an unusual sideline).
+- **Lc0: `lc0_multipv=8`** — Lc0 doesn't degrade the same way with multipv. Use it wide by default: 8 candidates give the LLM a real slate of practical ideas to inspect ("what does Lc0 think of the fun moves here?"). Lower it only when you don't need that breadth.
+
+Mental model:
+- **Stockfish = the checker.** "Is this line objectively good? What's actually best?" Narrow, deep, one answer.
+- **Lc0 = the explorer.** "What's practically interesting? What alternatives are worth a look?" Wide, breadth-first, several answers.
+
+Override the defaults with `stockfish_multipv` / `lc0_multipv` when a specific position warrants a different shape.
+
 ## Splitting engines on `cloud_analyse`
 
 `cloud_analyse` accepts an `engines` list to run only one leg:

package/docs/pgn-authoring.md

@@ -154,6 +154,14 @@ Prose is NEVER for:
 - Move recommendations ("here White should play h4") — add_move it.
 - Restating the eval a NAG already conveys.
 - **Describing a sibling variation you already added as a branch.** If move A has variation B added as `add_move(A, sibling)`, don't ALSO write `{if B then ...}` on A. The reader clicks B on the board — the branch is already there.
+- **Restating what the app already renders.** The reader opens the file in the app and sees: every sibling move (with count / avg rating / top players from the DB), each node's stored `ceoEval`, the NAG glyphs, the tree structure. Duplicating any of that in prose is pure noise.
+
+  - ❌ `{5...Bb4 (180/247), 5...d6 (26), 5...Be7 (18), 5...d5 (7), 5...g6 (2)}` — those are the sibling variations, already visible.
+  - ❌ `{Main move, 180 of 247 games (So, Giri, Karjakin, Duda). Eval −0.20/−0.27.}` — count, top players, eval all shown by the app.
+  - ✅ `{Main move; the sharpest test is actually 5...d5 (only 7 games but avg 2526) — see the variation.}`
+  - ✅ `{Popular, but leads to the endgame Black draws — 6.Bd2 is where prep depth matters.}`
+
+  Test: if the reader can see it by looking at the position or clicking a branch, don't write it. Prose is only for plans, prep-signal, or WHY — the layer the app can't derive.
 
 ## Move-judgment symbols (NAGs)
 

package/docs/prep-strategy.md

@@ -26,6 +26,7 @@ The move statistics endpoints return win %, game counts, and (in the big DB) a `
 - **Sample size scales trust.** 3 games at 66% is noise; 300 at 55% is signal. A great score is nice — with volume. When the opponent has only 2-4 games in a variation, the "opponent-specific" score is basically the general-DB score anyway.
 - **Score doesn't automatically indicate a level gap.** A 60% variation isn't necessarily "stronger players crushing weaker ones." Look at the per-move `avgWhite` / `avgBlack` fields (returned on every move statistic) before drawing conclusions about who is playing whom.
 - **Don't recommend the higher-percentage move just because it's higher.** If 1.b3 scores 60% and 1.d4 scores 50% against a given opponent, that is *not* on its own a case for playing 1.b3 — style, prep depth, transposition risk, and the practical questions below all matter more.
+- **Count is popular, avgRating is critical.** When you're choosing which branches deserve prep depth, the highest-avgRating move often matters more than the highest-count one. Top players play the moves they know work, sometimes ignoring the herd. Example: 5...Bb4 has 180 games at avg 2350; 5...d5 has 7 games at avg 2526. d5 is the sharper test even though Bb4 is "main". Skim the rating column before the count column when picking branches to cover.
 
 ## Which DB source: signal vs population
 
@@ -141,6 +142,39 @@ Meta-signal matters. Big changes in the user's repertoire are transparent to str
 - **Right:** stay inside the user's normal repertoire, pick a rare secondary line. Classic example: a 1.e4 player who always plays 6.Bg5 vs the Najdorf switching to 6.Bc4 for one game. The opponent recognizes the opening; they don't have prep on this specific line; the user's meta-signature ("I play 1.e4 vs Najdorf") stays intact.
 - Same logic for candidate move choice: the opponent's expectation of *what the user plays* is itself a variable to be manipulated.
 
+## Practical, not correspondence
+
+The reader is a human at the board, not a computer consuming a PGN.
+
+- **Don't paste long engine PVs into prose.** A 15-move variation in a comment is unreadable and unmemorable. Cite the eval, name the key move or two, stop. If the line matters as a variation, add it as a branch with `add_line` — the reader walks it interactively there — not as prose.
+- **Compress for human memory.** If the opponent has 6 plausible replies that all share one strategic theme, describe the theme once; add the two structurally different branches, not all 6. Long non-forcing lines are unmemorable regardless of eval; recommend depth only when the line is actually forced or the reader has a clear reason to remember it.
+
+## When the database runs thin, judge the position
+
+Sparse data (few games, low ratings, or literally zero) means no "what does the field play here" signal. The LLM has to actually judge the position — and it has two tools that stand in for the missing signal.
+
+- **Call `describe_position` before commenting on a position without concrete game data.** You cannot reliably read a FEN — pieces get swapped, hanging pieces missed, "the knight on d5" turns out to not exist. `describe_position` gives you the same board a human sees: piece placements, contested pieces with attackers/defenders, hanging list, check state, legal moves. Cheap (~1 ms, no engine). Mandatory when the DB is thin, since you no longer have "what won here historically" to anchor the reasoning.
+- **Call `predict_human_move` when past theory.** Once out of book, humans play *human* moves — natural, principled, sometimes objectively second-best. The engine's top choice is often not what the opponent actually picks. Rating-condition the prediction on the opponent's level.
+- **Think in plans, not lines.** With no games to anchor you, one 12-move engine line is nearly worthless as prep. Two plans described in a sentence each ("break with f4 and pile on the h-file" vs "consolidate with Nc4/Bd2 and play for a3-b4") give the reader something they can actually execute.
+
+## Prune obviously worse branches
+
+Not every legal move deserves a variation. Skip a move when it is **both** significantly worse AND barely played. Either condition alone isn't enough:
+
+- Rare-but-equal sideline → cover it (surprise value).
+- Bad move that top players still occasionally try → cover it (you'll face it).
+- Rare AND worse → skip. A covered-for-thoroughness branch dilutes the tree and wastes reader attention.
+
+Concrete: after 1.e4 e5 2.d4 from White's side, only 2...exd4 is worth analysing — every alternative is worse AND rare. Cross-check with `get_prep_position` (opponent's actual choices) and `get_position_stats` (population + objective eval) before spending depth on a branch.
+
+## When to stop, when to keep going
+
+Depth calibrates to the *character* of the position, not to whether the DB has games or how deep in the tree you are.
+
+- **Forcing → keep going.** Concrete tactics, only-moves, sharp sequences — analyse until the position calms (real endgame, stable middlegame structure). No game data doesn't matter; the moves are forced, so there's nothing to look up anyway. `describe_position` + engine is enough.
+- **Quiet → stop early.** Once the position is strategic — many reasonable moves, no immediate threats — one sentence of plans is worth more than another 6 plies of tree. Stop and describe.
+- **Novelties MUST branch.** If you're introducing a move nobody's played, "the DB has no games" is not a reason to stop — the reader will actually reach this position over the board and needs an answer. Predict the opponent's replies with `predict_human_move` (rating-conditioned to their level), sanity-check with Stockfish (objective best) and Lc0 (practical alternatives), then branch on the top ~2 predicted responses. This is precisely where all three signals matter most, because there's no historical answer to lean on. See also "Novelty burns" — save deep novelty-prep for the games that actually warrant it.
+
 ## How to combine these
 
 None of these are rules; they're weights. In one game against a specific opponent one factor dominates (they clearly hate Catalan structures); in another it's a different one (they're rigid and just play their repertoire, so tree-depth matters more than surprise). Reason through them explicitly when recommending, and cite the concrete numbers (game counts, dates, win rates) so the user can trust or overrule.

package/package.json

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