@chessceo/mcp 0.3.1 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chess.ceo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to grant persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.js

@@ -7,6 +7,7 @@
 // endpoints — see the public contract at https://chess.ceo/llms.txt.
 // No API key, no auth, no state; the API's own rate limits apply.
 import { createServer as createHttpServer } from "node:http";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Chess } from "chess.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -15,6 +16,27 @@ import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema
 const BASE = process.env.CHESSCEO_BASE_URL ?? "https://chess.ceo";
 const UA = `chessceo-mcp/${process.env.npm_package_version ?? "0.1.0"} (+https://chess.ceo)`;
 // ── HTTP ────────────────────────────────────────────────────────────
+//
+// Two auth flavours coexist:
+//   - Anonymous GETs (players, positions, prep, live) — no auth.
+//   - Authed tools (cloud engines) — `Authorization: Bearer mcp_...`.
+//
+// The token comes from one of two sources:
+//   - stdio: `CHESSCEO_TOKEN` env var, set by the MCP host config. Bare
+//     `mcp_...` — we prepend the `Bearer ` scheme when building the header.
+//   - streamable-http: the caller's `Authorization` header, forwarded
+//     per-request via AsyncLocalStorage so tool handlers can see it even
+//     though the MCP SDK's request handler doesn't know about HTTP.
+const authContext = new AsyncLocalStorage();
+function resolveAuthHeader() {
+    const store = authContext.getStore();
+    if (store?.authHeader)
+        return store.authHeader;
+    const env = process.env.CHESSCEO_TOKEN?.trim();
+    if (!env)
+        return undefined;
+    return env.toLowerCase().startsWith("bearer ") ? env : `Bearer ${env}`;
+}
 async function get(path, params) {
     const url = new URL(path, BASE);
     for (const [k, v] of Object.entries(params)) {
@@ -36,6 +58,37 @@ async function get(path, params) {
     }
     return res.json();
 }
+// authedRequest is the shared code path for POST/GET/DELETE calls that need
+// an MCP token. Missing-token errors are surfaced early with a message the
+// LLM can act on (either configure CHESSCEO_TOKEN or generate a token in
+// user settings) rather than a generic 401 from the backend.
+async function authedRequest(method, path, body) {
+    const auth = resolveAuthHeader();
+    if (!auth) {
+        throw new Error("No MCP token available. Set CHESSCEO_TOKEN env (stdio mode) or pass an " +
+            "Authorization: Bearer mcp_... header (streamable-http mode). Generate " +
+            "a token at chess.ceo → user settings → MCP tokens.");
+    }
+    const url = new URL(path, BASE);
+    const headers = {
+        "User-Agent": UA,
+        "Accept": "application/json",
+        "Authorization": auth,
+    };
+    const init = { method, headers };
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    if (res.status === 204)
+        return null;
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`chess.ceo ${res.status}: ${text.slice(0, 500)}`);
+    }
+    return text.length ? JSON.parse(text) : null;
+}
 // ── Tool definitions ───────────────────────────────────────────────
 //
 // Descriptions are written for the LLM, not humans — they should hint
@@ -121,6 +174,29 @@ const TOOLS = [
             required: ["fen"],
         },
     },
+    {
+        name: "analyse",
+        description: "Short Stockfish evaluation at a position. Returns the top-N candidate moves with score (centipawns from side-to-move POV, positive = advantage; or mate distance) and the principal variation for each. Defaults: 2s think time, top-3 lines. PV moves come back in UCI notation (e2e4, not e4). Use this to sanity-check candidate lines from get_position_stats or get_player_preparation — human game frequency tells you what people play, engine evaluation tells you what's actually good.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "FEN of the position to analyse." },
+                movetime_ms: {
+                    type: "integer",
+                    minimum: 100,
+                    maximum: 10000,
+                    description: "Think time in milliseconds (default 2000).",
+                },
+                multipv: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Number of candidate lines to return (default 3).",
+                },
+            },
+            required: ["fen"],
+        },
+    },
     {
         name: "get_head_to_head",
         description: "Complete head-to-head record between two players. Includes overall and per-colour W/D/L (from player A's perspective), splits by time control, most-played openings between them, first / last meeting, average game length, and the game list.",
@@ -162,6 +238,62 @@ const TOOLS = [
             required: ["fide_id"],
         },
     },
+    {
+        name: "start_cloud_engine",
+        description: "Rent a combo GPU instance (Stockfish + Lc0 in the same container) on the user's chess.ceo account. Real money — billed per second while running. Requires an MCP token with agent access. Use `list_cloud_engines` first to see if the user already has one running; don't start a second combo unless the user asked for it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                machine_type: {
+                    type: "string",
+                    description: "SKU picked from the user's cloud-engine options (e.g. 'rtx-5090', 'rtx-5090-dual'). Ask the user if you don't already know which one they want.",
+                },
+            },
+            required: ["machine_type"],
+        },
+    },
+    {
+        name: "list_cloud_engines",
+        description: "List the user's currently running cloud engines. Use before starting a new one, or to find the contract_id for stop_cloud_engine. `cloud_analyse` auto-picks the only running combo, so listing is only necessary when the user might have zero or several.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "stop_cloud_engine",
+        description: "Destroy a running cloud engine. Billing stops immediately. Use the contract_id from `list_cloud_engines` — don't guess.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                contract_id: {
+                    type: "string",
+                    description: "Instance contract_id, from list_cloud_engines.",
+                },
+            },
+            required: ["contract_id"],
+        },
+    },
+    {
+        name: "cloud_analyse",
+        description: "Runs a synchronous ~2s analysis on the user's running combo instance and returns both Stockfish and Lc0's final read for the FEN — depth, top-N candidate moves with scores (centipawns from side-to-move POV or mate distance), and each engine's principal variation. Auto-picks the caller's only running combo instance; errors clearly if there are zero (start one first) or more than one (destroy the extras first). Much deeper than `analyse` (the CPU-only public endpoint) — use this when the user is genuinely doing prep work and has cloud engines running.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: { type: "string", description: "FEN of the position to analyse." },
+                movetime_ms: {
+                    type: "integer",
+                    minimum: 100,
+                    maximum: 10000,
+                    description: "Think time in milliseconds (default 2000).",
+                },
+                multipv: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Number of candidate lines per engine (default 3).",
+                },
+            },
+            required: ["fen"],
+        },
+    },
     {
         name: "prep_snapshot",
         description: "One call, three parallel fetches at the same position: opponent's stats on their side, your stats on your side, and the 11.7M-game general database at that position. Use this while walking the opening tree — one round trip instead of three separate calls, and you can compare the three views directly (e.g. opponent has 2 games here but the general DB has 8k → prep candidate).",
@@ -212,6 +344,14 @@ async function callTool(name, args) {
                 limit: typeof args.limit === "number" ? args.limit : 20,
                 sort: "relevance",
             });
+        case "analyse": {
+            const params = { fen: String(args.fen) };
+            if (typeof args.movetime_ms === "number")
+                params.movetime_ms = args.movetime_ms;
+            if (typeof args.multipv === "number")
+                params.multipv = args.multipv;
+            return get("/api/chess/database/analyse", params);
+        }
         case "get_head_to_head":
             return get("/api/chess/players/h2h", {
                 a: Number(args.fide_id_a),
@@ -226,6 +366,22 @@ async function callTool(name, args) {
         case "list_player_live_tournaments":
             // Note: snake_case fide_id, unlike the prep endpoints. Documented quirk.
             return get("/api/chess/live/player", { fide_id: Number(args.fide_id) });
+        case "start_cloud_engine":
+            return authedRequest("POST", "/api/agent/cloud-engines", {
+                machineType: String(args.machine_type),
+            });
+        case "list_cloud_engines":
+            return authedRequest("GET", "/api/agent/cloud-engines");
+        case "stop_cloud_engine":
+            return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
+        case "cloud_analyse": {
+            const body = { fen: String(args.fen) };
+            if (typeof args.movetime_ms === "number")
+                body.movetime_ms = args.movetime_ms;
+            if (typeof args.multipv === "number")
+                body.multipv = args.multipv;
+            return authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
+        }
         case "prep_snapshot": {
             const me = Number(args.fide_id_me);
             const opp = Number(args.fide_id_opponent);
@@ -510,7 +666,13 @@ else if (transportKind === "http" || transportKind === "streamable-http") {
             res.on("close", () => transport.close());
             await server.connect(transport);
             const body = req.method === "POST" ? await readBody(req) : undefined;
-            await transport.handleRequest(req, res, body);
+            // Forward the caller's Authorization header down to tool handlers so
+            // they can attach it when calling authenticated backend endpoints.
+            // AsyncLocalStorage survives every await inside the tool handler.
+            const authHeader = req.headers["authorization"];
+            await authContext.run({ authHeader: Array.isArray(authHeader) ? authHeader[0] : authHeader }, async () => {
+                await transport.handleRequest(req, res, body);
+            });
         }
         catch (err) {
             if (!res.headersSent) {

package/package.json

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