@chessceo/mcp 0.12.0 → 0.16.0

package/dist/index.js

@@ -185,11 +185,15 @@ const TOOLS = [
                 },
                 line: {
                     type: "string",
-                    description: "Move sequence in SAN, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for the starting position.",
+                    description: "Move sequence in SAN from the starting position, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for startpos. Alias: `moves` (same thing).",
+                },
+                moves: {
+                    type: "string",
+                    description: "SAN moves to apply on top of `fen` (or on top of startpos if no fen). Same shape as `line`. Use this when you have a starting FEN and want to walk from there — e.g. fen='<game tabiya>', moves='b4 a5 c3' to explore that continuation. Wins over `line` if both are set.",
                 },
                 fen: {
                     type: "string",
-                    description: "Alternative to `line` — raw FEN of the target position.",
+                    description: "Starting position as FEN. Combine with `moves` to walk from there, or use alone.",
                 },
                 limit: {
                     type: "integer",
@@ -210,7 +214,15 @@ const TOOLS = [
             properties: {
                 fen: {
                     type: "string",
-                    description: "FEN of the position to look up.",
+                    description: "Starting position as FEN. Combine with `moves` to walk from there.",
+                },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5'.",
+                },
+                line: {
+                    type: "string",
+                    description: "Synonym for `moves` from the starting position; kept for compatibility.",
                 },
                 limit: {
                     type: "integer",
@@ -219,18 +231,22 @@ const TOOLS = [
                     description: "Number of top continuations to return.",
                 },
             },
-            required: ["fen"],
         },
     },
     {
         name: "analyse",
-        description: "Short Stockfish evaluation at a position. Returns the top-N candidate moves with score (centipawns from side-to-move POV, positive = advantage; or mate distance) and the principal variation for each. Defaults: 2s think time, top-3 lines. PV moves come back in UCI notation (e2e4, not e4). Free (no cloud instance needed) — use liberally.\n\n" +
+        description: "Short Stockfish evaluation at a position. Returns the top-N candidate moves with score (centipawns from side-to-move POV, positive = advantage; or mate distance) and the principal variation for each. Defaults: 2s think time, top-3 lines. PV moves come back in SAN (e4, Nf3, Bxc4 — not UCI). Free (no cloud instance needed) — use liberally.\n\n" +
             "GROUNDING: cite this tool's actual output when you claim things about positions. Don't invent evaluations from general principles or training data — if you don't have engine output for a FEN, call this. Compute is cheap.\n\n" +
+            "Position input is flexible — pass `fen`, or `moves` from startpos, or `fen + moves` to walk from an arbitrary position. Also see the flip-side-to-move threat check in read_engine_usage_guide.\n\n" +
             "Use this to sanity-check candidate lines from get_position_stats or get_player_preparation — human game frequency tells you what people play, engine evaluation tells you what's actually good.",
         inputSchema: {
             type: "object",
             properties: {
-                fen: { type: "string", description: "FEN of the position to analyse." },
+                fen: { type: "string", description: "Starting position as FEN (defaults to startpos)." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5'.",
+                },
                 movetime_ms: {
                     type: "integer",
                     minimum: 100,
@@ -244,7 +260,6 @@ const TOOLS = [
                     description: "Number of candidate lines to return (default 3).",
                 },
             },
-            required: ["fen"],
         },
     },
     {
@@ -338,12 +353,17 @@ const TOOLS = [
             "• Lc0 is practical eval — trust it for 'which side is easier?' 'which candidate is best when Stockfish shows several as equal?' Lc0 sees long-term positional factors Stockfish's fixed search can miss.\n" +
             "• When they agree → high confidence. When they disagree → look at both scores and reason WHY (Stockfish sharply higher = tactic Lc0 missed; Lc0 higher = long-term positional edge past Stockfish's horizon). Never dismiss either — the disagreement is the signal.\n\n" +
             "Contempt (`contempt`) skews Lc0 (only Lc0 — Stockfish always stays objective) toward White (positive) or Black (negative). Practical range -20..+20. Use it to find non-objective 'practical' ideas or when the user needs to steer toward fighting/solid lines with a specific colour. Do NOT quote a contempt-biased eval as objective — cross-check with Stockfish.\n\n" +
+            "Also useful: pass `moves` on top of `fen` to explore a variation without computing FENs yourself (e.g. fen='<tabiya>', moves='b4 a5 c3'). And the flip-side-to-move threat check documented in the guide is a great free trick.\n\n" +
             "For the full guide including worked examples, call the `read_engine_usage_guide` tool.\n\n" +
             "Not for casual questions — this costs real money per second. Use the free `analyse` tool (single Stockfish, 2s) or `get_position_stats` for anything that doesn't require deep prep.",
         inputSchema: {
             type: "object",
             properties: {
-                fen: { type: "string", description: "FEN of the position to analyse." },
+                fen: { type: "string", description: "Starting position as FEN. Combine with `moves` to walk from there." },
+                moves: {
+                    type: "string",
+                    description: "Optional SAN moves to apply on top of `fen` (or on top of startpos). Example: fen='<tabiya>', moves='b4 a5 c3' analyses the position after those three moves.",
+                },
                 movetime_ms: {
                     type: "integer",
                     minimum: 100,
@@ -404,6 +424,135 @@ const TOOLS = [
 // capped so the two doc-reading tools (~5-10 KB of static markdown each)
 // don't drown the log stream.
 const LOG_MAX_CHARS = 4096;
+// Convert a UCI move sequence into SAN by walking it move-by-move on
+// chess.js from the given starting FEN. LLMs reason far better in SAN
+// ("Nf3", "Bxc4") than UCI ("g1f3", "b5c4"), and matches how prep
+// discussion is written in the real world. If a move fails to parse
+// (illegal from the current position — bug or truncated PV), we
+// truncate cleanly rather than throwing so the response still carries
+// what we could convert.
+function uciLineToSAN(startFen, uciMoves) {
+    const board = new Chess(startFen);
+    const out = [];
+    for (const uci of uciMoves) {
+        if (uci.length < 4)
+            break;
+        try {
+            const move = board.move({
+                from: uci.slice(0, 2),
+                to: uci.slice(2, 4),
+                promotion: uci.length >= 5 ? uci[4] : undefined,
+            });
+            if (!move)
+                break;
+            out.push(move.san);
+        }
+        catch {
+            break;
+        }
+    }
+    return out;
+}
+function uciMoveToSAN(startFen, uci) {
+    if (!uci || uci.length < 4)
+        return uci;
+    const board = new Chess(startFen);
+    try {
+        const move = board.move({
+            from: uci.slice(0, 2),
+            to: uci.slice(2, 4),
+            promotion: uci.length >= 5 ? uci[4] : undefined,
+        });
+        return move ? move.san : uci;
+    }
+    catch {
+        return uci;
+    }
+}
+// Rewrite the local /chess/database/analyse response (single engine)
+// so PVs come back in SAN.
+function convertAnalyseResponse(raw, startFen) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const r = raw;
+    if (Array.isArray(r.lines)) {
+        for (const line of r.lines) {
+            if (Array.isArray(line.pv))
+                line.pv = uciLineToSAN(startFen, line.pv);
+        }
+    }
+    return raw;
+}
+// Rewrite the /api/agent/cloud-engines/analyse response (two engines,
+// each with lines[] and a bestMove) so PVs and bestMove come back in SAN.
+function convertCloudSnapshotResponse(raw, startFen) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const r = raw;
+    for (const eng of [r.stockfish, r.lc0]) {
+        if (!eng)
+            continue;
+        if (Array.isArray(eng.lines)) {
+            for (const line of eng.lines) {
+                if (Array.isArray(line.pv))
+                    line.pv = uciLineToSAN(startFen, line.pv);
+            }
+        }
+        if (typeof eng.bestMove === "string")
+            eng.bestMove = uciMoveToSAN(startFen, eng.bestMove);
+    }
+    return raw;
+}
+// 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
+// response through unchanged if there's no availableMoves array.
+function convertAvailableMovesToSAN(raw, fen) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const r = raw;
+    if (!Array.isArray(r.availableMoves))
+        return raw;
+    for (const m of r.availableMoves) {
+        if (typeof m.move === "string" && m.move.length >= 4) {
+            m.move = uciMoveToSAN(fen, m.move);
+        }
+    }
+    return raw;
+}
+// Resolve a starting FEN from any combination of `fen`, `line`, and
+// `moves` the tool received. Three modes, all valid:
+//
+//   fen alone                → use as-is
+//   line/moves alone         → walk from startpos
+//   fen + moves (or line)    → walk from that fen
+//
+// `line` is the historical field name from the backend's prep endpoint;
+// `moves` is the flexible-input name we now surface for LLM ergonomics
+// ("start from this FEN and play these moves next"). They're synonyms
+// here — same SAN sequence, same chess.js walker. `moves` wins if both
+// happen to be provided.
+function resolveFenFromArgs(args) {
+    const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
+    const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
+    const lineArg = typeof args.line === "string" ? args.line.trim() : "";
+    const sequence = movesArg || lineArg;
+    const board = fenArg ? new Chess(fenArg) : new Chess();
+    if (sequence) {
+        for (const raw of sequence.split(/\s+/)) {
+            const san = raw.replace(/^\d+\.+/, "");
+            if (!san)
+                continue;
+            try {
+                board.move(san);
+            }
+            catch {
+                throw new Error(`bad SAN token '${raw}' in moves`);
+            }
+        }
+    }
+    return board.fen();
+}
 function stringifyForLog(v) {
     let s;
     try {
@@ -440,34 +589,51 @@ async function callToolInner(name, args) {
         case "get_player_profile":
             return get("/api/chess/players/profile", { fideId: Number(args.fide_id) });
         case "get_player_preparation": {
+            // Prefer sending `line` to the backend when the caller specified moves
+            // WITHOUT a fen — the backend then attaches the cumulative-line SAN to
+            // each move in the response (nicer for the LLM's follow-up walks).
+            // When a fen was supplied, always resolve the effective position
+            // client-side and send just fen — the backend can't reconstruct
+            // history it didn't see anyway.
+            const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
+            const movesArg = typeof args.moves === "string" ? args.moves.trim() : "";
+            const lineArg = typeof args.line === "string" ? args.line.trim() : "";
             const params = {
                 fideId: Number(args.fide_id),
                 color: String(args.color),
                 compact: "true",
             };
-            if (typeof args.line === "string" && args.line.length > 0)
-                params.line = args.line;
-            if (typeof args.fen === "string" && args.fen.length > 0)
-                params.fen = args.fen;
+            if (fenArg || movesArg) {
+                params.fen = resolveFenFromArgs(args);
+            }
+            else if (lineArg) {
+                params.line = lineArg;
+            }
             if (typeof args.limit === "number")
                 params.limit = args.limit;
             if (typeof args.offset === "number")
                 params.offset = args.offset;
-            return get("/api/chess/prep/by-player", params);
+            const raw = await get("/api/chess/prep/by-player", params);
+            return convertAvailableMovesToSAN(raw, resolveFenFromArgs(args));
         }
-        case "get_position_stats":
-            return get("/api/chess/database/main", {
-                fen: String(args.fen),
+        case "get_position_stats": {
+            const fen = resolveFenFromArgs(args);
+            const raw = await get("/api/chess/database/main", {
+                fen,
                 limit: typeof args.limit === "number" ? args.limit : 20,
                 sort: "relevance",
             });
+            return convertAvailableMovesToSAN(raw, fen);
+        }
         case "analyse": {
-            const params = { fen: String(args.fen) };
+            const fen = resolveFenFromArgs(args);
+            const params = { fen };
             if (typeof args.movetime_ms === "number")
                 params.movetime_ms = args.movetime_ms;
             if (typeof args.multipv === "number")
                 params.multipv = args.multipv;
-            return get("/api/chess/database/analyse", params);
+            const raw = await get("/api/chess/database/analyse", params);
+            return convertAnalyseResponse(raw, fen);
         }
         case "get_head_to_head":
             return get("/api/chess/players/h2h", {
@@ -494,14 +660,16 @@ async function callToolInner(name, args) {
         case "stop_cloud_engine":
             return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
         case "cloud_analyse": {
-            const body = { fen: String(args.fen) };
+            const fen = resolveFenFromArgs(args);
+            const body = { fen };
             if (typeof args.movetime_ms === "number")
                 body.movetime_ms = args.movetime_ms;
             if (typeof args.multipv === "number")
                 body.multipv = args.multipv;
             if (typeof args.contempt === "number")
                 body.contempt = args.contempt;
-            return authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+            const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+            return convertCloudSnapshotResponse(raw, fen);
         }
         case "read_engine_usage_guide":
             return { guide: ENGINE_USAGE_DOC };
@@ -549,9 +717,9 @@ async function callToolInner(name, args) {
             ]);
             return {
                 position: { line, fen, my_color: myColor },
-                opponent,
-                you,
-                general,
+                opponent: convertAvailableMovesToSAN(opponent, fen),
+                you: convertAvailableMovesToSAN(you, fen),
+                general: convertAvailableMovesToSAN(general, fen),
             };
         }
         default:

package/docs/engine-usage.md

@@ -75,6 +75,19 @@ The eval Lc0 returns when contempt is set is **not** the objective eval — it's
 - **Playing for a win with the "worse" side** — negative contempt if the user needs to avoid drawing lines with Black in a must-win situation.
 - **Never with zero direction** — always know *why* you're skewing before you set contempt. It's a specific tool for a specific question, not a default knob.
 
+## Tricks worth knowing
+
+### Flip side-to-move to see threats
+
+If it's Black to move and you want to know what threats *White* has (i.e. "if Black passes, what does White do?"), take the FEN and flip the side-to-move field from `b` to `w` (or vice versa), then run analysis. This is the engine equivalent of the "null move" idea humans use to check for prophylaxis.
+
+- Real position: `... b KQkq -` — analyse says +0.2 for Black
+- Flipped:     `... w KQkq -` — analyse says +1.4 for White
+
+The gap (1.4 - 0.2 = 1.2) is roughly the value of the tempo Black has to spend defending. If it's huge, Black is under real pressure even if the current eval looks calm. If it's tiny, White has no immediate threats and Black can improve at leisure.
+
+**Gotcha:** flipping side-to-move invalidates the en passant target field (if the last move was a two-square pawn push, the ep square is now stale). Also, both sides are counted as still having whichever castling rights are in the FEN — don't do this in the middle of a castling sequence. For opening / middlegame threat-checking it's a very useful idiom.
+
 ## Worked example
 
 User is preparing Black against a 2600 opponent who plays 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Be3 e5. You want to know if 7.Nb3 or 7.Nf3 is more testing.

package/package.json

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