llm-chess-mcp 0.3.1 → 0.4.0

package/README.md

@@ -70,6 +70,34 @@ pnpm test:package
 `pnpm test:live` queries Lichess only when `LICHESS_TOKEN` is set; otherwise it
 skips without making a network request.
 
+## Transports
+
+stdio remains the default transport and requires no flags. To expose a local
+Streamable HTTP endpoint instead:
+
+```bash
+pnpm build
+node dist/index.js --transport http
+```
+
+The server listens on `http://127.0.0.1:3000/mcp` and supports Streamable HTTP
+sessions, JSON responses, and SSE. The equivalent development command is
+`pnpm dev:http`.
+
+HTTP options:
+
+```text
+--host <host>            Bind host (default: 127.0.0.1)
+--port <port>            Listen port (default: 3000)
+--path <path>            Endpoint path (default: /mcp)
+--allowed-host <host>    Allowed Host/Origin hostname; repeat as needed
+```
+
+Binding to `0.0.0.0` or `::` requires at least one `--allowed-host`. HTTP mode
+does not provide authentication or TLS; use a trusted network or an
+authenticated reverse proxy when exposing it beyond localhost. Origin values
+are validated when present, but the server does not emit browser CORS headers.
+
 ### Export Maia3 to ONNX (build-time only)
 
 This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies

package/dist/cli.js

@@ -0,0 +1,107 @@
+export const HELP = `Usage: llm-chess-mcp [options]
+
+Options:
+  --transport <stdio|http>  Transport to use (default: stdio)
+  --http                    Shortcut for --transport http
+  --host <host>             HTTP bind host (default: 127.0.0.1)
+  --port <port>             HTTP listen port (default: 3000)
+  --path <path>             HTTP endpoint path (default: /mcp)
+  --allowed-host <host>     Allowed HTTP Host/Origin hostname (repeatable)
+  -h, --help                Show this help
+`;
+function optionValue(args, index, option) {
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+        throw new Error(`${option} requires a value`);
+    }
+    return value;
+}
+function splitOption(arg) {
+    const index = arg.indexOf("=");
+    return index === -1 ? null : [arg.slice(0, index), arg.slice(index + 1)];
+}
+export function parseCli(args) {
+    let transport = "stdio";
+    let host = "127.0.0.1";
+    let port = 3_000;
+    let path = "/mcp";
+    let help = false;
+    let hasHttpOption = false;
+    const allowedHosts = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        const pair = splitOption(arg);
+        const option = pair?.[0] ?? arg;
+        const inlineValue = pair?.[1];
+        const value = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = optionValue(args, index, option);
+            index += 1;
+            return next;
+        };
+        switch (option) {
+            case "-h":
+            case "--help":
+                if (inlineValue !== undefined)
+                    throw new Error(`${option} takes no value`);
+                help = true;
+                break;
+            case "--http":
+                if (inlineValue !== undefined)
+                    throw new Error("--http takes no value");
+                transport = "http";
+                break;
+            case "--transport": {
+                const selected = value();
+                if (selected !== "stdio" && selected !== "http") {
+                    throw new Error("--transport must be stdio or http");
+                }
+                transport = selected;
+                break;
+            }
+            case "--host":
+                host = value();
+                hasHttpOption = true;
+                break;
+            case "--port": {
+                const selected = value();
+                if (!/^\d+$/.test(selected))
+                    throw new Error("--port must be an integer");
+                port = Number(selected);
+                hasHttpOption = true;
+                break;
+            }
+            case "--path":
+                path = value();
+                hasHttpOption = true;
+                break;
+            case "--allowed-host":
+                allowedHosts.push(value());
+                hasHttpOption = true;
+                break;
+            default:
+                throw new Error(`unknown option: ${option}`);
+        }
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+        throw new Error("--port must be between 1 and 65535");
+    }
+    if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+        throw new Error("--path must be an absolute URL path without query or fragment");
+    }
+    if (!host || allowedHosts.some((value) => !value)) {
+        throw new Error("HTTP hostnames must not be empty");
+    }
+    if (transport === "stdio" && hasHttpOption) {
+        throw new Error("HTTP options require --transport http");
+    }
+    if (transport === "http" &&
+        (host === "0.0.0.0" || host === "::" || host === "[::]") &&
+        allowedHosts.length === 0) {
+        throw new Error("wildcard HTTP binding requires at least one --allowed-host");
+    }
+    return { transport, host, port, path, allowedHosts, help };
+}

package/dist/http.js

@@ -0,0 +1,157 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { hostHeaderValidation, NodeStreamableHTTPServerTransport, originValidation, } from "@modelcontextprotocol/node";
+import { buildServer } from "./server.js";
+import { defaultAppServices } from "./services.js";
+const LOCAL_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+function isLocalHost(host) {
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+function jsonError(res, status, message) {
+    if (res.headersSent) {
+        res.destroy(new Error(message));
+        return;
+    }
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32_000, message },
+        id: null,
+    }));
+}
+function requestPath(req) {
+    try {
+        return new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        return null;
+    }
+}
+function sessionId(req) {
+    const value = req.headers["mcp-session-id"];
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function closeNodeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    });
+}
+export async function serveHttp(options = {}, services = defaultAppServices) {
+    const host = options.host ?? "127.0.0.1";
+    const requestedPort = options.port ?? 3_000;
+    const path = options.path ?? "/mcp";
+    const wildcard = host === "0.0.0.0" || host === "::" || host === "[::]";
+    if (wildcard && options.allowedHosts === undefined) {
+        throw new Error("wildcard HTTP binding requires allowed hostnames");
+    }
+    const allowedHosts = [
+        ...(options.allowedHosts ?? (isLocalHost(host) ? LOCAL_HOSTS : [host])),
+    ];
+    if (!host || !Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65_535) {
+        throw new Error("invalid HTTP listen address");
+    }
+    if (!path.startsWith("/") || path.includes("?") || path.includes("#")) {
+        throw new Error("invalid HTTP endpoint path");
+    }
+    if (allowedHosts.length === 0 || allowedHosts.some((value) => !value)) {
+        throw new Error("at least one allowed HTTP hostname is required");
+    }
+    const sessions = new Map();
+    const validateHost = hostHeaderValidation(allowedHosts);
+    const validateOrigin = originValidation(allowedHosts);
+    let closing = false;
+    const closeSession = async (id, session) => {
+        if (sessions.get(id) !== session)
+            return;
+        sessions.delete(id);
+        await session.server.close();
+    };
+    const handle = async (req, res) => {
+        if (closing) {
+            jsonError(res, 503, "server is shutting down");
+            return;
+        }
+        if (requestPath(req) !== path) {
+            jsonError(res, 404, "MCP endpoint not found");
+            return;
+        }
+        if (!validateHost(req, res) || !validateOrigin(req, res))
+            return;
+        const id = sessionId(req);
+        if (id === null) {
+            jsonError(res, 400, "invalid MCP session ID");
+            return;
+        }
+        if (id !== undefined) {
+            const session = sessions.get(id);
+            if (!session) {
+                jsonError(res, 404, "MCP session not found");
+                return;
+            }
+            await session.transport.handleRequest(req, res);
+            return;
+        }
+        let initializedId;
+        let session;
+        const transport = new NodeStreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            onsessioninitialized: (newId) => {
+                initializedId = newId;
+                sessions.set(newId, session);
+            },
+            onsessionclosed: (closedId) => {
+                const current = sessions.get(closedId);
+                if (current)
+                    void closeSession(closedId, current);
+            },
+        });
+        const mcp = buildServer(services);
+        session = { server: mcp, transport };
+        transport.onclose = () => {
+            if (initializedId && sessions.get(initializedId) === session) {
+                sessions.delete(initializedId);
+            }
+        };
+        try {
+            await mcp.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+        finally {
+            if (!initializedId)
+                await mcp.close();
+        }
+    };
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((error) => {
+            console.error("HTTP request failed", error);
+            jsonError(res, 500, "internal server error");
+        });
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (error) => reject(error);
+        server.once("error", onError);
+        server.listen(requestedPort, host, () => {
+            server.off("error", onError);
+            resolve();
+        });
+    });
+    server.on("error", (error) => console.error("HTTP server failed", error));
+    const address = server.address();
+    const port = address.port;
+    const displayHost = host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+    let shutdown;
+    return {
+        host,
+        port,
+        path,
+        url: `http://${displayHost}:${port}${path}`,
+        sessionCount: () => sessions.size,
+        close: () => (shutdown ??= (async () => {
+            closing = true;
+            await Promise.allSettled([...sessions.entries()].map(([id, session]) => closeSession(id, session)));
+            await closeNodeServer(server);
+        })()),
+    };
+}

package/dist/index.js

@@ -2,20 +2,56 @@
 import { realpathSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { HELP, parseCli } from "./cli.js";
 import { loadEnv } from "./env.js";
+import { serveHttp } from "./http.js";
 import { buildServer } from "./server.js";
 import { defaultAppServices } from "./services.js";
 export { buildServer } from "./server.js";
+export { serveHttp } from "./http.js";
 export { drawResult, MAX_EVALUATED_MOVES, MAX_PGN_BYTES, MAX_PGN_PLIES, parseImportedPgn, snapshotChess, } from "./chess.js";
 loadEnv();
-const entry = process.argv[1];
-if (entry && import.meta.url === pathToFileURL(realpathSync(entry)).href) {
-    const handle = serveStdio(() => buildServer());
+async function main() {
+    const options = parseCli(process.argv.slice(2));
+    if (options.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (options.transport === "stdio") {
+        const handle = serveStdio(() => buildServer());
+        let shutdown;
+        const close = () => (shutdown ??= Promise.all([defaultAppServices.quit(), handle.close()]).then(() => undefined));
+        const onClose = () => {
+            void close().catch((error) => console.error("shutdown failed", error));
+        };
+        process.stdin.once("end", onClose);
+        process.stdin.once("close", onClose);
+        return;
+    }
+    const handle = await serveHttp({
+        host: options.host,
+        port: options.port,
+        path: options.path,
+        ...(options.allowedHosts.length ? { allowedHosts: options.allowedHosts } : {}),
+    });
+    console.error(`llm-chess-mcp listening on ${handle.url}`);
     let shutdown;
-    const close = () => (shutdown ??= Promise.all([defaultAppServices.quit(), handle.close()]).then(() => undefined));
-    const onClose = () => {
-        void close().catch((error) => console.error("shutdown failed", error));
+    const close = () => (shutdown ??= handle.close().finally(() => defaultAppServices.quit()));
+    const onSignal = () => {
+        void close()
+            .then(() => process.exit(0))
+            .catch((error) => {
+            console.error("shutdown failed", error);
+            process.exit(1);
+        });
     };
-    process.stdin.once("end", onClose);
-    process.stdin.once("close", onClose);
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+}
+const entry = process.argv[1];
+if (entry && import.meta.url === pathToFileURL(realpathSync(entry)).href) {
+    void main().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+    });
 }

package/docs/architecture.md

@@ -1,15 +1,18 @@
 # Architecture
 
-`llm-chess-mcp` is a stateful MCP server over stdio. It owns chess-game state
-and exposes deterministic tool contracts; Stockfish, Maia3, and Lichess add
-independent signals without changing a game unless `game_play_move` succeeds.
+`llm-chess-mcp` is a stateful MCP server over stdio or Streamable HTTP. It owns
+chess-game state and exposes deterministic tool contracts; Stockfish, Maia3,
+and Lichess add independent signals without changing a game unless
+`game_play_move` succeeds.
 
 ## Runtime boundary
 
 `src/index.ts` is the executable boundary. It loads environment configuration,
-creates the server through `buildServer`, and passes it to `serveStdio`. Stdout
-is reserved for MCP JSON-RPC traffic; diagnostics belong on stderr. When stdin
-closes, the entrypoint closes the transport and terminates Stockfish.
+parses transport options, and creates servers through `buildServer`. stdio is
+the default; HTTP mode binds an explicit endpoint and creates one MCP server per
+Streamable HTTP session. All sessions share application services and game state.
+Stdout is reserved for protocol traffic; diagnostics belong on stderr. Shutdown
+closes active transports before terminating Stockfish.
 
 The server is assembled from injected `AppServices`, not from tool-level global
 lookups. Production constructs one service set for the process; tests pass
@@ -17,11 +20,11 @@ small fakes or controlled implementations. This keeps transport registration
 separate from engine startup, network I/O, time, and storage.
 
 ```text
-stdio -> entrypoint -> buildServer(AppServices) -> tool modules
-                                               |-> GameStore
-                                               |-> Stockfish service
-                                               |-> Maia service
-                                               `-> Lichess explorer
+stdio --------> entrypoint -> buildServer(AppServices) -> tool modules
+Streamable HTTP --^                                   |-> GameStore
+                                                      |-> Stockfish service
+                                                      |-> Maia service
+                                                      `-> Lichess explorer
 ```
 
 The tool modules have narrow ownership:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-chess-mcp",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "MCP server that lets an LLM analyze, judge, and choose chess moves (Stockfish + Maia3 + Lichess)",
   "type": "module",
   "license": "AGPL-3.0",
@@ -26,7 +26,9 @@
     "contract:update": "pnpm build && node scripts/tool-contract.mjs --write",
     "contract:check": "pnpm build && node scripts/tool-contract.mjs",
     "dev": "tsx src/index.ts",
+    "dev:http": "tsx src/index.ts --transport http",
     "start": "node dist/index.js",
+    "start:http": "node dist/index.js --transport http",
     "test:unit": "tsx --test tests/*.test.ts",
     "test:integration": "tsx --test tests/integration/*.test.ts",
     "test:e2e": "pnpm build && tsx --test tests/e2e/*.test.ts",
@@ -41,6 +43,7 @@
     "export:maia3": "python scripts/export_maia3.py"
   },
   "dependencies": {
+    "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "chess.js": "^1.4.0",
     "onnxruntime-node": "^1.27.0",