@chessceo/mcp 0.42.0 → 0.43.0

package/dist/index.js

@@ -73,8 +73,10 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "list_collections",
     "list_prep_files",
     "search_prep_files",
+    "find_position_in_files",
     "read_prep_file",
     "list_nodes",
     "list_transpositions",
@@ -174,6 +176,72 @@ async function authedRequest(method, path, body) {
     }
     return text.length ? JSON.parse(text) : null;
 }
+// ── Backend I/O layer ──────────────────────────────────────────────
+//
+// v0.43: MCP surface moved off the single-`/mcp`-folder model onto the
+// full user PGN library. LLM-facing tool ids are opaque composites of
+// the form `<collection_id>:<game_id>` so every existing tool that
+// takes `id` keeps taking `id` — the composite splits back into two
+// pieces at the HTTP layer. Backend routes live under
+// `/api/agent/pgns/*` (same handlers as `/me/pgns/*` browser routes;
+// a path-rewrite middleware in the server main.go maps the two).
+const PGN_BASE = "/api/agent/pgns";
+// Browser handlers wrap successful responses as
+//   { success: true, message: "...", data: <actual thing> }
+// via handlers.RespondSuccess. Peel that off; leave anything without
+// the envelope unchanged (some endpoints return raw bodies).
+function unwrap(raw) {
+    if (raw &&
+        typeof raw === "object" &&
+        "data" in raw &&
+        raw.success === true) {
+        return raw.data;
+    }
+    return raw;
+}
+// LLM-facing "prep file id" is always "<collection_id>:<game_id>" —
+// makeFileId to compose from a listing, splitFileId at the HTTP edge.
+function makeFileId(collectionId, gameId) {
+    return `${collectionId}:${gameId}`;
+}
+function splitFileId(id) {
+    const idx = id.indexOf(":");
+    if (idx <= 0 || idx === id.length - 1) {
+        throw new Error(`invalid prep file id "${id}" — expected "<collection_id>:<game_id>" ` +
+            `(get one from list_prep_files, search_prep_files, find_position_in_files, ` +
+            `or the create_prep_file return value)`);
+    }
+    return { collectionId: id.slice(0, idx), gameId: id.slice(idx + 1) };
+}
+// GET one game by composite id. Throws on 404.
+async function fetchGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+    const g = unwrap(raw);
+    if (!g || typeof g.pgnContent !== "string") {
+        throw new Error("prep file missing pgnContent");
+    }
+    return g;
+}
+// PUT the game body. Returns the saved game (new version).
+async function saveGame(id, pgn, expectedVersion) {
+    const { collectionId, gameId } = splitFileId(id);
+    const body = { pgnContent: pgn };
+    if (typeof expectedVersion === "number")
+        body.baseVersion = expectedVersion;
+    const raw = await authedRequest("PUT", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`, body);
+    return unwrap(raw);
+}
+// POST a new game into the given collection. Returns the created game.
+async function createGame(collectionId, pgn) {
+    const raw = await authedRequest("POST", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games`, { pgnContent: pgn });
+    return unwrap(raw);
+}
+// DELETE (soft) a game by composite id.
+async function deleteGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    await authedRequest("DELETE", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+}
 // ── Tool definitions ───────────────────────────────────────────────
 //
 // Descriptions are written for the LLM, not humans — they should hint
@@ -332,7 +400,8 @@ const TOOLS = [
     },
     {
         name: "describe_position",
-        description: "Everything you need to understand a position in one call. USE BEFORE COMMENTING — pieces get misplaced when reading a FEN, hanging pieces missed, 'the knight on d5' turns out to not exist. ~50-100 ms per call (chess-primitive analysis is instant; the Stockfish leg dominates wall time).\n\n" +
+        description: "**CALL WHEN**: about to write ANY comment on a position that describes what's happening on the board — piece activity, structure, plans, weaknesses. This is the single biggest lever for prose quality in the whole system. Live audit: nodes where describe_position was called first produced comments grounded specifically in the position (correct piece squares, real pawn structure, actual weak squares); nodes where it wasn't produced generic pattern-matched prose that confidently named pieces on wrong squares. `set_comment` now emits a warning whenever a substantive comment lands on a node whose position was never grounded via describe_position this session — that warning is telling you to fix a class of hallucination that already showed up in your output. Cheap: chess-primitive analysis is instant, Stockfish leg is ~50-100 ms, no billing.\n\n" +
+            "Everything you need to understand a position in one call. Pieces get misplaced when reading a FEN, hanging pieces missed, 'the knight on d5' turns out to not exist.\n\n" +
             "Returns three layers:\n\n" +
             "**Board state** — piece placements per colour, material balance in pawn units, contested pieces (attackers + defenders), hanging pieces, checkers if in check, castling rights, en passant, side to move, full LEGAL MOVES list. Use `.legalMoves` when `add_move` rejects an illegal SAN.\n\n" +
             "**Structural analysis** — chess-concept observations a human sees at a glance:\n" +
@@ -533,13 +602,27 @@ const TOOLS = [
         },
     },
     {
-        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.",
+        name: "list_collections",
+        description: "List the user's own PGN collections — every collection they've created, not just prep files. Response: `{collections: [{id, title, icon, folder_path, game_count, updated_at, position_search_enabled}]}`.\n\n" +
+            "**Call this before create_prep_file** — the LLM must pick a collection to write into (no default landing folder any more; the old hidden `/mcp` collection was retired in v0.43). Also useful when the user asks a position-shaped question — LLM can then run find_position_in_files to see which of these collections already covers the position.\n\n" +
+            "Encrypted collections (client-side-encrypted PGN) are excluded — the server can't read their contents, so they'd be dead weight on this surface.",
         inputSchema: { type: "object", properties: {} },
     },
+    {
+        name: "list_prep_files",
+        description: "List the games (prep files) inside one of the user's collections. **Requires `collection_id`** — call `list_collections` first if you don't have one. Returns id (composite `<collection_id>:<game_id>`, opaque to the LLM — pass as-is to read_prep_file / mutation tools), PGN header fields, updated_at.\n\n" +
+            "For cross-collection discovery use `search_prep_files` (text) or `find_position_in_files` (position); list_prep_files is the browse-one-collection tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection_id: { type: "string", description: "Collection id from list_collections. Required." },
+            },
+            required: ["collection_id"],
+        },
+    },
     {
         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').",
+        description: "Text search over the user's prep files ACROSS ALL their collections (matches PGN headers, comments, and content). Use when you know a keyword — e.g. search_prep_files(query='Firouzja') or search_prep_files(query='Najdorf'). Cheaper than paging list_collections + list_prep_files to find one file by name.",
         inputSchema: {
             type: "object",
             properties: {
@@ -548,6 +631,22 @@ const TOOLS = [
             required: ["query"],
         },
     },
+    {
+        name: "find_position_in_files",
+        description: "Position search across every one of the user's EDITABLE prep files (all their non-encrypted collections). Given a FEN, returns which of the user's files reach that exact position (or a transposition of it — matched by zobrist hash, so move-order variants are found automatically). Recency-sorted.\n\n" +
+            "Distinct from `find_position_in_courses`: courses are READ-ONLY reference material (Chessable PGNs, downloaded backups); this searches the user's OWN editable prep. Common workflow: user asks about a position → call this first to see if their existing prep covers it → if yes, extend that file; if no, consider whether to start new prep.\n\n" +
+            "Position input: `file_id`+`node_id` (from an already-open prep file), or `fen`, or `moves` from startpos, or `fen`+`moves`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file_id: { type: "string", description: "Prep file id. With `node_id`, derives FEN from the tree." },
+                node_id: { type: "string", description: "Node id inside `file_id`. Root is 'r'." },
+                fen: { type: "string", description: "Position as FEN. Only used if `file_id`/`node_id` not set." },
+                moves: { type: "string", description: "SAN moves from startpos (or on top of fen)." },
+                line: { type: "string", description: "Alias for moves." },
+            },
+        },
+    },
     {
         name: "read_prep_file",
         description: "Read one prep file. Response always includes `id`, `version`, `tags`. The tree/PGN part is controlled by `view` and `node_id`/`max_depth` — large files (500+ nodes) can otherwise blow the LLM's token limit.\n\n" +
@@ -611,17 +710,23 @@ const TOOLS = [
     },
     {
         name: "create_prep_file",
-        description: "Create a new (empty) prep file. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
-            "ALWAYS call list_prep_files (or search_prep_files with the opponent / opening keyword) FIRST — creating a duplicate 'Prep vs Firouzja' when one exists is the #1 LLM failure mode. If a file already covers the topic, add moves to that one instead.",
+        description: "Create a new (empty) prep file in the specified collection. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +
+            "**collection_id is REQUIRED** — call `list_collections` first to pick where it lives. There is no default landing folder any more (v0.43: the old hidden `/mcp` collection was removed; prep files now live wherever the user organizes them).\n\n" +
+            "**Duplicate-check first.** Call `search_prep_files(query=<opponent / opening keyword>)` OR `find_position_in_files(fen=...)` before creating — a second 'Prep vs Firouzja' file when one already exists is a common LLM failure mode. If a file already covers the topic, extend that one instead.\n\n" +
+            "Response: `{ok, id, collection_id, version}` — `id` is a composite you pass to every other prep-file tool as `id` or `file_id`.",
         inputSchema: {
             type: "object",
             properties: {
+                collection_id: {
+                    type: "string",
+                    description: "Collection id from list_collections. Required — this is where the new file lands.",
+                },
                 name: {
                     type: "string",
                     description: "User-facing name — becomes the [Event] tag. Example: 'Prep vs Firouzja (Black) 2026-07-23'.",
                 },
             },
-            required: ["name"],
+            required: ["collection_id", "name"],
         },
     },
     {
@@ -668,7 +773,10 @@ const TOOLS = [
     },
     {
         name: "set_comment",
-        description: "Set (or clear, with empty string) the text comment on the node identified by `node_id`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.",
+        description: "Set (or clear, with empty string) the text comment on the node identified by `node_id`. Comments are for plans, prep-signal, and interpretation the app can't derive — NOT for describing moves that should be variations instead. Auto-saves.\n\n" +
+            "**Two guardrails fire in the response as `warnings: [...]`:**\n" +
+            "  1. **Content scan** — comments containing spread lists (`≈50, ≈42, …`), raw centipawn values (`≈−60`, `+0.35`, `at depth 24`), or roster restatement (`146 GM games — Nakamura, …`) are all restating what the app already renders. The warning names the fix (set the NAG and drop the number; label the character not the numbers; cite a specific game instead of a count).\n" +
+            "  2. **Ungrounded prose** — substantive comments (≥40 chars) on a node whose position was never passed to `describe_position` this session are prone to hallucinated structural claims (piece on wrong square, invented captures, misidentified pawn structure). Call `describe_position` with `file_id`+`node_id` BEFORE writing prose about the position; the same node's warning clears once the position is described.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1092,6 +1200,16 @@ const positionsStatsChecked = new Set();
 // Nodes we've ALREADY warned on for the "no stats check" pattern this
 // session, so repeated adds under the same parent don't spam the LLM.
 const noStatsWarned = new Set();
+// Session-lifetime memory of positions the LLM has called
+// `describe_position` on. Same 3-field FEN key. Live-log audit
+// (2026-07-27 Modern Defence session): 13 describe_position calls
+// vs 50+ set_comment ops — most comments were written blind. When
+// describe_position IS called before commentary, prose accuracy
+// jumps sharply (user's own observation). This tracks the same way
+// as positionsStatsChecked and drives the noDescribeWarning below.
+const positionsDescribed = new Set();
+// Once-per-node dedup for the describe warning.
+const noDescribeWarned = new Set();
 // Detect the anti-patterns the LLM keeps producing in comment prose.
 // All of these restate what the app already renders elsewhere:
 //   - spread lists ("5.O-O ≈50, 6.h3 ≈42, ...")
@@ -1229,8 +1347,12 @@ function dispatchMutation(file, idIndex, op) {
         case "set_comment": {
             const commentStr = typeof op.comment === "string" ? op.comment : "";
             const commentWarns = commentAntiPatterns(commentStr);
-            const step = setComment(file, resolve(nodeIdField("node_id")), commentStr);
-            return { ...step, ...(commentWarns.length > 0 ? { warnings: commentWarns } : {}) };
+            const targetPath = resolve(nodeIdField("node_id"));
+            const targetNode = getNodeByPath(file.root, targetPath);
+            const describeWarn = noDescribeWarning(targetNode, commentStr);
+            const step = setComment(file, targetPath, commentStr);
+            const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
+            return { ...step, ...(all.length > 0 ? { warnings: all } : {}) };
         }
         case "set_nags":
             return setNags(file, resolve(nodeIdField("node_id")), Array.isArray(op.nags) ? op.nags.map(String) : []);
@@ -1263,10 +1385,7 @@ async function applyBatchMutations(args) {
     const mutations = Array.isArray(args.mutations) ? args.mutations : [];
     if (mutations.length === 0)
         throw new Error("mutations array required");
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     let file = parsePGN(g.pgnContent);
     let idIndex = buildIdIndex(file.root);
     const results = [];
@@ -1290,12 +1409,8 @@ async function applyBatchMutations(args) {
     }
     const newPgn = exportPGN(file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
-    const saved = await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
-        pgn: newPgn,
-        expected_version: expected,
-    });
-    const savedRow = saved;
-    return { ok: true, results, version: savedRow.version };
+    const saved = await saveGame(id, newPgn, expected);
+    return { ok: true, results, version: saved.version };
 }
 const evalJobs = new Map();
 // GC finished jobs after this long so status polling remains useful
@@ -1330,10 +1445,7 @@ async function autoEvaluate(args) {
         : ROOT_ID;
     const onlyMissing = args.only_missing !== false; // default true
     const movetimeMs = typeof args.movetime_ms === "number" ? args.movetime_ms : 1500;
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     const file = parsePGN(g.pgnContent);
     const idIndex = buildIdIndex(file.root);
     const startPath = resolveNodeId(idIndex, startNodeId);
@@ -1946,10 +2058,7 @@ function storedEvalToCompact(ev, analysis) {
 // resolve node_ids without rebuilding the index itself.
 async function applyMutation(args, mutator) {
     const id = String(args.id);
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
+    const g = await fetchGame(id);
     const file = parsePGN(g.pgnContent);
     const idIndex = buildIdIndex(file.root);
     let result;
@@ -1964,20 +2073,36 @@ async function applyMutation(args, mutator) {
     }
     const newPgn = exportPGN(result.file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
-    const saved = await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(id)}`, {
-        pgn: newPgn,
-        expected_version: expected,
-    });
-    const savedRow = saved;
+    const saved = await saveGame(id, newPgn, expected);
     return {
         ok: true,
         node_id: result.id,
         ...(result.results !== undefined ? { line: result.results } : {}),
         ...(result.warning ? { warning: result.warning } : {}),
         ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
-        version: savedRow.version,
+        version: saved.version,
     };
 }
+// Compute the "you never called describe_position on this node" warning.
+// Fires from set_comment when the comment is substantive (>= 40 chars —
+// anything shorter is a label / pointer, doesn't need structural
+// grounding). LLMs are unreliable at reading FEN strings and confidently
+// describe positions that don't match the actual board; describe_position
+// is a pure-computation grounding pass that reliably fixes this. Warn
+// once per node.
+function noDescribeWarning(node, comment) {
+    if (node.id === ROOT_ID)
+        return undefined;
+    if (comment.length < 40)
+        return undefined;
+    const key = positionKey(node.fen);
+    if (positionsDescribed.has(key))
+        return undefined;
+    if (noDescribeWarned.has(node.id))
+        return undefined;
+    noDescribeWarned.add(node.id);
+    return `substantive comment (${comment.length} chars) on a node whose position was never grounded via describe_position this session (id=${node.id}, ${node.san}). LLMs invent captures, miscount pieces, and swap files/ranks when reading FEN strings — describe_position is a pure-computation pass (~1 ms, no engine cost, structural facts + Stockfish's per-term eval breakdown) that reliably prevents this class of hallucination. In live audits, prose accuracy jumps sharply on nodes where describe_position was called first. Call describe_position with file_id+node_id=${node.id} BEFORE writing prose. Warned once per node.`;
+}
 // Compute the "you never DB-checked this parent" warning. Called from
 // add_move / add_line handlers with the parent node. Returns undefined
 // when either (a) the parent was checked this session (or is root — the
@@ -1997,11 +2122,11 @@ function noStatsCheckWarning(parent) {
     return `no get_position_stats call for the parent (id=${parent.id}, ${parent.san}) this session. Course chapter titles describe what an author chose to cover, not what practical opponents play — treating "the So chapter says 6.O-O-O" as "the mainline is 6.O-O-O" is the exact pattern this warning exists to catch. Call get_position_stats at this position (via file_id+node_id=${parent.id}) BEFORE deciding which branches belong here; suppress this warning by making that call. Warned once per parent per session.`;
 }
 async function loadPrepFile(id) {
-    const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(id)}`);
-    const g = raw;
-    if (typeof g.pgnContent !== "string")
-        throw new Error("prep file missing pgnContent");
-    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: g.id, pgn: g.pgnContent };
+    const g = await fetchGame(id);
+    // Echo the composite id back so read_prep_file responses match the
+    // exact id the LLM passed in. The backend returns the raw game_id;
+    // recompose so the LLM never sees the split form.
+    return { file: parsePGN(g.pgnContent), version: g.version, fileIdEcho: id, pgn: g.pgnContent };
 }
 // Recursively project a PrepNode into the requested view. `depthLeft`
 // null → unlimited; 0 → just the node without children.
@@ -2053,6 +2178,91 @@ function projectNode(node, view, depthLeft, fenIndex = null) {
     }
     return base;
 }
+async function listCollections(_args) {
+    const raw = await authedRequest("GET", PGN_BASE);
+    const collections = unwrap(raw) ?? [];
+    return {
+        collections: collections.map(c => ({
+            id: c.id,
+            title: c.title,
+            icon: c.icon,
+            folder_path: c.folderPath,
+            game_count: c.gameCount,
+            position_search_enabled: c.positionSearchEnabled,
+            updated_at: c.updatedAt,
+        })),
+    };
+}
+// Convert a browser-returned game list row into the LLM shape (composite
+// id, cleaned field names).
+function projectGameRow(row) {
+    const collId = row.collectionId ?? "";
+    return {
+        id: collId ? makeFileId(collId, row.id) : row.id,
+        collection_id: collId,
+        collection_title: row.collectionTitle,
+        event: row.event,
+        white: row.white_player,
+        black: row.black_player,
+        eco: row.eco,
+        opening: row.opening,
+        updated_at: row.updated_at,
+        ply: row.ply,
+    };
+}
+async function listPrepFiles(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to see your options, or search across collections with search_prep_files / find_position_in_files");
+    }
+    // Browser handler at GET /me/pgns/{id}/games returns a paginated list.
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games?page=1&limit=200`);
+    const data = unwrap(raw);
+    const games = data?.games ?? (Array.isArray(data) ? data : []);
+    return { collection_id: collectionId, prep_files: games.map(projectGameRow) };
+}
+async function searchPrepFiles(args) {
+    const q = typeof args.query === "string" ? args.query.trim() : "";
+    if (!q)
+        throw new Error("query required");
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?q=${encodeURIComponent(q)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return { query: q, prep_files: games.map(projectGameRow) };
+}
+async function findPositionInFiles(args) {
+    // FEN can come from a node handle OR a direct fen/moves/line. Reuse
+    // the same resolver everything else uses.
+    const resolved = await resolveFromNodeOrFen(args);
+    const fen = resolved.fen;
+    const raw = await authedRequest("GET", `${PGN_BASE}/games/search?position=${encodeURIComponent(fen)}&limit=100`);
+    const data = unwrap(raw);
+    const games = data?.games ?? [];
+    return {
+        fen,
+        match_count: games.length,
+        prep_files: games.map(projectGameRow),
+    };
+}
+async function createPrepFile(args) {
+    const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
+    if (!collectionId) {
+        throw new Error("collection_id required — call list_collections to pick where the new file lives. There is no default landing folder any more (v0.43: the old hidden /mcp collection was removed).");
+    }
+    const name = String(args.name || "").trim();
+    if (!name)
+        throw new Error("name is required");
+    // Seed with a PGN carrying the LLM-chosen name as the Event tag so
+    // subsequent list_prep_files calls display something useful.
+    const seedPgn = `[Event "${name.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"]\n\n*\n`;
+    const game = await createGame(collectionId, seedPgn);
+    return {
+        ok: true,
+        id: makeFileId(game.collectionId ?? collectionId, game.id),
+        collection_id: game.collectionId ?? collectionId,
+        version: game.version,
+    };
+}
 async function readPrepFile(args) {
     const id = String(args.id);
     const view = (typeof args.view === "string" && ["compact", "full", "spine", "pgn"].includes(args.view))
@@ -2429,10 +2639,7 @@ async function resolveFromNodeOrFen(args) {
     const fileId = typeof args.file_id === "string" ? args.file_id.trim() : "";
     const nodeId = typeof args.node_id === "string" ? args.node_id.trim() : "";
     if (fileId && nodeId) {
-        const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-        const g = raw;
-        if (typeof g.pgnContent !== "string")
-            throw new Error("prep file missing pgnContent");
+        const g = await fetchGame(fileId);
         const parsedFile = parsePGN(g.pgnContent);
         const idIndex = buildIdIndex(parsedFile.root);
         const nodePath = resolveNodeId(idIndex, nodeId);
@@ -2448,18 +2655,15 @@ async function resolveFromNodeOrFen(args) {
         // node_id had been supplied (auto-persist on match).
         const fen = resolveFenFromArgs(args);
         try {
-            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-            const g = raw;
-            if (typeof g.pgnContent === "string") {
-                const parsedFile = parsePGN(g.pgnContent);
-                const match = findNodeByFen(parsedFile.root, fen);
-                if (match) {
-                    const idIndex = buildIdIndex(parsedFile.root);
-                    return {
-                        fen,
-                        file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
-                    };
-                }
+            const g = await fetchGame(fileId);
+            const parsedFile = parsePGN(g.pgnContent);
+            const match = findNodeByFen(parsedFile.root, fen);
+            if (match) {
+                const idIndex = buildIdIndex(parsedFile.root);
+                return {
+                    fen,
+                    file: { id: fileId, version: g.version ?? 0, parsedFile, idIndex, nodePath: match.path, fen },
+                };
             }
         }
         catch {
@@ -2520,10 +2724,7 @@ async function storeEvalOnNode(handle, ev) {
         const paths = group.map(n => resolveNodeId(idIndex, n.id));
         const { file: newFile, ids } = setCeoEvalMany(handle.parsedFile, paths, ev);
         const newPgn = exportPGN(newFile);
-        await authedRequest("PUT", `/api/agent/prep-files/${encodeURIComponent(handle.id)}`, {
-            pgn: newPgn,
-            expected_version: handle.version,
-        });
+        await saveGame(handle.id, newPgn, handle.version);
         // Ensure the primary node (the one the LLM addressed) comes first.
         const anchorId = anchor.id;
         return [anchorId, ...ids.filter(x => x !== anchorId)];
@@ -2687,6 +2888,10 @@ async function callToolInner(name, args) {
             if (ev && ev.found === true) {
                 merged.engineEvalTerms = { terms: ev.terms, total: ev.total };
             }
+            // Record so set_comment on this node won't fire the "not described"
+            // warning. Keyed by 3-field FEN so a described position is
+            // credited across its transpositions too.
+            positionsDescribed.add(positionKey(resolved.fen));
             return merged;
         }
         case "predict_human_move": {
@@ -2807,10 +3012,14 @@ async function callToolInner(name, args) {
             return findPositionInCourses(args);
         case "read_course_at_position":
             return readCourseAtPosition(args);
+        case "list_collections":
+            return listCollections(args);
         case "list_prep_files":
-            return authedRequest("GET", "/api/agent/prep-files");
+            return listPrepFiles(args);
         case "search_prep_files":
-            return authedRequest("GET", `/api/agent/prep-files/search?q=${encodeURIComponent(String(args.query))}`);
+            return searchPrepFiles(args);
+        case "find_position_in_files":
+            return findPositionInFiles(args);
         case "read_prep_file":
             return readPrepFile(args);
         case "list_nodes":
@@ -2818,11 +3027,11 @@ async function callToolInner(name, args) {
         case "list_transpositions":
             return listTranspositions(args);
         case "create_prep_file":
-            return authedRequest("POST", "/api/agent/prep-files", {
-                name: String(args.name),
-            });
-        case "delete_prep_file":
-            return authedRequest("DELETE", `/api/agent/prep-files/${encodeURIComponent(String(args.id))}`);
+            return createPrepFile(args);
+        case "delete_prep_file": {
+            await deleteGame(String(args.id));
+            return { ok: true };
+        }
         case "add_move":
             return applyMutation(args, (file, idIndex) => {
                 const parentPath = resolveNodeId(idIndex, argNodeId(args, "parent_id"));
@@ -2853,10 +3062,14 @@ async function callToolInner(name, args) {
             const commentStr = typeof args.comment === "string" ? args.comment : "";
             const commentWarns = commentAntiPatterns(commentStr);
             return applyMutation(args, (file, idIndex) => {
-                const step = setComment(file, resolveNodeId(idIndex, argNodeId(args)), commentStr);
+                const targetPath = resolveNodeId(idIndex, argNodeId(args));
+                const targetNode = getNodeByPath(file.root, targetPath);
+                const describeWarn = noDescribeWarning(targetNode, commentStr);
+                const step = setComment(file, targetPath, commentStr);
+                const all = [...commentWarns, ...(describeWarn ? [describeWarn] : [])];
                 return {
                     ...step,
-                    ...(commentWarns.length > 0 ? { warnings: commentWarns } : {}),
+                    ...(all.length > 0 ? { warnings: all } : {}),
                 };
             });
         }
@@ -2890,10 +3103,7 @@ async function callToolInner(name, args) {
         case "quote_engine_eval": {
             const fileId = String(args.id);
             const nodeId = argNodeId(args);
-            const raw = await authedRequest("GET", `/api/agent/prep-files/${encodeURIComponent(fileId)}`);
-            const g = raw;
-            if (typeof g.pgnContent !== "string")
-                throw new Error("prep file missing pgnContent");
+            const g = await fetchGame(fileId);
             const file = parsePGN(g.pgnContent);
             const idIndex = buildIdIndex(file.root);
             const path = resolveNodeId(idIndex, nodeId);

package/docs/pgn-authoring.md

@@ -316,7 +316,9 @@ Contempt scale is signed 0-100 (same as the web UI's ContemptStrength slider). T
 
 ### Before you write any commentary: describe_position
 
-LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position(fen)`. Pure computation (~1 ms, no engine), returns two layers:
+**This is the biggest lever for prose quality in the whole system.** Live audit of a recent session — 13 `describe_position` calls versus 50+ `set_comment` ops. The nodes where `describe_position` was called first produced comments that grounded specifically in the position (correct piece squares, real pawn structure, actual weak squares). The nodes where it wasn't produced generic prose that pattern-matched to similar-*looking* positions and confidently named pieces on wrong squares. This gap is why `set_comment` now emits a warning whenever a substantive comment (≥40 chars) lands on a node whose position was never grounded via `describe_position` this session.
+
+LLMs are not reliable at reading FEN strings — you'll swap files/ranks, invent captures, miscount pieces. Before you write a comment describing what's happening in a position, call `describe_position` (with `file_id`+`node_id` inside a prep file). Pure computation (~1 ms, no engine), returns two layers:
 
 **Board state** — piece placements, material, contested pieces (attackers + defenders), hanging list, check state, castling, en passant, legal moves. Fixes the *"Black's queen on c7 is defended by the knight on d5"* failure when actually there's no knight on d5 and the queen is on c8.
 

package/docs/prep-files-guide.md

@@ -4,16 +4,23 @@ You can save chess prep to the user's chess.ceo account and read it back across
 
 ## 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.
+The user has **any number of PGN collections** in their chess.ceo library — you have full access to every non-encrypted one. A **prep file** is one PGN game with variations, inside a collection. Every prep file id is a composite `<collection_id>:<game_id>` — opaque to you, pass it through unchanged to any tool that takes `id` or `file_id`.
 
-File-level tools:
+Discovery tools:
 
-- `list_prep_files` — show me all my prep files
-- `search_prep_files(query)` — find by opponent name / opening keyword
-- `read_prep_file(id)` — parsed tree (every node carries a stable `id`) + tags + `version`
-- `create_prep_file(name)` — new empty file, `name` becomes the [Event] tag
+- `list_collections` — show me all the user's collections (their organizational scheme is theirs; browse before creating)
+- `list_prep_files(collection_id)` — the games inside one collection
+- `search_prep_files(query)` — text search across ALL of the user's collections
+- `find_position_in_files(fen)` — position search across ALL of the user's collections (matched by zobrist hash so move-order variants are found automatically). Distinct from `find_position_in_courses` — that's the user's read-only reference library (Chessable etc.); this is their own editable prep
+
+Per-file tools:
+
+- `read_prep_file(id)` — parsed tree (every node carries a stable content-derived `id`) + tags + `version`
+- `create_prep_file(collection_id, name)` — new empty file inside the given collection, `name` becomes the [Event] tag
 - `delete_prep_file(id)` — soft delete (user can restore from app)
 
+**No default landing folder.** v0.43 removed the old hidden `/mcp` collection — prep files now live wherever the user organizes them. Every `create_prep_file` call REQUIRES `collection_id`; call `list_collections` first if you don't have one. Permanent delete is not exposed on this surface — the user does that from the app.
+
 Mutation tools (edit an existing file — you never touch raw PGN):
 
 - `apply_mutations(id, [...])` — batch: N ops in one save. **Primary build tool.**
@@ -25,11 +32,12 @@ Every mutation call takes a `node_id` (or `parent_id` for add-style ops) and aut
 
 **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)
+1. **Text search first**: `search_prep_files(query=<opponent name or opening keyword>)` — searches across every collection the user owns.
+2. **Position search when the request is position-shaped** ("prep me against 6.f3 in the Najdorf"): `find_position_in_files(fen=<the specific tabiya>)` — catches files that reach the position via a different move order too. This is often more accurate than text search because file names don't always mention every position they cover.
+3. Read the ones that look relevant.
+4. Decide: extend an existing one or genuinely start fresh (`create_prep_file(collection_id, name)`).
 
-Duplicate files are the #1 way to lose your user's trust in this system.
+Duplicate files are the #1 way to lose your user's trust in this system. Two searches (text + position) cost roughly nothing and catch nearly all overlap.
 
 ## Before writing any prose: read the examples
 
@@ -107,6 +115,8 @@ Keep it short enough to fit in a picker (30-40 chars). Long titles get truncated
 - 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
+## Appearance
+
+Prep files land in whichever collection the user picked (via `create_prep_file(collection_id, name)`). They're first-class citizens in that collection — the user can browse, edit, share, or delete them from the app exactly like manually-created games. Your only visibility signal is the [Event] tag; make it descriptive.
 
-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.
+The `/mcp` "AI Prep" hidden folder from earlier versions no longer exists. If the user has a collection literally named "AI Prep" it's one they created themselves.

package/package.json

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