# Chess MCP Server

A Model Context Protocol (MCP) server that provides seamless access to Chess.com API data through AI assistants like Claude, ChatGPT, and others.

## MCP Resources

- **Official Documentation**: [Model Context Protocol](https://modelcontextprotocol.io/)
- **GitHub Repository**: [modelcontextprotocol](https://github.com/modelcontextprotocol)
- **Specification**: [MCP Specification](https://spec.modelcontextprotocol.io/)

## Project Architecture

This Chess MCP Server provides three main tools:

1. **`getPlayerProfile`** - Retrieve player information and statistics
2. **`getPlayerStats`** - Get detailed player ratings and performance data
3. **`getDailyPuzzle`** - Access the daily chess puzzle

## Quick Start

### Prerequisites

- Node.js 18.0.0 or higher
- npm or yarn package manager

### Installation

1. **Clone the repository**

   ```bash
   git clone https://github.com/dipalosalvatore/chess-mcp-server.git
   cd chess-mcp-server
   ```

2. **Install dependencies**

   ```bash
   npm install
   ```

3. **Build the project**

   ```bash
   npm run build
   ```

4. **Start the server**

   ```bash
   npm start
   ```

## Docker Support

### Using Docker

1. **Build the Docker image**

   ```bash
   docker build -t chess-mcp-server .
   ```

2. **Run the container**

   ```bash
   docker run -it chess-mcp-server
   ```

### Docker Configuration for MCP Clients

When using Docker, update your MCP client configuration to use the Docker container:

#### Claude Desktop with Docker

```json
{
  "mcpServers": {
    "chess": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chess-mcp-server"],
      "env": {}
    }
  }
}
```

## MCP Configuration

### For Claude Desktop

1. **Open Claude Desktop settings**
2. **Navigate to "Servers" section**
3. **Add a new server with these settings:**

```json
{
  "name": "Chess MCP Server",
  "command": "node",
  "args": ["/path/to/chess-mcp-server/dist/index.js"],
  "env": {}
}
```

### For Other MCP Clients

Most MCP clients support similar configuration. The server communicates via stdin/stdout, so you'll need to specify:

- **Command**: `node`
- **Arguments**: `[path-to-dist/index.js]`
- **Working Directory**: Your project directory

### Example Configuration Files

#### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "chess": {
      "command": "node",
      "args": ["/Users/username/projects/chess-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}
```

#### ChatGPT (if supported)

```json
{
  "servers": [
    {
      "name": "Chess Server",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/chess-mcp-server"
    }
  ]
}
```

## Available Tools

### 1. Get Player Profile

Retrieves comprehensive player information from Chess.com.

**Tool Name**: `getPlayerProfile`

**Parameters**:

- `username` (string, required): Chess.com username

**Example Usage**:

```
Get the profile for player "magnuscarlsen"
```

### 2. Get Player Stats

Retrieves detailed player statistics and ratings.

**Tool Name**: `getPlayerStats`

**Parameters**:

- `username` (string, required): Chess.com username

**Example Usage**:

```
Get statistics for player "hikaru"
```

### 3. Get Daily Puzzle

Retrieves the current daily puzzle from Chess.com.

**Tool Name**: `getDailyPuzzle`

**Parameters**: None

**Example Usage**:

```
Get today's chess puzzle
```

## Development

### Building from Source

```bash
# Install dependencies
npm install

# Type checking
npm run type-check

# Build the project
npm run build

```

### Project Structure Details

#### Chess API Wrapper (`src/chess/`)

The chess API is organized into specialized classes:

- **`PlayerApi`** - Player profiles, stats, and game history
- **`PuzzleApi`** - Daily puzzles and random puzzles
- **`CommunityApi`** - Clubs, tournaments, and teams
- **`BaseChessApi`** - Common functionality and HTTP client setup

#### MCP Tools (`src/tools/`)

Each tool is implemented as a function that:

1. Validates input using Zod schemas
2. Calls the appropriate Chess.com API
3. Returns standardized MCP responses
4. Handles errors gracefully

### Error Handling

The server provides comprehensive error handling:

- **Validation Errors** (400) - Invalid input parameters
- **Not Found Errors** (404) - Player or resource not found
- **Rate Limit Errors** (429) - API rate limit exceeded
- **Server Errors** (5xx) - Chess.com API issues

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Chess.com](https://chess.com) for providing the API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP standard
- [Anthropic](https://anthropic.com) for Claude and MCP support