Overview
Queen gives LLMs a perfect understanding of chess rules and deep tactical reasoning. While traditional chess engines only output computer moves, Queen uses symbolic logic to let AI agents understand why a move is illegal, detect pins or forks, and converse about chess tactics with human-like explanation.
Unlike pure heuristics-based engines, Queen implements chess rules as a set of logical symbolic constraints in SWI-Prolog. This allows the system to not only validate moves but also output natural diagnostics and explanations for rule violations (e.g. explaining exactly why a piece cannot move because it is pinned to the king).
These constraints are packaged into a Python layer using a seamless bridge, which is then exposed as a Model Context Protocol (MCP) Server. This enables LLMs like Claude or Gemini to query board positions, retrieve tactical details, and obtain rules explanations during chess play.
System Architecture
Queen's pipeline is cleanly divided into three distinct abstraction layers, each feeding structured insights to the next:
Constraint Logic Layer
queen.pl
Written in SWI-Prolog. Represents the chessboard state as a set of facts and defines logical rules for move legality, path blockers, checks, mate conditions, pins, forks, and defenses.
Orchestration Layer
queen.py
Written in Python. Uses pyswip to load the Prolog rulebase, parses standard FEN strings into symbolic variables, executes queries, and returns structured Python data structures.
Interface Layer
queen_mcp.py
Exposes functions in the orchestration layer as tools using FastMCP. Facilitates stdio communication with LLM hosts, matching tool calls to JSON-RPC schemas.
Interactive Playground
Select a preset tactical situation below to update the interactive chessboard and view the code outputs generated for each layer of the Queen stack:
👉 Click the dropdown to swap scenarios and watch the live data payload change across the stack.
Live FEN Sandbox
Test your own FEN positions in real-time. This sandbox runs the actual Prolog constraint rules compiled into JavaScript directly in your browser. Click pieces to highlight legal moves, select highlighted squares to execute them, or input a custom FEN.
JSON Analysis Summary will appear here after engine finishes loading...
Generated Prolog board state will appear here...
Use Case: R_Daneel_AI
The power of Queen's symbolic chess constraints is demonstrated in R_Daneel_AI, a neuro-symbolic chess bot. While traditional engines rely on raw mathematical calculation and LLMs normally struggle with legal move generation, R_Daneel_AI uses an LLM for planning and relies on Queen to act as its "eyes and referee."
By querying Queen for move legality, pins, discovered attacks, and mate checks, the LLM is able to play error-free chess and formulate chess strategies through reasoning rather than brute-force search.
Tactical Elo Benchmarks
To evaluate this approach, a comprehensive benchmark was run across 500 Lichess chess puzzles (ranging from 600 to 1500 Elo). The benchmark compared a pure LLM baseline (given legal moves but no tools) against R_Daneel_AI (powered by the local model gemma-4-26B served via vLLM, integrated with Queen):
| Evaluation Metric (500-Puzzle Benchmark) | Pure LLM Baseline gemma-4-26B |
R_Daneel_AI (Ours) gemma-4-26B + Queen |
Improvement Delta |
|---|---|---|---|
| Puzzles Solved | 80 / 500 | 404 / 500 | +324 puzzles solved |
| Accuracy / Pass Rate | 16.0% | 80.8% | +64.8% accuracy boost |
| Tactical Elo (Bisection Method) | 673 Elo | 1478 Elo | +805 Elo Points |
| Inference Retries / Logic Loops | High (6+ retries) | 0.18 avg retries | Resolved loop deadlocks |
API & Tool Reference
The Queen MCP server exposes these analytical tools to clients. Under the hood, they map directly to functions inside queen.py.
| Tool Name | Parameters | Exposes Logic From | Description |
|---|---|---|---|
validate_move |
fen (str), move_uci (str) |
validate_and_explain/4 |
Checks move legality. Returns boolean status and structured explanation if illegal. |
get_legal_moves |
fen (str) |
legal_move/4 |
Lists all legal moves in UCI format (e.g. e2e4). |
get_game_status |
fen (str) |
game_status/2 |
Calculates game status: active, checkmate, or stalemate. |
get_pinned_pieces |
fen (str) |
is_pinned/3 |
Identifies coordinates of friendly pieces pinned to the king. |
get_threats |
fen (str) |
is_attacked/3, is_defended/3 |
Retrieves lists of defended friendly pieces and threatened friendly pieces. |
get_discovered_attacks |
fen (str) |
discovered_attack_candidate/5 |
Detects slider alignments where moving a blocking piece opens an attack. |
get_forks |
fen (str) |
is_fork/5, creates_fork/5 |
Identifies existing forks and moves that create a new double attack. |
get_tactical_summary |
fen (str) |
All modules combined | Aggregates pins, forks, threats, checks, and phase data into a full position overview. |
Setup & Usage Guide
Follow these steps to integrate Queen as an MCP server or use it directly as a Python library:
1. System & Python Dependencies
Queen requires SWI-Prolog installed on your operating system (as the Python bridge binds to its shared library). On Debian/Ubuntu:
sudo apt-get install swi-prolog
If you are running the MCP server or modules directly from source without installing the pip package, install the Python dependencies manually:
pip install pyswip python-chess mcp
2. Configure MCP Client (Optional)
Required only for integrating Queen as an MCP tool server for AI assistants like Claude Desktop. Skip this step if you only want to import Queen as a Python package.
To use Queen with the Claude Desktop client, add the server configuration inside your claude_desktop_config.json file:
{
"mcpServers": {
"queen": {
"command": "python",
"args": [
"/absolute/path/to/Queen/queen_mcp.py"
]
}
}
}
3. Python Library Integration (Optional)
Required only if you want to import queen directly into a Python application. Skip this step if you are only using Queen via the MCP server interface.
Queen can be installed directly into your Python environment as a package, which automatically bundles and configures the Prolog symbolic engine:
pip install queen-chess
Or install the local repository in editable development mode:
pip install -e .
Once installed, you can import the library and query tactical constraints from any Python script:
import queen # Validate a move and get constraint-based rule explanations is_legal, explanation = queen.check_move_diagnostics( "r1bqkb1r/pppp1Qpp/2n2n2/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4", "e8f7" ) print(f"Legal: {is_legal}, Explanation: {explanation}")