@chessceo/mcp 0.34.0 → 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";
@@ -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",
@@ -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" +
@@ -1423,6 +1446,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;
@@ -1972,6 +2076,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":

package/package.json

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