@chessceo/mcp 0.1.0

package/README.md

@@ -0,0 +1,83 @@
+# @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.
+
+No API key. No auth. No state. Free to use.
+
+## What it can do
+
+The server exposes 8 tools that mirror the public GET API surface at `chess.ceo`:
+
+| 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?" |
+| `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?" |
+
+## Install (Claude Desktop)
+
+Add to your `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "chessceo": {
+      "command": "npx",
+      "args": ["-y", "@chessceo/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You should see the chess.ceo tools appear in the tool list at the bottom of the chat.
+
+## Install (Cursor)
+
+Similar `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "chessceo": {
+      "command": "npx",
+      "args": ["-y", "@chessceo/mcp"]
+    }
+  }
+}
+```
+
+## Try it
+
+Ask your model:
+
+- *"Who has the better record against Magnus Carlsen: Ding Liren or Fabiano Caruana?"*
+- *"What does Alireza Firouzja play with White against the Najdorf?"*
+- *"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?"*
+
+## Development
+
+```bash
+git clone <this repo>
+cd chessceo-mcp
+npm install
+npm run build   # tsc → dist/
+npm start       # runs the server on stdio (for MCP hosts)
+```
+
+Environment variable overrides:
+
+- `CHESSCEO_BASE_URL` — override the API base (default `https://chess.ceo`). Useful for testing against staging.
+
+## What's under the hood
+
+The chess.ceo public API is a GET-only surface documented at [`chess.ceo/llms.txt`](https://chess.ceo/llms.txt). This MCP server is a thin wrapper — one tool per endpoint, with input schemas so LLMs can call them safely. When you ask the model a chess question, it picks the right tool, calls it, and reasons over the JSON. Nothing is invented; the data is straight from the database.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// chess.ceo MCP server. Exposes the public GET API as MCP tools so LLM
+// hosts (Claude Desktop, Cursor, etc.) can look up players, positions,
+// preparation stats, and live broadcast state directly.
+//
+// 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 { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, 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 ────────────────────────────────────────────────────────────
+async function get(path, params) {
+    const url = new URL(path, BASE);
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && v !== "")
+            url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url, { headers: { "User-Agent": UA, "Accept": "application/json" } });
+    if (!res.ok) {
+        // Bubble up the ProblemDetail body when the API returns one — LLM can
+        // then correct the query (e.g. wrong fideId) rather than retry blind.
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch {
+            body = "";
+        }
+        throw new Error(`chess.ceo ${res.status}: ${body.slice(0, 500)}`);
+    }
+    return res.json();
+}
+// ── Tool definitions ───────────────────────────────────────────────
+//
+// Descriptions are written for the LLM, not humans — they should hint
+// at when to call the tool, what inputs mean, and what the response
+// contains. Terse is fine; the LLM already reads the parameter names.
+const TOOLS = [
+    {
+        name: "search_player",
+        description: "Fuzzy name lookup for FIDE-rated chess players. Returns candidate matches with their FIDE ID, current rating, title (GM/IM/etc.), and country. Use this to resolve a plain-English name (e.g. 'Carlsen', 'Ding Liren') to the FIDE ID that every other tool needs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Player name or partial name. Case-insensitive, fuzzy.",
+                },
+            },
+            required: ["name"],
+        },
+    },
+    {
+        name: "get_player_profile",
+        description: "Full stats for one player: identity, monthly rating history, peak / trend stats, career W/D/L by color and time control, top-10 openings as White and Black, opponent analysis by rating bracket, notable wins and worst losses, top events with performance ratings. Often enough on its own for 'how strong is X, what do they play, who have they beaten'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fide_id: {
+                    type: "integer",
+                    description: "FIDE ID from search_player.",
+                },
+            },
+            required: ["fide_id"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fide_id: { type: "integer", description: "FIDE ID from search_player." },
+                color: {
+                    type: "string",
+                    enum: ["white", "black"],
+                    description: "Which colour the player is analysed with.",
+                },
+                line: {
+                    type: "string",
+                    description: "Move sequence in SAN, space-separated, no move numbers required. Example: 'e4 e5 Nf3'. Leave empty for the starting position.",
+                },
+                fen: {
+                    type: "string",
+                    description: "Alternative to `line` — raw FEN of the target position.",
+                },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 10,
+                    description: "Number of games to return (max 10 per request; page with offset).",
+                },
+                offset: { type: "integer", minimum: 0 },
+            },
+            required: ["fide_id", "color"],
+        },
+    },
+    {
+        name: "get_position_stats",
+        description: "Move statistics from all 11.7M+ indexed games at a given position — game counts, win percentages, top continuations. Answers 'from position P, how often does White play 4. O-O vs 4. d3, and which scores better'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fen: {
+                    type: "string",
+                    description: "FEN of the position to look up.",
+                },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 50,
+                    description: "Number of top continuations to return.",
+                },
+            },
+            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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fide_id_a: { type: "integer", description: "FIDE ID of player A (record is from A's perspective)." },
+                fide_id_b: { type: "integer", description: "FIDE ID of player B." },
+                limit: { type: "integer", minimum: 1, maximum: 10 },
+                offset: { type: "integer", minimum: 0 },
+            },
+            required: ["fide_id_a", "fide_id_b"],
+        },
+    },
+    {
+        name: "list_live_tournaments",
+        description: "Tournaments currently being broadcast live on chess.ceo. Use this when the user asks 'what's on right now' / 'live tournaments today'.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "list_tournament_players",
+        description: "Players participating in one live-broadcast tournament.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                tour_id: { type: "string", description: "Tournament ID from list_live_tournaments." },
+            },
+            required: ["tour_id"],
+        },
+    },
+    {
+        name: "list_player_live_tournaments",
+        description: "Which currently-live broadcasts a given player is competing in. Use when the user asks 'is X playing anywhere right now'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fide_id: { type: "integer", description: "FIDE ID from search_player." },
+            },
+            required: ["fide_id"],
+        },
+    },
+];
+async function callTool(name, args) {
+    switch (name) {
+        case "search_player":
+            return get("/api/chess/players/search/simple", { q: String(args.name), view: "llm" });
+        case "get_player_profile":
+            return get("/api/chess/players/profile", { fideId: Number(args.fide_id) });
+        case "get_player_preparation": {
+            const params = {
+                fideId: Number(args.fide_id),
+                color: String(args.color),
+                compact: "true",
+            };
+            if (typeof args.line === "string" && args.line.length > 0)
+                params.line = args.line;
+            if (typeof args.fen === "string" && args.fen.length > 0)
+                params.fen = args.fen;
+            if (typeof args.limit === "number")
+                params.limit = args.limit;
+            if (typeof args.offset === "number")
+                params.offset = args.offset;
+            return get("/api/chess/prep/by-player", params);
+        }
+        case "get_position_stats":
+            return get("/api/chess/database/main", {
+                fen: String(args.fen),
+                limit: typeof args.limit === "number" ? args.limit : 20,
+                sort: "relevance",
+            });
+        case "get_head_to_head":
+            return get("/api/chess/players/h2h", {
+                a: Number(args.fide_id_a),
+                b: Number(args.fide_id_b),
+                limit: typeof args.limit === "number" ? args.limit : 10,
+                offset: typeof args.offset === "number" ? args.offset : 0,
+            });
+        case "list_live_tournaments":
+            return get("/api/chess/live/tournaments", {});
+        case "list_tournament_players":
+            return get("/api/chess/live/tournament/players", { tour_id: String(args.tour_id) });
+        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) });
+        default:
+            throw new Error(`Unknown tool: ${name}`);
+    }
+}
+// ── Server wiring ──────────────────────────────────────────────────
+const server = new Server({ name: "chessceo-mcp", version: process.env.npm_package_version ?? "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+        const result = await callTool(name, (args ?? {}));
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@chessceo/mcp",
+  "version": "0.1.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"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "modelcontextprotocol", "chess", "chessceo", "llm", "claude", "fide"],
+  "author": "chess.ceo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chessceo/chessceo-mcp"
+  },
+  "homepage": "https://chess.ceo",
+  "bugs": {
+    "url": "https://github.com/chessceo/chessceo-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}