@chessceo/mcp 0.42.0 → 0.44.0

package/dist/warnings.js

@@ -0,0 +1,121 @@
+// Anti-pattern scanners for LLM output + session-level tracking that
+// drives them. Every function returns either a string (the warning to
+// surface on the LLM's next tool response) or undefined (the mutation
+// looked fine). Callers append to a `warnings: string[]` field on the
+// response the LLM sees.
+//
+// Extracted from index.ts in v0.44. All prior v0.42/v0.42.1 behaviour
+// preserved bit-for-bit — this is a file split, not a rewrite.
+import { positionKey } from "./pgn/paths.js";
+import { ROOT_ID } from "./pgn/paths.js";
+// ── Session tracking sets ──────────────────────────────────────────
+//
+// Every one of these is per-process-lifetime memory (i.e. per-session
+// for stdio callers; per-server-instance for streamable-http). Not
+// persisted; a fresh MCP server starts empty. One MCP server process
+// per user in the common stdio case, so these are effectively per-user.
+// Positions the LLM has asked the DB about via `get_position_stats`.
+// Keyed by the 3-field FEN (piece placement + side to move + castling —
+// same key used for transposition detection). Used to warn on `add_move`
+// / `add_line` under a parent the LLM never DB-checked, which is the
+// exact shape of the bug where the LLM read course chapters and
+// cargo-culted a "mainline" that the actual games at the position don't
+// play.
+export 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.
+export const noStatsWarned = new Set();
+// 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.
+export const positionsDescribed = new Set();
+// Once-per-node dedup for the describe warning.
+export const noDescribeWarned = new Set();
+// ── Scanners ───────────────────────────────────────────────────────
+// 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, ...")
+//   - raw centipawn values in prose ("≈-60", "+0.35", "at depth 24")
+//   - long roster restatement ("146 GM games, Nakamura, Kramnik, MVL")
+// Return an array of warning strings — one per matched category — so the
+// LLM sees exactly which pattern to remove.
+export function commentAntiPatterns(comment) {
+    if (!comment || typeof comment !== "string")
+        return [];
+    const warns = [];
+    // Spread list: ≈ followed by a 2-3-digit number, appearing 2+ times
+    // (one appearance is a stray, two+ is a comma-separated spread the LLM
+    // pasted from stats output).
+    const spreadMatches = comment.match(/≈\s*[+\-−]?\d{1,3}/g) ?? [];
+    if (spreadMatches.length >= 2) {
+        warns.push("comment contains a spread list (≈ + counts) — the DB viewer already shows sibling counts and fashion scores next to every move, so this is doubled noise. Name the character of the choice instead (\"solid vs sharp\", \"old vs fashionable\") or drop the numbers.");
+    }
+    // Raw centipawn in prose: "+0.35", "-0.20", "+80" (not preceded by move
+    // number). Also "at depth N" or "N nodes" — engine metadata as prose.
+    if (/(?:^|[^\d.])[+-]\d\.\d\d(?!\d)/.test(comment) || /≈\s*[+\-−]?\d{2,3}\b/.test(comment) ||
+        /\bat depth \d+\b/i.test(comment) || /\b\d{2,3}M nodes\b/.test(comment)) {
+        warns.push("comment contains raw centipawn values or engine metadata — the app renders ceoEval + NAG glyph next to every node, so these numbers are doubled noise AND opaque (readers can't tell if ≈-60 means eval, spread, or something else). Set the NAG (set_nags) and let the glyph carry the judgment; drop the number from the prose.");
+    }
+    // Roster: "N GM games" pattern
+    if (/\b\d{2,4}\s+GM games\b/i.test(comment)) {
+        warns.push("comment restates game count — the app shows the count on hover. Either cite a specific game with signal (\"Caruana-Liang, Superbet 2026\") or drop the number.");
+    }
+    return warns;
+}
+// Return a warning string when an add_line is suspiciously long-and-linear
+// (the anti-pattern: LLM pastes a 15-ply engine PV into a single add_line
+// call as if it were prepared repertoire). Two thresholds so the message
+// escalates — a 10-ply Berlin mainline is fine, a 20-ply LLM extrapolation
+// almost never is. Threshold applies at the CALL level, not against
+// existing tree depth — the anti-pattern is a single tool call adding
+// many plies at once with no user thought about where the branching should
+// live.
+export function longLineWarning(sansLength) {
+    if (sansLength >= 14) {
+        return `you added ${sansLength} plies in one call without branching — this is the shape of a pasted engine PV, not a repertoire. Real prep branches at every ply where the opponent has meaningful alternatives. Either (a) delete the tail and rebuild with add_move at each decision point, calling cloud_analyse + get_position_stats to see what actually gets played, or (b) if this really is one forcing sequence (mate combination, tactical winner), add a comment naming what makes it forced. Long unbranched lines with no comment default to "engine PV pasted as prep" in the reader's eyes.`;
+    }
+    if (sansLength >= 9) {
+        return `${sansLength}-ply linear line — check that every ply is a genuine only-move or a documented mainline. If the opponent has real alternatives at any ply (get_position_stats would show 2+ moves with meaningful frequency), that ply should branch instead. Prep is a tree, not a line.`;
+    }
+    return undefined;
+}
+// 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.
+export 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
+// starting position doesn't need a DB check), (b) we already warned on
+// this parent (dedup so building a big branching subtree isn't spammy),
+// or (c) the mutator is running against a parent whose position has a
+// stored ceoEval (implies the LLM has done SOME analytical work here).
+export function noStatsCheckWarning(parent) {
+    if (parent.id === ROOT_ID)
+        return undefined;
+    const key = positionKey(parent.fen);
+    if (positionsStatsChecked.has(key))
+        return undefined;
+    if (noStatsWarned.has(parent.id))
+        return undefined;
+    noStatsWarned.add(parent.id);
+    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.`;
+}

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.44.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {