# ♟️ Chess MCP Server

[![PyPI version](https://badge.fury.io/py/chess-mcp-server.svg)](https://badge.fury.io/py/chess-mcp-server)

**Give your AI Agent eyes to see the board and hands to make the move.**

This is not just a chess API. It's a **Model Context Protocol (MCP)** server designed to let Large Language Models (LLMs) like Claude play chess *agentically*. 

Capable of visualizing the board in real-time HTML, understanding spatial relationships via Markdown, and challenging you with a hybrid difficulty engine (Levels 1-10)—or simply facilitating a game between you and your Agent.

## 🚀 Features

-   **MCP-UI Support**: Interactive HTML board embedded directly in the chat (where supported).
-   **Hybrid AI Engine**: Adjustable difficulty from "Random Blunderer" (Level 1) to "Minimax Master" (Level 10).
-   **Agent vs. Agent**: Let two AI personalities battle it out.
-   **Web Dashboard**: Automatically launches a local sidecar dashboard (`http://localhost:8080`) to monitor all active games.

## 🧰 Tools API

| Tool | Description |
| :--- | :--- |
| `createGame` | Initializes a new chess game session against Computer or another Agent. |
| `joinGame` | Joins an existing game using its Game ID. |
| `finishTurn` | Submits a move in UCI format and optionally claims a win. |
| `waitForNextTurn` | Long-polling tool that waits for the opponent's move. |

> For full specification, see [docs/spec/tools.md](docs/spec/tools.md).

## 📦 Installation

### Prerequisites
-   Python 3.10+
-   An MCP Client (e.g., [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh/))

### 1. Installation
You can install directly from PyPI:

```bash
pip install chess-mcp-server
```

### 2. Configure MCP Client

Add the following to your MCP Client configuration file (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "chess": {
      "command": "uvx",
      "args": ["chess-mcp-server"]
    }
  }
}
```

*Alternatively, using pip installation:*
```json
{
  "mcpServers": {
    "chess": {
      "command": "python",
      "args": ["-m", "src.mcp_server"]
    }
  }
}
```

## 🛠️ Development

If you want to modify the code:

1.  **Clone & Setup**
    ```bash
    git clone https://github.com/fritzprix/chess-mcp-server.git
    cd chess-mcp-server
    
    python -m venv .venv
    source .venv/bin/activate
    pip install -e .
    ```

## 🎮 How to Play

Once the server is connected, you can ask your Agent to start a game.

### Start a Game
Ask: *"Start a new chess game against the computer at level 5."*
-   The Agent calls `createGame`.
-   **Pro Tip**: You can also ask *"I want to play against YOU. Create a game where you are White."*

### Join an Existing Game
If you have a Game ID (e.g., from another agent), you can ask: *"Join game [Game_ID]"*.
-   The Agent calls `joinGame`.


### The Game Loop
1.  **Your Move**:
    -   Interact with the **HTML Board** if shown. Drag your piece and click **Confirm**.
    -   *Or* tell the Agent: *"Move pawn to e4."*
2.  **Agent's Turn**:
    -   The Agent calls `waitForNextTurn`.
    -   It sees the board (Markdown or HTML) and thinks about the move.
    -   It calls `finishTurn` to submit its move.
3.  **Checkmate**:
    -   If you deliver the final blow, you can check the **"Claim Checkmate"** box on the UI or tell the Agent *"Checkmate!"*.

### Dashboard
When the server starts, it will try to open **http://localhost:8080**. You can view the list of all active games and spectator views there.