@chessceo/mcp 0.12.0 → 0.15.0

package/dist/index.js

@@ -224,7 +224,7 @@ const TOOLS = [
     },
     {
         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" +
             "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: {
@@ -404,6 +404,127 @@ 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 either the `fen` or `line` argument the tool
+// received. Same logic prep_snapshot already had inline — extracted so we
+// can reuse it wherever we need to walk a SAN line to a concrete FEN
+// (e.g. for UCI→SAN conversion of availableMoves).
+function resolveFenFromArgs(args) {
+    const fenArg = typeof args.fen === "string" ? args.fen.trim() : "";
+    if (fenArg)
+        return fenArg;
+    const lineArg = typeof args.line === "string" ? args.line.trim() : "";
+    const board = new Chess();
+    if (lineArg) {
+        for (const raw of lineArg.split(/\s+/)) {
+            const san = raw.replace(/^\d+\.+/, "");
+            if (!san)
+                continue;
+            try {
+                board.move(san);
+            }
+            catch {
+                throw new Error(`bad SAN token '${raw}' in line`);
+            }
+        }
+    }
+    return board.fen();
+}
 function stringifyForLog(v) {
     let s;
     try {
@@ -453,21 +574,27 @@ async function callToolInner(name, args) {
                 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 = String(args.fen);
+            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 = String(args.fen);
+            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 +621,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 = String(args.fen);
+            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 +678,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.15.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {