@chessceo/mcp 0.16.0 → 0.19.0

package/dist/index.js

@@ -35,6 +35,7 @@ function loadBundledDoc(filename, fallbackLabel) {
 }
 const ENGINE_USAGE_DOC = loadBundledDoc("engine-usage.md", "Engine usage guide");
 const PREP_STRATEGY_DOC = loadBundledDoc("prep-strategy.md", "Prep strategy guide");
+const PREP_FILES_DOC = loadBundledDoc("prep-files-guide.md", "Prep files guide");
 // ── HTTP ────────────────────────────────────────────────────────────
 //
 // Two auth flavours coexist:
@@ -58,6 +59,13 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "list_prep_files",
+    "search_prep_files",
+    "read_prep_file",
+    "create_prep_file",
+    "save_prep_file",
+    "delete_prep_file",
+    "predict_human_move",
 ]);
 function isAuthedToolCall(body) {
     if (!body || typeof body !== "object")
@@ -262,6 +270,51 @@ 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 is flexible — pass `fen`, or `moves` from startpos, or `fen + moves`. Default rating 2400 both sides. ~1-2s per call. **Premium (or admin/moderator) only** — anonymous calls get 402.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "Starting position as FEN." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or startpos).",
+                },
+                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,
+                    maximum: 20,
+                    description: "Number of top predicted moves to return (default 5).",
+                },
+                prev_fens: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Previous FEN(s), most recent first. Optional — omit for quiet-position analysis. Useful mid-trade so the model doesn't assume the position is stable.",
+                },
+            },
+        },
+    },
     {
         name: "get_head_to_head",
         description: "Complete head-to-head record between two players. Includes overall and per-colour W/D/L (from player A's perspective), splits by time control, most-played openings between them, first / last meeting, average game length, and the game list.",
@@ -386,6 +439,84 @@ const TOOLS = [
             required: ["fen"],
         },
     },
+    {
+        name: "list_prep_files",
+        description: "List every prep file the user has (all games inside their dedicated AI Prep collection). Returns id, PGN tags (Event, White, Black, Date, etc. — read the Event tag for the user-facing name), size, updated_at. ALWAYS call this before create_prep_file to check for existing coverage — creating a second 'Prep vs Firouzja' when one already exists is a common LLM failure. If the user has many, use search_prep_files with a query to narrow down.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "search_prep_files",
+        description: "Text search over the user's prep files (matches PGN headers, comments, and content). Use this instead of list_prep_files when you know a keyword — e.g. search_prep_files(query='Firouzja') or search_prep_files(query='Najdorf').",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Free-text query (opponent name, opening name, event keyword)." },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "read_prep_file",
+        description: "Read one prep file. Returns the full PGN text and a compact tree JSON of the mainline (SAN + FEN per move) for programmatic reasoning. Also carries the `version` field you need to pass back to save_prep_file for the optimistic-lock check.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id, from list_prep_files or search_prep_files." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "create_prep_file",
+        description: "Create a new prep file. `name` becomes the Event PGN tag (user-facing label). Optional `pgn` seeds the file — if omitted, a minimal empty PGN is written and you can save_prep_file into it later.\n\n" +
+            "ALWAYS run list_prep_files (or search_prep_files with the opponent / opening keyword) BEFORE creating, so you don't duplicate an existing file. If a file already exists that fits, extend it via save_prep_file instead.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "User-facing name for the file — becomes the [Event] tag in the PGN. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
+                },
+                pgn: {
+                    type: "string",
+                    description: "Optional initial PGN content. Supports full PGN with headers and parenthesised variations. If omitted, an empty PGN is created.",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "save_prep_file",
+        description: "Save (replace) a prep file's PGN content. Optimistic-lock via `expected_version` — pass the `version` you got from read_prep_file. If someone else (user in the app, or another agent session) updated the file since you read it, save returns 409 with the current version — re-read and merge.\n\n" +
+            "PGN structure guidance:\n" +
+            "- Keep the mainline clean (your top recommendation).\n" +
+            "- Alternative candidates go in parenthesised variations at the branching move.\n" +
+            "- Attach one-sentence commentary at key branch points using PGN {curly-brace comments}. Cite the actual tool output ('Lc0 gives +0.15 in this line') — don't dress the file up with unsourced chess prose.\n" +
+            "- Use PGN NAGs for evaluations: $1 !, $2 ?, $3 !!, $4 ??, $6 =, $10 = (equal), $14 +/= (slight edge), etc. Optional but nice.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+                pgn: { type: "string", description: "Full replacement PGN (headers + moves)." },
+                expected_version: {
+                    type: "integer",
+                    description: "The `version` you got from read_prep_file. If omitted, no optimistic check runs (last-write-wins — riskier).",
+                },
+            },
+            required: ["id", "pgn"],
+        },
+    },
+    {
+        name: "delete_prep_file",
+        description: "Soft-delete a prep file. The user can restore it from the chess.ceo app's recycle bin if you deleted something valuable. Rare — usually you extend or replace instead.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "string", description: "Prep file id." },
+            },
+            required: ["id"],
+        },
+    },
     {
         name: "read_engine_usage_guide",
         description: "Returns the full chess.ceo engine-usage guide: when to trust Stockfish (objective truth) vs Lc0 (practical eval), how to read disagreements between them, and how to use Lc0 contempt to find non-objective 'practical' ideas. Call this ONCE per session before running expensive `cloud_analyse` calls or when the user asks WHY the engines gave certain scores. Same content is also available as the `engine_usage_primer` prompt (for clients that surface prompts as slash commands), but many clients do not expose prompts to the model — this tool works everywhere.",
@@ -396,6 +527,11 @@ const TOOLS = [
         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.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "read_prep_files_guide",
+        description: "Returns the full guide on how to store prep in the user's chess.ceo account via list_prep_files / read_prep_file / create_prep_file / save_prep_file / delete_prep_file. Covers: how to structure a repertoire PGN (mainline + variations + comments + NAGs), the critical 'search-before-create' habit to avoid duplicates, optimistic-locking with `version`, and how to write comments that cite tool output instead of inventing chess prose. Call this ONCE per session before your first create_prep_file / save_prep_file call.",
+        inputSchema: { type: "object", properties: {} },
+    },
     {
         name: "prep_snapshot",
         description: "One call, three parallel fetches at the same position: opponent's stats on their side, your stats on your side, and the 11.7M-game general database at that position. Use this while walking the opening tree — one round trip instead of three separate calls, and you can compare the three views directly (e.g. opponent has 2 games here but the general DB has 8k → prep candidate).",
@@ -503,6 +639,24 @@ function convertCloudSnapshotResponse(raw, startFen) {
     }
     return raw;
 }
+function pgnToTree(pgn) {
+    try {
+        const board = new Chess();
+        // chess.js loadPgn accepts full PGN incl. tags; loadPgn returns true on
+        // success or throws on newer versions. Wrap defensively.
+        board.loadPgn(pgn);
+        // history({verbose:true}) walks the mainline only; variations aren't
+        // exposed by chess.js's built-in PGN loader at time of writing. If the
+        // PGN carries parenthesised variations they get flattened.
+        const hist = board.history({ verbose: true });
+        if (hist.length === 0)
+            return [];
+        return hist.map(h => ({ san: h.san, fen: h.after }));
+    }
+    catch {
+        return null;
+    }
+}
 // Rewrite availableMoves[].move UCI → SAN. The prep + position-stats
 // endpoints return moves in UCI on the wire — same LLM-readability
 // concern as engine PVs, and the same wrapper-only fix. Passes the
@@ -635,6 +789,24 @@ async function callToolInner(name, args) {
             const raw = await get("/api/chess/database/analyse", params);
             return convertAnalyseResponse(raw, fen);
         }
+        case "predict_human_move": {
+            const fen = resolveFenFromArgs(args);
+            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));
+            if (typeof args.top === "number")
+                qs.set("top", String(args.top));
+            if (Array.isArray(args.prev_fens)) {
+                for (const p of args.prev_fens) {
+                    if (typeof p === "string" && p.length > 0)
+                        qs.append("prev_fen", p);
+                }
+            }
+            return authedRequest("GET", `/api/agent/predict-move?${qs.toString()}`);
+        }
         case "get_head_to_head":
             return get("/api/chess/players/h2h", {
                 a: Number(args.fide_id_a),
@@ -671,10 +843,41 @@ async function callToolInner(name, args) {
             const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
             return convertCloudSnapshotResponse(raw, fen);
         }
+        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))}`);
+            // MCP layer adds the tree JSON view — backend stays pure PGN in/out.
+            // If parse fails the LLM still has the raw PGN text to work with.
+            if (raw && typeof raw === "object") {
+                const g = raw;
+                if (typeof g.pgnContent === "string") {
+                    const tree = pgnToTree(g.pgnContent);
+                    return { ...raw, tree };
+                }
+            }
+            return raw;
+        }
+        case "create_prep_file":
+            return authedRequest("POST", "/api/agent/prep-files", {
+                name: String(args.name),
+                pgn: typeof args.pgn === "string" ? args.pgn : undefined,
+            });
+        case "save_prep_file":
+            return authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`, {
+                pgn: String(args.pgn),
+                expected_version: typeof args.expected_version === "number" ? args.expected_version : undefined,
+            });
+        case "delete_prep_file":
+            return authedRequest("DELETE", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
         case "read_engine_usage_guide":
             return { guide: ENGINE_USAGE_DOC };
         case "read_prep_strategy_guide":
             return { guide: PREP_STRATEGY_DOC };
+        case "read_prep_files_guide":
+            return { guide: PREP_FILES_DOC };
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);

package/docs/prep-files-guide.md

@@ -0,0 +1,125 @@
+# Prep files guide
+
+You can save chess prep to the user's chess.ceo account and read it back across sessions. This is the persistence layer that turns your analysis from ephemeral chat into a durable, viewable-in-app repertoire.
+
+## The mental model
+
+The user has **one** collection dedicated to your work — labelled "AI Prep" in their chess.ceo app with a 🤖 icon. Inside it, each **prep file** is one PGN game with variations. You never see the collection itself; the tools operate directly on the files inside it.
+
+Six tools:
+
+- `list_prep_files` — show me all my prep files
+- `search_prep_files(query)` — find by opponent name / opening keyword
+- `read_prep_file(id)` — full PGN + parsed mainline tree + `version`
+- `create_prep_file(name, pgn?)` — new file, `name` becomes the [Event] tag
+- `save_prep_file(id, pgn, expected_version)` — replace the whole PGN
+- `delete_prep_file(id)` — soft delete (user can restore from app)
+
+## The single most important habit
+
+**Before creating a new file, search for an existing one.** LLMs make three "Prep vs Firouzja" files in a row all the time. Always:
+
+1. `list_prep_files` (if the user has ≤20-30 files) or `search_prep_files(query=<opponent name>)` for their key term
+2. Read the ones that look relevant
+3. Decide: extend an existing one (save_prep_file) or genuinely start fresh (create_prep_file)
+
+Duplicate files are the #1 way to lose your user's trust in this system.
+
+## PGN structure
+
+Real chess prep files are PGN with parenthesised variations. Learn the shape:
+
+```pgn
+[Event "Prep vs Firouzja (Black) — 2026-07-23"]
+[White "Firouzja, Alireza"]
+[Black "Van Foreest, Jorden"]
+[Date "2026.07.23"]
+
+1. e4 c5 2. Nf3 d6 3. d4 cxd4 4. Nxd4 Nf6 5. Nc3 a6 6. Be3 e5 7. Nb3
+{Main line. Firouzja plays this in 68% of his English Attacks (32 games, 2023-2025).}
+7... Be6 8. f3
+(8. Qd2 Nbd7 9. f3 h5 {Sideline he tried once and lost — probably patched.})
+8... Nbd7 9. Qd2 h5
+{Critical position for us. Lc0 at multipv=3 gives:
+ - h5: +0.12 (main line, active)
+ - Be7: +0.08 (calm, more classical)
+ - Rc8: 0.00 (Stockfish preferred)}
+
+*
+```
+
+The pieces:
+
+- **PGN tag pairs at the top** (`[Key "Value"]`) — `Event` is the name you show the user. `White` / `Black` set the game headers. `Date` is standard.
+- **Mainline** = your top recommendation. Numbered SAN moves separated by whitespace.
+- **Variations** in parentheses `(...)` at the branching move. Nesting is allowed but be conservative — three deep is a lot.
+- **Comments** in curly braces `{...}` between moves. This is where you cite tool output:
+  - `{Lc0 says +0.15 in this line vs 0.00 for the alternative}`
+  - `{Firouzja plays this in 32/47 games with Black. Scores 41%.}`
+  - `{Stockfish sees h4 as a tactical shot; Lc0 disagrees. Deep look needed.}`
+- **NAG glyphs** for evaluations at a move (optional): `$1` (!), `$2` (?), `$3` (!!), `$4` (??), `$6` (=), `$10` (=), `$14` (+/=). Placed right after the SAN: `7. Nb3 $1`.
+- **Result marker** at the end: `*` for unfinished (prep files are always unfinished), `1-0`, `0-1`, `1/2-1/2`.
+
+## Editing without breaking the tree
+
+You get the whole PGN back from `read_prep_file`, edit it in your head, send back via `save_prep_file`. There's no partial-patch API — small edits still resend the full text. The file is small (repertoire = maybe 5-20 KB), that's fine.
+
+Common LLM failure modes to catch yourself doing:
+
+- **Unbalanced parentheses.** Every `(` needs a matching `)`. Count them if you added variations. The backend parses on save; if invalid, you get 400 with the parser error and have to retry.
+- **Bad SAN.** `Nfd7` where you meant `Nbd7`. Always trace the position in your head (or use the tree from read_prep_file's response) before writing a move.
+- **Forgotten move numbers.** `1. e4 c5 2. Nf3` — after each White move you need `<num>.`, after each Black move the number continues implicitly until the next full move. In variations at Black's move, PGN wants `2... Nc6`.
+- **Nested variations losing context.** `1.e4 e5 (1...c5 (2.Nf3 d6))` — the inner variation branches at `2.Nf3` off the c5 sideline, not off the mainline. This gets confusing fast; two levels is usually enough.
+- **Blank Event tag** — the user's list_prep_files response shows the Event tag as the name. Empty tag = "Untitled" everywhere.
+
+## Optimistic locking
+
+`read_prep_file` returns a `version` integer. Pass it back as `expected_version` on `save_prep_file`. If someone else (the user in the app, or a parallel agent session) updated the file since you read it, save returns `409 Conflict` with the current version. You should:
+
+1. Re-read the file to see what changed.
+2. Merge your edits with theirs.
+3. Retry the save with the new version.
+
+If you don't pass `expected_version`, it's last-write-wins — you might silently overwrite the user's manual edits. Only skip it when you know the file is untouched (e.g. you just created it).
+
+## Grounding
+
+Same rule as everywhere else in this MCP: **cite tool output in your PGN comments, don't invent chess prose**. A prep file that reads "White has practical chances" without a tool call to back it up is worse than a file that says "TODO: run cloud_analyse here". The user can view the file; if the commentary doesn't match the actual engine output, they see it.
+
+Concrete pattern:
+
+```
+7. Nb3 {Lc0 at movetime=2000 gives +0.14 for White in the resulting IQP structure.
+Stockfish scores 0.00 — the disagreement is the long-term positional weight Lc0
+sees on the c6 pawn. Verified by running cloud_analyse at move 12 and confirming
+Lc0's evaluation persists.}
+```
+
+vs
+
+```
+7. Nb3 {A strong positional move that gives White good chances.}
+```
+
+The first is what earns trust; the second is what makes the file worthless.
+
+## Naming conventions
+
+For the [Event] tag (which is the user-visible file name):
+
+- Opponent prep: `"Prep vs <Player> (<Color>) — <YYYY-MM-DD>"`
+- Opening study: `"<Opening> — <side>"` e.g. `"Najdorf 6.Bg5 — Black side"`
+- Position analysis: `"<Position description> — <date>"`
+
+Keep it short enough to fit in a picker (30-40 chars). Long titles get truncated in the app UI.
+
+## When to create vs extend
+
+- User asks "prep me against X" and no file matches → create.
+- User asks "check line Y for our Firouzja prep" and a file matches → extend that file with new variations, save with expected_version.
+- User asks "I found a novelty in the Najdorf" and a Najdorf file exists → extend.
+- Rule of thumb: if the user's request semantically overlaps with an existing file's [Event] name or main opening line, extend.
+
+## Icons and appearance
+
+The user sees your files in a collection called "AI Prep" with a 🤖 icon under folder `/mcp` in their chess.ceo app. This is intentional — they can tell at a glance which prep came from you, and they can browse / edit / delete from the app just like their manual work. Your files are first-class citizens on their account.

package/package.json

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