@chessceo/mcp 0.1.0 → 0.3.0

package/README.md

@@ -51,6 +51,17 @@ Similar `~/.cursor/mcp.json`:
 }
 ```
 
+## Install (Claude Code)
+
+This repo is also a [Claude Code plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces), so you can add it directly:
+
+```
+/plugin marketplace add chessceo/chessceo-mcp
+/plugin install chessceo@chessceo
+```
+
+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.
+
 ## Try it
 
 Ask your model:
@@ -60,6 +71,112 @@ 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:
+
+```
+https://mcp.chess.ceo/mcp
+```
+
+In Claude Code:
+
+```
+/plugin add-mcp url https://mcp.chess.ceo/mcp
+```
+
+In Claude Desktop, edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chessceo": {
+      "url": "https://mcp.chess.ceo/mcp"
+    }
+  }
+}
+```
+
+Same 8 tools, same data, zero-install. Useful when the host can't spawn subprocesses (e.g. Claude.ai web, Claude mobile, ChatGPT connectors).
+
+## Self-host the HTTP transport
+
+The same package can run as a persistent HTTP server, not just a stdio subprocess:
+
+```bash
+chessceo-mcp --transport=http --http-port=8080 --http-host=127.0.0.1
+```
+
+Flags (or the corresponding env vars):
+
+| Flag | Env var | Default | Purpose |
+|---|---|---|---|
+| `--transport` | `MCP_TRANSPORT` | `stdio` | `stdio` or `http` |
+| `--http-port` | `MCP_HTTP_PORT` | `8080` | Port to bind |
+| `--http-host` | `MCP_HTTP_HOST` | `127.0.0.1` | Bind address |
+| `--http-path` | `MCP_HTTP_PATH` | `/mcp` | Streamable-HTTP endpoint |
+
+`GET /healthz` returns `200 ok\n` — wire it into your uptime monitor.
+
+### systemd unit (example)
+
+```ini
+# /etc/systemd/system/chessceo-mcp.service
+[Unit]
+Description=chess.ceo MCP server (Streamable HTTP)
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+Environment=NODE_ENV=production
+Environment=MCP_TRANSPORT=http
+Environment=MCP_HTTP_PORT=8127
+Environment=MCP_HTTP_HOST=127.0.0.1
+ExecStart=/usr/bin/npx -y @chessceo/mcp
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+### nginx snippet (example)
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name mcp.chess.ceo;
+
+    ssl_certificate     /etc/letsencrypt/live/mcp.chess.ceo/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/mcp.chess.ceo/privkey.pem;
+
+    # Streamable HTTP is short JSON POSTs — no long-poll SSE required.
+    location /mcp {
+        proxy_pass         http://127.0.0.1:8127/mcp;
+        proxy_http_version 1.1;
+        proxy_set_header   Host $host;
+        proxy_set_header   X-Real-IP $remote_addr;
+        proxy_buffering    off;   # streaming responses shouldn't be buffered
+        proxy_read_timeout 300s;
+    }
+
+    location = /healthz { proxy_pass http://127.0.0.1:8127/healthz; }
+}
+```
+
 ## Development
 
 ```bash
@@ -68,11 +185,16 @@ cd chessceo-mcp
 npm install
 npm run build   # tsc → dist/
 npm start       # runs the server on stdio (for MCP hosts)
+
+# or run the HTTP transport locally:
+node dist/index.js --transport=http --http-port=8127
+curl http://127.0.0.1:8127/healthz     # should print "ok"
 ```
 
 Environment variable overrides:
 
 - `CHESSCEO_BASE_URL` — override the API base (default `https://chess.ceo`). Useful for testing against staging.
+- MCP transport env vars — see the self-host table above.
 
 ## What's under the hood
 

package/dist/index.js

@@ -6,9 +6,11 @@
 // Everything here is a thin wrapper around https://chess.ceo/api/chess/*
 // 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 { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.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 ────────────────────────────────────────────────────────────
@@ -69,7 +71,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: {
@@ -206,9 +208,133 @@ async function callTool(name, args) {
             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 {
@@ -224,5 +350,127 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         };
     }
 });
-const transport = new StdioServerTransport();
-await server.connect(transport);
+// ── Transport selection ────────────────────────────────────────────
+//
+// Two modes:
+//   stdio        (default)  — local subprocess, host spawns via npx / config.
+//                             Every existing Claude Desktop / Cursor / Claude Code
+//                             install of this package uses stdio.
+//   http         (--transport=http --http-port=8080)
+//                            — remote MCP over Streamable HTTP. Bind to a port,
+//                              expose /mcp, users add the URL to their host
+//                              instead of running npx. This is what
+//                              claude.ai / mobile / other zero-install hosts
+//                              need. Stateless mode: each request creates a
+//                              fresh transport + response, no session
+//                              persistence, safe to scale horizontally.
+const argv = process.argv.slice(2);
+const arg = (name, def) => {
+    const i = argv.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+    if (i < 0)
+        return def;
+    const cur = argv[i];
+    return cur.includes("=") ? cur.split("=").slice(1).join("=") : argv[i + 1];
+};
+const transportKind = (arg("transport", process.env.MCP_TRANSPORT ?? "stdio") ?? "stdio").toLowerCase();
+if (transportKind === "stdio") {
+    await server.connect(new StdioServerTransport());
+}
+else if (transportKind === "http" || transportKind === "streamable-http") {
+    const port = Number(arg("http-port", process.env.MCP_HTTP_PORT ?? "8080"));
+    const host = arg("http-host", process.env.MCP_HTTP_HOST ?? "127.0.0.1") ?? "127.0.0.1";
+    const path = arg("http-path", process.env.MCP_HTTP_PATH ?? "/mcp") ?? "/mcp";
+    // Read a JSON body off req into memory. Bodies are tiny (JSON-RPC), so
+    // no streaming needed; guard against absurd payloads with a hard cap.
+    const MAX_BODY = 1_048_576; // 1 MB
+    const readBody = (req) => new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on("data", (c) => {
+            total += c.length;
+            if (total > MAX_BODY) {
+                req.destroy();
+                reject(new Error("body too large"));
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => {
+            try {
+                const text = Buffer.concat(chunks).toString("utf8");
+                resolve(text.length === 0 ? undefined : JSON.parse(text));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        req.on("error", reject);
+    });
+    const httpServer = createHttpServer(async (req, res) => {
+        // Basic CORS so browser-based MCP hosts can call us cross-origin.
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Mcp-Session-Id, Last-Event-ID");
+        res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id");
+        if (req.method === "OPTIONS") {
+            res.statusCode = 204;
+            res.end();
+            return;
+        }
+        // Liveness — cheap health check for load balancers / uptime monitors.
+        if (req.method === "GET" && (req.url === "/healthz" || req.url === "/health")) {
+            res.statusCode = 200;
+            res.setHeader("Content-Type", "text/plain");
+            res.end("ok\n");
+            return;
+        }
+        // Everything else must hit the MCP path.
+        const urlPath = (req.url ?? "").split("?")[0];
+        if (urlPath !== path) {
+            res.statusCode = 404;
+            res.end();
+            return;
+        }
+        try {
+            // Stateless: one transport per request, no session store. Simpler,
+            // scales trivially, matches how claude.ai / ChatGPT connectors call.
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+                enableJsonResponse: true,
+            });
+            res.on("close", () => transport.close());
+            await server.connect(transport);
+            const body = req.method === "POST" ? await readBody(req) : undefined;
+            await transport.handleRequest(req, res, body);
+        }
+        catch (err) {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("Content-Type", "application/json");
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: err instanceof Error ? err.message : String(err),
+                    },
+                    id: null,
+                }));
+            }
+        }
+    });
+    httpServer.listen(port, host, () => {
+        console.error(`chessceo-mcp: streamable-http on http://${host}:${port}${path}`);
+    });
+    // Graceful shutdown so `systemctl stop` doesn't leak connections.
+    const shutdown = (sig) => {
+        console.error(`chessceo-mcp: ${sig} received, closing`);
+        httpServer.close(() => process.exit(0));
+        setTimeout(() => process.exit(1), 5000).unref();
+    };
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGINT", () => shutdown("SIGINT"));
+}
+else {
+    console.error(`chessceo-mcp: unknown --transport '${transportKind}' (expected stdio or http)`);
+    process.exit(2);
+}

package/package.json

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