@chessceo/mcp 0.1.0 → 0.2.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,100 @@ 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?"*
 
+## 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 +173,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,8 +6,10 @@
 // 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 { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.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)`;
@@ -224,5 +226,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.2.0",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {