stockfish-lc0-mcp: Instructions file for Codex

AGENTS.md — Chess Engine MCP Server (Stockfish + Lc0)

Project Overview

MCP server wrapping UCI chess engines (Stockfish and Leela Chess Zero). Provides 8 tools for chess analysis over the Model Context Protocol stdio transport. Written in TypeScript (strict mode), runs on Node.js 22+ (CI-tested on LTS 22/24/26), deployed via Docker.

Both engines are enabled by default in Docker. Lc0 ships with the Maia-1900 neural network and uses the OpenBLAS CPU backend. Stockfish tools (sf_*) are always available. Lc0 tools (lc0_*) are conditionally registered when LC0_WEIGHTS_PATH is set (enabled by default in Docker).

Architecture

src/
├── index.ts              # Entry point: MCP server setup, tool registration, lifecycle
├── types.ts              # UciEngine interface, all TypeScript types, centipawns() helper
├── constants.ts          # Thresholds, defaults, starting FEN, Lc0 depth-to-nodes map
├── schemas/
│   └── index.ts          # Zod input schemas for all tools
├── services/
│   ├── engine.ts         # BaseUciEngine, StockfishEngine, Lc0Engine (spawn, send, parse)
│   ├── chess-utils.ts    # chess.js utilities: PGN parsing, FEN validation, opening book
│   └── formatting.ts     # Markdown formatting for analysis output
└── tools/
    ├── analyse-position.ts  # sf/lc0_analyse_position — single FEN analysis
    ├── analyse-game.ts      # sf/lc0_analyse_game — full PGN move-by-move analysis
    ├── openings.ts          # sf_lookup_opening, sf_identify_opening
    └── puzzle.ts            # sf/lc0_generate_puzzle — tactic puzzle generation
tests/
├── chess-utils.test.ts
├── formatting.test.ts
├── schemas.test.ts
├── constants.test.ts
├── types.test.ts
├── tools-openings.test.ts
├── tools-analyse-position.test.ts
├── tools-analyse-game.test.ts
└── tools-puzzle.test.ts

Key design decisions

• UciEngine interface: All tools accept a UciEngine interface, not a concrete engine class. This allows Stockfish and Lc0 tools to share the same tool implementations.
• BaseUciEngine abstract class: Shared UCI protocol logic (process spawn, sendAndWait, info line parsing) lives in BaseUciEngine. Subclasses (StockfishEngine, Lc0Engine) override configureOptions() and buildGoCommand().
• Side-by-side tools: Stockfish (sf_*) and Lc0 (lc0_*) tools are registered in parallel. Opening tools (sf_lookup_opening, sf_identify_opening) are engine-agnostic and shared.
• Lc0 depth-to-nodes mapping: Lc0 uses MCTS, where "depth" means something fundamentally different from alpha-beta depth. The depth parameter is mapped to node counts via LC0_DEPTH_TO_NODES in constants.ts for consistent UX.
• WDL parsing: The UCI info line parser extracts Lc0's native wdl W D L data when present, stored in UciLine.wdl.
• Engine as long-lived process: Each engine spawns one child process and reuses it across all tool calls. Commands are sent via UCI protocol over stdin/stdout.
• Dual output: Every tool returns both content (Markdown text for display) and structuredContent (JSON for programmatic use).
• Eval perspective: Both engines report scores from the side-to-move's perspective. Code that compares evals across moves must negate when the side-to-move changes. This is the most bug-prone area.
• Win-probability accuracy model: Game analysis uses the Lichess win-probability formula (1 / (1 + exp(-0.00368208 * cp))) to compute per-move accuracy. Note: this was calibrated for Stockfish evals; Lc0 accuracy percentages may differ in calibration.
• Terminal positions: Checkmate/stalemate/draw positions are detected before engine analysis to avoid garbage evals.