Metadata-Version: 2.4
Name: classicchess-mcp
Version: 0.1.0
Summary: Classic Chess stdio MCP client for its hosted study-plan 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
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, and save study plans with notes and shared progress.
The hosted MCP URL is `https://classicchess.com/mcp/`.

## Release availability

Version 0.1.0 is a development preview of the relay. The Python package is
available on PyPI; the hosted MCP endpoint and browser setup guide are awaiting
the website deployment. Until then, use a local Classic Chess development
server with `--base-url http://127.0.0.1:PORT`, replacing `PORT` with its port.

## 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. 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
```

Codex may start browser sign-in when adding the server. The login command also
lets you connect again later. Plans and progress 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)
will also be available after the website deployment.

Create a personal token in [Settings](https://classicchess.com/settings/) with
`library:read` and `library:write`, 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 nine 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 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.
