Reconnaissance Blind Chess MCP Server

# 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](https://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](https://rbc.jhuapl.edu) ### Setup 1. Clone or download this repository: ```bash cd /Users/diept1/projects/rbc_mcp_server ``` 2. Create and activate a virtual environment: ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` 3. Install dependencies: ```bash pip install -r requirements.txt ``` ## Usage ### Running the MCP Server Start the server using: ```bash 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` ```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.edu - `password` (string): Your password on rbc.jhuapl.edu **Example:** ```json { "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_games` to 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.edu - `password` (string): Your password on rbc.jhuapl.edu - `max_concurrent_games` (integer, optional): Maximum number of concurrent ranked games to play (default: 1) **Example:** ```json { "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_games` to see which games are running - Use `stop_ranked_listener` to stop accepting new invitations ### 3. `stop_ranked_listener` Stop listening for ranked game invitations. **Parameters:** None **Example:** ```json {} ``` **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 ID - `square` (string): Square to sense (e.g., "e4", "d5") or "pass" to skip sensing **Example:** ```json { "game_id": "unranked_trout_20231130_143022", "square": "e5" } ``` ### 7. `submit_move` Submit a move for the current turn. **Parameters:** - `game_id` (string): The game ID - `move` (string): Move in UCI format (e.g., "e2e4", "e7e8q" for promotion) or "pass" to skip moving **Example:** ```json { "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: 1. **Opponent Move Result**: You're informed if your opponent captured one of your pieces 2. **Sense Phase**: Choose a square to sense (reveals 3x3 area around it) 3. **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](https://reconchess.readthedocs.io/en/latest/rules.html) ## API Documentation This server implements the reconchess Player API. For full API details, see: [Reconchess API Documentation](https://reconchess.readthedocs.io/en/latest/reconchess.html#player) ## 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`: ```bash 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_left` in 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. ## Links - [RBC Server](https://rbc.jhuapl.edu) - [Reconchess Documentation](https://reconchess.readthedocs.io/) - [RBC Rules](https://reconchess.readthedocs.io/en/latest/rules.html) - [MCP Documentation](https://modelcontextprotocol.io/)