@chessceo/mcp 0.2.0 → 0.3.1

package/README.md

@@ -71,6 +71,18 @@ Ask your model:
 - *"Are there any live tournaments right now with Hikaru Nakamura?"*
 - *"From the position after 1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6, what's the top continuation across the whole database?"*
 
+## Prep workflow (built-in prompts)
+
+For MCP hosts that show prompts in a slash-menu (Claude Desktop, Cursor, Claude Code), three pre-baked prompts are included so users get a proper preparation workflow without prompt-engineering their own:
+
+| Prompt | Purpose |
+|---|---|
+| `prepare_for_game(me, opponent, my_color?, time_control?)` | Full pre-match workflow: resolves both players, weights games by recency + format (classical OTB > rapid/blitz > online), walks the opponent's repertoire looking for lines where they score under 40%, checks head-to-head, and delivers a concrete plan with the moves to steer toward the opponent's weak points. |
+| `scout_player(player)` | Deep scouting report on one player — style, top openings, recent form, biggest wins and losses, recurring weaknesses. |
+| `head_to_head_briefing(player_a, player_b)` | One-paragraph read on the history between two players — who has the edge, dominant openings, style clash, current form. |
+
+Pick one from the host's slash-menu, fill in the arguments, and the model does the rest.
+
 ## Remote MCP (chess.ceo-hosted)
 
 You can also connect to chess.ceo's hosted instance and skip installing anything:

package/dist/index.js

@@ -7,10 +7,11 @@
 // 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";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 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 ────────────────────────────────────────────────────────────
@@ -71,7 +72,7 @@ const TOOLS = [
     },
     {
         name: "get_player_preparation",
-        description: "For a given player, colour and starting position, return both the moves the player actually chose (frequency + win rate) and the underlying games. Position is specified either as a move sequence in SAN (`line`) or a raw FEN. Use `line` iteratively to walk the opening tree: call once with empty `line`, pick a move, call again with `line` extended by that move, etc.",
+        description: "For a given player, colour and starting position, return both the moves the player actually chose (frequency + win rate) and the underlying games. Position is specified either as a move sequence in SAN (`line`) or a raw FEN. Use `line` iteratively to walk the opening tree: call once with empty `line`, pick a move, call again with `line` extended by that move, etc. When preparing for a real game, weight recent games (last 12-24 months) more heavily than old ones, classical over-the-board > rapid/blitz > online, and look for variations the player scores poorly in (below ~40%) or plays with less variety (shallower prep).",
         inputSchema: {
             type: "object",
             properties: {
@@ -161,6 +162,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) {
@@ -204,13 +226,184 @@ 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}`);
     }
 }
+// ── Prompt templates ───────────────────────────────────────────────
+//
+// MCP prompts are pre-baked instructions the host surfaces in a slash-menu
+// (Claude Desktop, Cursor, etc.). Users pick one and the templated content
+// gets injected into the conversation. Perfect for workflows the LLM
+// wouldn't reliably discover from tool descriptions alone — chess prep
+// especially, where "call the right tools in the right order weighted by
+// recency and format" is non-obvious.
+const PROMPTS = [
+    {
+        name: "prepare_for_game",
+        description: "Prep workflow for an upcoming chess game. Walks both players' repertoires and identifies where the opponent is weakest.",
+        arguments: [
+            { name: "me", description: "Your name (or FIDE ID)", required: true },
+            { name: "opponent", description: "Opponent's name (or FIDE ID)", required: true },
+            { name: "my_color", description: "The color you'll be playing: 'white' or 'black'. Optional — if you don't know yet, ask.", required: false },
+            { name: "time_control", description: "Optional: 'classical', 'rapid', 'blitz'. Weights which of the opponent's games matter most.", required: false },
+        ],
+    },
+    {
+        name: "scout_player",
+        description: "Deep scouting report on one player. Their style, top openings, recent form, and where they've been beaten.",
+        arguments: [
+            { name: "player", description: "Player name or FIDE ID", required: true },
+        ],
+    },
+    {
+        name: "head_to_head_briefing",
+        description: "Briefing on the history between two players — who has the edge, what openings decide their meetings, style clash.",
+        arguments: [
+            { name: "player_a", description: "First player (name or FIDE ID)", required: true },
+            { name: "player_b", description: "Second player (name or FIDE ID)", required: true },
+        ],
+    },
+];
+// The workflow text for prepare_for_game. Kept in one place so both the
+// MCP prompt handler and the /prepare fallback can share it.
+const PREP_WORKFLOW = (args) => {
+    const me = args.me ?? "the user";
+    const opp = args.opponent ?? "the opponent";
+    const color = args.my_color ? ` as ${args.my_color}` : "";
+    const tc = args.time_control ? ` in a ${args.time_control} game` : "";
+    return `You are preparing ${me} for a chess game against ${opp}${color}${tc}.
+
+Preparation workflow — follow the steps in order and be explicit about which tools you called at each step:
+
+1. **Resolve both players.** Call \`search_player\` for "${me}" and "${opp}" to get their FIDE IDs. Confirm the identity — many players share names.
+
+2. **Understand the opponent.** Call \`get_player_profile\` for the opponent. Read out:
+   - Current classical / rapid / blitz ratings.
+   - Top openings as White and Black (from openingRepertoire).
+   - Career win / draw / loss splits — is the draw rate above ~40%? That's a stylistic hint (drawish opponents need to be unbalanced).
+   - Notable wins and worst losses — patterns?
+
+3. **Weight games by quality when interpreting the data.**
+   - Recent games (last 12-24 months) matter far more than old ones. Opening repertoires evolve.
+   - Classical over-the-board games are the strongest signal — that's what real preparation reveals.
+   - Rapid and blitz reveal what they play under time pressure but may include experiments.
+   - Online games are useful but noisier (blitz gambits, alt accounts).
+
+4. **Walk the opponent's repertoire against ${me}'s color.** Call \`get_player_preparation\` on the opponent for the color they'll have in this game. Iterate: start from move 1, pick the opponent's most-played reply, call again with \`line\` extended. Look for:
+   - **Weak lines**: variations where the opponent scores below 40% as their side.
+   - **Shallow lines**: openings the opponent has played only a few times — probably less deeply prepared.
+   - **Abandoned lines**: openings they used to play but stopped. Something went wrong; may not want to revisit.
+   - **Variety**: places where the opponent picks different moves game to game — those are branching points where they can't predict your prep.
+
+5. **Style considerations.**
+   - High draw rate → propose openings that unbalance early (Benoni, King's Indian, gambit lines).
+   - Sharp tactician → don't play their prepared attacks; steer toward quiet positional lines.
+   - Endgame strong → keep queens on and keep complications.
+
+6. **Cross-check head-to-head.** Call \`get_head_to_head\` on the two players. If they've met before, what openings decided those games? Anything the opponent showed only against ${me}?
+
+7. **Deliver a concrete plan.** Summarize:
+   - What the opponent will likely play on move 1 (with confidence level).
+   - The 2-3 branching points where the opponent is weakest for ${me}'s color.
+   - The concrete move sequence ${me} should aim for to steer into those positions.
+   - What to avoid — the opponent's strongest weapons.
+
+Don't just dump data. Reason about it. Cite specific numbers (game counts, win rates, dates) so the user can trust your conclusions.`;
+};
 // ── Server wiring ──────────────────────────────────────────────────
-const server = new Server({ name: "chessceo-mcp", version: process.env.npm_package_version ?? "0.1.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "chessceo-mcp", version: process.env.npm_package_version ?? "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    const promptArgs = {};
+    if (args)
+        for (const [k, v] of Object.entries(args))
+            promptArgs[k] = String(v);
+    let text;
+    switch (name) {
+        case "prepare_for_game":
+            text = PREP_WORKFLOW(promptArgs);
+            break;
+        case "scout_player": {
+            const p = promptArgs.player ?? "the player";
+            text = `Produce a scouting report on ${p}. Steps:
+1. \`search_player\` to get their FIDE ID.
+2. \`get_player_profile\` — pull rating history, career splits by color and time control, opening repertoire, opponent analysis, top events, notable wins and losses.
+3. Weight the data: recent (last 12-24 months) > older, classical OTB > rapid/blitz > online.
+4. \`get_player_preparation\` for both colors from the starting position to summarise their opening choices with actual frequencies and win rates.
+5. Deliver: current strength, characteristic openings, one-sentence style read, biggest wins, biggest losses / recurring weakness. Cite the numbers.`;
+            break;
+        }
+        case "head_to_head_briefing": {
+            const a = promptArgs.player_a ?? "player A";
+            const b = promptArgs.player_b ?? "player B";
+            text = `Briefing on the ${a} vs ${b} history. Steps:
+1. Resolve both FIDE IDs with \`search_player\`.
+2. \`get_head_to_head\` for the pair — pull overall + per-color W/D/L (from ${a}'s perspective), splits by time format, first / last meeting, most-played openings between them, average game length.
+3. Read the pattern: who has the edge, in which colour, in which time format. Which openings decide the meetings? Anything unusual — very drawish, very sharp, big rating gap?
+4. If either player is currently live in a tournament, note it with \`list_player_live_tournaments\`.
+5. Deliver a one-paragraph read: score, dominant openings, one-line style clash, current form.`;
+            break;
+        }
+        default:
+            throw new Error(`Unknown prompt: ${name}`);
+    }
+    return {
+        description: `chessceo prompt: ${name}`,
+        messages: [
+            { role: "user", content: { type: "text", text } },
+        ],
+    };
+});
 server.setRequestHandler(CallToolRequestSchema, async (req) => {
     const { name, arguments: args } = req.params;
     try {

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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": {