llm-chess-mcp 0.4.1 → 0.4.3

package/README.md

@@ -279,7 +279,7 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `game_legal_moves` | All legal moves with metadata |
 | `game_pgn` | Export the game as PGN |
 | `game_import_pgn` | Import a PGN into a new game |
-| `position_analyze` | Stockfish multipv lines (cp/mate/WDL + PV), `analysis_level` preset |
+| `position_analyze` | Stockfish multipv lines (cp/mate/WDL + UCI/SAN PV), `analysis_level` preset |
 | `human_move_distribution` | Maia3 human-move probabilities at a target Elo |
 | `move_evaluate` | Score one or more moves + cpLoss + classification |
 | `move_candidates` | **Primary tool**: unified candidates (objective + human + opening) |
@@ -307,6 +307,9 @@ human-readable summary and must not be parsed as data.
   `best / excellent / good / inaccuracy / mistake / blunder`.
 - `maia3Prob` is a **human-likelihood**, not move quality. A high-probability move
   can still be objectively bad.
+- Analysis continuations return `pv` in UCI and the same legal prefix in
+  `pvSan` as SAN. If an engine line contains an invalid move, `pvSan` stops
+  before it while the original `pv` remains unchanged.
 
 ## Candidate structure
 

package/dist/chess.js

@@ -81,3 +81,20 @@ export function parseMove(chess, move) {
 export function playParsedMove(chess, move) {
     return chess.move(moveDescriptor(move));
 }
+export function pvToSan(chess, pv) {
+    const copy = new Chess(chess.fen());
+    const san = [];
+    for (const uci of pv) {
+        try {
+            const move = parseMove(copy, uci);
+            san.push(move.san);
+            playParsedMove(copy, move);
+        }
+        catch (error) {
+            if (!(error instanceof ChessError))
+                throw error;
+            break;
+        }
+    }
+    return san;
+}

package/dist/tool-meta.js

@@ -46,7 +46,7 @@ export const TOOL_META = {
     },
     position_analyze: {
         title: "Analyze Chess Position",
-        description: "Run Stockfish on the current position and return the top engine lines (multipv). Scores are from the side-to-move perspective: positive cp = side to move is better; mate N = side to move mates in N. wdl is [win, draw, loss] in permille for the side to move. Use analysis_level (fast/normal/deep) or explicit depth/multipv. Does NOT mutate the game.",
+        description: "Run Stockfish on the current position and return the top engine lines (multipv) as UCI pv and SAN pvSan. Scores are from the side-to-move perspective: positive cp = side to move is better; mate N = side to move mates in N. wdl is [win, draw, loss] in permille for the side to move. Use analysis_level (fast/normal/deep) or explicit depth/multipv. Does NOT mutate the game.",
         annotations: readOnly(),
     },
     human_move_distribution: {
@@ -56,7 +56,7 @@ export const TOOL_META = {
     },
     move_evaluate: {
         title: "Evaluate Chess Moves",
-        description: "Evaluate one or more moves with Stockfish without mutating the game. Pass a single move string or an array of moves to compare. Returns, for each move, the score after the move (from the mover's perspective), cpLoss vs the best move, and a classification (best/excellent/good/inaccuracy/mistake/blunder).",
+        description: "Evaluate one or more moves with Stockfish without mutating the game. Pass a single move string or an array of moves to compare. Returns, for each move, the score after the move (from the mover's perspective), cpLoss vs the best move, a classification (best/excellent/good/inaccuracy/mistake/blunder), and the continuation as UCI pv and SAN pvSan.",
         annotations: readOnly(),
     },
     move_candidates: {

package/dist/tool-schemas.js

@@ -45,6 +45,10 @@ export const SfLineSchema = z.strictObject({
     wdl: wdl.nullable(),
     pv: z.array(z.string()),
 });
+export const AnalysisLineSchema = z.strictObject({
+    ...SfLineSchema.shape,
+    pvSan: z.array(z.string()),
+});
 export const OpeningStatsSchema = z.strictObject({
     status: z.enum(["available", "no_data", "unavailable", "disabled"]),
     reason: z.enum(EXPLORER_ERROR_KINDS).optional(),
@@ -121,7 +125,7 @@ export const PositionAnalyzeOutputSchema = z.strictObject({
     turn: color,
     revision,
     analysis_level: z.enum(["fast", "normal", "deep"]),
-    lines: z.array(SfLineSchema),
+    lines: z.array(AnalysisLineSchema),
 });
 export const Maia3MoveSchema = z.strictObject({
     uci: z.string(),
@@ -155,6 +159,7 @@ const moveEvaluation = z.strictObject({
         .enum(["best", "excellent", "good", "inaccuracy", "mistake", "blunder"])
         .nullable(),
     pv: z.array(z.string()),
+    pvSan: z.array(z.string()),
 });
 export const MoveEvaluateOutputSchema = z.strictObject({
     game_id: z.string(),

package/dist/tools/analysis.js

@@ -1,4 +1,4 @@
-import { drawResult, parseMove, playParsedMove, snapshotChess, } from "../chess.js";
+import { drawResult, parseMove, playParsedMove, pvToSan, snapshotChess, } from "../chess.js";
 import { ANALYSIS_PRESETS, classifyCpLoss, evalToCp, negateEval, toEval, } from "../eval.js";
 import { TOOL_INPUT_SCHEMAS } from "../tool-inputs.js";
 import { TOOL_META } from "../tool-meta.js";
@@ -28,6 +28,7 @@ export function registerAnalysisTools(server, services) {
                 scoreMate: line.scoreMate,
                 wdl: line.wdl,
                 pv: line.pv,
+                pvSan: pvToSan(chess, line.pv),
             })),
         };
         return toolResult(payload, `Analyzed game ${game_id} at revision ${revision}; ${payload.lines.length} lines`);
@@ -80,6 +81,7 @@ export function registerAnalysisTools(server, services) {
                     cpLoss: null,
                     classification: "best",
                     pv: [],
+                    pvSan: [],
                 });
                 continue;
             }
@@ -98,6 +100,7 @@ export function registerAnalysisTools(server, services) {
                         ? classifyCpLoss(cpLoss)
                         : null,
                     pv: [],
+                    pvSan: [],
                 });
                 continue;
             }
@@ -108,6 +111,7 @@ export function registerAnalysisTools(server, services) {
             const moverEval = afterEval ? negateEval(afterEval) : null;
             const afterCp = moverEval ? evalToCp(moverEval) : null;
             const cpLoss = afterCp !== null && beforeCp !== null ? beforeCp - afterCp : null;
+            const pv = after?.pv ?? [];
             results.push({
                 move: parsed.san,
                 uci: parsed.lan,
@@ -119,7 +123,8 @@ export function registerAnalysisTools(server, services) {
                 classification: cpLoss !== null
                     ? classifyCpLoss(cpLoss)
                     : null,
-                pv: after?.pv ?? [],
+                pv,
+                pvSan: pvToSan(copy, pv),
             });
         }
         return toolResult({ game_id, revision, results }, `Evaluated ${results.length} move${results.length === 1 ? "" : "s"} in game ${game_id}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-chess-mcp",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "MCP server that lets an LLM analyze, judge, and choose chess moves (Stockfish + Maia3 + Lichess)",
   "type": "module",
   "license": "AGPL-3.0",