Reconnaissance Blind Chess MCP Server
An MCP (Model Context Protocol) server that enables LLM agents to play Reconnaissance Blind Chess (RBC) games remotely on rbc.jhuapl.edu against various bots.
Overview
This server provides tools for LLM agents to:
- Play unranked games against specific bots (random, attacker, trout, Oracle, StrangeFish2, etc.)
- Wait for and accept ranked game invitations
- Choose colors (white, black, or random) for unranked games
- Track game state, board positions, and move history
- View ASCII representations of the current board
- Submit sense actions and moves during gameplay
Installation
Prerequisites
- Python 3.8 or higher
- An account on rbc.jhuapl.edu
Setup
- Clone or download this repository:
cd /Users/diept1/projects/rbc_mcp_server
- Create and activate a virtual environment:
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
Usage
Running the MCP Server
Start the server using:
python rbc_mcp_server.py
The server communicates via stdio and is designed to be used with MCP-compatible clients (like Claude Desktop or other LLM interfaces).
Configuring Claude Desktop
Add this to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"rbc": {
"command": "python",
"args": ["/Users/diept1/projects/new_rbc_mcp_server/rbc_mcp_server.py"],
"env": {}
}
}
}
Adjust the path to match your installation directory.
Available Tools
1. start_unranked_game
Start an unranked game against a specific bot by sending an invitation (based on rc_play_on_server.py).
Parameters:
opponent_bot(string): Bot name (e.g., "random", "attacker", "trout", "oracle", "strangefish2")color(string): Color to play as ("white", "black", or "random")- "white": Always play as white
- "black": Always play as black
- "random": 50/50 chance of either color
username(string): Your username on rbc.jhuapl.edupassword(string): Your password on rbc.jhuapl.edu
Example:
{
"opponent_bot": "trout",
"color": "white",
"username": "your_username",
"password": "your_password"
}
Notes:
- The server sends an invitation to the bot via
server.send_invitation() - The game starts automatically when the bot accepts the invitation
- Use
list_active_gamesto see when the game has started - The game ID is generated by the server upon invitation acceptance
2. start_ranked_game
Start listening for ranked game invitations from the RBC server. Automatically accepts invitations and plays games with assigned colors.
Parameters:
username(string): Your username on rbc.jhuapl.edupassword(string): Your password on rbc.jhuapl.edumax_concurrent_games(integer, optional): Maximum number of concurrent ranked games to play (default: 1)
Example:
{
"username": "your_username",
"password": "your_password",
"max_concurrent_games": 2
}
Notes:
- The listener runs continuously in the background, checking for invitations every 5 seconds
- When an invitation is received, it's automatically accepted and a game starts
- You'll be assigned a color by the server
- Use
list_active_gamesto see which games are running - Use
stop_ranked_listenerto stop accepting new invitations
3. stop_ranked_listener
Stop listening for ranked game invitations.
Parameters: None
Example:
{}
Notes:
- Games already in progress will continue
- You can start listening again with
start_ranked_game
4. get_game_state
Get the current state of a game including all tracking information.
Parameters:
game_id(string): The game ID returned when starting a game
5. get_board_ascii
Get an ASCII representation of the current board state with game information.
Parameters:
game_id(string): The game ID
Example Output:
8 r n b q k b n r
7 p p p p p p p p
6 . . . . . . . .
5 . . . . . . . .
4 . . . . P . . .
3 . . . . . . . .
2 P P P P . P P P
1 R N B Q K B N R
a b c d e f g h
Turn: 1
Playing as: White
Opponent: trout
Last move: e2e4
Actual move: e2e4
6. submit_sense
Submit a sense action for the current turn. In RBC, sensing reveals a 3x3 area centered on the chosen square.
Parameters:
game_id(string): The game IDsquare(string): Square to sense (e.g., "e4", "d5") or "pass" to skip sensing
Example:
{
"game_id": "unranked_trout_20231130_143022",
"square": "e5"
}
7. submit_move
Submit a move for the current turn.
Parameters:
game_id(string): The game IDmove(string): Move in UCI format (e.g., "e2e4", "e7e8q" for promotion) or "pass" to skip moving
Example:
{
"game_id": "unranked_trout_20231130_143022",
"move": "e2e4"
}
8. list_active_games
List all currently active games.
Parameters: None
9. get_game_history
Get detailed move-by-move history of a game.
Parameters:
game_id(string): The game ID
Game Flow
Each turn in Reconnaissance Blind Chess follows this sequence:
- Opponent Move Result: You're informed if your opponent captured one of your pieces
- Sense Phase: Choose a square to sense (reveals 3x3 area around it)
- Move Phase: Choose a move to make
Example Unranked Game Session
1. Start a game:
Use: start_unranked_game with opponent="trout", color="white"
2. View the board:
Use: get_board_ascii with the returned game_id
3. Submit sense:
Use: submit_sense with square="e5"
4. Submit move:
Use: submit_move with move="e2e4"
5. Repeat steps 2-4 for each turn
Example Ranked Game Session
1. Start listening for invitations:
Use: start_ranked_game with username="your_username", password="your_password"
2. Wait for invitations (happens automatically in background):
The server will accept invitations and start games
3. Check active games:
Use: list_active_games to see which games are running
4. Play each game:
For each game_id, use get_board_ascii, submit_sense, and submit_move
5. Stop listening (when done):
Use: stop_ranked_listener
RBC Rules Summary
- Objective: Capture the opponent's king (not checkmate)
- Sensing: Each turn, sense a 3x3 area to see the true board state
- Moves: Make standard chess moves, but illegal moves may fail or be modified
- No check warnings: Kings can move into check
- Limited information: You only see what you sense and capture feedback
For complete rules, see: RBC Rules Documentation
API Documentation
This server implements the reconchess Player API. For full API details, see: Reconchess API Documentation
Game State Tracking
The server tracks for each game:
- Current board state (based on your sensing)
- Turn number
- All opponent move results
- All sense results
- All your move results
- Game history when complete
Resources
The server exposes game states as MCP resources at:
rbc://game/{game_id}- JSON representation of game state
Troubleshooting
Import Errors
If you see import errors for mcp, chess, or reconchess:
pip install -r requirements.txt
Connection Issues
- Verify your rbc.jhuapl.edu credentials
- Check that the server is accessible
- Ensure you have an active internet connection
Game Timeout
Games have time limits. If a turn times out:
- The server will auto-pass for sense/move
- Check
seconds_leftin game state
Contributing
This is a basic implementation. Potential improvements:
- Better error handling and retry logic
- Support for local games
- Game replay functionality
- Enhanced board visualization
- Tournament support
License
This project uses the reconchess library and follows its license terms.