llm-chess-mcp 0.3.0 → 0.3.1

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,13 @@ 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.
+
 ### Export Maia3 to ONNX (build-time only)
 
 This step needs Python + PyTorch once. It downloads the Maia3 checkpoint, verifies
@@ -180,7 +184,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 +192,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 +316,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/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/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,122 @@
+# 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.
+
+## 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.
+
+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
+                                               |-> 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.3.1",
   "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"
@@ -29,10 +30,13 @@
     "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"
   },