Metadata-Version: 2.4
Name: classicchess-mcp
Version: 0.1.1
Summary: Classic Chess stdio MCP client for its hosted study-plan and puzzles server
Author: Christian Walls
License-Expression: MIT
Project-URL: Homepage, https://classicchess.com/api/
Project-URL: Documentation, https://classicchess.com/api/docs/integration/#ai-agents
Project-URL: Download, https://classicchess.com/api/downloads/classicchess-mcp.zip
Project-URL: Support, https://classicchess.com/support/
Keywords: chess,mcp,study-plans,puzzles
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Classic Chess MCP

Connect an assistant to Classic Chess to find games, read PGNs, biographies and
published annotations, save study plans with notes and shared progress, and
play your puzzles.
The hosted MCP URL is `https://classicchess.com/mcp/`.

## Release availability

Version 0.1.1 connects to the hosted MCP endpoint and is available on PyPI.
Use the browser setup guide below to connect an assistant, or install the
optional Python stdio relay.

## Browser users

Claude and ChatGPT browser users connect to the hosted URL and sign in with
their own Classic Chess account. Follow the
[browser setup guide](https://classicchess.com/api/docs/integration/#ai-agents)
for the current menus, account-plan requirements and workspace permissions.
Choose automatic OAuth client registration in Claude. ChatGPT's available
read and write actions depend on its plan and workspace permissions.

Public searches work without account access. Approve library read and write
access to save plans and read progress, and puzzle read and write access to
play your puzzles and save the results. Revoke the connection in Classic Chess
[Settings](https://classicchess.com/settings/). A Python installation is needed
only for the optional stdio relay below.

## Claude Code

```sh
claude mcp add --scope user --transport http classicchess https://classicchess.com/mcp/
claude mcp login classicchess
```

Complete browser sign-in and approve library access. Enable Classic Chess in
a new session and ask, for example: “Build a five-game rook-endgame study plan
and save it to my account.”

## Codex

```sh
codex mcp add classicchess --url https://classicchess.com/mcp/
codex mcp login classicchess --scopes library:read,library:write,puzzles:read,puzzles:write
```

Codex may start browser sign-in when adding the server. The login command also
lets you connect again later. Plans, progress and puzzle results belong to the
account you approve, and are shared with the Classic Chess website.

## Optional Python stdio relay

This MIT-licensed package needs Python 3.10 or later and has no runtime
dependencies. It relays newline-delimited MCP messages to the same server.
Install it from [PyPI](https://pypi.org/project/classicchess-mcp/) into a virtual
environment.

On Linux or macOS:

```sh
python3 -m venv classicchess-mcp-env
classicchess-mcp-env/bin/python -m pip install classicchess-mcp
classicchess-mcp-env/bin/classicchess-mcp --help
```

On Windows:

```powershell
py -m venv classicchess-mcp-env
classicchess-mcp-env\Scripts\python -m pip install classicchess-mcp
classicchess-mcp-env\Scripts\classicchess-mcp --help
```

In a source checkout, install with `python3 -m pip install .` inside your virtual
environment. The distribution name is `classicchess-mcp`. The
[website source ZIP](https://classicchess.com/api/downloads/classicchess-mcp.zip)
is also available from the website.

Create a personal token in [Settings](https://classicchess.com/settings/) with
`library:read` and `library:write`, and with `puzzles:read` and `puzzles:write`
for puzzles, then configure your MCP client's private environment:

```json
{
  "mcpServers": {
    "classicchess": {
      "command": "FULL_PATH_TO_CLASSICCHESS_MCP",
      "env": {"CLASSICCHESS_API_TOKEN": "YOUR_PERSONAL_TOKEN"}
    }
  }
}
```

Replace `FULL_PATH_TO_CLASSICCHESS_MCP` with the absolute path to the executable
in the virtual environment above (`bin/classicchess-mcp` on Linux/macOS,
`Scripts\classicchess-mcp.exe` on Windows). Replace `YOUR_PERSONAL_TOKEN` only
in your client's private configuration. Revoke the token in Settings.
The relay writes only MCP messages to stdout and never prints credentials,
follows redirects or sends credentials to another origin.

For local development, pass `--base-url http://127.0.0.1:PORT`, replacing `PORT`
with your development server's port. The canonical HTTPS site and an explicitly
selected HTTP loopback origin are accepted.

## Tools and protocol

The study tools are `search_players`, `search_games`, `get_game_pgn`,
`get_annotations`, `get_player_bio`, `create_plan`, `update_plan`, `mark_studied`
and `get_progress`. Plan creation accepts 1–100 ordered game slugs and original
notes. Reuse a stable idempotency key when retrying the same plan. `update_plan`
performs one operation per call: metadata, reorder, a note, add a game or
remove an item. Theme rules and evidence are at `/api/v1/public/themes/`.

The puzzle tools are `get_puzzle_summary`, `next_puzzle`, `get_puzzle`,
`get_puzzle_history` and `record_puzzle_result`. Puzzles are for signed-in
accounts. `next_puzzle` returns a random puzzle from the account's rotation with
every accepted solver move; keep the solution hidden while the learner solves.
Record each play once: `missed` at the first wrong move or when the solution is
shown, `solved` for a clean finish. A first-try solve leaves the rotation until
the learner resets puzzles on the website or in the app.

The server uses stateless Streamable HTTP with JSON responses. It supports
protocol `2026-07-28` with per-request metadata and bound routing headers, plus
the initialization flows for `2025-11-25`, `2025-06-18` and `2025-03-26`.
It publishes OAuth discovery, supports dynamic client registration, requires
S256 PKCE and accepts native loopback callbacks when the issuer is production
HTTPS. Clients supporting fixed headers can use personal API tokens instead.
Source-attributed annotations retain their source and reuse terms.
