llm-chess-mcp 0.3.0 → 0.4.0

package/README.md

@@ -54,8 +54,7 @@ the MCP transport tests. `pnpm check` runs the full local gate; use
 
 ### Maintainers
 
-[Architecture](docs/architecture.md) describes runtime and service boundaries;
-[the changelog](CHANGELOG.md) records client-visible changes.
+[Architecture](docs/architecture.md) describes runtime and service boundaries.
 
 Local quality commands:
 
@@ -64,8 +63,41 @@ pnpm typecheck
 pnpm test:coverage
 pnpm contract:check
 pnpm check
+pnpm test:package
 ```
 
+`pnpm test:stress` runs the short real-engine concurrency check.
+`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
@@ -180,7 +212,7 @@ codex mcp add llm-chess-mcp --command npx --args -y llm-chess-mcp --env LICHESS_
 | `move_candidates_by_intent` | Convenience layer: candidates ranked for a strategic intent |
 | `opening_explorer` | Lichess human game statistics |
 
-## Result format and 0.1.x migration
+## Result format
 
 `structuredContent` is the canonical successful result. Handler-level failures
 set `isError` and provide `structuredContent.error`. Input-schema failures are
@@ -188,12 +220,6 @@ generated by the MCP SDK before the handler and use its standard `isError` text
 result without `structuredContent`. Otherwise, `content` is only a short
 human-readable summary and must not be parsed as data.
 
-Clients upgrading from 0.1.x should stop parsing `content` and consume
-`structuredContent` instead. Check `isError` and the structured error code when
-a tool fails. `move_evaluate` now always returns
-`{ game_id, revision, results }`; its former single-move top-level duplicates
-are removed.
-
 ## Score conventions
 
 - Stockfish scores are **side-to-move perspective**: positive cp = side to move is
@@ -318,15 +344,16 @@ It checks top-1/top-k move agreement and max probability error to detect
 export/runtime regressions. The bundled `maia3-5m.onnx` passes with 100% top-1
 and top-5 agreement and max probability error < 1e-4.
 
-## Releases
+## Package verification
 
-Releases are verified locally; this project intentionally has no hosted CI
-release workflow.
+Package artifacts are verified locally; this project intentionally has no
+hosted CI workflow.
 
-For `0.2.0`, run `pnpm release:check`, pack the tarball, and smoke-test a clean
-install of that tarball with `llm-chess-mcp`. Publish only after that succeeds.
-Use the same local gate and clean-install smoke test before promoting the proven
-`0.2.x` release process to `1.0.0`.
+Run `pnpm check` for the deterministic offline gate. Use `pnpm test:package` to
+pack the project, install the tarball in a clean temporary directory, and run
+the installed `llm-chess-mcp` binary against the real Stockfish and Maia
+runtimes. `pnpm release:check` runs both checks plus the production dependency
+audit and package manifest dry run.
 
 ## License & attribution
 

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/engines/stockfish.js

@@ -252,15 +252,19 @@ export class Stockfish {
                     const scoreToken = line.match(/ score (?<value>cp -?\d+|mate -?\d+)/)?.groups?.value;
                     const pv = line.match(/ pv (?<value>.+)$/)?.groups?.value;
                     const n = Number(multipv);
+                    const previous = byPv.get(n);
                     const score = scoreToken
                         ? parseScore(scoreToken)
-                        : { cp: null, mate: null };
+                        : {
+                            cp: previous?.scoreCp ?? null,
+                            mate: previous?.scoreMate ?? null,
+                        };
                     byPv.set(n, {
                         multipv: n,
                         scoreCp: score.cp,
                         scoreMate: score.mate,
-                        wdl: parseWdl(line),
-                        pv: pv ? pv.split(" ") : [],
+                        wdl: parseWdl(line) ?? previous?.wdl ?? null,
+                        pv: pv ? pv.split(" ") : (previous?.pv ?? []),
                     });
                 }
                 else if (line.startsWith("bestmove")) {

package/dist/eval.js

@@ -11,7 +11,8 @@ export function evalToCp(e) {
     if (e.type === "cp")
         return e.value;
     const sign = e.plies >= 0 ? 1 : -1;
-    return sign * (10000 - Math.abs(e.plies) * 100);
+    const magnitude = Math.max(9_000, 10_000 - Math.abs(e.plies) * 100);
+    return sign * magnitude;
 }
 export function negateEval(e) {
     if (e.type === "cp")

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/dist/intents.js

@@ -50,16 +50,18 @@ export function explorerCandidateData(result) {
 export function candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResult) {
     const turn = chess.turn();
     const maiaByUci = new Map(maiaMoves.map((move) => [move.uci, move.prob]));
+    const legalUcis = new Set(chess.moves({ verbose: true }).map((move) => move.lan));
     const sfByUci = new Map();
     for (const line of sfLines) {
         const uci = line.pv[0];
-        if (uci !== undefined)
-            sfByUci.set(uci, line);
+        const evaluation = toEval(line);
+        if (uci !== undefined && legalUcis.has(uci) && evaluation !== null) {
+            sfByUci.set(uci, { line, evaluation });
+        }
     }
     const lichessByUci = new Map(lichessResult.moves.map((move) => [move.uci, move]));
-    const evals = sfLines
-        .map(toEval)
-        .filter((value) => value !== null);
+    const normalizedSfLines = [...sfByUci.values()];
+    const evals = normalizedSfLines.map(({ evaluation }) => evaluation);
     const bestCp = evals.length
         ? Math.max(...evals.map((value) => evalToCp(value)))
         : null;
@@ -71,7 +73,7 @@ export function candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResu
     ]);
     const candidates = [];
     for (const uci of ucis) {
-        const sf = sfByUci.get(uci);
+        const sf = sfByUci.get(uci)?.line;
         const lichess = lichessByUci.get(uci);
         let opening;
         if (lichess) {
@@ -115,7 +117,10 @@ export function candidateSetFromData(chess, elo, sfLines, maiaMoves, lichessResu
             opening,
         });
     }
-    return { candidates, moveSensitivity: computeMoveSensitivity(sfLines) };
+    return {
+        candidates,
+        moveSensitivity: computeMoveSensitivity(normalizedSfLines.map(({ line }) => line)),
+    };
 }
 export async function computeCandidates(chess, elo, sfDepth, sfMultipv, maiaTopN, lichess) {
     const [sfLines, maiaMoves, lichessResult] = await Promise.all([

package/dist/tools/analysis.js

@@ -83,6 +83,7 @@ export function registerAnalysisTools(server, services) {
             }
             const result = drawResult(copy);
             if (result) {
+                const cpLoss = beforeCp;
                 results.push({
                     move: parsed.san,
                     uci: parsed.lan,
@@ -90,8 +91,10 @@ export function registerAnalysisTools(server, services) {
                     scoreCp: 0,
                     scoreMate: null,
                     bestCp: beforeCp,
-                    cpLoss: null,
-                    classification: null,
+                    cpLoss,
+                    classification: cpLoss !== null
+                        ? classifyCpLoss(cpLoss)
+                        : null,
                     pv: [],
                 });
                 continue;

package/docs/architecture.md

@@ -0,0 +1,125 @@
+# Architecture
+
+`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,
+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
+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
+Streamable HTTP --^                                   |-> GameStore
+                                                      |-> Stockfish service
+                                                      |-> Maia service
+                                                      `-> Lichess explorer
+```
+
+The tool modules have narrow ownership:
+
+| Module | Owns |
+|---|---|
+| `game` | session creation/deletion, state, legal moves, PGN, and the only game mutation |
+| `analysis` | Stockfish analysis, Maia distributions, and per-move evaluation |
+| `candidates` | joins objective, human, and opening facets; intent ranking |
+| `explorer` | Lichess input validation, requests, retry policy, and response validation |
+
+Tool modules validate inputs, take a game snapshot where needed, call services,
+and adapt data to output schemas. They do not reach into another module's
+storage or manage an engine session directly.
+
+## App services and game lifecycle
+
+`AppServices` carries the application dependencies: a `GameStore`, Stockfish,
+Maia inference, candidate computation, and the Lichess explorer. Dependencies
+are interfaces at this boundary so tests can inject controlled services without
+patching process globals. Clock and ID generation are injected into `GameStore`;
+fetch, timeout, and sleep are injected at the explorer boundary.
+
+`GameStore` owns `Chess` instances and their metadata:
+
+1. Creating a game assigns an opaque ID and revision `0`; importing a PGN also
+   creates a new game at revision `0`.
+2. Reads refresh `lastAccessedAt`. Idle games expire after one hour, cleanup
+   runs before store operations, and the store rejects creation once its
+   1,000-session limit is reached.
+3. `game_play_move` compares `expected_revision` with the current revision,
+   makes a legal move only on equality, then increments the revision.
+4. Deleting a game removes its session. Expired and deleted IDs are no longer
+   valid.
+
+All asynchronous readers clone the position first. The snapshot is rebuilt
+from the initial position and move history, preserving history-dependent chess
+rules such as threefold repetition. A long analysis therefore observes one FEN
+and one revision even if a later request changes the live game.
+
+```text
+read game -> snapshot + revision R -> async analysis -> result tagged R
+                                                   \
+play(expected_revision: R) -> mutate live game -> revision R + 1
+```
+
+An analysis result is informational, not a lock. A caller must use the revision
+it read when submitting `game_play_move`; a stale write returns
+`STALE_POSITION` rather than applying a move to a different position.
+
+## Compute and network services
+
+Stockfish is a single worker-backed engine, so its service serializes analysis
+requests through a bounded queue (32 active or waiting requests). It lazily
+initializes the configured packaged flavor, performs the UCI/ready handshake,
+and gives each request an analysis timeout plus a stop grace period. Init,
+handshake, or analysis failure invalidates and terminates the worker; a queued
+later request initializes a fresh worker. Queue capacity fails fast, and
+shutdown invalidates work from the old generation.
+
+Maia runs in-process with the bundled ONNX model (5M by default). Its inference
+session is lazy and shared after successful creation. For each snapshot it
+tokenizes position history, supplies both Elo inputs, masks logits to legal
+moves, mirrors black-to-move moves for the model vocabulary, and normalizes the
+remaining logits. The output is human move likelihood, never an evaluation.
+
+Lichess is optional and token-gated. The explorer validates speed/rating filters
+locally and forbids filters for `masters`. Each request has a five-second
+attempt timeout, at most two attempts, and a twelve-second overall budget.
+Only timeouts, network failures, HTTP 429, and 5xx responses retry. `Retry-After`
+is honored only when it fits the remaining budget and does not exceed two
+seconds; authentication errors, other 4xx responses, invalid input, and
+malformed responses fail without retry. Successful payloads are checked against
+the legal moves of the snapshot before they can affect a candidate result.
+
+## Result and contract rules
+
+Every registered tool declares an MCP output schema. On success its payload is
+the canonical `structuredContent`; `content` is one short display summary and
+is deliberately not a JSON data channel. Handler failures set `isError: true`
+and return `{ error: { code, message } }` in `structuredContent`. SDK
+input-schema failures happen before the handler and retain the SDK's standard
+text-only error result.
+
+Contract snapshots capture the externally visible tool list, descriptions,
+annotations, and input/output schemas. Update them only as part of an
+intentional contract change:
+
+1. Change the relevant input/output schema and tool adapter together.
+2. Update focused unit and stdio tests, then run `pnpm contract:update` to
+   regenerate the snapshot.
+3. Review the snapshot diff as an API diff: names, required fields, enum values,
+   nullability, and error codes are compatibility surface.
+4. Run `pnpm contract:check` and the full local gate before merging.
+
+Do not regenerate a snapshot merely to make a failing check pass. If a change
+is not intended to alter the public MCP contract, its snapshot must remain
+unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-chess-mcp",
-  "version": "0.3.0",
+  "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",
@@ -14,6 +14,7 @@
   "files": [
     "dist",
     "models",
+    "docs",
     "LICENSE",
     "README.md",
     ".env.example"
@@ -25,18 +26,24 @@
     "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",
+    "test:package": "node scripts/package-smoke.mjs",
+    "test:stress": "tsx --test tests/stress/*.test.ts",
+    "test:live": "tsx --test tests/live/*.test.ts",
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-lines=85 --test-coverage-branches=80 --test-coverage-functions=80 tests/*.test.ts tests/integration/*.test.ts",
     "test": "pnpm test:unit && pnpm test:integration && pnpm test:e2e",
     "check": "pnpm typecheck && pnpm typecheck:test && pnpm test && pnpm test:coverage && pnpm contract:check",
-    "release:check": "pnpm check && pnpm audit --prod && npm pack --dry-run --ignore-scripts",
+    "release:check": "pnpm check && pnpm test:package && pnpm audit --prod && npm pack --dry-run --ignore-scripts",
     "prepublishOnly": "pnpm check",
     "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",