@chessceo/mcp 0.36.4 → 0.39.1

package/dist/index.js

@@ -76,6 +76,7 @@ const AUTHED_TOOLS = new Set([
     "list_prep_files",
     "search_prep_files",
     "read_prep_file",
+    "list_nodes",
     "create_prep_file",
     "delete_prep_file",
     "add_move",
@@ -94,6 +95,7 @@ const AUTHED_TOOLS = new Set([
     "deep_analyse_status",
     "deep_analyse_cancel",
     "find_position_in_courses",
+    "read_course_at_position",
     "quote_engine_eval",
     "predict_human_move",
     "prepare_opponent",
@@ -329,10 +331,21 @@ const TOOLS = [
     },
     {
         name: "describe_position",
-        description: "Structured facts about a chess position: piece placements per colour (SAN-style letters), material balance in pawn units, list of every contested piece (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant square, side to move, and the full list of LEGAL MOVES for the side to move. Pure computation — no engine, ~1 ms per call.\n\n" +
-            "USE THIS BEFORE COMMENTING ON A POSITION. LLMs are not reliable at reading FEN strings — you'll misplace pieces or invent captures. This tool gives you the same board state a human sees.\n\n" +
-            "ALSO USE THIS if `add_move` rejects an illegal SAN — the `.legalMoves` array shows exactly what's playable from that position.\n\n" +
-            "Position input: prefer `file_id`+`node_id` if you're inside a prep file. Otherwise `fen`, `moves` from startpos, or `fen + moves`.",
+        description: "Everything you need to understand a position in one call. USE BEFORE COMMENTING — pieces get misplaced when reading a FEN, hanging pieces missed, 'the knight on d5' turns out to not exist. ~50-100 ms per call (chess-primitive analysis is instant; the Stockfish leg dominates wall time).\n\n" +
+            "Returns three layers:\n\n" +
+            "**Board state** — piece placements per colour, material balance in pawn units, contested pieces (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant, side to move, full LEGAL MOVES list. Use `.legalMoves` when `add_move` rejects an illegal SAN.\n\n" +
+            "**Structural analysis** — chess-concept observations a human sees at a glance:\n" +
+            "  • `pawnStructure.files` — each file `open`/`half_open_for_white`/`half_open_for_black`/`closed`. Half-open files are natural rook targets.\n" +
+            "  • `pawnStructure.islands` — count per colour (more = weaker structure).\n" +
+            "  • `pawnStructure.isolated` / `doubled` / `passed` / `backward` — structural weaknesses (and strengths, for passed).\n" +
+            "  • `weakSquares` — holes in ranks 3-6 that no friendly pawn can ever attack. Prime real estate for enemy pieces.\n" +
+            "  • `outposts` — friendly N/B on an enemy hole defended by own pawn. Classic strong squares.\n" +
+            "  • `bishops` — per-bishop `good`/`mixed`/`bad` from own pawns on its colour. `bishops.pair` flags who has both.\n" +
+            "  • `space` — squares controlled in the enemy half.\n\n" +
+            "**Engine eval terms** (`engineEvalTerms`) — Stockfish's classical eval decomposed into 13 named contributing terms (Material, Imbalance, Pawns, Knights, Bishops, Rooks, Queens, Mobility, King safety, Threats, Passed, Space, Winnable), each with white / black / total values in mg + eg. Stockfish's own answer to WHY the position stands the way it does.\n" +
+            "  → **Primary use: the delta pattern.** Call `describe_position` on the position BEFORE and AFTER a candidate move, compare `engineEvalTerms` — the term with the biggest shift tells you WHAT the move changed (king safety collapsed → move exposed the king; mobility jumped → move improved coordination). Kim et al. NAACL 2025 showed this named-delta pattern roughly doubles LLM chess-commentary correctness vs a bare eval number.\n" +
+            "  → Omitted from the response if Stockfish isn't installed on the server.\n\n" +
+            "Position input: prefer `file_id`+`node_id` if inside a prep file. Otherwise `fen`, `moves` from startpos, or `fen + moves`.",
         inputSchema: {
             type: "object",
             properties: {
@@ -345,15 +358,11 @@ const TOOLS = [
     },
     {
         name: "predict_human_move",
-        description: "Predicts what a HUMAN of the given rating will most likely play from a position. Rating-conditioned neural net (ResNet-20x256) — you get the top-N most likely moves with their probabilities and a WDL value head (White POV).\n\n" +
-            "This is a completely different question from the engine tools (analyse / cloud_analyse):\n" +
-            "• Engines answer: 'what is objectively best?'\n" +
-            "• predict_human_move answers: 'what will my 2200-rated opponent actually play here?'\n\n" +
-            "Prime use cases in prep:\n" +
-            "• After you've found what the opponent SHOULD do (with the engine), check what they'll ACTUALLY do at their rating. If the top human move is a mistake, you have a real practical advantage.\n" +
-            "• The WDL head is rating-aware — a 400-point gap will show up as a big win probability even in equal positions (the model has learned that human errors compound).\n" +
-            "• Pass `prev_fen` (most recent first) when analysing mid-trade positions — without history the model treats the position as quiet.\n\n" +
-            "Position input: prefer `file_id`+`node_id` when inside a prep file. Otherwise `fen`, `moves` from startpos, or `fen + moves`. Default rating 2400 both sides. ~1-2s per call. **Premium (or admin/moderator) only** — anonymous calls get 402.",
+        description: "Neural net (ResNet-20x256) trained on real games. Always evaluated at **2850 vs 2850** (top-level play) — the rating is fixed on purpose, so cross-position comparisons stay apples-to-apples. Returns two signals — both useful, treat as independent:\n\n" +
+            "1. **Top-N most likely moves** (`moves: [{san, p}, ...]`) — what a top player will actually pick. Different question from engines: cloud_analyse says objectively best, this says what the human will play. If the human top move is a mistake, that's a real practical advantage.\n\n" +
+            "2. **`wdlWhitePov: {win, draw, loss}`** — game-outcome prediction, White POV. Directly comparable across positions: call on two positions, compare `draw` to find which line is drawier / more forcing. Two-line comparisons are how you answer 'must-win with Black, which of these openings gives more play'.\n\n" +
+            "Pass `prev_fens` (most recent first) when the position is mid-trade — without history the model treats it as quiet, which under-counts practical chances.\n\n" +
+            "Position input: prefer `file_id`+`node_id` when inside a prep file. Otherwise `fen`, `moves` from startpos, or `fen + moves`. ~1-2s per call. **Premium (or admin/moderator) only** — anonymous calls get 402.",
         inputSchema: {
             type: "object",
             properties: {
@@ -364,18 +373,6 @@ const TOOLS = [
                     type: "string",
                     description: "Optional SAN moves to apply on top of `fen` (or startpos). Only used if `node_id` is not set.",
                 },
-                white_elo: {
-                    type: "integer",
-                    minimum: 100,
-                    maximum: 3400,
-                    description: "White's rating (default 2400).",
-                },
-                black_elo: {
-                    type: "integer",
-                    minimum: 100,
-                    maximum: 3400,
-                    description: "Black's rating (default 2400).",
-                },
                 top: {
                     type: "integer",
                     minimum: 1,
@@ -545,17 +542,50 @@ const TOOLS = [
     },
     {
         name: "read_prep_file",
-        description: "Read one prep file. Returns a compact tree (each node carries a stable `id`, `san`, `fen`, `ply`, optional `comment`/`nags`/`annotations`/`ceoEval`, and `children`) plus tags and the `version` for optimistic locking on subsequent mutations. NO raw PGN — all edits go through the mutation tools (add_move / add_line / set_comment / set_nags / set_annotations / delete_subtree / promote_variation / set_tag), which validate SAN and structure for you.\n\n" +
-            "**Node addressing.** Every node has a stable `id` — root is `'r'`, every other node is an 8-hex-char content hash derived from its parent's id + its SAN. Sibling insertions, deletions and variation promotions do NOT change any other node's id. Pass this id as `node_id` (or `parent_id` for add_move / add_line) to every mutation and engine/DB tool.\n\n" +
+        description: "Read one prep file. Response always includes `id`, `version`, `tags`. The tree/PGN part is controlled by `view` and `node_id`/`max_depth` — large files (500+ nodes) can otherwise blow the LLM's token limit.\n\n" +
+            "**Views** (pick the smallest one that answers your question):\n" +
+            "  • `compact` (default) — per-node: `id`, `san`, `ply`, `nags`, `comment`, `ceoEval`, `children`. Drops `fen` and `annotations`. Typical size: ~120 chars/node vs ~330 in `full`.\n" +
+            "  • `full` — everything (`fen`, `annotations` too). Use when you actually need the FEN inline or want to inspect arrows/highlights. On a 500+-node file this can exceed token limits.\n" +
+            "  • `spine` — mainline only (children[0] recursively). Great for a 'what does this repertoire cover' summary.\n" +
+            "  • `pgn` — subtree as raw PGN text (comments, NAGs, [%cal] arrows all preserved). Useful for sanity-checking formatting against reference material.\n\n" +
+            "**Node addressing.** Every node has a stable `id` — root is `'r'`, every other node is an 8-hex-char content hash of parent-id + SAN. Sibling insertions, deletions, variation promotions never shift ids. Pass as `node_id` (or `parent_id` for add_move / add_line) to every mutation and engine/DB tool.\n\n" +
+            "**Scoping.** `node_id` starts the tree from a subtree root (default `'r'`). `max_depth` caps the tree at that many plies below the anchor (default unlimited). Use both to drill into a specific branch without dumping the whole file — the LLM never needs to see the full 800-node tree at once.\n\n" +
+            "For querying the tree without reading it (\"which nodes have no ceoEval?\", \"give me the mainline spine\") call `list_nodes` — cheaper than parsing a full read.\n\n" +
             "**Every engine/DB tool accepts `file_id`+`node_id`** (get_position_stats, cloud_analyse, describe_position, predict_human_move, prep_snapshot, get_prep_position, quote_engine_eval). Use it whenever a file is open — the server derives the FEN from the tree, so you can't 'analyse the wrong position' by mis-typing a FEN.",
         inputSchema: {
             type: "object",
             properties: {
                 id: { type: "string", description: "Prep file id, from list_prep_files or search_prep_files." },
+                view: { type: "string", enum: ["compact", "full", "spine", "pgn"], description: "Response shape. Default `compact` — drops fen + annotations to keep token count sane. See tool description for when to use each." },
+                node_id: { type: "string", description: "Subtree root (default `'r'` = whole file)." },
+                max_depth: { type: "integer", minimum: 0, description: "Cap the returned tree at this many plies below `node_id`. Omit for unlimited." },
             },
             required: ["id"],
         },
     },
+    {
+        name: "list_nodes",
+        description: "Cheap tree queries without reading the whole file. Returns only the node ids matching the filter (plus san, ply, and any filter-specific bits), so the LLM can find what it needs in ~KBs instead of MBs.\n\n" +
+            "Filters:\n" +
+            "  • `missing_eval` — nodes without a stored `ceoEval`. Use before `auto_evaluate` to know how much work is left, or to target a small batch.\n" +
+            "  • `has_comment` — nodes with a text comment. Use to audit what's been annotated.\n" +
+            "  • `has_annotations` — nodes with arrows or highlighted squares.\n" +
+            "  • `mainline` — the spine (children[0] recursively). Use for a compact 'what does the repertoire cover' view.\n" +
+            "  • `novelties` — nodes carrying the `$146` NAG.\n" +
+            "  • `leaves` — nodes with no children (variation endpoints). Useful for finding lines that need continuation.\n" +
+            "  • `all` — every node id. Use only when you really need the whole list.\n\n" +
+            "Response: `{ file_id, filter, count, nodes: [{node_id, san, ply, ...}] }`. `...` is filter-specific — e.g. `has_comment` includes the first 80 chars of the comment; `missing_eval` includes nothing extra (just the addressing).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+                filter: { type: "string", enum: ["missing_eval", "has_comment", "has_annotations", "mainline", "novelties", "leaves", "all"], description: "Which nodes to list." },
+                node_id: { type: "string", description: "Subtree root (default `'r'` = whole file)." },
+                max_depth: { type: "integer", minimum: 0, description: "Cap the walk at this many plies below `node_id`. Omit for unlimited." },
+            },
+            required: ["id", "filter"],
+        },
+    },
     {
         name: "create_prep_file",
         description: "Create a new (empty) prep file. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
@@ -831,10 +861,13 @@ const TOOLS = [
     },
     {
         name: "find_position_in_courses",
-        description: "Look up which of the USER's own Chessable / PGN courses cover a position, ranked by how much ANNOTATED material sits below that position in each course. This is the LLM's window into what the user has personally studied — not a general database. Complements engine + big-DB tools: the general database says what the world plays, this says what the user has literature on.\n\n" +
-            "Ranking: files/chapters where the position sits at a branching point with lots of text under it rank first. A chapter that merely passes through the position on its way somewhere else ranks last, which is the whole point — the LLM wants to point the user at where the material actually explains this specific position.\n\n" +
-            "Use this to: cite specific chapters the user already owns when recommending an opening decision, cross-check whether the user has coverage of a rare line, find author overlap when the user asks 'what do I have on this?'\n\n" +
-            "Returns: `{fen, found, total_occurrences, excluded: {game_db_hits, unmapped_files, thin_entries_below_min, min_notes_chars}, hits: [{course, file, author, chapter, line, ply, notes_chars, subtree_moves}], truncated}`. `notes_chars` is the total characters of commentary in the subtree rooted at this occurrence — the primary rank signal. `ply` tells you how deep in the chapter's game tree this position sits (small ply = near the chapter's start).\n\n" +
+        description: "Look up which of the USER's own Chessable / PGN courses cover a position. This is the LLM's window into what the user has personally studied — not a general database. Two-step: `find_position_in_courses` returns metadata (course, chapter, author, updated_at, notes_chars, `course_file_id`); `read_course_at_position` fetches the actual commentary + variations from a specific hit.\n\n" +
+            "Use it as a reference library, not memory. Query patterns:\n" +
+            "  • 'Does my chosen line have coverage?' → search from the position, see which repertoires cover it.\n" +
+            "  • 'What do opposite-colour repertoires recommend against this move?' → search, filter by author/course to the other side.\n" +
+            "  • 'Has anyone tried my novelty before?' → search the position, if hits exist read the ones that reach it.\n\n" +
+            "Default sort is `recency` (most-recently-updated file first — theory shifts, 10-year-old material is less trustworthy than 2-month-old). Switch to `notes` when you specifically want the deepest annotated chapter regardless of age.\n\n" +
+            "Returns: `{fen, found, total_occurrences, sort, excluded, hits: [{course_file_id, course, file, author, chapter, line, ply, notes_chars, subtree_moves, updated_at}], truncated}`. Pass `course_file_id` to `read_course_at_position` to actually see the material.\n\n" +
             "Not available if the fenfind index isn't installed on the server — response includes a clear note in that case.",
         inputSchema: {
             type: "object",
@@ -843,6 +876,7 @@ const TOOLS = [
                 node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'. When set, overrides `fen`/`moves`." },
                 fen: { type: "string", description: "Starting position as FEN. Only used if `node_id` is not set." },
                 moves: { type: "string", description: "Optional SAN moves on top of `fen` (or startpos). Only used if `node_id` is not set." },
+                sort: { type: "string", enum: ["recency", "notes"], description: "Ranking. `recency` (default) = most-recently-updated file first. `notes` = deepest annotation first regardless of age." },
                 include_games: { type: "boolean", description: "Include hits from game-database PGNs (player headers instead of course/chapter titles). Default false — those are noise for course-lookup." },
                 chapters_mode: { type: "boolean", description: "Return every chapter separately rather than best-per-course. Default false. Useful when a course has multiple chapters covering the same position." },
                 min_notes_chars: { type: "number", description: "Minimum notes_chars per hit to be included. Default 400 (~a paragraph of prose). Set to 0 to see every occurrence." },
@@ -850,6 +884,27 @@ const TOOLS = [
             },
         },
     },
+    {
+        name: "read_course_at_position",
+        description: "Read the actual commentary + variations from a course file at a specific position. Second half of the find→read pair — `find_position_in_courses` returns metadata; this returns the material itself.\n\n" +
+            "Response includes the subtree as PGN (comments, NAGs, `[%cal]`/`[%csl]` arrows all preserved), plus the moves-to-position and chapter metadata. Depth-capped by `max_plies_below` (default 20) to keep responses small — widen when you want to see deeper analysis, or call with a different `fen` to jump to another position in the same file.\n\n" +
+            "Usage patterns:\n" +
+            "  • Read what an author says about a specific position → pass `course_file_id` from a find hit + the FEN.\n" +
+            "  • Explore a chapter from move 1 → pass `course_file_id` + `chapter`, no FEN.\n" +
+            "  • Skim deeper into a branch you're interested in → same file/chapter, wider `max_plies_below`.\n" +
+            "  • Compare how two authors annotate the same position → two calls with different `course_file_id`s.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                course_file_id: { type: "integer", description: "File id from a `find_position_in_courses` hit (`course_file_id` field)." },
+                fen: { type: "string", description: "Position to walk to (matched by polyglot Zobrist hash, so move-order transpositions work). Omit to return the chapter from move 1." },
+                moves: { type: "string", description: "Alternative to `fen`: SAN moves from startpos." },
+                chapter: { type: "string", description: "Substring match on chapter title (the White header in the PGN). Omit to auto-pick the first chapter containing the position; supply when a course has multiple chapters and you want a specific one." },
+                max_plies_below: { type: "integer", minimum: 0, maximum: 200, description: "How many plies of subtree to include below the target position. Default 20. Cap 200." },
+            },
+            required: ["course_file_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" +
@@ -902,9 +957,9 @@ const TOOLS = [
     },
     {
         name: "read_example_prep_files",
-        description: "Returns two full reference PGNs authored by a strong human coach — one a general opening overview (Italian Fried Liver, both sides, 1600+ audience) and one a one-sided repertoire (Najdorf 6.f4 for White, 2200+ audience). Bundled with the MCP; not the user's files.\n\n" +
-            "Read these ONCE per session before writing your first substantial prep file. The authoring guide (read_pgn_authoring_guide) tells you the rules; these examples show you what the rules look like when applied by someone who knows what they're doing — comment density, when to cite games by player name, how to use `$146` / `$3` / `$44` sparingly and correctly, when a bare `[%csl Rf7]` says everything, how to acknowledge transpositions, how to phrase practical guidance vs objective evaluation. Study the rhythm before writing your own.\n\n" +
-            "Response: `{ overview: <pgn>, repertoire: <pgn> }`. Raw PGN — comments, arrows, NAGs, and stored evals all intact.",
+        description: "**CALL WHEN**: about to write ANY prose commentary in a prep file, ever. Even one comment. Even one variation. This is not optional and not once-per-project — call it early in the session and read the examples before your first `set_comment` or `apply_mutations` batch that includes comments. Log analysis showed <5% of sessions call this despite it being the single biggest quality lift documented in this MCP; that's the mistake this description is trying to fix.\n\n" +
+            "Why: `read_pgn_authoring_guide` tells you the rules in prose. These files show you the *sound* of them applied by a strong human coach — comment density (short and load-bearing, not verbose), how citations look in-line (`WeiYi-Svidler` not `\"Svidler's choice at the FIDE World Blitz Team, June 2026\"`), when `$146` / `$3` / `$44` earn their place, when a bare `[%csl Rf7]` says everything a sentence would say. LLMs default to florid, restate-what's-visible commentary; reading these once inoculates against that.\n\n" +
+            "Two files bundled with the MCP (not the user's own): one general opening overview (Italian Fried Liver, both sides, 1600+ audience) and one one-sided repertoire (Najdorf 6.f4 for White, 2200+ audience). Response: `{ overview: <pgn>, repertoire: <pgn> }` — raw PGN with comments, arrows, NAGs, stored evals intact.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -1177,6 +1232,7 @@ async function autoEvaluate(args) {
             targetCount: 0,
             evaluated: 0,
             errored: 0,
+            failedNodeIds: [],
             finalVersion: g.version,
             startedAt: Date.now(),
             finishedAt: Date.now(),
@@ -1192,6 +1248,7 @@ async function autoEvaluate(args) {
         targetCount: targets.length,
         evaluated: 0,
         errored: 0,
+        failedNodeIds: [],
         startedAt: Date.now(),
         cancelled: false,
     };
@@ -1235,8 +1292,15 @@ async function runEvalJob(job, fileId, targets, movetimeMs) {
             job.finalVersion = sr.version;
         pending.length = 0;
     };
+    // Consecutive-failure abort. If N cloud_analyse calls in a row error,
+    // the engine is almost certainly dead (vanished contract, network to
+    // VastAI down) and burning through the rest of the tree just wastes
+    // time. Bail with an explicit reason so a targeted retry is possible.
+    const MAX_CONSECUTIVE_FAILURES = 3;
+    let consecutiveFailures = 0;
+    let aborted = false;
     for (const t of targets) {
-        if (job.cancelled)
+        if (job.cancelled || aborted)
             break;
         try {
             const analysis = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen: t.fen, movetime_ms: movetimeMs, multipv: 1 });
@@ -1244,15 +1308,25 @@ async function runEvalJob(job, fileId, targets, movetimeMs) {
             if (ev) {
                 pending.push({ op: "set_ceo_eval", node_id: t.nodeId, ceoEval: ev });
                 job.evaluated++;
+                consecutiveFailures = 0;
             }
             else {
                 job.errored++;
+                job.failedNodeIds.push(t.nodeId);
+                consecutiveFailures++;
             }
         }
         catch {
-            // Per-node failure — record and continue; a bad FEN or a transient
-            // engine hiccup on one node shouldn't kill the whole walk.
+            // Per-node failure — record the node_id so the caller can retry
+            // just those, and count consecutive failures for the abort check.
             job.errored++;
+            job.failedNodeIds.push(t.nodeId);
+            consecutiveFailures++;
+        }
+        if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
+            aborted = true;
+            job.abortedReason = `aborted after ${MAX_CONSECUTIVE_FAILURES} consecutive cloud_analyse failures — check that the cloud combo is still running (list_cloud_engines)`;
+            break;
         }
         if (pending.length >= SAVE_EVERY_N) {
             try {
@@ -1297,6 +1371,8 @@ function autoEvaluateStatus(args) {
         target_count: job.targetCount,
         evaluated: job.evaluated,
         errored: job.errored,
+        failed_node_ids: job.failedNodeIds, // exact ids for targeted retry — pass as node_id list or check with list_nodes
+        aborted_reason: job.abortedReason, // present when the job stopped early due to consecutive engine failures
         remaining: Math.max(0, job.targetCount - job.evaluated - job.errored),
         done: job.status !== "running",
         error: job.error,
@@ -1475,41 +1551,74 @@ function deepAnalyseCancel(args) {
 // available (venv at $here/.venv/bin/python preferred, then falls back
 // to system python3). DB path is resolved inside fenfind.py itself
 // (FENFIND_DB env, then ~/positions.db).
-const FENFIND_SCRIPT = (() => {
-    const envPath = process.env.FENFIND_PATH?.trim();
-    if (envPath) {
-        const p = join(envPath, "fenfind");
-        return existsSync(p) ? p : null;
-    }
+// Path resolution shared by both fenfind + readpgn. FENFIND_PATH env
+// overrides the bundled tools/fenfind/ directory.
+// Path to sf_eval helper (spawns local stockfish, parses its `eval`
+// verbose output). Uses the same resolution pattern as FENFIND_DIR.
+const SF_EVAL_SCRIPT = (() => {
+    const envPath = process.env.SF_EVAL_PATH?.trim();
+    if (envPath && existsSync(join(envPath, "sf_eval")))
+        return join(envPath, "sf_eval");
     const here = dirname(fileURLToPath(import.meta.url));
-    const bundled = join(here, "..", "tools", "fenfind", "fenfind");
+    const bundled = join(here, "..", "tools", "sf_eval", "sf_eval");
     return existsSync(bundled) ? bundled : null;
 })();
-// Cap on how long we let fenfind run — SQLite query with a hash index
-// should return in well under a second, but a stuck subprocess
-// shouldn't pin the MCP handler.
-const FENFIND_TIMEOUT_MS = 15_000;
-async function findPositionInCourses(args) {
-    if (!FENFIND_SCRIPT) {
+const SF_EVAL_TIMEOUT_MS = 12_000;
+async function runSfEval(fen) {
+    if (!SF_EVAL_SCRIPT) {
         return {
-            status: "not_available",
-            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind` script and positions.db, or install the tools/fenfind bundle shipped in the npm package.",
+            found: false,
+            error: "sf_eval script not bundled; set SF_EVAL_PATH or install tools/sf_eval/",
         };
     }
-    const resolved = await resolveFromNodeOrFen(args);
-    const cliArgs = [resolved.fen, "--json"];
-    if (args.include_games)
-        cliArgs.push("--games");
-    if (args.chapters_mode)
-        cliArgs.push("--chapters");
-    if (typeof args.min_notes_chars === "number")
-        cliArgs.push("--min", String(args.min_notes_chars));
-    if (typeof args.limit === "number")
-        cliArgs.push("-n", String(args.limit));
     const stdout = await new Promise((resolve, reject) => {
-        const p = spawn(FENFIND_SCRIPT, cliArgs, {
-            stdio: ["ignore", "pipe", "pipe"],
+        const p = spawn(SF_EVAL_SCRIPT, ["--fen", fen], { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        p.stdout.on("data", d => { out += d.toString("utf8"); });
+        p.stderr.on("data", d => { err += d.toString("utf8"); });
+        const to = setTimeout(() => {
+            try {
+                p.kill("SIGTERM");
+            }
+            catch { /* already dead */ }
+            reject(new Error(`sf_eval timed out after ${SF_EVAL_TIMEOUT_MS}ms`));
+        }, SF_EVAL_TIMEOUT_MS);
+        p.on("error", e => { clearTimeout(to); reject(e); });
+        p.on("close", code => {
+            clearTimeout(to);
+            if (code !== 0)
+                reject(new Error(`sf_eval exited ${code}: ${err.slice(0, 500)}`));
+            else
+                resolve(out);
         });
+    });
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (e) {
+        throw new Error(`sf_eval returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
+    }
+}
+const FENFIND_DIR = (() => {
+    const envPath = process.env.FENFIND_PATH?.trim();
+    if (envPath && existsSync(join(envPath, "fenfind")))
+        return envPath;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const bundled = join(here, "..", "tools", "fenfind");
+    return existsSync(join(bundled, "fenfind")) ? bundled : null;
+})();
+// Cap on how long we let the subprocess run. SQLite hash lookup returns
+// sub-second; PGN read from a course file is O(chapter size) and rarely
+// exceeds a second. 15s is a stuck-process backstop, not a real limit.
+const FENFIND_TIMEOUT_MS = 15_000;
+async function runFenfindScript(scriptName, args) {
+    if (!FENFIND_DIR) {
+        throw new Error("fenfind index not installed — set FENFIND_PATH or install the tools/fenfind bundle");
+    }
+    const script = join(FENFIND_DIR, scriptName);
+    return new Promise((resolve, reject) => {
+        const p = spawn(script, args, { stdio: ["ignore", "pipe", "pipe"] });
         let out = "";
         let err = "";
         p.stdout.on("data", d => { out += d.toString("utf8"); });
@@ -1519,25 +1628,71 @@ async function findPositionInCourses(args) {
                 p.kill("SIGTERM");
             }
             catch { /* already dead */ }
-            reject(new Error(`fenfind timed out after ${FENFIND_TIMEOUT_MS}ms`));
+            reject(new Error(`${scriptName} timed out after ${FENFIND_TIMEOUT_MS}ms`));
         }, FENFIND_TIMEOUT_MS);
         p.on("error", e => { clearTimeout(to); reject(e); });
         p.on("close", code => {
             clearTimeout(to);
-            if (code !== 0) {
-                reject(new Error(`fenfind exited ${code}: ${err.slice(0, 500)}`));
-            }
-            else {
+            if (code !== 0)
+                reject(new Error(`${scriptName} exited ${code}: ${err.slice(0, 500)}`));
+            else
                 resolve(out);
-            }
         });
     });
+}
+function parseFenfindJson(scriptName, stdout) {
     try {
         return JSON.parse(stdout);
     }
     catch (e) {
-        throw new Error(`fenfind returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
+        throw new Error(`${scriptName} returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
+    }
+}
+async function findPositionInCourses(args) {
+    if (!FENFIND_DIR) {
+        return {
+            status: "not_available",
+            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind` script and positions.db, or install the tools/fenfind bundle shipped in the npm package.",
+        };
+    }
+    const resolved = await resolveFromNodeOrFen(args);
+    const cliArgs = [resolved.fen, "--json"];
+    if (typeof args.sort === "string" && (args.sort === "recency" || args.sort === "notes")) {
+        cliArgs.push("--sort", args.sort);
+    }
+    if (args.include_games)
+        cliArgs.push("--games");
+    if (args.chapters_mode)
+        cliArgs.push("--chapters");
+    if (typeof args.min_notes_chars === "number")
+        cliArgs.push("--min", String(args.min_notes_chars));
+    if (typeof args.limit === "number")
+        cliArgs.push("-n", String(args.limit));
+    const stdout = await runFenfindScript("fenfind", cliArgs);
+    return parseFenfindJson("fenfind", stdout);
+}
+async function readCourseAtPosition(args) {
+    if (!FENFIND_DIR) {
+        return {
+            status: "not_available",
+            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind`/`readpgn` scripts and positions.db.",
+        };
+    }
+    const fileId = typeof args.course_file_id === "number" ? args.course_file_id : Number(args.course_file_id);
+    if (!Number.isFinite(fileId) || fileId <= 0) {
+        throw new Error("`course_file_id` is required — pass the value from a find_position_in_courses hit");
     }
+    const cliArgs = ["--file-id", String(fileId)];
+    if (typeof args.fen === "string" && args.fen.trim() !== "")
+        cliArgs.push("--fen", args.fen.trim());
+    if (typeof args.moves === "string" && args.moves.trim() !== "")
+        cliArgs.push("--moves", args.moves.trim());
+    if (typeof args.chapter === "string" && args.chapter.trim() !== "")
+        cliArgs.push("--chapter", args.chapter.trim());
+    if (typeof args.max_plies_below === "number")
+        cliArgs.push("--max-plies-below", String(args.max_plies_below));
+    const stdout = await runFenfindScript("readpgn", cliArgs);
+    return parseFenfindJson("readpgn", stdout);
 }
 // Walk chess.js-free: resolve a path against a tree, throw if invalid.
 function pathIntoTree(root, path) {
@@ -1665,6 +1820,174 @@ async function applyMutation(args, mutator) {
         version: savedRow.version,
     };
 }
+async function loadPrepFile(id) {
+    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
+    const g = raw;
+    if (typeof g.pgnContent !== "string")
+        throw new Error("prep file missing pgnContent");
+    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: g.id, pgn: g.pgnContent };
+}
+// Recursively project a PrepNode into the requested view. `depthLeft`
+// null → unlimited; 0 → just the node without children.
+function projectNode(node, view, depthLeft) {
+    const base = {
+        id: node.id,
+        san: node.san,
+        ply: node.ply,
+    };
+    if (node.nags && node.nags.length > 0)
+        base.nags = node.nags;
+    if (node.comment)
+        base.comment = node.comment;
+    if (node.ceoEval)
+        base.ceoEval = node.ceoEval;
+    if (view === "full") {
+        base.fen = node.fen;
+        if (node.annotations)
+            base.annotations = node.annotations;
+    }
+    // Children handling depends on view + depth budget.
+    const showChildren = depthLeft === null || depthLeft > 0;
+    const childDepth = depthLeft === null ? null : depthLeft - 1;
+    if (showChildren && node.children.length > 0) {
+        if (view === "spine") {
+            // Only follow children[0] — collapses the tree to the mainline.
+            base.children = [projectNode(node.children[0], view, childDepth)];
+        }
+        else {
+            base.children = node.children.map(c => projectNode(c, view, childDepth));
+        }
+    }
+    else {
+        base.children = [];
+    }
+    return base;
+}
+async function readPrepFile(args) {
+    const id = String(args.id);
+    const view = (typeof args.view === "string" && ["compact", "full", "spine", "pgn"].includes(args.view))
+        ? args.view
+        : "compact";
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file, version, fileIdEcho, pgn } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const header = {
+        id: fileIdEcho ?? id,
+        version,
+        tags: file.tags,
+        view,
+        node_id: startNodeId,
+        max_depth: maxDepth,
+    };
+    if (view === "pgn") {
+        // For the root, just return the file's actual PGN as-is. For a
+        // subtree, build a mini-Game from the anchor and export it. Keeps
+        // formatting identical to what the app renders.
+        if (startNodeId === ROOT_ID && (maxDepth === null || maxDepth >= 999)) {
+            return { ...header, pgn };
+        }
+        // Truncate to a subtree with max_depth. Simple: walk the anchor's
+        // subtree, produce a synthetic PGN starting from the anchor's FEN.
+        const subtreePgn = exportSubtreePgn(file, anchor, maxDepth);
+        return { ...header, pgn: subtreePgn };
+    }
+    return { ...header, tree: projectNode(anchor, view, maxDepth) };
+}
+// Produce a PGN string for a subtree rooted at `anchor`, truncated
+// at `maxDepth` plies below (null = unlimited). Reuses the exporter
+// by building a synthetic PrepFile whose root is a shallow clone of
+// the anchor with its children trimmed to depth.
+function exportSubtreePgn(file, anchor, maxDepth) {
+    const trim = (n, depthLeft) => {
+        if (depthLeft !== null && depthLeft <= 0)
+            return { ...n, children: [] };
+        const next = depthLeft === null ? null : depthLeft - 1;
+        return { ...n, children: n.children.map(c => trim(c, next)) };
+    };
+    const trimmedAnchor = trim(anchor, maxDepth);
+    // If the anchor IS the root, exporter handles it. If it's an inner
+    // node, we set the root's FEN to the anchor's position and hang the
+    // trimmed subtree off it. Tags carried over.
+    if (anchor.id === ROOT_ID) {
+        return exportPGN({ tags: file.tags, root: trimmedAnchor });
+    }
+    const syntheticRoot = {
+        id: ROOT_ID,
+        san: null,
+        fen: anchor.fen,
+        ply: 0,
+        children: trimmedAnchor.children,
+    };
+    const tags = { ...file.tags, FEN: anchor.fen, SetUp: "1" };
+    return exportPGN({ tags, root: syntheticRoot });
+}
+async function listNodes(args) {
+    const id = String(args.id);
+    const filter = String(args.filter || "");
+    const startNodeId = typeof args.node_id === "string" && args.node_id.length > 0 ? args.node_id : ROOT_ID;
+    const maxDepth = typeof args.max_depth === "number" && args.max_depth >= 0 ? args.max_depth : null;
+    const { file } = await loadPrepFile(id);
+    const idIndex = buildIdIndex(file.root);
+    const path = resolveNodeId(idIndex, startNodeId);
+    const anchor = getNodeByPath(file.root, path);
+    const hits = [];
+    const walk = (node, depthLeft, spineOnly) => {
+        // Root has no san — never emit it as a match. Everything else is fair game.
+        if (node.id !== ROOT_ID) {
+            let include = false;
+            let extra = {};
+            switch (filter) {
+                case "missing_eval":
+                    include = !node.ceoEval;
+                    break;
+                case "has_comment":
+                    include = !!(node.comment && node.comment.length > 0);
+                    if (include)
+                        extra.comment_preview = (node.comment || "").slice(0, 80);
+                    break;
+                case "has_annotations":
+                    include = !!(node.annotations && (node.annotations.arrows.length > 0 || node.annotations.highlights.length > 0));
+                    break;
+                case "novelties":
+                    include = !!(node.nags && node.nags.includes("$146"));
+                    break;
+                case "leaves":
+                    include = node.children.length === 0;
+                    break;
+                case "mainline":
+                    include = spineOnly;
+                    break;
+                case "all":
+                    include = true;
+                    break;
+                default:
+                    throw new Error(`unknown filter: ${filter}`);
+            }
+            if (include) {
+                const hit = { node_id: node.id, san: node.san, ply: node.ply };
+                Object.assign(hit, extra);
+                hits.push(hit);
+            }
+        }
+        if (depthLeft !== null && depthLeft <= 0)
+            return;
+        const nextDepth = depthLeft === null ? null : depthLeft - 1;
+        if (filter === "mainline" && spineOnly) {
+            if (node.children.length > 0)
+                walk(node.children[0], nextDepth, true);
+        }
+        else {
+            for (const c of node.children)
+                walk(c, nextDepth, filter === "mainline");
+        }
+    };
+    const rootIsSpineForFilter = filter === "mainline";
+    walk(anchor, maxDepth, rootIsSpineForFilter);
+    return { file_id: id, filter, node_id: startNodeId, max_depth: maxDepth, count: hits.length, nodes: hits };
+}
 // Strip cruft the LLM doesn't need from the DB-position response.
 // Called AFTER trimGamesMovetext so plyNumber survives long enough to
 // slice each game's movetext. Also renames the `transpositions` field
@@ -1852,10 +2175,21 @@ function normalizeSourceForBackend(src, idx) {
     }
     return out;
 }
-// Async resolver used by every engine / DB tool. If the caller supplied
-// file_id + node_id (preferred), load the file, resolve the node, and
-// return both the FEN and a handle we can use to persist ceoEval later.
-// Otherwise fall back to the raw fen/moves/line inputs.
+// Async resolver used by every engine / DB tool. Three paths:
+//
+//   1. file_id + node_id → load file, resolve node, return FEN + handle
+//      to persist ceoEval later. Cheapest, most explicit.
+//
+//   2. file_id + (fen | moves | line) → load file, resolve FEN
+//      client-side, then scan the file's nodes for one matching that
+//      FEN. If found, return the same handle as (1) so cloud_analyse
+//      auto-stores on the matching node. Fixes the previous footgun
+//      where `cloud_analyse({file_id, moves})` silently dropped the
+//      eval because the server didn't try to match the resulting FEN
+//      back to a node.
+//
+//   3. Just fen | moves | line, no file_id → scratch mode, no
+//      persistence. Same as before.
 async function resolveFromNodeOrFen(args) {
     const fileId = typeof args.file_id === "string" ? args.file_id.trim() : "";
     const nodeId = typeof args.node_id === "string" ? args.node_id.trim() : "";
@@ -1870,18 +2204,51 @@ async function resolveFromNodeOrFen(args) {
         const node = getNodeByPath(parsedFile.root, nodePath);
         return {
             fen: node.fen,
-            file: {
-                id: fileId,
-                version: g.version ?? 0,
-                parsedFile,
-                idIndex,
-                nodePath,
-                fen: node.fen,
-            },
+            file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath, fen: node.fen },
         };
     }
+    if (fileId) {
+        // file_id only — resolve FEN from fen/moves/line, then look it up
+        // in the file's nodes. If a node has that FEN, treat this as if
+        // node_id had been supplied (auto-persist on match).
+        const fen = resolveFenFromArgs(args);
+        try {
+            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
+            const g = raw;
+            if (typeof g.pgnContent === "string") {
+                const parsedFile = parsePGN(g.pgnContent);
+                const match = findNodeByFen(parsedFile.root, fen);
+                if (match) {
+                    const idIndex = buildIdIndex(parsedFile.root);
+                    return {
+                        fen,
+                        file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
+                    };
+                }
+            }
+        }
+        catch {
+            // Best-effort: if the file load fails, fall through to scratch mode.
+        }
+        return { fen };
+    }
     return { fen: resolveFenFromArgs(args) };
 }
+// Search the tree for a node whose FEN matches. Full-tree scan — trees
+// max out ~1000 nodes so this is fine. FEN comparison is exact string
+// match (both come from the same chessops normalisation).
+function findNodeByFen(root, targetFen) {
+    const stack = [{ node: root, path: [] }];
+    while (stack.length > 0) {
+        const { node, path } = stack.pop();
+        if (node.fen === targetFen)
+            return { node, path };
+        for (let i = 0; i < node.children.length; i++) {
+            stack.push({ node: node.children[i], path: [...path, i] });
+        }
+    }
+    return null;
+}
 // Local wrapper — the mutation module re-exports paths.getNode so this
 // import stays consistent with the rest of the file's imports.
 function getNodeByPath(root, path) {
@@ -1924,19 +2291,50 @@ function stringifyForLog(v) {
     }
     return s;
 }
+// Version tag stamped on every log line so a bug report can be traced
+// to the exact MCP release that produced it. process.env.npm_package_version
+// is set by npm when the package is run via `npx` / `npm start` (and by
+// our systemd unit which uses npx); falls back to reading package.json
+// during dev when we `node dist/index.js` directly. "unknown" if all
+// else fails — better than pretending we know.
+const MCP_VERSION = (() => {
+    const fromEnv = process.env.npm_package_version?.trim();
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/index.js is one level below package.json; src/index.ts is two
+        // (src/index.ts → ../package.json). Try both.
+        for (const p of [join(here, "..", "package.json"), join(here, "..", "..", "package.json")]) {
+            if (existsSync(p)) {
+                const pkg = JSON.parse(readFileSync(p, "utf8"));
+                if (pkg.version)
+                    return pkg.version;
+            }
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "unknown";
+})();
+const MCP_TAG = `[mcp v${MCP_VERSION}]`;
+// One-shot startup line so tailing the log from the beginning shows
+// the running version immediately, before any tool call.
+console.error(`${MCP_TAG} chessceo-mcp startup`);
 async function callTool(name, args) {
     const started = Date.now();
-    console.error(`[mcp] IN  ${name} args=${stringifyForLog(args)}`);
+    console.error(`${MCP_TAG} IN  ${name} args=${stringifyForLog(args)}`);
     try {
         const result = await callToolInner(name, args);
         const dur = Date.now() - started;
-        console.error(`[mcp] OUT ${name} ok ${dur}ms result=${stringifyForLog(result)}`);
+        console.error(`${MCP_TAG} OUT ${name} ok ${dur}ms result=${stringifyForLog(result)}`);
         return result;
     }
     catch (err) {
         const dur = Date.now() - started;
         const msg = err instanceof Error ? err.message : String(err);
-        console.error(`[mcp] OUT ${name} err ${dur}ms error=${JSON.stringify(msg)}`);
+        console.error(`${MCP_TAG} OUT ${name} err ${dur}ms error=${JSON.stringify(msg)}`);
         throw err;
     }
 }
@@ -2012,17 +2410,37 @@ async function callToolInner(name, args) {
         }
         case "describe_position": {
             const resolved = await resolveFromNodeOrFen(args);
-            return describePosition(resolved.fen);
+            // Chess-primitive analysis (structural, ~1 ms) + Stockfish eval-
+            // term breakdown (~50-100 ms) in parallel. Merge into one response
+            // so the LLM sees the whole position in one call — chess-concepts,
+            // structural weaknesses, AND engine's per-term reasoning.
+            // If Stockfish isn't installed the eval leg returns {found: false,
+            // error} and we drop it from the response so callers see the same
+            // shape either way (just without `engineEvalTerms`).
+            const [structural, evalRaw] = await Promise.all([
+                Promise.resolve(describePosition(resolved.fen)),
+                runSfEval(resolved.fen).catch(err => ({
+                    found: false,
+                    error: err instanceof Error ? err.message : String(err),
+                })),
+            ]);
+            const merged = structural;
+            const ev = evalRaw;
+            if (ev && ev.found === true) {
+                merged.engineEvalTerms = { terms: ev.terms, total: ev.total };
+            }
+            return merged;
         }
         case "predict_human_move": {
             const resolved = await resolveFromNodeOrFen(args);
             const fen = resolved.fen;
+            // Rating is fixed at 2850 vs 2850. Not exposed to the LLM —
+            // cross-position comparisons only mean something at a constant
+            // rating, and top-level is the useful reference point for prep.
             const qs = new URLSearchParams();
             qs.set("fen", fen);
-            if (typeof args.white_elo === "number")
-                qs.set("white_elo", String(args.white_elo));
-            if (typeof args.black_elo === "number")
-                qs.set("black_elo", String(args.black_elo));
+            qs.set("white_elo", "2850");
+            qs.set("black_elo", "2850");
             if (typeof args.top === "number")
                 qs.set("top", String(args.top));
             if (Array.isArray(args.prev_fens)) {
@@ -2031,7 +2449,20 @@ async function callToolInner(name, args) {
                         qs.append("prev_fen", p);
                 }
             }
-            return authedRequest("GET", `/api/agent/predict-move?${qs.toString()}`);
+            const raw = await authedRequest("GET", `/api/agent/predict-move?${qs.toString()}`);
+            // Strip uci from each move — san is enough for the LLM and the
+            // duplicate field is context bloat. Also drop whiteElo/blackElo
+            // from the response (always 2850 now — echoing them adds nothing).
+            if (raw && typeof raw === "object") {
+                const r = raw;
+                if (Array.isArray(r.moves)) {
+                    for (const m of r.moves)
+                        delete m.uci;
+                }
+                delete r.whiteElo;
+                delete r.blackElo;
+            }
+            return raw;
         }
         case "get_head_to_head":
             return get("/api/chess/players/h2h", {
@@ -2094,23 +2525,16 @@ async function callToolInner(name, args) {
             return deepAnalyseCancel(args);
         case "find_position_in_courses":
             return findPositionInCourses(args);
+        case "read_course_at_position":
+            return readCourseAtPosition(args);
         case "list_prep_files":
             return authedRequest("GET", "/api/agent/prep-files");
         case "search_prep_files":
             return authedRequest("GET", `/api/agent/prep-files/search?q=${encodeURIComponent(String(args.query))}`);
-        case "read_prep_file": {
-            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
-            const g = raw;
-            if (typeof g.pgnContent !== "string")
-                throw new Error("prep file missing pgnContent");
-            const file = parsePGN(g.pgnContent);
-            return {
-                id: g.id,
-                version: g.version,
-                tags: file.tags,
-                tree: file.root,
-            };
-        }
+        case "read_prep_file":
+            return readPrepFile(args);
+        case "list_nodes":
+            return listNodes(args);
         case "create_prep_file":
             return authedRequest("POST", "/api/agent/prep-files", {
                 name: String(args.name),