@chessceo/mcp 0.33.1 → 0.35.0

package/dist/index.js

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

package/docs/engine-usage.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.33.1",
+  "version": "0.35.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
   "files": [
     "dist",
     "docs",
-    "README.md"
+    "README.md",
+    "tools"
   ],
   "scripts": {
     "build": "tsc",

package/tools/fenfind/README.md

@@ -0,0 +1,51 @@
+# fenfind — find which of your PGN files cover a position
+
+Small python tool the MCP shells out to for the `find_position_in_courses`
+tool. Given a FEN it looks up every course/chapter that reaches that
+position, ranked by how much annotated material sits below it (comment
+chars in the subtree). Uses polyglot Zobrist hashing so the FEN → hash
+map matches the pre-built `positions.db` index.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `fenfind` | bash wrapper; picks a python with `python-chess` installed |
+| `fenfind.py` | the actual query tool (`--json` for MCP consumption) |
+| `_INDEXER.py` | one-off script that builds `positions.db` from a folder of PGNs (kept out of the npm package via `.npmignore`) |
+
+## Runtime dependencies
+
+- **python-chess** — either at `./venv/bin/python` (the wrapper's preferred path) or system-wide `python3`.
+  Install locally: `python3 -m venv .venv && .venv/bin/pip install python-chess`.
+- **positions.db** — the pre-built index. Resolved via, in order:
+  1. `$FENFIND_DB` env var (absolute path).
+  2. `<script-dir>/positions.db`
+  3. `~/chess/positions.db`
+  4. `~/positions.db`
+
+The DB is a runtime asset and never ships in the npm package. Put it at
+one of the paths above on any host that runs the MCP.
+
+## MCP integration
+
+`src/index.ts` resolves the script via, in order:
+1. `$FENFIND_PATH` env var (directory containing the `fenfind` script).
+2. `<package-root>/tools/fenfind/fenfind` (this directory, shipped in the
+   npm package).
+
+If neither path exists, the `find_position_in_courses` tool returns a
+clear `status: "not_available"` response with the note above rather
+than erroring.
+
+## Rebuilding the index
+
+```
+python3 _INDEXER.py    # expects PGNs at /home/lucas/chess/raw and a
+                        # course-mapping CSV at /home/lucas/chess/chessable/_originals.csv
+                        # — edit the paths at the top of the file for
+                        # your own layout.
+```
+
+Full re-index of ~2k PGN files is a few minutes; produces the ~2 GB
+positions.db in place.

package/tools/fenfind/fenfind

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Run fenfind.py with whichever interpreter has python-chess available.
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for py in "$here/.venv/bin/python" "$HOME/chess/.venv/bin/python" "$HOME/.venv/bin/python" python3; do
+    if "$py" -c 'import chess' 2>/dev/null; then
+        exec "$py" "$here/fenfind.py" "$@"
+    fi
+done
+echo "fenfind: python-chess not found. Install it, e.g.:" >&2
+echo "  python3 -m venv \"$here/.venv\" && \"$here/.venv/bin/pip\" install python-chess" >&2
+exit 1

package/tools/fenfind/fenfind.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Find which courses/chapters cover a position.
+
+  fenfind.py "<FEN>"                        look up a position
+  fenfind.py -m "1.e4 c5 2.Nf3 d6"          give moves instead of a FEN
+  fenfind.py -m "..." --courses             only files mapped to a known course
+  fenfind.py -m "..." --all                 don't hide thin entries
+  fenfind.py -m "..." --chapters            list every chapter, not best-per-file
+  fenfind.py -m "..." --min 500             custom "worth reading" threshold (note chars)
+
+Ranking: entries are sorted by how much ANNOTATED material sits below the
+position at that point -- i.e. words of explanation first, moves second.  A
+chapter that merely passes through the position on its way somewhere else
+ranks last, which is the whole point.
+"""
+import chess, chess.polyglot as zbl, sqlite3, argparse, re, os, json, sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+DB = os.environ.get('FENFIND_DB') or next(
+    (p for p in (os.path.join(HERE, 'positions.db'),
+                 os.path.expanduser('~/chess/positions.db'),
+                 os.path.expanduser('~/positions.db')) if os.path.exists(p)),
+    os.path.join(HERE, 'positions.db'))
+
+def board_from_moves(s):
+    b = chess.Board()
+    for tok in re.sub(r'\d+\.(\.\.)?', ' ', s).split():
+        if tok in ('*', '1-0', '0-1', '1/2-1/2'):
+            continue
+        try:
+            b.push_san(tok)
+        except Exception:
+            raise SystemExit(f"illegal/unparsable move: {tok}")
+    return b
+
+def looks_like_gamedb(chapter, line):
+    """Game collections put player names in the header; courses put chapter titles.
+    'Surname, Firstname' in both slots is the giveaway."""
+    return bool(re.match(r'^[A-Z][\w.\'-]+,\s*[A-Z]', chapter or '')) and \
+           bool(re.match(r'^[A-Z][\w.\'-]+,\s*[A-Z]', line or ''))
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('pos')
+    ap.add_argument('-m', '--moves', action='store_true')
+    ap.add_argument('--all', action='store_true')
+    ap.add_argument('--courses', action='store_true')
+    ap.add_argument('--chapters', action='store_true')
+    ap.add_argument('--games', action='store_true', help='include game-database hits')
+    ap.add_argument('--min', type=float, default=400)
+    ap.add_argument('-n', type=int, default=25)
+    ap.add_argument('--json', action='store_true', help='emit structured JSON on stdout instead of the text table (used by the MCP wrapper)')
+    a = ap.parse_args()
+
+    b = board_from_moves(a.pos) if a.moves else chess.Board(
+        a.pos if len(a.pos.split()) >= 6 else a.pos + ' 0 1')
+    z = zbl.zobrist_hash(b)
+    if z >= (1 << 63):
+        z -= (1 << 64)
+
+    con = sqlite3.connect(DB); con.row_factory = sqlite3.Row
+    rows = [dict(r) for r in con.execute(
+        """SELECT f.name,f.course,f.author,o.chapter,o.line,o.ply,o.subtree,o.chars
+           FROM occ o JOIN files f ON f.id=o.file_id WHERE o.z=?""", (z,))]
+    if not rows:
+        if a.json:
+            json.dump({"fen": b.fen(), "found": False, "total_occurrences": 0, "hits": []}, sys.stdout)
+            print()
+            return
+        print("position not found in the collection"); return
+    total = len(rows)
+
+    ngame = 0
+    if not a.games:
+        keep = [r for r in rows if not looks_like_gamedb(r['chapter'], r['line'])]
+        ngame = len(rows) - len(keep); rows = keep
+    ncourse = 0
+    if a.courses:
+        keep = [r for r in rows if r['course']]
+        ncourse = len(rows) - len(keep); rows = keep
+
+    # collapse duplicate FILES: "Foo.pgn", "Foo (2).pgn" and re-exports of the same
+    # course produce byte-identical hits -- keep one, remember how many copies.
+    def norm_file(n):
+        return re.sub(r'\s*\(\d+\)(?=\.pgn$)', '', n).lower()
+    for r in rows:
+        r['key'] = (r['course'] or norm_file(r['name']))
+
+    if a.chapters:
+        groups = {}
+        for r in rows:
+            k = (r['key'], r['chapter'])
+            if k not in groups or r['chars'] > groups[k]['chars']:
+                groups[k] = r
+    else:
+        groups = {}                       # best chapter per course/file
+        for r in rows:
+            k = r['key']
+            if k not in groups or (r['chars'], r['subtree']) > (groups[k]['chars'], groups[k]['subtree']):
+                groups[k] = r
+
+    hits = sorted(groups.values(), key=lambda r: (-r['chars'], -r['subtree']))
+    shown = hits if a.all else [h for h in hits if h['chars'] >= a.min]
+    thin = len(hits) - len(shown)
+
+    if a.json:
+        # Structured output for the MCP wrapper. Field names spelled out
+        # so the LLM reader doesn't need to know the SQLite column names.
+        payload = {
+            "fen": b.fen(),
+            "found": True,
+            "total_occurrences": total,
+            "excluded": {
+                "game_db_hits": ngame,
+                "unmapped_files": ncourse,
+                "thin_entries_below_min": thin,
+                "min_notes_chars": a.min,
+            },
+            "hits": [
+                {
+                    "course": h['course'] or None,
+                    "file":   h['name'],
+                    "author": h['author'] or None,
+                    "chapter": h['chapter'] or None,
+                    "line":    h['line'] or None,
+                    "ply":     h['ply'],
+                    "notes_chars":   h['chars'],
+                    "subtree_moves": h['subtree'],
+                }
+                for h in shown[:a.n]
+            ],
+            "truncated": max(0, len(shown) - a.n),
+        }
+        json.dump(payload, sys.stdout, ensure_ascii=False)
+        print()
+        return
+
+    print(f"\nposition: {b.fen()}")
+    note = [f"{total:,} indexed occurrences"]
+    if ngame:   note.append(f"{ngame:,} game-db hits excluded (--games to keep)")
+    if ncourse: note.append(f"{ncourse:,} unmapped files excluded")
+    note.append(f"{len(hits):,} distinct {'chapters' if a.chapters else 'courses'}")
+    if thin:    note.append(f"{thin:,} thin entries hidden (--all to show)")
+    print("  " + "\n  ".join(note) + "\n")
+
+    print(f"{'notes':>7} {'moves':>6} {'ply':>4}   course")
+    print("-" * 96)
+    for h in shown[:a.n]:
+        title = h['course'] or h['name'][:-4]
+        who = f"  [{h['author']}]" if h['author'] else ''
+        print(f"{h['chars']:>7} {h['subtree']:>6} {h['ply']:>4}   {title[:70]}{who}")
+        ch = h['chapter'] or '?'
+        extra = f"   |  {h['line']}" if h['line'] and h['line'] != ch else ''
+        print(f"{'':>19}   ch: {ch}{extra}")
+    if len(shown) > a.n:
+        print(f"\n... {len(shown)-a.n:,} more (-n to raise the limit)")
+
+main()