@chessceo/mcp 0.3.0 → 0.4.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 { Chess } from "chess.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -120,6 +121,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.",
@@ -161,6 +185,27 @@ const TOOLS = [
             required: ["fide_id"],
         },
     },
+    {
+        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).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fide_id_me: { type: "integer", description: "Your FIDE ID." },
+                fide_id_opponent: { type: "integer", description: "Opponent's FIDE ID." },
+                my_color: { type: "string", enum: ["white", "black"], description: "The colour YOU will play." },
+                line: {
+                    type: "string",
+                    description: "Move sequence in SAN, space-separated. Empty = starting position. Example: 'e4 c5 Nf3'. Either line or fen (or neither for the starting position).",
+                },
+                fen: {
+                    type: "string",
+                    description: "Alternative to line — raw FEN of the target position.",
+                },
+            },
+            required: ["fide_id_me", "fide_id_opponent", "my_color"],
+        },
+    },
 ];
 async function callTool(name, args) {
     switch (name) {
@@ -190,6 +235,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),
@@ -204,6 +257,53 @@ 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 "prep_snapshot": {
+            const me = Number(args.fide_id_me);
+            const opp = Number(args.fide_id_opponent);
+            const myColor = String(args.my_color);
+            const oppColor = myColor === "white" ? "black" : "white";
+            const line = typeof args.line === "string" ? args.line.trim() : "";
+            let fen = typeof args.fen === "string" ? args.fen.trim() : "";
+            // General DB lookup needs a FEN. If we only have a line, compute it
+            // locally with chess.js — one dep, keeps the three data-fetches truly
+            // parallel instead of doing a preliminary round-trip.
+            if (!fen) {
+                const board = new Chess();
+                if (line.length > 0) {
+                    for (const raw of line.split(/\s+/)) {
+                        // Tolerant of move-number tokens like "1." / "12..." that some
+                        // clients include; chess.js rejects those outright.
+                        const san = raw.replace(/^\d+\.+/, "");
+                        if (!san)
+                            continue;
+                        try {
+                            board.move(san);
+                        }
+                        catch {
+                            throw new Error(`bad SAN token '${raw}' in line`);
+                        }
+                    }
+                }
+                fen = board.fen();
+            }
+            const prepParams = (fideId, color) => ({
+                fideId,
+                color,
+                compact: "true",
+                ...(line.length > 0 ? { line } : { fen }),
+            });
+            const [opponent, you, general] = await Promise.all([
+                get("/api/chess/prep/by-player", prepParams(opp, oppColor)),
+                get("/api/chess/prep/by-player", prepParams(me, myColor)),
+                get("/api/chess/database/main", { fen, limit: 20, sort: "relevance" }),
+            ]);
+            return {
+                position: { line, fen, my_color: myColor },
+                opponent,
+                you,
+                general,
+            };
+        }
         default:
             throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {
     "chessceo-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
     "start": "node dist/index.js",
     "prepublishOnly": "npm run build"
   },
-  "keywords": ["mcp", "modelcontextprotocol", "chess", "chessceo", "llm", "claude", "fide"],
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "chess",
+    "chessceo",
+    "llm",
+    "claude",
+    "fide"
+  ],
   "author": "chess.ceo",
   "license": "MIT",
   "repository": {
@@ -30,6 +41,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "chess.js": "^1.4.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {