# Chess MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to play chess against users. The server provides tools for managing chess games, making moves, evaluating positions, and visualizing the board.

## Features

- **Game Management**: Create new games, get board state, visualize positions
- **Move Validation**: Validate moves before making them
- **AI Opponent**: Play against Stockfish chess engine
- **Position Evaluation**: Get engine evaluation of positions
- **Move History**: Track moves with undo functionality
- **Board Visualization**: ASCII art board representation

## Requirements

- Python 3.11 or higher
- [uv](https://github.com/astral-sh/uv) package manager
- Stockfish chess engine (included in `server/bin/stockfish/`)

## Installation

1. Clone the repository:
```bash
git clone <repository-url>
cd chess-mcp
```

2. Install dependencies and the package:
```bash
uv sync
```

This will:
- Create a virtual environment
- Install all dependencies (including `mcp` and `chess`)
- Install the package in editable mode

## Running the Server

### Using the Entry Point

After installation, you can run the server using:

```bash
uv run chess-mcp
```

### Running as a Module

Alternatively, you can run it as a Python module:

```bash
uv run -m server.main
```

The server runs on `stdio` transport, which means it communicates via standard input/output. This is the standard way MCP servers interact with clients.

## Configuration for MCP Clients

### Claude Desktop

To use this server with Claude Desktop, add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chess-game": {
      "command": "uv",
      "args": [
        "run",
        "chess-mcp"
      ],
      "cwd": "/path/to/chess-mcp"
    }
  }
}
```

Replace `/path/to/chess-mcp` with the absolute path to this project directory.

### Other MCP Clients

For other MCP clients, configure them to run:
```bash
uv run chess-mcp
```

Make sure the working directory is set to the project root.

## Available Tools

The server provides the following MCP tools:

### Game State
- **`new_game_tool`**: Creates a new chess game
- **`get_state_tool`**: Returns the current board state in FEN format
- **`visualize_board_tool`**: Returns an ASCII art visualization of the board

### Moves
- **`make_move_tool(move: str)`**: Makes a move in UCI format (e.g., "e2e4")
- **`ai_make_move_tool`**: Makes a move using the AI opponent
- **`undo_move_tool`**: Undoes the last move

### Validation
- **`validate_move_tool(move: str)`**: Validates if a move is legal

### Analysis
- **`evaluate_board_tool`**: Returns the engine's evaluation of the position in centipawns

## Project Structure

```
appli/
├── server/
│   ├── main.py              # MCP server entry point
│   ├── config.py            # Configuration (paths, etc.)
│   ├── engine/              # Stockfish engine wrapper
│   ├── storage/             # File I/O and serialization
│   └── tools/               # MCP tool implementations
├── storage/                 # Game state storage
│   ├── current_game.fen     # Current board position
│   └── move_history.json    # Move history for undo
├── tests/                   # Test files for tools
├── pyproject.toml           # Project configuration
└── README.md                # This file
```

## Storage

The server stores game state in the `storage/` directory:
- `current_game.fen`: Current board position in FEN notation
- `move_history.json`: List of moves made (for undo functionality)

## Development

### Running Tests

Install test dependencies:
```bash
uv sync --extra dev
```

Run tests:
```bash
uv run pytest
```

Run tests with coverage:
```bash
uv run pytest --cov=server --cov-report=html
```

### Adding New Tools

1. Create a function in the appropriate `server/tools/` module
2. Register it in `server/tools/registry.py`
3. Add it to the `register_tools()` function

## Troubleshooting

### Stockfish Not Found

If you get an error about Stockfish not being found:
- Check that `server/bin/stockfish/` contains the appropriate binary for your platform
- The server automatically detects your platform and selects the correct binary
- Supported: macOS (Intel/Apple Silicon), Linux, Windows

### Import Errors

If you encounter import errors:
- Make sure you've run `uv sync` to install the package
- Verify you're in the project root directory
- Check that the virtual environment is activated

## Acknowledgments

- Uses [python-chess](https://github.com/niklasf/python-chess) for chess logic
- Uses [Stockfish](https://stockfishchess.org/) chess engine
- Built with [FastMCP](https://github.com/jlowin/fastmcp) for MCP server functionality