@chessceo/mcp 0.34.0 → 0.35.1

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";
@@ -92,6 +93,7 @@ const AUTHED_TOOLS = new Set([
     "deep_analyse",
     "deep_analyse_status",
     "deep_analyse_cancel",
+    "find_position_in_courses",
     "quote_engine_eval",
     "predict_human_move",
     "prepare_opponent",
@@ -212,7 +214,7 @@ const TOOLS = [
             "- `chesscom` — needs `username`. Filters: `color`, `startMonth`/`endMonth` (**required** for chesscom/lichess), `timeControl`.\n" +
             "- `lichess` — needs `username`. Same filters as chesscom; `timeControl` also accepts `bullet` on Lichess.\n\n" +
             "Multi-source example: one player with both a FIDE ID and a Lichess account → two sources in one call, all their games combined into one session.\n\n" +
-            "GROUNDING: every claim about the opponent's repertoire must trace back to a `get_prep_position` call on this session. Don't assert 'they play sharply' or 'they hate isolated queen pawn' without pointing at actual game counts / win rates in the response. Prep is a two-player game — see `read_prep_strategy_guide` before recommending an opening plan.",
+            "GROUNDING: every claim about the opponent's repertoire must trace back to a `get_prep_position` call on this session. Don't assert 'they play sharply' or 'they hate isolated queen pawn' without pointing at actual game counts / win rates in the response. Prep is a two-player game — see `read_opening_prep_guide` before recommending an opening plan.",
         inputSchema: {
             type: "object",
             properties: {
@@ -250,7 +252,7 @@ const TOOLS = [
             "• Prep is symmetric information — both sides see the same history. Assume the opponent knows the weakness you spotted.\n" +
             "• Recency > career. The last 12-24 months dominate — filter your session with `start_month` if the player's repertoire shifted.\n" +
             "• Opponent will deviate early. Prep is a tree — cover the 2 most likely replies at each real branching point, not one 20-move line.\n\n" +
-            "For the full guide call `read_prep_strategy_guide`.",
+            "For the full guide call `read_opening_prep_guide`.",
         inputSchema: {
             type: "object",
             properties: {
@@ -821,6 +823,27 @@ const TOOLS = [
             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" +
@@ -854,13 +877,16 @@ const TOOLS = [
         inputSchema: { type: "object", properties: {} },
     },
     {
-        name: "read_prep_strategy_guide",
-        description: "Returns the full chess.ceo prep-strategy guide: why win% is one weight not a verdict, why prep is a two-player game with symmetric information (opponent sees your history too), how sample size and recency change the reading, when 'revealed weaknesses' are actionable vs already patched, how to use move-order tricks with the `trs` field, and how to calibrate surprise (rare secondary lines inside the existing repertoire, not big first-move switches). Call this ONCE per session before recommending an opening plan, especially when the user is preparing for a specific real opponent.",
+        name: "read_opening_prep_guide",
+        description: "**CALL WHEN**: the user asks about OPENING PREPARATION — 'prep me against X', 'what should I play vs the Najdorf', 'help me build a repertoire against 1.e4', 'walk this opponent's Sveshnikov'. This guide is chess-and-analysis philosophy, not storage semantics.\n\n" +
+            "Covers: why win% is one weight not a verdict, why prep is a two-player game with symmetric information (opponent sees your history too), how sample size and recency change the reading, when 'revealed weaknesses' are actionable vs already patched, how to choose between the GM-classical DB and the main DB, when to combine chesscom/lichess sources with FIDE, the three chess.com profile shapes (consistent / eclectic / split-personality), the reversed-colours scarcity trick, how to calibrate surprise (rare secondary lines inside the existing repertoire, not big first-move switches).\n\n" +
+            "Different tool: `read_prep_files_guide` covers the FILE STORAGE feature (how to list/create/save prep files) — call that only when about to manipulate files, not for opening questions.",
         inputSchema: { type: "object", properties: {} },
     },
     {
         name: "read_prep_files_guide",
-        description: "Returns the guide to the prep-files FEATURE — how the storage works, when to list vs search vs create, optimistic locking with `version`, and naming conventions for the [Event] tag. Call this ONCE per session before your first create_prep_file. For how to actually WRITE PGN (mainline, variations, NAGs, arrows, comments) call read_pgn_authoring_guide instead — separate concern.",
+        description: "**CALL WHEN**: you're about to CREATE, LIST, SAVE, or DELETE a prep file — the persistent file storage feature. Not for opening prep philosophy (that's `read_opening_prep_guide`) and not for how to write PGN (that's `read_pgn_authoring_guide`).\n\n" +
+            "Covers: the AI Prep folder, when to list vs search vs create (avoid duplicate 'Prep vs Firouzja' files), optimistic locking with `version`, naming conventions for the [Event] tag, node-id addressing basics.",
         inputSchema: { type: "object", properties: {} },
     },
     {
@@ -1423,6 +1449,87 @@ function deepAnalyseCancel(args) {
     // 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;
@@ -1442,17 +1549,26 @@ function analysisToStoredEval(analysis, fen) {
     if (!analysis || typeof analysis !== "object")
         return null;
     const r = analysis;
-    const whiteToMove = / w /.test(fen);
-    const flip = (n) => (whiteToMove ? n : -n);
+    // 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;
     const engineEval = (block) => {
         const line = block?.lines?.[0];
         if (!line)
             return undefined;
         const depth = line.depth ?? block?.depth;
         if (typeof line.mate === "number")
-            return { mate: flip(line.mate), depth };
+            return { mate: line.mate, depth };
         if (typeof line.scoreCp === "number")
-            return { cp: flip(line.scoreCp), depth };
+            return { cp: line.scoreCp, depth };
         return undefined;
     };
     const sf = engineEval(r.stockfish);
@@ -1972,6 +2088,8 @@ async function callToolInner(name, args) {
             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":
@@ -2049,7 +2167,7 @@ async function callToolInner(name, args) {
         }
         case "read_engine_usage_guide":
             return { guide: ENGINE_USAGE_DOC };
-        case "read_prep_strategy_guide":
+        case "read_opening_prep_guide":
             return { guide: PREP_STRATEGY_DOC };
         case "read_prep_files_guide":
             return { guide: PREP_FILES_DOC };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.34.0",
+  "version": "0.35.1",
   "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()