# Classic Chess

Classic Chess (https://classicchess.com) is an archive of games, players,
tournaments and attributed historical annotations for learning chess.
Engine-assisted learners can compare ideas with analysis. By-hand learners
can hide the move panel, guess a move, then advance with the next-move control.
The game result stays visible. The /beginners/ guide saves no place.

## Discover
- API catalog: https://classicchess.com/api/v1/
- OpenAPI: https://classicchess.com/api/openapi.yaml
- Human documentation: https://classicchess.com/api/
- Theme taxonomy, rules, precision and inventory: https://classicchess.com/api/v1/public/themes/
- Hosted MCP (Streamable HTTP): https://classicchess.com/mcp/
- Browser and native MCP setup: https://classicchess.com/api/docs/integration/#ai-agents
- Python MCP relay on PyPI: https://pypi.org/project/classicchess-mcp/
- Python API SDK on PyPI: https://pypi.org/project/classicchess-sdk/
- Optional Python relay source ZIP: https://classicchess.com/api/downloads/classicchess-mcp.zip

## Account access
Create an account and sign in at https://classicchess.com/accounts/login/.
MCP clients use browser sign-in and explicit library consent. For direct API
calls or the optional stdio relay, create a personal API token in
Settings (https://classicchess.com/settings/)
with library:read and library:write. Supply it as Authorization: Bearer TOKEN.
Only library:write is needed to create a plan; library:read reads progress.
Keep the token private. Revoke it in Settings when it is no longer needed.
No billing or paid tier is required. Public archive reads need no token.

## Build a study plan
1. Ask about the learner's goals, current level and engine-assisted or by-hand style.
2. GET /api/v1/public/themes/ to select existing theme slugs and inspect evidence.
3. GET /api/v1/public/games/?theme=SLUG&page_size=20. Theme filters combine
   with archive_player, archive_event, eco, result and annotation_q/annotation_author/annotation_book.
   Read PGNs and attributed annotations through each game's returned links.
   Use each result's slug (not its legacy player/game token) in plan items.
   For games published only in an annotated book, search that book's notes at
   GET /api/v1/annotated/books/BOOK_SLUG/games/?q=TEXT&author=AUTHOR.
   Board-detected configurations are candidates; prefer curated evidence for
   an instructive lesson and write your own explanation.
4. POST /api/v1/account/plans/ with {"name":"Personal study plan",
   "idempotency_key":"a-stable-unique-key","items":[{"game":"GAME_SLUG",
   "note":"Your own explanation of what to study"}]}. Include 1–100 items
   in the desired order. Retrying the identical body/key returns the same plan;
   changing the body for that key fails. No more than one write request is needed.
5. Open a returned game URL with ?collection=COLLECTION_ID. Playback follows
   manual order and the account owner can mark studied without leaving the viewer.
6. GET /api/v1/account/collections/ID/progress/ reads ordered notes and progress.
   PATCH /api/v1/account/collections/ID/items/ITEM_ID/ with {"studied":true}
   or {"studied":false}; the same route edits {"note":"..."}.
   PUT /api/v1/account/collections/ID/reorder/ with {"item_ids":[...]} adapts
   the full order. Progress is opt-in and never changes the /beginners/ guide.

## Puzzles
Puzzles come from master games and are for signed-in accounts only. Each
account has its own rotation: a puzzle solved on the first try leaves it
until the learner resets puzzles; a missed one stays.
1. GET /api/v1/account/puzzles/ reads the figures (puzzles:read).
2. GET /api/v1/account/puzzles/next/?after=LAST_ID gives a puzzle: the game
   so far (start_fen and lead), the position (fen), its goal and
   solution.moves. The accepted moves at each point are the entries whose
   after equals the moves played so far. Keep the solution hidden while the
   learner solves.
3. POST /api/v1/account/puzzles/ID/result/ with {"result":"missed"} at the
   first wrong move or when the solution is shown, or {"result":"solved"}
   for a clean finish (puzzles:write). Report each play once.
4. GET /api/v1/account/puzzles/history/ lists what the learner played and
   how it went, most recent first. Only the learner resets puzzles, from the
   website or app.

## MCP clients
Connect a remote MCP client to https://classicchess.com/mcp/. Public tools work
without signing in. To save a plan, read account progress or work with the
learner's puzzles, follow the hosted OAuth sign-in and consent flow granting
library:read and library:write, and puzzles:read and puzzles:write for puzzles.
Clients that support bearer headers can also use personal tokens from Settings.
Tools: search_players, search_games,
get_game_pgn, get_annotations, get_player_bio, create_plan, update_plan,
mark_studied, get_progress, get_puzzle_summary, next_puzzle, get_puzzle,
get_puzzle_history, record_puzzle_result.
For stdio, run python -m pip install classicchess-mcp in a Python 3.10+ virtual environment
and run classicchess-mcp with CLASSICCHESS_API_TOKEN in the private environment.
The stdio package connects to this same hosted server; no separate account is needed.
For Python API scripts, run python -m pip install classicchess-sdk.

## Request budgets and sources
Page sequentially and cache public catalogs. Valid personal tokens have bounded
per-token budgets; anonymous limits are unchanged. HTTP 429 means slow down:
honor Retry-After and use bounded backoff. Retry writes only with the documented
idempotency rules. Preserve source attribution and each asset's reuse terms.
Training-crawler blocking remains in place; these endpoints serve user-driven agents.