@chessceo/mcp 0.48.2 → 0.49.1

package/README.md

@@ -1,23 +1,27 @@
 # @chessceo/mcp
 
-Model Context Protocol server for [chess.ceo](https://chess.ceo) — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts. Lets Claude, Cursor, and any other MCP host answer chess questions directly against real data instead of hallucinating.
+Model Context Protocol server for [chess.ceo](https://chess.ceo) — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts, cloud engine analysis, and (signed-in) a full read/write prep-file workflow. Lets Claude, Cursor, and any other MCP host answer chess questions directly against real data instead of hallucinating.
 
-No API key. No auth. No state. Free to use.
+Player/game lookups need no API key or auth. Cloud engines and prep-file tools need a `mcp_...` bearer token (see Auth below).
 
 ## What it can do
 
-The server exposes 8 tools that mirror the public GET API surface at `chess.ceo`:
+49 tools as of v0.49.0, mirroring the `chess.ceo` API surface. A few of the most-used:
 
 | Tool | What it answers |
 |---|---|
 | `search_player` | "Find FIDE ID for Magnus Carlsen" |
 | `get_player_profile` | "How strong is X, what do they play, who have they beaten" |
-| `get_player_preparation` | "What does X play against 1.e4? What's their win rate with the Najdorf?" |
+| `prepare_opponent` + `get_prep_position` | "What does X play against 1.e4? What's their win rate with the Najdorf?" |
 | `get_position_stats` | "From this position, which move scores best in the 11.7M-game database?" |
 | `get_head_to_head` | "What's the record between X and Y?" |
-| `list_live_tournaments` | "What's being broadcast live right now?" |
-| `list_tournament_players` | "Who's playing in tournament T?" |
-| `list_player_live_tournaments` | "Is X playing anywhere right now?" |
+| `list_live_tournaments` / `list_tournament_players` / `list_player_live_tournaments` | "What's being broadcast live right now? Who's playing? Is X in it?" |
+| `cloud_analyse` | "Run Stockfish + Lc0 on this position on my rented GPU instance" |
+| `read_prep_file` / `add_line` / `add_move` / `apply_mutations` | Read and edit your own repertoire/course PGNs stored server-side |
+| `auto_evaluate` / `deep_analyse` | Kick off a long-running engine-evaluation job over a whole prep file, poll it, cancel it |
+| `read_docs` | Bundled guides (engine usage, opening prep, prep-file conventions, PGN authoring, summary authoring) |
+
+Full tool inventory with categories lives in [`CLAUDE.md`](CLAUDE.md) under "Tools cheatsheet" — that's the maintained source of truth; this table is illustrative, not exhaustive.
 
 ## Install (Claude Desktop)
 
@@ -62,6 +66,25 @@ This repo is also a [Claude Code plugin marketplace](https://code.claude.com/doc
 
 Claude Code will pull the plugin from GitHub and wire the MCP server automatically. Enable "Sync automatically" in the marketplace UI if you want future updates fetched on push.
 
+## Auth (for cloud engines and prep files)
+
+Read-only chess data — player search, profiles, position stats, head-to-head, live tournaments — needs nothing. Cloud engine tools and your own prep-file tools (list/read/create/edit) need a `mcp_...` bearer token.
+
+- **Local (`npx`/Claude Desktop/Cursor):** set `CHESSCEO_TOKEN` in the server's `env` block:
+  ```json
+  {
+    "mcpServers": {
+      "chessceo": {
+        "command": "npx",
+        "args": ["-y", "@chessceo/mcp"],
+        "env": { "CHESSCEO_TOKEN": "mcp_..." }
+      }
+    }
+  }
+  ```
+  Get a token from your chess.ceo account settings.
+- **Remote (`mcp.chess.ceo/mcp`):** no config needed — calling an authed tool without a token triggers the host's normal OAuth flow (claude.ai, ChatGPT connectors) automatically.
+
 ## Try it
 
 Ask your model:
@@ -109,7 +132,7 @@ In Claude Desktop, edit `claude_desktop_config.json`:
 }
 ```
 
-Same 8 tools, same data, zero-install. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).
+Same tools, same data, zero-install. Bearer-authed tools (cloud engines, prep files) go through this host's OAuth flow instead of a config-file token. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).
 
 ## Self-host the HTTP transport
 

package/dist/index.js

@@ -29,7 +29,7 @@ import { getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysi
 import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
 import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
 import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
-import { createPrepFile, findPositionInFiles, listCollections, listPrepFiles, searchPrepFiles, } from "./prep/library.js";
+import { createCollection, createPrepFile, findPositionInFiles, listCollections, listPrepFiles, searchPrepFiles, } from "./prep/library.js";
 import { convertAvailableMovesToSAN, normalizeSourceForBackend, stripPositionResponse, trimGamesMovetext, } from "./response_transforms.js";
 // Tools that require an MCP token — cloud engine + prep-file tools
 // operate on the caller's own account so we can't service them
@@ -42,6 +42,7 @@ const AUTHED_TOOLS = new Set([
     "stop_cloud_engine",
     "cloud_analyse",
     "list_collections",
+    "create_collection",
     "list_prep_files",
     "search_prep_files",
     "find_position_in_files",
@@ -437,6 +438,8 @@ async function callToolInner(name, args) {
             return readCourseAtPosition(args);
         case "list_collections":
             return listCollections(args);
+        case "create_collection":
+            return createCollection(args);
         case "list_prep_files":
             return listPrepFiles(args);
         case "search_prep_files":

package/dist/prep/library.js

@@ -53,8 +53,11 @@ export async function searchPrepFiles(args) {
     if (!q)
         throw new Error("query required");
     const raw = await authedRequest("GET", `${PGN_BASE}/games/search?q=${encodeURIComponent(q)}&limit=100`);
-    const data = unwrap(raw);
-    const games = data?.games ?? [];
+    // Unlike list_prep_files' {games:[...]} envelope, the cross-collection
+    // search handler (RespondPaginated) puts the array straight into `data` —
+    // `data?.games` was always undefined here, so this silently returned []
+    // for every query/position regardless of real matches (found 2026-09-11).
+    const games = unwrap(raw) ?? [];
     return { query: q, prep_files: games.map(projectGameRow) };
 }
 export async function findPositionInFiles(args) {
@@ -63,14 +66,31 @@ export async function findPositionInFiles(args) {
     const resolved = await resolveFromNodeOrFen(args);
     const fen = resolved.fen;
     const raw = await authedRequest("GET", `${PGN_BASE}/games/search?position=${encodeURIComponent(fen)}&limit=100`);
-    const data = unwrap(raw);
-    const games = data?.games ?? [];
+    // See searchPrepFiles above — RespondPaginated's `data` is the array itself.
+    const games = unwrap(raw) ?? [];
     return {
         fen,
         match_count: games.length,
         prep_files: games.map(projectGameRow),
     };
 }
+export async function createCollection(args) {
+    const title = String(args.title || "").trim();
+    if (!title)
+        throw new Error("title is required");
+    const folderPath = typeof args.folder_path === "string" ? args.folder_path.trim() : undefined;
+    const raw = await authedRequest("POST", PGN_BASE, {
+        title,
+        ...(folderPath ? { folderPath } : {}),
+    });
+    const collection = unwrap(raw);
+    return {
+        ok: true,
+        id: collection.id,
+        title: collection.title,
+        folder_path: collection.folderPath,
+    };
+}
 export async function createPrepFile(args) {
     const collectionId = typeof args.collection_id === "string" ? args.collection_id.trim() : "";
     if (!collectionId) {

package/dist/tools.js

@@ -466,6 +466,27 @@ export const TOOLS = [
             required: ["id"],
         },
     },
+    {
+        name: "create_collection",
+        description: "Create a new, empty PGN collection (a folder of prep files) — NOT a prep file itself. Use this when the user asks for a new file/course and `list_collections` shows nothing suitable to put it in; then call `create_prep_file` with the returned `id`.\n\n" +
+            "**Check `list_collections` first** — a duplicate folder with a slightly different name is the common failure mode here, same as `create_prep_file`.\n\n" +
+            "`folder_path` is optional (root if omitted) but should almost always be set — an ungrouped pile of top-level collections is exactly what this tool exists to avoid creating.\n\n" +
+            "Response: `{ok, id, title, folder_path}` — pass `id` to `create_prep_file` as `collection_id`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Collection name, shown in the user's file browser. Example: 'Sicilian Rauzer'.",
+                },
+                folder_path: {
+                    type: "string",
+                    description: "Virtual folder path, e.g. '/AI Organized/Sicilian Rauzer'. Omit for root.",
+                },
+            },
+            required: ["title"],
+        },
+    },
     {
         name: "create_prep_file",
         description: "Create a new (empty) prep file in the specified collection. `name` becomes the Event PGN tag. You then extend it with mutation tools (add_move, set_comment, …).\n\n" +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.48.2",
+  "version": "0.49.1",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {