Reconnaissance Blind Chess MCP Server

A Model Context Protocol (MCP) server that enables humans and LLMs to play Reconnaissance Blind Chess (RBC) both locally against AI bots and remotely on the official RBC server at rbc.jhuapl.edu.

What is Reconnaissance Blind Chess?

Reconnaissance Blind Chess is a variant of chess where you can only see your own pieces. Key rules:

• Limited Vision: You only see your own pieces, not your opponent's
• Sensing Phase: Each turn, you can sense a 3x3 area to discover opponent pieces
• Move Phase: Make a move based on your incomplete knowledge
• Capture to Win: The goal is to capture the opponent's king (not checkmate)
• Check Rules Removed: You can move into check, castle through check, etc.

For complete rules, see: https://reconchess.readthedocs.io/en/latest/rules.html

Features

• Play local games against three different AI bots:
  • RandomBot: Plays random legal moves
  • AttackerBot: Prefers capturing moves and senses in opponent territory
  • TroutBot: Actively seeks and tracks the opponent's king
• Connect to remote games on rbc.jhuapl.edu
• Full MCP tool integration for Claude and other LLM clients
• Game state tracking with turn-by-turn information
• Asynchronous game execution in background threads

Installation

Prerequisites

• Python 3.9 or higher
• pip or pip3

Setup

1. Clone or download this repository

2. Create a virtual environment and install dependencies:

cd rbc_mcp_server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Verify installation:

python3 rbc_mcp_server.py --version

Usage

Running the MCP Server

The MCP server communicates via stdio and is designed to be used with MCP clients like Claude Desktop.

To run standalone (for testing):

source venv/bin/activate
python3 rbc_mcp_server.py

Configuring with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "rbc": {
      "command": "/Users/YOUR_USERNAME/projects/rbc_mcp_server/venv/bin/python3",
      "args": ["/Users/YOUR_USERNAME/projects/rbc_mcp_server/rbc_mcp_server.py"]
    }
  }
}

Replace /Users/YOUR_USERNAME/projects/rbc_mcp_server with your actual path.

MCP Tools

Local Game Tools

create_local_game

Create and start a new local game against a bot.

Parameters:

• bot_type (optional): "random", "attacker", or "trout" (default: "random")
• color (optional): "white", "black", or "random" (default: "random")

Returns: Game ID and initial game information

get_game_status

Get the current status of a game.

Parameters:

• game_id: The game ID

Returns: Game status including whether it's waiting for your input

get_board_state

Get your current view of the board (only pieces you can see).

Parameters:

• game_id: The game ID

Returns: Board FEN and unicode representation

choose_sense

Choose a square to sense (reveals 3x3 area).

Parameters:

• game_id: The game ID
• square: Square name (e.g., "e4", "d5") or "pass"

choose_move

Choose a move to make.

Parameters:

• game_id: The game ID
• move: Move in UCI format (e.g., "e2e4") or "pass"

get_sense_result

Get the result of your last sense action.

get_move_result

Get the result of your last move.

get_opponent_move_info

Get information about opponent's last move.

list_local_games

List all active local game IDs.

delete_local_game

Delete a game and free its resources.

Remote Game Tools

create_remote_game

Connect to a game on rbc.jhuapl.edu.

Parameters:

• server_url (optional): Server URL (default: "https://rbc.jhuapl.edu")
• auth_token: Base64 encoded authentication token
• remote_game_id: Game ID on the remote server

get_remote_game_status

Get the status of a remote game.

list_remote_games

List all active remote game sessions.

delete_remote_game

Delete a remote game session.

Example Game Flow

Here's how a typical game works:

1. Create a game:

create_local_game(bot_type="trout", color="white")
→ Returns game_id: 1

2. Check status (repeat until waiting_for_sense is true):

get_game_status(game_id=1)
→ waiting_for_sense: true

3. Sense the board:

choose_sense(game_id=1, square="e4")
get_sense_result(game_id=1)
→ Shows 3x3 area around e4

4. Check status (repeat until waiting_for_move is true):

get_game_status(game_id=1)
→ waiting_for_move: true

5. Make a move:

choose_move(game_id=1, move="e2e4")
get_move_result(game_id=1)
→ Shows if move succeeded and if you captured anything

6. Repeat steps 2-5 until game is over

Playing on Remote Server

To play on the official RBC server at rbc.jhuapl.edu:

1. Authentication: Use the provided token: bWNwX3JiYzpCZWF6ZXJCMzNz

2. Get a game ID: You'll need to create or join a game on the RBC server (outside of this MCP)

3. Connect:

create_remote_game(
  auth_token="bWNwX3JiYzpCZWF6ZXJCMzNz",
  remote_game_id="YOUR_GAME_ID"
)

4. Play: Use the same sense/move flow as local games

Architecture

The server is structured as follows:

• Bot Players: Three AI opponents implementing the reconchess Player interface
• Human Player: Interactive player that waits for MCP tool calls
• Game Manager: Manages multiple concurrent games (local and remote)
• Background Threads: Games run asynchronously to avoid blocking the MCP server
• MCP Server: Provides tools for game interaction

Dependencies

• reconchess>=1.0.0 - Official Reconnaissance Blind Chess library
• python-chess>=1.0.0 - Chess logic and board representation
• mcp>=0.1.0 - Model Context Protocol SDK
• httpx>=0.24.0 - HTTP client for remote games

Game Rules Reference

From the official documentation:

Turn Structure

Each turn has three phases:

1. Opponent Move Notification: Learn if opponent captured your piece
2. Sense Phase: Choose a square to sense (3x3 area)
3. Move Phase: Make your move

Move Execution

• Moves must be legal on the true board
• Sliding pieces (Q, R, B) capture if blocked by opponent
• Pawns moving 2 squares move 1 if blocked
• Illegal moves result in passing

Winning

• Capture the opponent's king to win
• No checkmate rules
• Games can end by timeout or other conditions

Troubleshooting

"reconchess could not be resolved"

Make sure you've activated the virtual environment:

source venv/bin/activate

Game not responding

Check the game status to see if it's waiting for your input:

get_game_status(game_id=1)

Remote game connection issues

Verify:

1. You have the correct authentication token
2. The game ID exists on the server
3. The game hasn't already started or finished

License

This project uses the reconchess library and follows its licensing terms.

References

• Reconchess Documentation
• Reconchess Rules
• RBC Server
• Model Context Protocol