Chess Esca MCP server

esca

Esca is the anglerfish's lure — the light that shows what is really on the board.

Rust/Python MIT chess library: rules, facts, explanations, PGN, opening books and names, UCI client, and an MCP server over it; one API, Chess960 throughout.

Position is placement and state and nothing else. Rules live in Variant implementations — Classic and Chess960 — so a position answers a rules question by taking the variant that defines it, and a new variant is a new implementation and nothing else. A Game pairs a variant with the moves played, which is what repetition and claimable draws need. Facts answers what is true about one position — 221 named facts in 14 groups — and annotated_moves() answers what each of its legal moves does, with 27 more. Every fact is typed, named after what a player would call it, and told about White and Black by name.

Rust

[dependencies]
esca = "0.4"

use esca::{Colour, Game, classic};

let mut game = Game::new(classic());   // Chess960 rules: `esca::chess960()`
game.play_san("e4").unwrap();
game.play_uci("e7e5").unwrap();
println!("{}", game.position().fen());

let facts = game.facts();
println!("{}", facts.tactics.legal_move_count.white);
println!("{:?}", facts.pawns.passed.of(Colour::Black).files());
println!("{}", facts.summary());

Cargo features, none on by default: lichess (streaming reader for the Lichess evaluation dump), pgn (reading and writing games as PGN), polyglot (opening books), openings (the bundled ECO catalogue), serde (the one JSON form of the facts, and the JSON Schema for it), tensors (a run of positions as one typed array per fact) and python (the PyO3 module the wheel is built from). Position::polyglot_key needs no feature.

Python

pip install esca

import esca

game = esca.Game()  # Chess960 rules: esca.Game(variant=esca.CHESS960)
game.play_san("e4")
game.play("e7e5")
print(game.position.fen)

facts = game.facts()
print(facts.tactics.legal_move_count.white)
print(list(facts.pawns.passed.black.files))
print(facts.to_dict()["material"])  # every group in the one JSON form

Wheels are abi3 for Python 3.12 and up. pip install esca[tensors] adds NumPy and esca.tensors, which turns a run of positions into one typed array per fact.

Examples

Three short programs a side, reading the same examples/games.pgn, in examples/ and python/examples/:

arrays. Takes the engine's path; without one it says so and stops.

• pgnreport / readgames.py — per game of a PGN file: opening, final position, ending, passers.
• whyillegal / legalmoves.py — every legal move and what it does, then why one other is not.
• enginegame / enginegame.py — a UCI engine against itself, its ending as English, JSON and

What it covers

Shortened. The full README is on GitHub.