FireKickerton/rbc-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 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

1. Clone or download this repository:

cd /Users/diept1/projects/rbc_mcp_server

2. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. 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.edu
• password (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_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:

{
  "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:

{}

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:

{
  "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:

{
  "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

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_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
• Reconchess Documentation
• RBC Rules
• MCP Documentation