@chessceo/mcp 0.49.11 → 0.50.1

package/dist/analysis/response.js

@@ -1,18 +1,106 @@
-// Shared engine-response helpers used across cloud_analyse, auto_evaluate,
-// deep_analyse, and get_position_stats. All PGN-shape data comes back
-// from the backend in UCI ("g1f3") — this module converts to SAN, extracts
-// stored evals from the raw JSON, and derives the eval → NAG mapping.
-//
-// Extracted from src/index.ts in v0.44 as part of the file split.
+// Shared engine helpers for cloud_analyse, auto_evaluate, deep_analyse and
+// the compact eval attached to position tools. The backend returns one
+// result per position with a block per engine (stockfish, lc0, human), PVs
+// in UCI and WDL in per mille. This module calls it in chunks, converts PVs
+// to SAN and WDL to percent, and turns a result into the stored ceoEval.
 import { Chess } from "chess.js";
 import { authedRequest } from "../http.js";
-// Convert a UCI move sequence into SAN by walking it move-by-move on
-// chess.js from the given starting FEN. LLMs reason far better in SAN
-// ("Nf3", "Bxc4") than UCI ("g1f3", "b5c4"), and matches how prep
-// discussion is written in the real world. If a move fails to parse
-// (illegal from the current position — bug or truncated PV), we
-// truncate cleanly rather than throwing so the response still carries
-// what we could convert.
+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" };
+// Backend limits (handlers/agent.go): positions per call, and positions ×
+// movetime per call. analysePositions chunks to stay inside both.
+export const MAX_POSITIONS_PER_CALL = 10;
+const MAX_CALL_BUDGET_MS = 150_000;
+export const DEFAULT_MOVETIME_MS = 2000;
+// Validate an `engines` argument. Unknown names throw (better than silently
+// running fewer engines than the caller asked for).
+export function parseEngines(v, fallback) {
+    if (v === undefined || v === null)
+        return fallback;
+    const list = Array.isArray(v) ? v : [v];
+    const out = [];
+    for (const e of list) {
+        const name = String(e).trim().toLowerCase();
+        if (!ENGINES.includes(name)) {
+            throw new Error(`unknown engine '${e}' (allowed: stockfish, lc0, human)`);
+        }
+        if (!out.includes(name))
+            out.push(name);
+    }
+    if (out.length === 0)
+        throw new Error("engines must list at least one of: stockfish, lc0, human");
+    return out;
+}
+// Pull the optional per-engine knobs (multipv, contempt, rentals) out of tool
+// args. Shared by every analysis tool so they all accept the same shape.
+export function analyseOptionsFromArgs(args, engines, movetimeMs) {
+    const opts = { engines, movetime_ms: movetimeMs };
+    const pickMap = (v) => v && typeof v === "object" && !Array.isArray(v) ? v : undefined;
+    const mpv = pickMap(args.multipv);
+    if (mpv) {
+        const out = {};
+        for (const e of ENGINES)
+            if (typeof mpv[e] === "number")
+                out[e] = mpv[e];
+        opts.multipv = out;
+    }
+    if (typeof args.contempt === "number")
+        opts.contempt = args.contempt;
+    const rentals = pickMap(args.rentals);
+    if (rentals) {
+        const out = {};
+        for (const e of ENGINES)
+            if (typeof rentals[e] === "string" && rentals[e].trim())
+                out[e] = rentals[e].trim();
+        opts.rentals = out;
+    }
+    return opts;
+}
+// Run positions through the backend, chunked to its per-call limits. Results
+// come back in input order, raw (UCI PVs, per-mille WDL).
+export async function analysePositions(positions, opts) {
+    const movetime = opts.movetime_ms ?? DEFAULT_MOVETIME_MS;
+    const perCall = Math.max(1, Math.min(MAX_POSITIONS_PER_CALL, Math.floor(MAX_CALL_BUDGET_MS / movetime)));
+    // Every position gets an id; results are matched back by id, not order.
+    const withIds = positions.map((p, i) => ({ id: p.id ?? `p${i + 1}`, fen: p.fen }));
+    const byId = new Map();
+    for (let i = 0; i < withIds.length; i += perCall) {
+        const body = {
+            positions: withIds.slice(i, i + perCall),
+            engines: opts.engines,
+            movetime_ms: movetime,
+        };
+        if (opts.multipv && Object.keys(opts.multipv).length > 0)
+            body.multipv = opts.multipv;
+        if (typeof opts.contempt === "number")
+            body.contempt = opts.contempt;
+        if (opts.rentals && Object.keys(opts.rentals).length > 0)
+            body.rentals = opts.rentals;
+        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");
+        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.
+    return withIds.map(p => byId.get(p.id) ?? { id: p.id, fen: p.fen, engines: {} });
+}
+// Convert a UCI move sequence into SAN by walking it on chess.js from the
+// given FEN. LLMs reason far better in SAN. If a move fails to parse
+// (truncated PV), stop cleanly rather than throw.
 export function uciLineToSAN(startFen, uciMoves) {
     const board = new Chess(startFen);
     const out = [];
@@ -51,131 +139,105 @@ export function uciMoveToSAN(startFen, uci) {
         return uci;
     }
 }
-// Fetch a compact cloud eval for `fen`. Returns null on any error — no
-// running combo instance, engine failure, network timeout. Callers
-// attach the result to their response as `.eval` so the LLM has the
-// stockfish + lc0 read without a separate tool call.
-export async function fetchCompactEval(fen) {
-    try {
-        const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", { fen, movetime_ms: 1500, multipv: 1 });
-        const converted = convertCloudSnapshotResponse(raw, fen);
-        const stored = analysisToStoredEval(converted);
-        return storedEvalToCompact(stored, converted);
-    }
-    catch {
-        return null;
-    }
-}
-// Trim every PV in a converted cloud-analyse response to `maxPlies`
-// and mark each trimmed line with `pv_truncated: true` so the LLM
-// sees what happened. Applied ONLY to cloud_analyse (short synchronous
-// snapshot); deep_analyse is the explicit "give me the deep line"
-// tool and keeps its full PV.
-export function capPvsInResponse(converted, maxPlies) {
-    if (!converted || typeof converted !== "object")
-        return;
-    const r = converted;
-    for (const eng of [r.stockfish, r.lc0]) {
-        if (!eng || !Array.isArray(eng.lines))
+// In place: PVs and bestMove to SAN, WDL from per mille to percent, and (if
+// pvMaxPlies is set) PVs capped with `pv_truncated` on trimmed lines. PVs
+// past ~6 plies are speculative, and long ones get pasted into add_line as
+// if they were prep; the caller re-analyses the end position to see more.
+export function convertPositionResult(r, pvMaxPlies) {
+    for (const e of ENGINES) {
+        const block = r.engines?.[e];
+        if (!block)
             continue;
-        for (const line of eng.lines) {
-            if (Array.isArray(line.pv) && line.pv.length > maxPlies) {
-                line.pv = line.pv.slice(0, maxPlies);
-                line.pv_truncated = true;
+        for (const line of block.lines ?? []) {
+            if (Array.isArray(line.pv)) {
+                line.pv = uciLineToSAN(r.fen, line.pv);
+                if (pvMaxPlies && line.pv.length > pvMaxPlies) {
+                    line.pv = line.pv.slice(0, pvMaxPlies);
+                    line.pv_truncated = true;
+                }
             }
+            if (line.wdl)
+                line.wdl = wdlPercent(line.wdl);
         }
+        if (typeof block.bestMove === "string")
+            block.bestMove = uciMoveToSAN(r.fen, block.bestMove);
     }
-    converted.pv_max_plies = maxPlies;
+    return r;
 }
-export function convertCloudSnapshotResponse(raw, startFen) {
-    if (!raw || typeof raw !== "object")
-        return raw;
-    const r = raw;
-    for (const eng of [r.stockfish, r.lc0]) {
-        if (!eng)
-            continue;
-        if (Array.isArray(eng.lines)) {
-            for (const line of eng.lines) {
-                if (Array.isArray(line.pv))
-                    line.pv = uciLineToSAN(startFen, line.pv);
-            }
-        }
-        if (typeof eng.bestMove === "string")
-            eng.bestMove = uciMoveToSAN(startFen, eng.bestMove);
+// Per mille → whole percent summing to 100 (largest remainder), so a
+// stored W/D/L never reads 101%.
+function wdlPercent(m) {
+    const total = m.w + m.d + m.l || 1;
+    const exact = [m.w, m.d, m.l].map(v => (v * 100) / total);
+    const floor = exact.map(Math.floor);
+    let left = 100 - floor.reduce((a, b) => a + b, 0);
+    const order = exact.map((v, i) => [v - floor[i], i]).sort((a, b) => b[0] - a[0]);
+    for (const [, i] of order) {
+        if (left <= 0)
+            break;
+        floor[i]++;
+        left--;
     }
-    return raw;
+    return { w: floor[0], d: floor[1], l: floor[2] };
 }
-export function analysisToStoredEval(analysis) {
-    if (!analysis || typeof analysis !== "object")
-        return null;
-    const r = analysis;
-    // Backend returns White-POV cp/mate (engine-ws flips in ParseInfo
-    // based on side-to-move, cloud_snapshot passes through). Pure
-    // pass-through here — a previous sign-flip on black-to-move was
-    // wrong and silently inverted every Black-to-move stored eval.
-    const engineEval = (block) => {
-        const line = block?.lines?.[0];
-        if (!line)
-            return undefined;
-        const depth = line.depth ?? block?.depth;
-        if (typeof line.mate === "number")
-            return { mate: line.mate, depth };
-        if (typeof line.scoreCp === "number")
-            return { cp: line.scoreCp, depth };
-        return undefined;
-    };
-    const sf = engineEval(r.stockfish);
-    const lc0 = engineEval(r.lc0);
-    if (!sf && !lc0)
-        return null;
+// Stored eval from a CONVERTED result (WDL already in percent). Stockfish
+// stores cp/mate; lc0 and human store WDL, falling back to cp/mate if an
+// engine sent no WDL. Engines that errored or returned no line are left out,
+// so a merge keeps whatever was stored for them before.
+export function resultToStoredEval(r) {
     const ev = {};
-    if (sf)
-        ev.sf = sf;
-    if (lc0)
-        ev.lc0 = lc0;
-    ev.nag = nagFromCp(sf?.cp, sf?.mate) ?? nagFromCp(lc0?.cp, lc0?.mate) ?? undefined;
-    return ev;
+    for (const e of ENGINES) {
+        const block = r.engines?.[e];
+        const line = block?.lines?.[0];
+        if (!block || block.error || !line)
+            continue;
+        const depth = line.depth ?? block.depth;
+        let stored;
+        if (e !== "stockfish" && line.wdl) {
+            stored = { w: line.wdl.w, d: line.wdl.d, l: line.wdl.l, depth };
+        }
+        else if (typeof line.mate === "number") {
+            stored = { mate: line.mate, depth };
+        }
+        else if (typeof line.scoreCp === "number") {
+            stored = { cp: line.scoreCp, depth };
+        }
+        if (stored)
+            ev[STORED_KEY[e]] = stored;
+    }
+    return ev.sf || ev.lc0 || ev.human ? ev : null;
 }
-export function nagFromCp(cp, mate) {
-    let effective;
-    if (typeof mate === "number")
-        effective = mate > 0 ? 10000 : -10000;
-    else if (typeof cp === "number")
-        effective = cp;
-    else
-        return null;
-    const abs = Math.abs(effective);
-    if (abs < 25)
-        return "$10";
-    if (abs < 60)
-        return effective > 0 ? "$14" : "$15";
-    if (abs < 130)
-        return effective > 0 ? "$16" : "$17";
-    return effective > 0 ? "$18" : "$19";
+// Engines that produced no usable line for this position, with the reason.
+export function engineFailures(r, engines) {
+    const out = {};
+    for (const e of engines) {
+        const block = r.engines?.[e];
+        if (!block)
+            out[e] = "no result";
+        else if (block.error)
+            out[e] = block.error;
+        else if (!block.lines || block.lines.length === 0)
+            out[e] = "no lines";
+    }
+    return out;
 }
-// Adapter for the compact eval attached to live query responses. Same
-// derivation logic; different output shape (needs the .nag + summary
-// used by get_position_stats / prep_snapshot).
-export function storedEvalToCompact(ev, analysis) {
-    if (!ev)
-        return null;
-    const a = analysis;
-    const compact = { nag: ev.nag ?? null };
-    if (ev.sf) {
-        compact.stockfish = {
-            cp: ev.sf.cp,
-            mate: ev.sf.mate,
-            bestMove: a.stockfish?.bestMove,
-            pv: a.stockfish?.lines?.[0]?.pv,
-        };
+export async function fetchCompactEval(fen) {
+    try {
+        const [raw] = await analysePositions([{ fen }], {
+            engines: ["stockfish"],
+            movetime_ms: 1500,
+            multipv: { stockfish: 1 },
+        });
+        if (!raw)
+            return null;
+        const r = convertPositionResult(raw, 6);
+        const sf = r.engines.stockfish;
+        const line = sf?.lines?.[0];
+        if (!sf || sf.error || !line)
+            return null;
+        return { stockfish: { cp: line.scoreCp, mate: line.mate, bestMove: sf.bestMove, pv: line.pv } };
     }
-    if (ev.lc0) {
-        compact.lc0 = {
-            cp: ev.lc0.cp,
-            mate: ev.lc0.mate,
-            bestMove: a.lc0?.bestMove,
-            pv: a.lc0?.lines?.[0]?.pv,
-        };
+    catch {
+        return null;
     }
-    return compact;
 }

package/dist/index.js

@@ -22,10 +22,11 @@ import { TOOLS } from "./tools.js";
 import { PROMPTS } from "./prompts.js";
 import { commentAntiPatterns, longLineWarning, noDescribeWarning, noStatsCheckWarning, positionalNagOnIntermediateWarning, positionsDescribed, positionsStatsChecked, } from "./warnings.js";
 import { authContext, authedRequest, deleteGame, fetchGame, get, makeFileId, restoreGame, } from "./http.js";
-import { analysisToStoredEval, capPvsInResponse, convertCloudSnapshotResponse, fetchCompactEval, } from "./analysis/response.js";
+import { fetchCompactEval, } from "./analysis/response.js";
+import { cloudAnalyse, ensureEngines } from "./analysis/cloud.js";
 import { autoEvaluate, autoEvaluateCancel, autoEvaluateStatus, } from "./analysis/auto.js";
 import { deepAnalyseCancel, deepAnalyseStart, deepAnalyseStatus, } from "./analysis/deep.js";
-import { analyseRouting, getNodeByPath, resolveFromNodeOrFen, storeEvalOnNode, } from "./analysis/file_handle.js";
+import { getNodeByPath, resolveFromNodeOrFen, } from "./analysis/file_handle.js";
 import { findPositionInCourses, readCourseAtPosition, runSfEval } from "./courses.js";
 import { applyBatchMutations, applyMutation, argNodeId, } from "./prep/mutations.js";
 import { listNodes, listTranspositions, readPrepFile, } from "./prep/read.js";
@@ -41,6 +42,8 @@ const AUTHED_TOOLS = new Set([
     "list_cloud_engines",
     "stop_cloud_engine",
     "cloud_analyse",
+    "ensure_engines",
+    "list_cloud_machine_options",
     "list_collections",
     "create_collection",
     "rename_collection",
@@ -125,11 +128,23 @@ const ENGINE_GUIDE = {
     stockfish: "Objective calculation, the default cloud engine at about 100 million nodes per second. A few seconds gives a very strong view of the position. Use it on every position, including when steering by lc0 or human. Its score is the objective value with best defense: 0.00 means objectively a draw with best play, not that nothing is happening or that neither side has chances. Many positions that are very hard to play for a human score 0.00. Scores drift toward 0.00 as the search deepens, especially in drawn positions. Use it to check whether a tactic is real, whether a defense holds, and whether a move loses material or the game.",
     lc0: "Neural-net engine trained on self-play games, not human games. It is better than Stockfish at long-term ideas and at judging which side is practically on top. Never gives 0.00: it always says which side prefers the position, at least a little. Use it when Stockfish gives 0.00 to see who still has the practical edge, and to find where the long-term ideas are. Contempt changes how it values a draw and which side it plays for: contempt at -20 makes Black play for a win, which is useful for finding ideas, including in openings. It is much weaker tactically than Stockfish, so confirm any concrete line with Stockfish.",
     human: "Neural net trained only on human games, about 11 million rated games. Its moves and evaluations are practical, not objective: the moves it suggests are the ones a human would find and play. It punishes dubious moves less than Stockfish, because human games contain many imperfect moves that still work in practice, so a move with a sound idea behind it can score well here. Use it to predict how a person will respond to an idea, to find ideas (it may like a move that only fails to a refutation no human would find; Stockfish shows whether that refutation exists), and to see how a human would evaluate a position, especially positional or unclear ones. Like lc0 it is weaker in very unusual positions, and its evaluations there can be trusted much less. Stockfish remains the check on tactics and on whether a practical idea is objectively sound.",
-    combo: "Runs Stockfish and Lc0 together — use when you want both the objective read and the practical/human-feel read on the same position.",
 };
 // Modern engines give equality very often, so small numbers are not "equal".
 // Rough guide, not exact thresholds. Shown alongside ENGINE_GUIDE above.
 const ENGINE_EVAL_SCALE = "Small numbers are not equality. ±0.00 to ±0.10 is equal in practice (+0.10 is '=' or '+=' at most). +0.20 to +0.40 is real pressure, not 'a bit better'. +0.50 and up is a clear advantage. Stockfish 0.00 with a plus from Lc0 is a practical edge, not equality. Check both engines before calling a position equal.";
+// How to run analysis end to end. Authed response only, with ENGINE_GUIDE.
+const ENGINE_WORKFLOW = [
+    "1. Plan: ensure_engines({engines, positions}) shows what is running, what to start, the price and an estimate. It starts nothing.",
+    "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");
+// Eval symbols are the writer's call, not the engine's. Recommendation
+// only; nothing in the MCP sets a symbol automatically.
+const EVAL_SYMBOL_GUIDE = "The eval symbol (=, +=, ±, +-) is your call, written for a human reader. The engines inform it; no tool sets it for you. Stockfish 0.00 can still be += when Lc0 or the human engine clearly prefer one side, because the symbol describes the practical picture, not only the objective one. Look at all engines you ran before choosing, and don't put a symbol on a position nobody analysed.";
 // v0.48: consolidated the five `read_*_guide` / `read_example_prep_files`
 // tools into ONE `read_docs`. LLM lists what it wants; we return them
 // in a single response. Also cleaner: enumerating available docs in one
@@ -390,68 +405,26 @@ async function callToolInner(name, args) {
                 ...(resp && typeof resp === "object" ? resp : { options: [] }),
                 engine_guide: ENGINE_GUIDE,
                 eval_scale: ENGINE_EVAL_SCALE,
+                eval_symbols: EVAL_SYMBOL_GUIDE,
+                workflow: ENGINE_WORKFLOW,
             };
         }
+        case "ensure_engines":
+            return {
+                ...await ensureEngines(args),
+                engine_guide: ENGINE_GUIDE,
+                workflow: ENGINE_WORKFLOW,
+            };
         case "start_cloud_engine":
             return authedRequest("POST", "/api/agent/cloud-engines", {
                 machineType: String(args.machine_type),
-                ...(typeof args.engine_type === "string" ? { engineType: args.engine_type } : {}),
             });
         case "list_cloud_engines":
             return authedRequest("GET", "/api/agent/cloud-engines");
         case "stop_cloud_engine":
             return authedRequest("DELETE", `/api/agent/cloud-engines/${encodeURIComponent(String(args.contract_id))}`);
-        case "cloud_analyse": {
-            const resolved = await resolveFromNodeOrFen(args);
-            const fen = resolved.fen;
-            const body = { fen };
-            if (typeof args.movetime_ms === "number")
-                body.movetime_ms = args.movetime_ms;
-            if (typeof args.stockfish_multipv === "number")
-                body.stockfish_multipv = args.stockfish_multipv;
-            if (typeof args.lc0_multipv === "number")
-                body.lc0_multipv = args.lc0_multipv;
-            if (typeof args.contempt === "number")
-                body.contempt = args.contempt;
-            Object.assign(body, analyseRouting(args));
-            const raw = await authedRequest("POST", "/api/agent/cloud-engines/analyse", body);
-            const converted = convertCloudSnapshotResponse(raw, fen);
-            // PV cap: engine PVs beyond ~6 plies are speculative (the tail is
-            // where the search's confidence collapses — SF at depth 24 has
-            // seen the first few plies solidly and hedged everything after).
-            // More importantly, LLMs paste long PVs into `add_line` as if
-            // they were prepared repertoire. A 15-move PV pasted as a
-            // variation is one line of engine output through positions
-            // where both sides had real choices — not a repertoire. Cap the
-            // affordance: return only what's load-bearing (3 full moves for
-            // understanding the point), let the caller re-analyse the
-            // resulting position if they want to see further. Override via
-            // `pv_max_plies` for the rare case (deep tactics verification).
-            const pvMaxPlies = typeof args.pv_max_plies === "number" && args.pv_max_plies > 0
-                ? Math.min(args.pv_max_plies, 40)
-                : 6;
-            capPvsInResponse(converted, pvMaxPlies);
-            // Node-addressed calls: persist the result on the node's ceoEval
-            // so a later quote_engine_eval can cite this measurement. This is
-            // the anti-hallucination hinge — prose that says "engines say X
-            // on node Y" can only trace back to a call actually made against
-            // node_id=Y, because the store only fires when file_id+node_id
-            // was supplied and the eval survives via the [%ceo-eval] escape.
-            if (resolved.file) {
-                const ev = analysisToStoredEval(converted);
-                if (ev) {
-                    const stamped = await storeEvalOnNode(resolved.file, ev);
-                    if (stamped.length > 1) {
-                        // Surface the propagation so the LLM sees exactly which
-                        // other nodes now carry this eval (and can skip them for
-                        // re-analysis).
-                        converted.also_stored_on = stamped.slice(1);
-                    }
-                }
-            }
-            converted.eval_scale = ENGINE_EVAL_SCALE;
-            return converted;
-        }
+        case "cloud_analyse":
+            return cloudAnalyse(args, ENGINE_EVAL_SCALE);
         case "deep_analyse":
             return deepAnalyseStart(args);
         case "deep_analyse_status":
@@ -562,7 +535,7 @@ async function callToolInner(name, args) {
         case "apply_mutations":
             return applyBatchMutations(args);
         case "auto_evaluate":
-            return autoEvaluate(args, applyBatchMutations);
+            return autoEvaluate(args);
         case "auto_evaluate_status":
             return autoEvaluateStatus(args);
         case "auto_evaluate_cancel":
@@ -659,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) }],
+            description: `chessceo prompt: ${name}`,
+            messages: [
+                { role: "user", content: { type: "text", text } },
+            ],
         };
-    }
-    catch (err) {
-        return {
-            isError: true,
-            content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
-        };
-    }
-});
+    });
+    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:
@@ -749,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"));
@@ -847,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.