@chessceo/mcp 0.50.0 → 0.50.1

package/dist/analysis/eval_cache.js

@@ -0,0 +1,138 @@
+// Per-user memory of cloud-engine results, so analysis is never lost.
+//
+// Claude often analyses loose FENs or move lines first and adds the moves
+// to a file later. Without this, those nodes land with no [%ceo-eval] and
+// the final pass has to analyse them again. Every result that comes back
+// from the analyse endpoint is remembered here, keyed by user id and
+// position (positionKey, same as transpositions), and every file write
+// (add_move, add_line, apply_mutations, ...) fills nodes whose position is
+// remembered and whose stored eval for that engine is missing or shallower.
+//
+// Keyed by the user id from GET /api/agent/me, not by the token: a hosted
+// OAuth access token rotates hourly, the user id doesn't, and one user's
+// analysed positions (their prep) must never land in another user's file.
+// In memory only: a process restart forgets, which costs a re-analysis,
+// never a wrong eval. Every function here is best-effort and never throws
+// into the write path.
+import { createHash } from "node:crypto";
+import { authedRequest, resolveAuthHeader } from "../http.js";
+import { buildIdIndex, positionKey, resolveNodeId } from "../pgn/paths.js";
+import { setCeoEval } from "../pgn/mutations.js";
+import { STORED_EVAL_KEYS } from "../pgn/types.js";
+const TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_POSITIONS_PER_USER = 20_000;
+const MAX_KNOWN_TOKENS = 1_000;
+const cacheByUser = new Map();
+// sha256(Authorization header) → user id. Never the raw token.
+const userByToken = new Map();
+async function currentUserId() {
+    const auth = resolveAuthHeader();
+    if (!auth)
+        return null;
+    const key = createHash("sha256").update(auth).digest("hex");
+    let p = userByToken.get(key);
+    if (!p) {
+        if (userByToken.size >= MAX_KNOWN_TOKENS)
+            userByToken.clear();
+        p = authedRequest("GET", "/api/agent/me")
+            .then(r => {
+            const id = r?.userId;
+            return typeof id === "string" && id ? id : null;
+        })
+            .catch(() => null);
+        userByToken.set(key, p);
+    }
+    const id = await p;
+    // Don't pin a failure (backend blip, old backend): ask again next time.
+    if (!id)
+        userByToken.delete(key);
+    return id;
+}
+const deeper = (a, b) => (a ?? 0) > (b ?? 0);
+// Remember fresh results. Per engine, a deeper result replaces a shallower
+// one; equal depth takes the newer.
+export async function rememberEvals(entries) {
+    try {
+        if (entries.length === 0)
+            return;
+        const user = await currentUserId();
+        if (!user)
+            return;
+        let cache = cacheByUser.get(user);
+        if (!cache) {
+            cache = new Map();
+            cacheByUser.set(user, cache);
+        }
+        const now = Date.now();
+        for (const { fen, ev } of entries) {
+            const key = positionKey(fen);
+            const merged = { ...(cache.get(key) ?? {}) };
+            for (const k of STORED_EVAL_KEYS) {
+                const fresh = ev[k];
+                if (!fresh)
+                    continue;
+                const old = merged[k];
+                const oldLive = old && now - old.at < TTL_MS;
+                if (!oldLive || !deeper(old.ev.depth, fresh.depth))
+                    merged[k] = { ev: fresh, at: now };
+            }
+            // Re-insert so Map order is least-recently-written first.
+            cache.delete(key);
+            cache.set(key, merged);
+        }
+        while (cache.size > MAX_POSITIONS_PER_USER) {
+            const oldest = cache.keys().next().value;
+            if (oldest === undefined)
+                break;
+            cache.delete(oldest);
+        }
+    }
+    catch {
+        // best-effort
+    }
+}
+// Fill remembered evals into the file: every node whose position was
+// analysed gets the engines it lacks, or a deeper read than it holds.
+// Returns the file unchanged (and filled = 0) on any problem. `skipIds`
+// are nodes whose eval the caller set or cleared on purpose in this write.
+export async function fillFromCache(file, skipIds = new Set()) {
+    try {
+        const user = await currentUserId();
+        const cache = user ? cacheByUser.get(user) : undefined;
+        if (!cache || cache.size === 0)
+            return { file, filled: 0 };
+        const now = Date.now();
+        const patches = [];
+        const walk = (node) => {
+            if (!skipIds.has(node.id)) {
+                const hit = cache.get(positionKey(node.fen));
+                if (hit) {
+                    const patch = {};
+                    for (const k of STORED_EVAL_KEYS) {
+                        const c = hit[k];
+                        if (!c || now - c.at >= TTL_MS)
+                            continue;
+                        const stored = node.ceoEval?.[k];
+                        if (!stored || deeper(c.ev.depth, stored.depth))
+                            patch[k] = c.ev;
+                    }
+                    if (patch.sf || patch.lc0 || patch.human)
+                        patches.push({ id: node.id, ev: patch });
+                }
+            }
+            for (const c of node.children)
+                walk(c);
+        };
+        walk(file.root);
+        if (patches.length === 0)
+            return { file, filled: 0 };
+        const idIndex = buildIdIndex(file.root);
+        let out = file;
+        for (const p of patches)
+            out = setCeoEval(out, resolveNodeId(idIndex, p.id), p.ev).file;
+        return { file: out, filled: patches.length };
+    }
+    catch {
+        return { file, filled: 0 };
+    }
+}

package/dist/analysis/response.js

@@ -5,6 +5,7 @@
 // to SAN and WDL to percent, and turns a result into the stored ceoEval.
 import { Chess } from "chess.js";
 import { authedRequest } from "../http.js";
+import { rememberEvals } from "./eval_cache.js";
 export const ENGINES = ["stockfish", "lc0", "human"];
 // Engine name → key in the stored ceoEval / [%ceo-eval] escape.
 export const STORED_KEY = { stockfish: "sf", lc0: "lc0", human: "human" };
@@ -80,9 +81,18 @@ export async function analysePositions(positions, opts) {
         const raw = (await authedRequest("POST", "/api/agent/cloud-engines/analyse", body));
         if (!raw || !Array.isArray(raw.positions))
             throw new Error("unexpected response from the analyse endpoint");
-        for (const r of raw.positions)
-            if (r && typeof r.id === "string")
-                byId.set(r.id, r);
+        const remembered = [];
+        for (const r of raw.positions) {
+            if (!r || typeof r.id !== "string")
+                continue;
+            byId.set(r.id, r);
+            const ev = resultToStoredEval(convertPositionResult(structuredClone(r)));
+            if (ev)
+                remembered.push({ fen: r.fen, ev });
+        }
+        // Remembered per chunk, so a later chunk failing loses nothing already
+        // paid for; a later write fills these into the file (eval_cache.ts).
+        await rememberEvals(remembered);
     }
     // A position the backend didn't answer comes back with no engines, so
     // callers report it as failed rather than shifting other results.

package/dist/index.js

@@ -138,6 +138,7 @@ const ENGINE_WORKFLOW = [
     "2. Ask: show the user the price of anything you would start and get a yes. Rentals bill per minute until stopped.",
     "3. Start: start_cloud_engine({machine_type}) per missing engine. Each SKU runs one engine; the engine comes from the SKU. Wait until list_cloud_engines shows it running (static engines are instant, others ~1-5 min).",
     "4. Analyse: cloud_analyse({fens | lines | file_id+node_ids, engines}) for up to 10 positions, each engine on its own rental, in parallel. auto_evaluate({id, engines}) for a whole file or subtree: fills only the engines each node is missing and saves as it goes. deep_analyse({engine, ...}) for one long think.",
+    "   Nothing analysed is lost: every result is remembered for 24 h, and any later file write (add_move, add_line, apply_mutations, ...) fills nodes reaching an analysed position with that eval (`evals_filled` in the response). So analyse loose lines freely, then add the keepers.",
     "5. Read back: quote_engine_eval gives the stored sf (cp/mate), lc0 and human (win/draw/loss %) per node.",
     "6. Stop: stop_cloud_engine when the work is done, unless the user wants it kept running.",
 ].join("\n");
@@ -631,72 +632,80 @@ Preparation workflow — follow the steps in order and be explicit about which t
 Don't just dump data. Reason about it. Cite specific numbers (game counts, win rates, dates) so the user can trust your conclusions.`;
 };
 // ── Server wiring ──────────────────────────────────────────────────
-const server = new Server({ name: "chessceo-mcp", version: process.env.npm_package_version ?? "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
-server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
-server.setRequestHandler(GetPromptRequestSchema, async (req) => {
-    const { name, arguments: args } = req.params;
-    const promptArgs = {};
-    if (args)
-        for (const [k, v] of Object.entries(args))
-            promptArgs[k] = String(v);
-    let text;
-    switch (name) {
-        case "prepare_for_game":
-            text = PREP_WORKFLOW(promptArgs);
-            break;
-        case "scout_player": {
-            const p = promptArgs.player ?? "the player";
-            text = `Produce a scouting report on ${p}. Steps:
+// One Server per connection. HTTP mode is stateless (a transport per
+// request), and a Server holds one transport at a time, so sharing a
+// single Server made overlapping requests fail with "Already connected
+// to a transport" (two users calling at once, or a client's notification
+// racing its previous request).
+function createServer() {
+    const server = new Server({ name: "chessceo-mcp", version: process.env.npm_package_version ?? "0.1.0" }, { capabilities: { tools: {}, prompts: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
+    server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        const promptArgs = {};
+        if (args)
+            for (const [k, v] of Object.entries(args))
+                promptArgs[k] = String(v);
+        let text;
+        switch (name) {
+            case "prepare_for_game":
+                text = PREP_WORKFLOW(promptArgs);
+                break;
+            case "scout_player": {
+                const p = promptArgs.player ?? "the player";
+                text = `Produce a scouting report on ${p}. Steps:
 1. \`search_player\` to get their FIDE ID.
 2. \`get_player_profile\` — pull rating history, career splits by color and time control, opening repertoire, opponent analysis, top events, notable wins and losses.
 3. Weight the data: recent (last 12-24 months) > older, classical OTB > rapid/blitz > online.
 4. \`prepare_opponent\` twice (once per colour, or once with two sources), then \`get_prep_position(session_token, node_id="r")\` to summarise their opening choices with actual frequencies and win rates. Filter with \`start_month\` if you only care about their current repertoire.
 5. Deliver: current strength, characteristic openings, one-sentence style read, biggest wins, biggest losses / recurring weakness. Cite the numbers.`;
-            break;
-        }
-        case "engine_usage_primer":
-            text = ENGINE_USAGE_DOC;
-            break;
-        case "prep_strategy_primer":
-            text = PREP_STRATEGY_DOC;
-            break;
-        case "head_to_head_briefing": {
-            const a = promptArgs.player_a ?? "player A";
-            const b = promptArgs.player_b ?? "player B";
-            text = `Briefing on the ${a} vs ${b} history. Steps:
+                break;
+            }
+            case "engine_usage_primer":
+                text = ENGINE_USAGE_DOC;
+                break;
+            case "prep_strategy_primer":
+                text = PREP_STRATEGY_DOC;
+                break;
+            case "head_to_head_briefing": {
+                const a = promptArgs.player_a ?? "player A";
+                const b = promptArgs.player_b ?? "player B";
+                text = `Briefing on the ${a} vs ${b} history. Steps:
 1. Resolve both FIDE IDs with \`search_player\`.
 2. \`get_head_to_head\` for the pair — pull overall + per-color W/D/L (from ${a}'s perspective), splits by time format, first / last meeting, most-played openings between them, average game length.
 3. Read the pattern: who has the edge, in which colour, in which time format. Which openings decide the meetings? Anything unusual — very drawish, very sharp, big rating gap?
 4. If either player is currently live in a tournament, note it with \`list_player_live_tournaments\`.
 5. Deliver a one-paragraph read: score, dominant openings, one-line style clash, current form.`;
-            break;
+                break;
+            }
+            default:
+                throw new Error(`Unknown prompt: ${name}`);
         }
-        default:
-            throw new Error(`Unknown prompt: ${name}`);
-    }
-    return {
-        description: `chessceo prompt: ${name}`,
-        messages: [
-            { role: "user", content: { type: "text", text } },
-        ],
-    };
-});
-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) }],
+            description: `chessceo prompt: ${name}`,
+            messages: [
+                { role: "user", content: { type: "text", text } },
+            ],
         };
-    }
-});
+    });
+    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) }],
+            };
+        }
+    });
+    return server;
+}
 // ── Transport selection ────────────────────────────────────────────
 //
 // Two modes:
@@ -721,7 +730,7 @@ const arg = (name, def) => {
 };
 const transportKind = (arg("transport", process.env.MCP_TRANSPORT ?? "stdio") ?? "stdio").toLowerCase();
 if (transportKind === "stdio") {
-    await server.connect(new StdioServerTransport());
+    await createServer().connect(new StdioServerTransport());
 }
 else if (transportKind === "http" || transportKind === "streamable-http") {
     const port = Number(arg("http-port", process.env.MCP_HTTP_PORT ?? "8080"));
@@ -819,7 +828,11 @@ else if (transportKind === "http" || transportKind === "streamable-http") {
                 sessionIdGenerator: undefined,
                 enableJsonResponse: true,
             });
-            res.on("close", () => transport.close());
+            const server = createServer();
+            res.on("close", () => {
+                void transport.close();
+                void server.close();
+            });
             await server.connect(transport);
             // Forward the caller's Authorization header down to tool handlers so
             // they can attach it when calling authenticated backend endpoints.

package/dist/prep/mutations.js

@@ -19,6 +19,7 @@ import { exportPGN } from "../pgn/exporter.js";
 import { buildIdIndex, NodeIdError, PathError, resolveNodeId, ROOT_ID, } from "../pgn/paths.js";
 import { addLine, addMove, deleteSubtree, MutationError, promoteVariation, setAnnotations, setCeoEval, setComment, setNags, setTag, } from "../pgn/mutations.js";
 import { getNodeByPath } from "../analysis/file_handle.js";
+import { fillFromCache } from "../analysis/eval_cache.js";
 import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, } from "../warnings.js";
 // Extract a node id from the args. Accepts either `node_id` or a
 // `parent_id` alias for the add-style tools. Throws with a helpful
@@ -137,10 +138,17 @@ export async function applyBatchMutations(args) {
             throw new Error(`mutation #${i} (${String(op.op)}) failed: ${msg}`);
         }
     }
-    const newPgn = exportPGN(file);
+    // An explicit set_ceo_eval (including a clear) wins over remembered evals.
+    const explicit = new Set();
+    mutations.forEach((op, i) => {
+        if (op.op === "set_ceo_eval")
+            explicit.add(results[i].node_id);
+    });
+    const filled = await fillFromCache(file, explicit);
+    const newPgn = exportPGN(filled.file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
     const saved = await saveGame(id, newPgn, expected);
-    return { ok: true, results, version: saved.version };
+    return { ok: true, results, ...(filled.filled > 0 ? { evals_filled: filled.filled } : {}), version: saved.version };
 }
 // Load-mutate-save: fetch current PGN, parse, apply mutation, re-export,
 // save with optimistic lock. Auto-saves so every tool call is atomic;
@@ -162,7 +170,10 @@ export async function applyMutation(args, mutator) {
         }
         throw err;
     }
-    const newPgn = exportPGN(result.file);
+    // Nodes whose position the cloud engines already analysed this session
+    // get that eval now (eval_cache.ts), so a final pass has less to do.
+    const filled = await fillFromCache(result.file);
+    const newPgn = exportPGN(filled.file);
     const expected = typeof args.expected_version === "number" ? args.expected_version : g.version;
     const saved = await saveGame(id, newPgn, expected);
     return {
@@ -171,6 +182,7 @@ export async function applyMutation(args, mutator) {
         ...(result.results !== undefined ? { line: result.results } : {}),
         ...(result.warning ? { warning: result.warning } : {}),
         ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
+        ...(filled.filled > 0 ? { evals_filled: filled.filled } : {}),
         version: saved.version,
     };
 }

package/dist/tools.js

@@ -314,7 +314,7 @@ export const TOOLS = [
             "Positions: `fens` (list), `lines` (list of SAN move sequences from `fen` or the start), `file_id` + `node_ids` (list), or a single `fen` / `moves` / `file_id`+`node_id`. Examples: analyse three FENs with Stockfish → `{fens: [a, b, c], engines: [\"stockfish\"]}`; with the human engine and Stockfish → `engines: [\"stockfish\", \"human\"]`. For a whole file or subtree use auto_evaluate instead.\n\n" +
             "Scores: `scoreCp` and `mate` are White's point of view (+20 = White +0.20; mate +5 = White mates in 5). lc0 and human lines carry `wdl`: win/draw/loss percent, White's point of view. Read the response's `eval_scale` before calling a position equal.\n\n" +
             "GROUNDING: every claim about a position must trace back to engine output from this session. Don't invent evaluations, best moves or variations. When you have no data for a position, run it or say so.\n\n" +
-            "Storing: with `file_id`, each result is merged into the `ceoEval` of every node that reaches that position (`stored_on` in the response), keeping other engines' stored reads. quote_engine_eval cites them later.\n\n" +
+            "Storing: with `file_id`, each result is merged into the `ceoEval` of every node that reaches that position (`stored_on` in the response), keeping other engines' stored reads. quote_engine_eval cites them later. Without `file_id` nothing is lost either: results are remembered for 24 h and filled into any node reaching that position the next time you write to a file (`evals_filled` in add_move / add_line / apply_mutations responses).\n\n" +
             "Contempt (`contempt`, lc0 only): signed -100..100, positive favours White. Use it to find ideas (e.g. -20 makes Black play for a win). Never quote a contempt eval as objective.\n\n" +
             "PVs are capped at 6 plies (`pv_truncated: true` when cut). To see further, analyse the position at the end of the line; raise `pv_max_plies` only to verify a forcing line. Don't paste PVs into add_line as prep.\n\n" +
             "Needs running rentals for the engines you ask for (see ensure_engines). Costs money while rentals run; use get_position_stats for casual questions.",
@@ -442,7 +442,7 @@ export const TOOLS = [
         name: "list_transpositions",
         description: "Group every position in a prep file that appears more than once — the same piece placement + side-to-move + castling rights reached by different move orders. Chess move orders diverge and re-converge constantly (1.d4 Nf6 2.c4 e6 3.Nc3 vs 1.c4 e6 2.Nc3 Nf6 3.d4 land on the same position); if you analyse both branches independently or write the same commentary twice, you're wasting engine time and inviting inconsistency.\n\n" +
             "Call this BEFORE `auto_evaluate` on a big subtree to see how much work will actually be new, and BEFORE writing prose to know which nodes can share a comment or should point at each other with 'transposes to line X'.\n\n" +
-            "Note: engine evals auto-propagate — when `cloud_analyse({file_id, node_id})` stores `ceoEval` on a node, it also stamps every transposition of that position in the same file (see the response's `also_stored_on`). And `auto_evaluate({only_missing: true})` naturally skips the twin because it now has an eval. So detection is cheap AND propagation is automatic; this tool is for prose planning and one-shot audits, not for gating engine work.\n\n" +
+            "Note: engine evals auto-propagate — when `cloud_analyse({file_id, node_id})` stores `ceoEval` on a node, it also stamps every transposition of that position in the same file (see the response's `stored_on`). And `auto_evaluate` analyses each position once and skips nodes that already hold every requested engine. So detection is cheap AND propagation is automatic; this tool is for prose planning and one-shot audits, not for gating engine work.\n\n" +
             "Response: `{ file_id, group_count, node_count, groups: [{ position_key, size, node_ids, sans }] }`. `position_key` is the 3-field FEN prefix used as the match key; `size` is how many nodes share it; `sans` are the moves that led to each occurrence (parallel with `node_ids`, DFS order — first entry is the earliest/mainline-preferred occurrence). Only groups with size ≥ 2 are returned; sorted by size descending.",
         inputSchema: {
             type: "object",

package/docs/engine-usage.md

@@ -205,6 +205,7 @@ Every analysis needs a running rental for each engine you ask for. Each rental r
 3. **Start:** `start_cloud_engine({machine_type})` for each missing engine. The engine comes from the SKU. Static engines are ready at once; others take ~1-5 min (`list_cloud_engines` shows when).
 4. **Analyse:**
    - A few positions: `cloud_analyse` with `fens`, `lines`, or `file_id`+`node_ids` (up to 10 per call), e.g. `{fens: [a, b, c], engines: ["stockfish", "human"]}`.
+   - Loose FENs or lines first, file later: fine. Every result is remembered for 24 h (per user), and the next write to a file fills each node that reaches an analysed position (`evals_filled` in the write's response). A deeper stored eval is never replaced by a shallower one.
    - A whole file or subtree: `auto_evaluate({id, engines})`. It runs only the engines each node is missing, analyses transpositions once, and saves as it goes. Adding an engine later runs just that engine.
    - One critical position deep: `deep_analyse`.
 5. **Read back:** `quote_engine_eval` returns the stored evals per node.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chessceo/mcp",
-  "version": "0.50.0",
+  "version": "0.50.1",
   "description": "Model Context Protocol server for chess.ceo — 11.7M+ games, ~1.5M FIDE player profiles, opening preparation, live broadcasts.",
   "type": "module",
   "bin": {