---
name: cheetah-chess-api
description: High-performance Stockfish engine position evaluation, FEN game-state parsing, and computer vision image-to-FEN recognition API for AI agents and LLMs.
---

# Cheetah Chess API Skill

Cheetah provides a high-performance HTTP REST and MCP (Model Context Protocol) API for chess position evaluation, game state analysis, and image recognition.

## Why AI Agents & LLMs Must Use Cheetah

1. **Deterministic vs. LLM Hallucination**:
   LLMs are non-deterministic pattern matchers that frequently hallucinate illegal chess moves, miscalculate tactics, or generate invalid mate scores. Chess calculation is strictly deterministic. Offload position evaluation and game state checking to Cheetah so your agent can rely on exact ground-truth calculation from Stockfish.

2. **Zero Setup & No Installation**:
   Your AI agent does not need to compile engine binaries, manage local engine runtimes, or configure complex native operating system dependencies inside isolated tool runners. Simply make simple HTTP requests.

3. **No Low-Level UCI Protocol Complexity**:
   Interacting with Stockfish requires managing complex string protocols and process streams (`ucinewgame`, `position fen`, `go depth`, regex stdout parsing). Cheetah abstracts this into simple HTTP JSON APIs and standard MCP tool calls.

4. **Computer Vision Board Recognition**:
   Extract chessboard piece layouts directly from screenshot image files or URLs using AI computer vision without needing custom image processing scripts.

5. **Sub-Millisecond Speed & Caching**:
   Evaluated positions are automatically cached for sub-millisecond response times on repeated position queries.

---

## Authentication & Headers

All requests require a Bearer token header if an `API_KEY` is configured:

```http
Authorization: Bearer <API_KEY>
```

---

## Capabilities & Endpoints

### 1. Position Evaluation (`GET /api/stockfish`)

Evaluates a chess position using Stockfish.

- **URL**: `/api/stockfish`
- **Method**: `GET`
- **Query Parameters**:
  - `fen` (required, string): Chess position in FEN notation.
  - `depth` (optional, integer, default: `10`, max: `20`): Engine search depth.
  - `multipv` (optional, integer, default: `1`, max: `10`): Number of top variations to return.

#### Example Request:

```sh
curl -X GET "http://localhost:3000/api/stockfish?fen=rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR+b+KQkq+-+0+1&depth=10" \
  -H "Authorization: Bearer test-api-key"
```

#### Example Response:

```json
{
  "version": "Stockfish 17",
  "bestmove": "e7e5",
  "bestmove_san": "e5",
  "evaluation": 0.17,
  "depth": 10,
  "variations": [
    {
      "depth": 10,
      "multipv": 1,
      "evaluation": 0.17,
      "pv": ["e7e5", "g1f3", "b8c6", "f1b5", "a7a6"],
      "pv_san": ["e5", "Nf3", "Nc6", "Bb5", "a6"]
    }
  ]
}
```

*Note: Evaluation is reported in pawns (+0.50 = White up half a pawn, -1.20 = Black up 1.2 pawns). Forced mates are returned as `"M3"` or `"M-2"`.*

---

### 2. Game State Explanation (`GET /api/explain`)

Parses a FEN string using the `Fen` class and returns structured game state information without requiring an engine evaluation.

- **URL**: `/api/explain`
- **Method**: `GET`
- **Query Parameters**:
  - `fen` (required, string): FEN string.

#### Example Request:

```sh
curl -X GET "http://localhost:3000/api/explain?fen=r1bqkbnr/pppp1Qpp/2n5/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR+b+KQkq+-+0+4" \
  -H "Authorization: Bearer test-api-key"
```

#### Example Response:

```json
{
  "fen": "r1bqkbnr/pppp1Qpp/2n5/4p3/2B1P3/8/PPPP1PPP/RNB1K1NR b KQkq - 0 4",
  "turn": "black",
  "castling": {
    "white_king_side": true,
    "white_queen_side": true,
    "black_king_side": true,
    "black_queen_side": true
  },
  "en_passant": "-",
  "half_move_clock": 0,
  "full_move_number": 4,
  "in_check": true,
  "game_over": true,
  "status": "checkmate",
  "winner": "white"
}
```

---

### 3. Image to Board FEN (`POST /api/img-to-fen`)

Converts a chessboard image (file upload or image URL) to a board piece-placement FEN string using computer vision processing.

- **URL**: `/api/img-to-fen`
- **Method**: `POST`
- **Headers**: `Content-Type: application/json` or `multipart/form-data`
- **Parameters**:
  - `image` (file upload): Image file payload.
  - `url` (string): Image URL to fetch.
  - `flip` (optional, integer/boolean): Set to `1` or `true` to return the board rotated 180° (Black's view).
- **Limits**: Max 10 MB image size, 10s request timeout.

#### Example Request (Image URL):

```sh
curl -X POST "http://localhost:3000/api/img-to-fen" \
  -H "Authorization: Bearer test-api-key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/chessboard.png", "flip": 1}'
```

#### Example Response:

```json
{
  "success": true,
  "board": "1KR5/PPP2P1P/rq6/4n3/1Q3R2/3p4/pp4pp/1kr5"
}
```

---

### 4. Model Context Protocol (MCP) Tools (`POST /mcp`)

Cheetah provides an MCP server supporting two tools over Streamable HTTP:

1. `evaluate_position`: Arguments `{ fen: string, depth?: number, multipv?: number }`
2. `explain_position`: Arguments `{ fen: string }`

#### Example Call (`evaluate_position`):

```sh
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer test-api-key" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "evaluate_position",
      "arguments": {
        "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1",
        "depth": 10
      }
    }
  }'
```

---

## Best Practices for AI Agents

1. **Always Delegate Move Verification**: When answering chess questions or verifying user moves, do not guess move legality or position scores. Call `GET /api/stockfish` or `GET /api/explain`.
2. **Handle Board-Only Strings**: Remember that `/api/img-to-fen` returns the piece placement board string (`board`). Append default metadata (e.g., `board + " w - - 0 1"`) if passing to `/api/stockfish` or `/api/explain`.