# 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/)