# chess-coach-mcp

[![PyPI](https://img.shields.io/pypi/v/chess-coach-mcp.svg)](https://pypi.org/project/chess-coach-mcp/)
[![CI](https://github.com/parkseokjune/chess-coach-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/parkseokjune/chess-coach-mcp/actions/workflows/ci.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

A **hybrid AI chess coach** exposed as an [MCP](https://modelcontextprotocol.io)
server. A local **Stockfish** engine supplies grounded evaluations, mistake
classifications and tactical motifs; your MCP host model (e.g. Claude) turns
those facts into natural-language — **Korean or English** — coaching.

> The engine knows **what** the best move is. The model explains **why**.
> This project wires the two together and adds the piece neither does alone:
> *"here is **your** recurring mistake, drilled from **your** own games."*

```bash
pip install chess-coach-mcp      # or: uvx chess-coach-mcp   (needs a local Stockfish)
```

## See it in action

<p align="center">
  <img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/demo.gif" alt="Demo: a blunder, the engine's preferred move, and the recurring pattern" width="420">
</p>

`diagnose_weaknesses` turns your recent games into a weakness report — recurring
tactical blind spots and where you lose the most (by phase):

<p align="center">
  <img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/weakness_report.png" alt="Weakness heatmap: tactical blind spots and average centipawn loss by phase" width="820">
</p>

…then `recommend_drills` hands back the exact positions you went wrong in — your
move in red, the engine's in green — so you re-solve *your own* mistakes:

<p align="center">
  <img src="https://raw.githubusercontent.com/parkseokjune/chess-coach-mcp/main/docs/board_example.png" alt="Annotated drill board: your move in red, the engine's move in green" width="340">
</p>

> Numbers above are real Stockfish output; the weakness report uses an example
> dataset. Regenerate everything with
> `uv run --with matplotlib --with pillow python docs/generate_assets.py`.

## Why this exists

Engines (Stockfish) tell you the best move but not the reason. Raw LLMs explain
fluently but play/evaluate chess poorly and hallucinate lines. Existing trainers
are fragmented (one app for stats, one for explanations, one for courses) and
rarely give a *personalised, guided* path. `chess-coach-mcp` is the grounding
layer: every claim the coach makes is backed by Stockfish, and the weakness
diagnosis is computed from the player's actual games.

## What it does

- **Fetch** recent games from **Lichess** or **Chess.com** (public APIs, no key).
- **Analyse a game**: per-move classification (best / good / inaccuracy /
  mistake / blunder, with Korean labels), win% before/after, centipawn loss,
  the engine's preferred move, tactical-motif tags, and per-phase summary.
- **Analyse a position** (FEN): top engine lines in SAN, win%, material, and
  fork/pin flags — so the model can explain the *why*.
- **Diagnose weaknesses** across many games: phase weaknesses
  (opening/middlegame/endgame), recurring tactical blind spots with example
  positions, leaky openings, a time-trouble proxy, and a ranked top-weakness
  list.
- **Recommend drills**: re-solvable positions taken from the player's **own
  blunders**, ordered to target their top weaknesses, plus a Lichess daily
  puzzle warm-up.

## What makes it different (차별점)

Most chess tools do one thing well, so you end up stitching several together.
`chess-coach-mcp` is the missing **grounding + personalisation layer**, delivered
right where you already work — inside your AI assistant.

| | chess-coach-mcp | Stockfish alone | DecodeChess | Aimchess | Chessable |
|---|:---:|:---:|:---:|:---:|:---:|
| Best move (**what**) | ✅ | ✅ | ✅ | ◐ | – |
| Explains the **why** in prose | ✅ | ❌ | ✅ | ❌ | – |
| **Personal** weakness diagnosis across your games | ✅ | ❌ | ❌ | ✅ | ❌ |
| Drills from **your own** blunders | ✅ | ❌ | ❌ | ◐ | ❌ |
| **Korean** (bilingual) coaching | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Local / private** (your engine, no account) | ✅ | ✅ | ❌ cloud | ❌ cloud | ❌ cloud |
| Lives **inside your AI assistant** (MCP) | ✅ | ❌ | ❌ | ❌ | ❌ |
| Cost | free, OSS | free | subscription | subscription | paid courses |

The five things that set it apart:

1. **Hybrid & grounded** — Stockfish is the judge, the LLM is the explainer.
   Every coaching claim is backed by the engine, so there are no hallucinated
   evaluations or made-up lines (the failure mode of asking a raw LLM about chess).
2. **Personal, not generic** — `diagnose_weaknesses` aggregates *your* games into
   phase weaknesses, recurring tactical blind spots and leaky openings;
   `recommend_drills` quizzes you on *your own* blunder positions — not random
   puzzles at your rating.
3. **Bilingual EN/KO** — every structured fact carries a Korean label, so the
   coaching reads naturally in Korean (한국어 코칭).
4. **Local-first & private** — your own Stockfish binary + public read-only APIs.
   No account, no API key, nothing about your games is uploaded anywhere.
5. **Inside your assistant** — it's an MCP server, so coaching happens in the same
   chat you already use, composable with everything else your assistant can do.

## Tools

| Tool | Purpose |
|---|---|
| `engine_status` | Check the local Stockfish binary is available. |
| `render_board(fen, orientation)` | Show a position as a text board + Lichess link (no engine). |
| `fetch_recent_games(username, source, max_games, speed)` | List recent games (no analysis). |
| `analyze_position(fen, depth, multipv)` | Evaluate one position; top lines + flags. |
| `analyze_game(pgn, depth, user_color, max_plies)` | Full per-move game review. |
| `diagnose_weaknesses(username, source, max_games, depth, speed)` | Cross-game weakness report. |
| `recommend_drills(username, source, max_games, depth, num_drills, include_daily_puzzle)` | Personalised drill set. |

`source` is `lichess` (default) or `chesscom`. Every numeric/categorical fact
ships with a `*_ko` Korean label for natural Korean coaching. Positions in tool
output also carry a `board_ascii` text board and a `lichess_url`, so the coach
can draw the board right in the chat or link you to an interactive one.

### Does a board show up in chat?

This is an MCP server: it returns **data** (FENs, evaluations, a `board_ascii`
text board, a `lichess_url`), and your assistant turns that into coaching. So a
graphical board doesn't pop up by itself — but the model can print the
`board_ascii` board in any client, you can click the `lichess_url` for a real
interactive board, and on claude.ai the model can draw an SVG board from the
FEN. (The demo GIF above is a generated README asset, not the live chat UI.)

## Requirements

- Python ≥ 3.11
- **Stockfish** on your `PATH` (or set `STOCKFISH_PATH`):
  - macOS: `brew install stockfish`
  - Debian/Ubuntu: `apt install stockfish`

## Install & run

From PyPI:

```bash
pip install chess-coach-mcp
chess-coach-mcp               # run the MCP server over stdio
# …or run without installing:
uvx chess-coach-mcp
```

From source:

```bash
uv sync                      # install dependencies
uv run chess-coach-mcp       # run the MCP server over stdio
```

### Register with Claude Code

```bash
claude mcp add chess-coach -- uv --directory /ABS/PATH/TO/chess-coach-mcp run chess-coach-mcp
```

Or add to an MCP client config:

```json
{
  "mcpServers": {
    "chess-coach": {
      "command": "uv",
      "args": ["--directory", "/ABS/PATH/TO/chess-coach-mcp", "run", "chess-coach-mcp"],
      "env": { "STOCKFISH_PATH": "/opt/homebrew/bin/stockfish" }
    }
  }
}
```

## Example coaching flow

> "내 리체스 약점 좀 진단해줘. 아이디 `myname`."

The host calls `diagnose_weaknesses("myname")`, gets back per-phase ACPL,
recurring motifs (e.g. `hanging_piece` ×4, `missed_tactic` ×3) with example
FENs, then explains in Korean *why* those positions went wrong and calls
`recommend_drills("myname")` to quiz the user on their own blunders.

## Configuration (environment variables)

| Variable | Default | Meaning |
|---|---|---|
| `STOCKFISH_PATH` | autodetect | Path to the Stockfish binary. |
| `CHESS_COACH_ENGINE_THREADS` | 1 | Engine threads. |
| `CHESS_COACH_ENGINE_HASH_MB` | 128 | Engine hash size (MB). |
| `CHESS_COACH_POSITION_DEPTH` | 16 | Default depth for `analyze_position`. |
| `CHESS_COACH_GAME_DEPTH` | 14 | Default depth for `analyze_game`. |
| `CHESS_COACH_DIAGNOSE_DEPTH` | 12 | Default depth for diagnosis (lower = faster). |

## How move classification works

Moves are classified by the **drop in win percentage**, not raw centipawns,
using Lichess' logistic model — far more meaningful in already-winning or
already-losing positions. A move is a **blunder** if it loses ≥20% win
probability, a **mistake** at ≥10%, an **inaccuracy** at ≥5%. Mate-aware: a move
that throws away a forced mate or walks into one is flagged accordingly.

Tactical motifs are **heuristic** labels (depth-1 static exchange for hanging
pieces, geometric detection for forks/pins/back-rank). They exist to *group*
engine-found mistakes into human themes, not to replace the engine's judgement.

## Development

```bash
uv run pytest                       # unit + engine tests (skips engine tests if no Stockfish)
uv run python examples/mcp_smoke.py # boot the server over MCP and call tools
uv run python examples/live_check.py <lichess_username>  # live network E2E
```

Tests marked `engine` require a Stockfish binary; `live` tests (none by
default) hit the network and are deselected unless you pass `-m live`.

## License

MIT