llm-chess-mcp 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,12 @@
 # llm-chess-mcp
 
-An MCP server for truly enjoying chess games with your LLM. It adds a feature that, rather than simply making the best move, allows it to think and judge on its own and make moves. the MCP server handles all the computation (Stockfish evaluation, Maia3 human-move prediction, Lichess opening statistics).
+An MCP chess runtime that lets LLMs play, analyze, and adapt their strength
+without outsourcing every decision to an engine.
+
+Rather than returning a single best move, it exposes objective strength
+(Stockfish), human move likelihood (Maia3), and real-game statistics (Lichess)
+so the LLM can choose how it wants to play. The LLM does the strategy and
+judgment; the MCP server handles all the computation.
 
 ## Engines
 
@@ -10,8 +16,8 @@ An MCP server for truly enjoying chess games with your LLM. It adds a feature th
 | **Maia3** (ONNX) | Human-like move probabilities conditioned on Elo | In-process (`onnxruntime-node`) |
 | **Lichess explorer** | Real human game statistics | HTTP (needs token) |
 
-Everything runs inside the Node process — no separate engine binaries or Python
-runtime needed at deploy time. Maia3 is exported to ONNX once at build time.
+Everything runs inside the Node process — no external engine process or Python
+runtime is required at deploy time. Maia3 is exported to ONNX once at build time.
 
 ## Install
 
@@ -135,32 +141,93 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 |---|---|
 | `create_game` | Create a game (optionally from a FEN), returns `game_id` |
 | `delete_game` | Delete a game and free its session |
-| `game_state` | Authoritative state: FEN, turn, check/mate/draw flags, history, last move, castling |
-| `game_state_ascii` | ASCII board diagram |
-| `game_play_move` | Play a move (SAN or UCI) — the only mutating tool |
+| `game_state` | Authoritative state: FEN, turn, revision, check/mate/draw flags, history, last move, castling (optional ASCII) |
+| `game_play_move` | Play a move (SAN or UCI) — the only mutating tool, with stale-position guard |
 | `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 + PV) |
+| `position_analyze` | Stockfish multipv lines (cp/mate/WDL + PV), `analysis_level` preset |
 | `human_move_distribution` | Maia3 human-move probabilities at a target Elo |
-| `move_evaluate` | Score a move + cpLoss + classification |
-| `move_candidates` | Unified candidates (SF eval + cpLoss + Maia3 prob + Lichess stats) |
-| `move_candidates_by_intent` | Candidates ranked for a strategic intent |
+| `move_evaluate` | Score one or more moves + cpLoss + classification |
+| `move_candidates` | **Primary tool**: unified candidates (objective + human + opening) |
+| `move_candidates_by_intent` | Convenience layer: candidates ranked for a strategic intent |
 | `opening_explorer` | Lichess human game statistics |
 
 ## Score conventions
 
 - Stockfish scores are **side-to-move perspective**: positive cp = side to move is
-  better; `mate N` = side to move mates in N.
-- `move_evaluate` reports the score **from the mover's perspective** (negated after
-  the move), plus `cpLoss` (centipawns lost vs the best move) and a classification:
+  better; `mate N` = side to move mates in N. `wdl` is `[win, draw, loss]` in
+  permille for the side to move.
+- `move_candidates` gives `moverCp` (the mover's perspective — higher is better
+  for the player choosing the move) and `whiteCp` (fixed white perspective) so
+  the sign never flips on you.
+- `move_evaluate` reports the score **from the mover's perspective**, plus `cpLoss`
+  (centipawns lost vs the best move) and a classification:
   `best / excellent / good / inaccuracy / mistake / blunder`.
 - `maia3Prob` is a **human-likelihood**, not move quality. A high-probability move
   can still be objectively bad.
 
+## Candidate structure
+
+`move_candidates` returns each candidate with three independent facets:
+
+```json
+{
+  "uci": "g1f3",
+  "san": "Nf3",
+  "objective": { "rank": 1, "moverCp": 55, "whiteCp": 55, "cpLoss": 0, "moverMate": null, "wdl": [153, 844, 3] },
+  "human": { "maia3Prob": 0.62, "selfElo": 1500, "opponentElo": 1500 },
+  "opening": { "status": "available", "games": 18421, "frequency": 0.31 }
+}
+```
+
+- `objective` — Stockfish: engine strength, never conflated with human-likeness.
+  `moverCp` is from the mover's perspective (higher = better for the chooser).
+- `human` — Maia3 conditional probability at a target Elo.
+- `opening` — Lichess empirical frequency (a different signal from Maia3).
+
+`opening.status` is `available`, `no_data` (API ok but no games in this
+position), `unavailable` (timeout/429/401), or `disabled` (no token).
+Stockfish + Maia3 results are always returned regardless.
+
+`move_candidates` also returns `moveSensitivity`, describing how sharply the
+evaluation changes across the top engine lines:
+
+```json
+{ "moveSensitivity": { "level": "high", "topMoveSpreadCp": 245 } }
+```
+
+`level` is `low` (<80cp spread), `medium` (80–200cp), or `high` (≥200cp). High
+sensitivity means choosing among plausible alternatives can materially change
+the evaluation — useful for deciding whether to ease off or play precisely.
+
+## Analysis levels
+
+Stockfish tools accept an `analysis_level` preset instead of raw UCI knobs:
+
+| Level | Depth | MultiPV |
+|---|---|---|
+| `fast` | 8 | 5 |
+| `normal` | 15 | 8 |
+| `deep` | 22 | 10 |
+
+Explicit `depth`/`multipv` overrides are still available for advanced use.
+
+## Stale-position guard
+
+Every state read returns a `revision`. `game_play_move` **requires**
+`expected_revision`; if the game has advanced since your last read, the move is
+rejected:
+
+```json
+{ "error": { "code": "STALE_POSITION", "message": "position changed: expected revision 2, current 3" } }
+```
+
 ## Intents
 
-`move_candidates_by_intent` ranks candidates for a chosen intent:
+`move_candidates_by_intent` ranks candidates for a chosen intent. It is a
+convenience layer over `move_candidates`; the fixed thresholds below are
+heuristic defaults, not the source of truth:
 
 | Intent | Meaning |
 |---|---|
@@ -168,16 +235,40 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `strong` | Engine-strong but human-plausible |
 | `natural` | Most human-typical at the target Elo |
 | `balanced` | Blend of strength and human-likeness |
-| `ease_off` | Slightly weaker (−30..−80cp) but human |
-| `give_chance` | Clearly weaker (−80..−150cp), gives the opponent chances |
+| `ease_off` | Human-plausible moves that modestly reduce advantage without changing the expected result |
+| `give_chance` | Human-plausible inaccuracies that meaningfully improve the opponent's chances |
+
+This tool ranks candidates but does not choose a move. Use the returned signals
+and conversation context to make the final decision — do not map user skill
+mechanically to an intent.
 
 ## Example flow
 
+The normal play loop is three calls:
+
 1. `create_game` → `game_id`
-2. `position_analyze` to see the objective best lines
-3. `human_move_distribution` to see what a human of a given Elo would play
-4. `move_candidates_by_intent` with the intent that fits the situation
-5. `game_play_move` to commit the chosen move
+2. `move_candidates` → pick a move
+3. `game_play_move` (with `expected_revision`) → commit it
+
+Go deeper only when you need to:
+
+- `position_analyze` — objective best lines
+- `human_move_distribution` — what a human of a given Elo would play
+- `opening_explorer` — real-game statistics
+- `move_evaluate` — score a specific move (or compare several)
+
+## Maia3 ONNX verification
+
+The exported ONNX model is regression-tested against the upstream Maia3
+implementation across fixed positions and Elo pairs:
+
+```bash
+.venv-maia3/bin/python scripts/verify_maia3.py --model 5m
+```
+
+It checks top-1/top-k move agreement and max probability error to detect
+export/runtime regressions. The bundled `maia3-5m.onnx` passes with 100% top-1
+and top-5 agreement and max probability error < 1e-4.
 
 ## License & attribution
 

package/dist/engines/stockfish.js

@@ -10,6 +10,12 @@ function parseScore(token) {
         return { cp: null, mate: Number(token.slice(4)) };
     return { cp: null, mate: null };
 }
+function parseWdl(line) {
+    const m = line.match(/ wdl (\d+) (\d+) (\d+)/);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
 export class Stockfish {
     engine = null;
     ready = null;
@@ -84,6 +90,7 @@ export class Stockfish {
                         multipv: n,
                         scoreCp: score.cp,
                         scoreMate: score.mate,
+                        wdl: parseWdl(line),
                         pv: pv ? pv[1].split(" ") : [],
                     });
                 }
@@ -95,6 +102,7 @@ export class Stockfish {
             };
             engine.sendCommand("position fen " + fen);
             engine.sendCommand(`setoption name MultiPV value ${multipv}`);
+            engine.sendCommand("setoption name UCI_ShowWDL value true");
             engine.sendCommand(`go depth ${depth}`);
             stopTimer = setTimeout(() => {
                 engine.sendCommand("stop");

package/dist/eval.js

@@ -1,9 +1,22 @@
-export function scoreToCp(line) {
+export function toEval(line) {
     if (line.scoreMate !== null) {
-        const sign = line.scoreMate >= 0 ? 1 : -1;
-        return sign * (10000 - Math.abs(line.scoreMate) * 100);
+        return { type: "mate", plies: line.scoreMate };
     }
-    return line.scoreCp ?? 0;
+    if (line.scoreCp !== null) {
+        return { type: "cp", value: line.scoreCp };
+    }
+    return null;
+}
+export function evalToCp(e) {
+    if (e.type === "cp")
+        return e.value;
+    const sign = e.plies >= 0 ? 1 : -1;
+    return sign * (10000 - Math.abs(e.plies) * 100);
+}
+export function negateEval(e) {
+    if (e.type === "cp")
+        return { type: "cp", value: -e.value };
+    return { type: "mate", plies: -e.plies };
 }
 export const CLASSIFICATION = {
     best: 0,
@@ -25,3 +38,8 @@ export function classifyCpLoss(cpLoss) {
         return "mistake";
     return "blunder";
 }
+export const ANALYSIS_PRESETS = {
+    fast: { depth: 8, multipv: 5 },
+    normal: { depth: 15, multipv: 8 },
+    deep: { depth: 22, multipv: 10 },
+};

package/dist/games.js

@@ -5,12 +5,12 @@ const games = new Map();
 export function createGame(fen) {
     const id = randomUUID();
     const chess = fen ? new Chess(fen) : new Chess();
-    games.set(id, { chess, createdAt: Date.now() });
+    games.set(id, { chess, createdAt: Date.now(), revision: 0 });
     return id;
 }
 export function createGameFromChess(chess) {
     const id = randomUUID();
-    games.set(id, { chess, createdAt: Date.now() });
+    games.set(id, { chess, createdAt: Date.now(), revision: 0 });
     return id;
 }
 export function getGame(id) {
@@ -19,6 +19,13 @@ export function getGame(id) {
         throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
     return g;
 }
+export function bumpRevision(id) {
+    const g = games.get(id);
+    if (!g)
+        throw new ChessError("GAME_NOT_FOUND", `game not found: ${id}`);
+    g.revision += 1;
+    return g.revision;
+}
 export function deleteGame(id) {
     return games.delete(id);
 }

package/dist/index.js

@@ -4,12 +4,12 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
 import { Chess } from "chess.js";
 import { loadEnv } from "./env.js";
-import { createGame, createGameFromChess, getGame, deleteGame } from "./games.js";
+import { createGame, createGameFromChess, getGame, deleteGame, bumpRevision, } from "./games.js";
 import { stockfish } from "./engines/stockfish.js";
 import { humanMoveDistribution } from "./maia3/inference.js";
 import { openingExplorer, explorerEnabled } from "./explorer.js";
 import { computeCandidates, rankByIntent } from "./intents.js";
-import { scoreToCp, classifyCpLoss } from "./eval.js";
+import { toEval, evalToCp, negateEval, classifyCpLoss, ANALYSIS_PRESETS } from "./eval.js";
 import { ChessError } from "./errors.js";
 const INTENTS = [
     "best",
@@ -22,11 +22,12 @@ const INTENTS = [
 function text(data) {
     return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function stateOf(chess) {
+function stateOf(chess, revision) {
     const last = chess.history({ verbose: true }).at(-1);
     return {
         fen: chess.fen(),
         turn: chess.turn(),
+        revision,
         isCheck: chess.isCheck(),
         isCheckmate: chess.isCheckmate(),
         isStalemate: chess.isStalemate(),
@@ -86,7 +87,7 @@ export function buildServer() {
         catch {
             throw new ChessError("INVALID_FEN", "invalid FEN");
         }
-        return text({ game_id: id });
+        return text({ game_id: id, revision: 0 });
     }));
     server.registerTool("delete_game", {
         description: "Delete a game and free its session.",
@@ -98,30 +99,39 @@ export function buildServer() {
         return text({ game_id, deleted: true });
     }));
     server.registerTool("game_state", {
-        description: "Return the authoritative state of a game: FEN, turn, check/mate/draw flags, move history, last move, castling rights. Use this instead of remembering the board.",
-        inputSchema: z.object({ game_id: z.string() }),
-    }, wrap(async ({ game_id }) => {
-        const { chess } = getGame(game_id);
-        return text({ game_id, ...stateOf(chess) });
-    }));
-    server.registerTool("game_state_ascii", {
-        description: "Return an ASCII diagram of the current board.",
-        inputSchema: z.object({ game_id: z.string() }),
-    }, wrap(async ({ game_id }) => {
-        const { chess } = getGame(game_id);
-        return text({ game_id, board: chess.ascii() });
+        description: "Return the authoritative state of a game: FEN, turn, revision, check/mate/draw flags, move history, last move, castling rights. Use this instead of remembering the board. Set include_ascii=true to also get a board diagram.",
+        inputSchema: z.object({
+            game_id: z.string(),
+            include_ascii: z.boolean().default(false),
+        }),
+    }, wrap(async ({ game_id, include_ascii }) => {
+        const { chess, revision } = getGame(game_id);
+        const state = stateOf(chess, revision);
+        return text({
+            game_id,
+            ...state,
+            ...(include_ascii ? { board: chess.ascii() } : {}),
+        });
     }));
     server.registerTool("game_play_move", {
-        description: "Play a move (SAN like 'e4' or UCI like 'e2e4') and return the resulting state. This is the ONLY tool that mutates the game. Illegal moves are rejected and the state is unchanged.",
-        inputSchema: z.object({ game_id: z.string(), move: z.string() }),
-    }, wrap(async ({ game_id, move }) => {
-        const { chess } = getGame(game_id);
+        description: "Play a move (SAN like 'e4' or UCI like 'e2e4') and return the resulting state. This is the ONLY tool that mutates the game. expected_revision is required: pass the revision from your most recent game_state/move_candidates read. If the game has advanced since then, the move is rejected with STALE_POSITION.",
+        inputSchema: z.object({
+            game_id: z.string(),
+            move: z.string(),
+            expected_revision: z.number().int().min(0),
+        }),
+    }, wrap(async ({ game_id, move, expected_revision }) => {
+        const { chess, revision } = getGame(game_id);
+        if (expected_revision !== revision) {
+            throw new ChessError("STALE_POSITION", `position changed: expected revision ${expected_revision}, current ${revision}`);
+        }
         if (chess.isGameOver()) {
             throw new ChessError("GAME_OVER", "game is already over");
         }
         const m = parseMove(chess, move);
         chess.move({ from: m.from, to: m.to, promotion: m.promotion });
-        return text({ game_id, move: m.san, ...stateOf(chess) });
+        const newRevision = bumpRevision(game_id);
+        return text({ game_id, move: m.san, ...stateOf(chess, newRevision) });
     }));
     server.registerTool("game_legal_moves", {
         description: "List all legal moves in the current position (SAN, UCI, piece, capture, promotion).",
@@ -142,23 +152,30 @@ export function buildServer() {
         return text({ game_id, count: moves.length, moves });
     }));
     server.registerTool("position_analyze", {
-        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. Does NOT mutate the game.",
+        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.",
         inputSchema: z.object({
             game_id: z.string(),
-            depth: z.number().int().min(1).max(30).default(15),
-            multipv: z.number().int().min(1).max(10).default(3),
+            analysis_level: z.enum(["fast", "normal", "deep"]).default("normal"),
+            depth: z.number().int().min(1).max(30).optional(),
+            multipv: z.number().int().min(1).max(10).optional(),
         }),
-    }, wrap(async ({ game_id, depth, multipv }) => {
-        const { chess } = getGame(game_id);
-        const lines = await stockfish.analyze(chess.fen(), depth, multipv);
+    }, wrap(async ({ game_id, analysis_level, depth, multipv }) => {
+        const { chess, revision } = getGame(game_id);
+        const preset = ANALYSIS_PRESETS[analysis_level];
+        const d = depth ?? preset.depth;
+        const mpv = multipv ?? preset.multipv;
+        const lines = await stockfish.analyze(chess.fen(), d, mpv);
         return text({
             game_id,
             fen: chess.fen(),
             turn: chess.turn(),
+            revision,
+            analysis_level,
             lines: lines.map((l) => ({
                 multipv: l.multipv,
                 scoreCp: l.scoreCp,
                 scoreMate: l.scoreMate,
+                wdl: l.wdl,
                 pv: l.pv,
             })),
         });
@@ -172,109 +189,140 @@ export function buildServer() {
             top_n: z.number().int().min(1).max(20).default(5),
         }),
     }, wrap(async ({ game_id, elo, oppo_elo, top_n }) => {
-        const { chess } = getGame(game_id);
+        const { chess, revision } = getGame(game_id);
         const moves = await humanMoveDistribution(chess, elo, oppo_elo ?? elo, top_n);
-        return text({ game_id, elo, oppo_elo: oppo_elo ?? elo, moves });
+        return text({ game_id, elo, oppo_elo: oppo_elo ?? elo, revision, moves });
     }));
     server.registerTool("move_evaluate", {
-        description: "Evaluate a specific move with Stockfish without mutating the game. Returns the score after the move (from the mover's perspective) plus 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, and a classification (best/excellent/good/inaccuracy/mistake/blunder).",
         inputSchema: z.object({
             game_id: z.string(),
-            move: z.string(),
+            move: z.union([z.string(), z.array(z.string())]),
             depth: z.number().int().min(1).max(30).default(15),
         }),
     }, wrap(async ({ game_id, move, depth }) => {
-        const { chess } = getGame(game_id);
-        const m = parseMove(chess, move);
-        const copy = new Chess(chess.fen());
-        copy.move({ from: m.from, to: m.to, promotion: m.promotion });
-        if (copy.isCheckmate()) {
-            return text({
-                game_id,
-                move: m.san,
-                uci: m.lan,
-                result: "checkmate",
-                scoreCp: null,
-                scoreMate: 0,
-                bestCp: null,
-                cpLoss: null,
-                classification: "best",
-                pv: [],
-            });
-        }
-        if (copy.isStalemate()) {
-            return text({
-                game_id,
+        const { chess, revision } = getGame(game_id);
+        const moves = Array.isArray(move) ? move : [move];
+        const beforeLines = await stockfish.analyze(chess.fen(), depth, 1);
+        const before = beforeLines[0];
+        const beforeEval = before ? toEval(before) : null;
+        const beforeCp = beforeEval ? evalToCp(beforeEval) : null;
+        const results = [];
+        for (const mv of moves) {
+            const m = parseMove(chess, mv);
+            const copy = new Chess(chess.fen());
+            copy.move({ from: m.from, to: m.to, promotion: m.promotion });
+            if (copy.isCheckmate()) {
+                results.push({
+                    move: m.san,
+                    uci: m.lan,
+                    result: "checkmate",
+                    scoreCp: null,
+                    scoreMate: 0,
+                    bestCp: beforeCp,
+                    cpLoss: null,
+                    classification: "best",
+                    pv: [],
+                });
+                continue;
+            }
+            if (copy.isStalemate()) {
+                results.push({
+                    move: m.san,
+                    uci: m.lan,
+                    result: "stalemate",
+                    scoreCp: 0,
+                    scoreMate: null,
+                    bestCp: beforeCp,
+                    cpLoss: null,
+                    classification: null,
+                    pv: [],
+                });
+                continue;
+            }
+            const afterLines = await stockfish.analyze(copy.fen(), depth, 1);
+            const after = afterLines[0];
+            const afterEval = after ? toEval(after) : null;
+            const moverEval = afterEval ? negateEval(afterEval) : null;
+            const afterCp = moverEval ? evalToCp(moverEval) : null;
+            const cpLoss = afterCp !== null && beforeCp !== null ? beforeCp - afterCp : null;
+            results.push({
                 move: m.san,
                 uci: m.lan,
-                result: "stalemate",
-                scoreCp: 0,
-                scoreMate: null,
-                bestCp: null,
-                cpLoss: null,
-                classification: null,
-                pv: [],
+                result: "ongoing",
+                scoreCp: afterCp,
+                scoreMate: moverEval?.type === "mate" ? moverEval.plies : null,
+                bestCp: beforeCp,
+                cpLoss,
+                classification: cpLoss !== null ? classifyCpLoss(cpLoss) : null,
+                pv: after?.pv ?? [],
             });
         }
-        const [afterLines, beforeLines] = await Promise.all([
-            stockfish.analyze(copy.fen(), depth, 1),
-            stockfish.analyze(chess.fen(), depth, 1),
-        ]);
-        const after = afterLines[0];
-        const before = beforeLines[0];
-        // Stockfish scores are side-to-move perspective. After the move the side
-        // to move is the opponent, so negate to get the mover's perspective.
-        const afterCp = after ? -scoreToCp(after) : null;
-        const beforeCp = before ? scoreToCp(before) : null;
-        const cpLoss = afterCp !== null && beforeCp !== null ? beforeCp - afterCp : null;
-        return text({
-            game_id,
-            move: m.san,
-            uci: m.lan,
-            result: "ongoing",
-            scoreCp: afterCp,
-            scoreMate: after?.scoreMate != null ? -after.scoreMate : null,
-            bestCp: beforeCp,
-            cpLoss,
-            classification: cpLoss !== null ? classifyCpLoss(cpLoss) : null,
-            pv: after?.pv ?? [],
-        });
+        const payload = { game_id, revision, results };
+        return text(moves.length === 1 ? { ...payload, ...results[0] } : payload);
     }));
     server.registerTool("move_candidates", {
-        description: "Combine Stockfish evaluation, Maia3 human probability, and Lichess human statistics into a unified candidate list. Each candidate has sfCp (side-to-move perspective), cpLoss (vs best), maia3Prob (human likelihood, NOT quality), and lichess (real game counts). Use this before choosing a move; the final choice is yours.",
+        description: "The primary move-selection tool. Combine Stockfish objective evaluation (moverCp, whiteCp, cpLoss, mate, WDL), Maia3 human probability, and Lichess real-game statistics into a unified candidate list. moverCp is from the mover's perspective: higher = better for the player choosing the move. Use this before choosing a move; the final choice is yours.",
         inputSchema: z.object({
             game_id: z.string(),
             elo: z.number().int().min(600).max(2600).default(1500),
-            sf_depth: z.number().int().min(1).max(30).default(15),
-            sf_multipv: z.number().int().min(1).max(10).default(5),
+            analysis_level: z.enum(["fast", "normal", "deep"]).default("normal"),
+            sf_depth: z.number().int().min(1).max(30).optional(),
+            sf_multipv: z.number().int().min(1).max(10).optional(),
             maia_top_n: z.number().int().min(1).max(20).default(5),
             lichess_db: z.enum(["lichess", "masters"]).default("lichess"),
             lichess_speeds: z.array(z.string()).default([]),
             lichess_ratings: z.array(z.number().int()).default([]),
         }),
-    }, wrap(async ({ game_id, elo, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
-        const { chess } = getGame(game_id);
-        const candidates = await computeCandidates(chess, elo, sf_depth, sf_multipv, maia_top_n, { db: lichess_db, speeds: lichess_speeds, ratings: lichess_ratings });
-        return text({ game_id, elo, candidates });
+    }, wrap(async ({ game_id, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
+        const { chess, revision } = getGame(game_id);
+        const preset = ANALYSIS_PRESETS[analysis_level];
+        const d = sf_depth ?? preset.depth;
+        const mpv = sf_multipv ?? preset.multipv;
+        const { candidates, moveSensitivity } = await computeCandidates(chess, elo, d, mpv, maia_top_n, { db: lichess_db, speeds: lichess_speeds, ratings: lichess_ratings });
+        return text({
+            game_id,
+            revision,
+            fen: chess.fen(),
+            turn: chess.turn(),
+            elo,
+            analysis_level,
+            moveSensitivity,
+            candidates,
+        });
     }));
     server.registerTool("move_candidates_by_intent", {
-        description: "Return candidate moves ranked for a given strategic intent. intents: best (strongest engine move), strong (engine-strong but human-plausible), natural (most human-typical), balanced (blend of strength and human-likeness), ease_off (slightly weaker but human), give_chance (clearly weaker, gives opponent chances).",
+        description: "Convenience layer over move_candidates: rank candidates for a strategic intent. This tool RANKS candidates but does NOT choose a move — use the returned signals and conversation context to make the final decision. Do not map user skill mechanically to an intent. intents: best (strongest engine move), strong (engine-strong but human-plausible), natural (most human-typical), balanced (blend of strength and human-likeness), ease_off (human-plausible moves that modestly reduce advantage without changing the expected result), give_chance (human-plausible inaccuracies that meaningfully improve the opponent's chances).",
         inputSchema: z.object({
             game_id: z.string(),
             intent: z.enum(INTENTS),
             elo: z.number().int().min(600).max(2600).default(1500),
-            sf_depth: z.number().int().min(1).max(30).default(15),
-            sf_multipv: z.number().int().min(1).max(10).default(8),
+            analysis_level: z.enum(["fast", "normal", "deep"]).default("normal"),
+            sf_depth: z.number().int().min(1).max(30).optional(),
+            sf_multipv: z.number().int().min(1).max(10).optional(),
             maia_top_n: z.number().int().min(1).max(20).default(10),
             lichess_db: z.enum(["lichess", "masters"]).default("lichess"),
             lichess_speeds: z.array(z.string()).default([]),
             lichess_ratings: z.array(z.number().int()).default([]),
         }),
-    }, wrap(async ({ game_id, intent, elo, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
-        const { chess } = getGame(game_id);
-        const candidates = await computeCandidates(chess, elo, sf_depth, sf_multipv, maia_top_n, { db: lichess_db, speeds: lichess_speeds, ratings: lichess_ratings });
+    }, wrap(async ({ game_id, intent, elo, analysis_level, sf_depth, sf_multipv, maia_top_n, lichess_db, lichess_speeds, lichess_ratings, }) => {
+        const { chess, revision } = getGame(game_id);
+        const preset = ANALYSIS_PRESETS[analysis_level];
+        const d = sf_depth ?? preset.depth;
+        const mpv = sf_multipv ?? preset.multipv;
+        const { candidates, moveSensitivity } = await computeCandidates(chess, elo, d, mpv, maia_top_n, { db: lichess_db, speeds: lichess_speeds, ratings: lichess_ratings });
         const ranked = rankByIntent(candidates, intent);
-        return text({ game_id, intent, elo, candidates: ranked });
+        return text({
+            game_id,
+            revision,
+            fen: chess.fen(),
+            turn: chess.turn(),
+            intent,
+            elo,
+            analysis_level,
+            moveSensitivity,
+            candidates: ranked,
+        });
     }));
     server.registerTool("opening_explorer", {
         description: "Query the Lichess opening explorer for real human game statistics in the current position (requires LICHESS_TOKEN).",
@@ -312,7 +360,7 @@ export function buildServer() {
             throw new ChessError("INVALID_PGN", "invalid or illegal PGN");
         }
         const id = createGameFromChess(chess);
-        return text({ game_id: id, ...stateOf(chess) });
+        return text({ game_id: id, ...stateOf(chess, 0) });
     }));
     return server;
 }

package/dist/intents.js

@@ -1,7 +1,7 @@
 import { stockfish } from "./engines/stockfish.js";
 import { humanMoveDistribution } from "./maia3/inference.js";
 import { openingExplorer, explorerEnabled } from "./explorer.js";
-import { scoreToCp } from "./eval.js";
+import { toEval, evalToCp } from "./eval.js";
 function softmax(values, temperature) {
     const scaled = values.map((v) => v / temperature);
     const max = Math.max(...scaled);
@@ -9,22 +9,65 @@ function softmax(values, temperature) {
     const sum = exps.reduce((a, b) => a + b, 0);
     return exps.map((e) => e / sum);
 }
+function toSan(chess, uci) {
+    const m = chess.moves({ verbose: true }).find((x) => x.lan === uci);
+    return m ? m.san : uci;
+}
+function objectiveFromLine(line, turn, bestCp) {
+    if (!line) {
+        return {
+            rank: null,
+            moverCp: null,
+            whiteCp: null,
+            cpLoss: null,
+            moverMate: null,
+            whiteMate: null,
+            wdl: null,
+        };
+    }
+    const e = toEval(line);
+    const cp = e ? evalToCp(e) : null;
+    const whiteCp = cp !== null ? (turn === "w" ? cp : -cp) : null;
+    const mate = line.scoreMate;
+    const whiteMate = mate !== null ? (turn === "w" ? mate : -mate) : null;
+    return {
+        rank: line.multipv,
+        moverCp: cp,
+        whiteCp,
+        cpLoss: cp !== null && bestCp !== null ? bestCp - cp : null,
+        moverMate: mate,
+        whiteMate,
+        wdl: line.wdl,
+    };
+}
 export async function computeCandidates(chess, elo, sfDepth, sfMultipv, maiaTopN, lichess) {
-    const [sfLines, maiaMoves, lichessMoves] = await Promise.all([
+    const [sfLines, maiaMoves, lichessResult] = await Promise.all([
         stockfish.analyze(chess.fen(), sfDepth, sfMultipv),
         humanMoveDistribution(chess, elo, elo, maiaTopN),
         lichess && explorerEnabled()
             ? openingExplorer(chess, lichess.db, lichess.speeds, lichess.ratings)
-                .then((r) => r.moves)
-                .catch(() => [])
-            : Promise.resolve([]),
+                .then((r) => ({
+                status: (r.moves.length > 0 ? "available" : "no_data"),
+                moves: r.moves,
+            }))
+                .catch((e) => ({
+                status: "unavailable",
+                reason: e instanceof Error ? e.message : String(e),
+                moves: [],
+            }))
+            : Promise.resolve({
+                status: "disabled",
+                moves: [],
+            }),
     ]);
+    const turn = chess.turn();
     const maiaByUci = new Map(maiaMoves.map((m) => [m.uci, m.prob]));
     const sfByUci = new Map(sfLines.map((l) => [l.pv[0], l]));
-    const lichessByUci = new Map(lichessMoves.map((m) => [m.uci, m]));
+    const lichessByUci = new Map(lichessResult.moves.map((m) => [m.uci, m]));
     const bestCp = sfLines.length
-        ? Math.max(...sfLines.map((l) => scoreToCp(l)))
-        : 0;
+        ? Math.max(...sfLines.map((l) => evalToCp(toEval(l))))
+        : null;
+    const totalGames = lichessResult.moves.reduce((a, m) => a + m.count, 0);
     const ucis = new Set([
         ...sfByUci.keys(),
         ...maiaByUci.keys(),
@@ -33,58 +76,107 @@ export async function computeCandidates(chess, elo, sfDepth, sfMultipv, maiaTopN
     const candidates = [];
     for (const uci of ucis) {
         const sf = sfByUci.get(uci);
-        const cp = sf ? scoreToCp(sf) : null;
+        const lc = lichessByUci.get(uci);
+        const opening = lc
+            ? {
+                status: lichessResult.status,
+                games: lc.count,
+                frequency: totalGames > 0 ? lc.count / totalGames : null,
+                white: lc.white,
+                draws: lc.draws,
+                black: lc.black,
+                averageRating: lc.averageRating,
+            }
+            : {
+                status: lichessResult.status,
+                reason: lichessResult.status === "unavailable" ? lichessResult.reason : undefined,
+                games: null,
+                frequency: null,
+                white: null,
+                draws: null,
+                black: null,
+                averageRating: null,
+            };
         candidates.push({
             uci,
             san: toSan(chess, uci),
-            sfCp: cp,
-            cpLoss: cp !== null ? bestCp - cp : null,
-            maia3Prob: maiaByUci.get(uci) ?? null,
-            lichess: lichessByUci.get(uci) ?? null,
+            objective: objectiveFromLine(sf, turn, bestCp),
+            human: {
+                maia3Prob: maiaByUci.get(uci) ?? null,
+                selfElo: elo,
+                opponentElo: elo,
+            },
+            opening,
         });
     }
-    return candidates;
+    return { candidates, moveSensitivity: computeMoveSensitivity(sfLines) };
 }
-function toSan(chess, uci) {
-    const m = chess.moves({ verbose: true }).find((x) => x.lan === uci);
-    return m ? m.san : uci;
+function winMargin(c) {
+    const wdl = c.objective.wdl;
+    if (!wdl)
+        return null;
+    return wdl[0] - wdl[2];
+}
+export function computeMoveSensitivity(sfLines) {
+    const cps = sfLines
+        .map((l) => toEval(l))
+        .filter((e) => e !== null)
+        .map((e) => evalToCp(e));
+    if (cps.length < 2) {
+        return { level: "low", topMoveSpreadCp: null };
+    }
+    const spread = Math.max(...cps) - Math.min(...cps);
+    const level = spread >= 200 ? "high" : spread >= 80 ? "medium" : "low";
+    return { level, topMoveSpreadCp: spread };
 }
 export function rankByIntent(candidates, intent) {
-    const withSf = candidates.filter((c) => c.sfCp !== null);
-    const bestCp = withSf.length ? Math.max(...withSf.map((c) => c.sfCp)) : 0;
-    const sfProbs = intent === "balanced"
-        ? softmax(candidates.map((x) => x.sfCp ?? -1000), 100)
-        : null;
+    const withSf = candidates.filter((c) => c.objective.moverCp !== null);
+    const bestMargin = withSf.length
+        ? Math.max(...withSf.map((c) => winMargin(c) ?? -Infinity))
+        : 0;
     const scored = candidates.map((c) => {
         let score;
         switch (intent) {
             case "best":
-                score = c.sfCp ?? -Infinity;
+                score = c.objective.moverCp ?? -Infinity;
                 break;
             case "strong": {
-                const sf = c.sfCp ?? -Infinity;
-                const human = c.maia3Prob ?? 0;
+                const sf = c.objective.moverCp ?? -Infinity;
+                const human = c.human.maia3Prob ?? 0;
                 score = human > 0 ? sf : -Infinity;
                 break;
             }
             case "natural":
-                score = c.maia3Prob ?? 0;
+                score = c.human.maia3Prob ?? 0;
                 break;
             case "balanced": {
+                const sfProbs = softmax(candidates.map((x) => x.objective.moverCp ?? -1000), 100);
                 const idx = candidates.indexOf(c);
-                score = 0.5 * sfProbs[idx] + 0.5 * (c.maia3Prob ?? 0);
+                score = 0.5 * sfProbs[idx] + 0.5 * (c.human.maia3Prob ?? 0);
                 break;
             }
             case "ease_off": {
-                const gap = bestCp - (c.sfCp ?? -Infinity);
-                const inRange = gap >= 30 && gap <= 80;
-                score = inRange ? c.maia3Prob ?? 0 : -Infinity;
+                const margin = winMargin(c);
+                const human = c.human.maia3Prob ?? 0;
+                if (margin === null || human === 0) {
+                    score = -Infinity;
+                    break;
+                }
+                const drop = bestMargin - margin;
+                const modest = drop >= 15 && drop <= 50 && margin > 0;
+                score = modest ? human : -Infinity;
                 break;
             }
             case "give_chance": {
-                const gap = bestCp - (c.sfCp ?? -Infinity);
-                const inRange = gap >= 80 && gap <= 150;
-                score = inRange ? c.maia3Prob ?? 0 : -Infinity;
+                const margin = winMargin(c);
+                const human = c.human.maia3Prob ?? 0;
+                if (margin === null || human === 0) {
+                    score = -Infinity;
+                    break;
+                }
+                const drop = bestMargin - margin;
+                const meaningful = drop >= 50 && drop <= 150;
+                score = meaningful ? human : -Infinity;
                 break;
             }
         }
@@ -95,9 +187,9 @@ export function rankByIntent(candidates, intent) {
         .sort((a, b) => b.score - a.score)
         .map((x) => x.c);
     if (ranked.length === 0 && (intent === "ease_off" || intent === "give_chance")) {
-        const human = candidates.filter((c) => c.maia3Prob !== null);
+        const human = candidates.filter((c) => c.human.maia3Prob !== null && c.objective.moverCp !== null);
         return human
-            .sort((a, b) => (a.sfCp ?? -Infinity) - (b.sfCp ?? -Infinity))
+            .sort((a, b) => (a.objective.moverCp ?? -Infinity) - (b.objective.moverCp ?? -Infinity))
             .slice(0, 5);
     }
     return ranked;

package/package.json

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