@chessceo/mcp 0.43.0 → 0.46.0

package/dist/analysis/response.js

@@ -0,0 +1,181 @@
+// 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.
+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.
+export function uciLineToSAN(startFen, uciMoves) {
+    const board = new Chess(startFen);
+    const out = [];
+    for (const uci of uciMoves) {
+        if (uci.length < 4)
+            break;
+        try {
+            const move = board.move({
+                from: uci.slice(0, 2),
+                to: uci.slice(2, 4),
+                promotion: uci.length >= 5 ? uci[4] : undefined,
+            });
+            if (!move)
+                break;
+            out.push(move.san);
+        }
+        catch {
+            break;
+        }
+    }
+    return out;
+}
+export function uciMoveToSAN(startFen, uci) {
+    if (!uci || uci.length < 4)
+        return uci;
+    const board = new Chess(startFen);
+    try {
+        const move = board.move({
+            from: uci.slice(0, 2),
+            to: uci.slice(2, 4),
+            promotion: uci.length >= 5 ? uci[4] : undefined,
+        });
+        return move ? move.san : uci;
+    }
+    catch {
+        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))
+            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;
+            }
+        }
+    }
+    converted.pv_max_plies = maxPlies;
+}
+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);
+    }
+    return raw;
+}
+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;
+    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;
+}
+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";
+}
+// 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,
+        };
+    }
+    if (ev.lc0) {
+        compact.lc0 = {
+            cp: ev.lc0.cp,
+            mate: ev.lc0.mate,
+            bestMove: a.lc0?.bestMove,
+            pv: a.lc0?.lines?.[0]?.pv,
+        };
+    }
+    return compact;
+}

package/dist/courses.js

@@ -0,0 +1,167 @@
+// Subprocess wrappers for two Python-backed helpers:
+//   - fenfind / readpgn — polyglot Zobrist search over the user's
+//     Chessable / PGN course library (the `find_position_in_courses`
+//     and `read_course_at_position` tools).
+//   - sf_eval — spawns local stockfish, parses its `eval` verbose
+//     output (the eval-terms leg of `describe_position`).
+//
+// Both live outside the pure-TS MCP because they reuse Python code
+// (python-chess for polyglot hashing / PGN parsing; the local
+// stockfish binary for eval terms) that porting to TS would just
+// duplicate.
+//
+// Extracted from index.ts in v0.44 as part of the file split.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveFromNodeOrFen } from "./analysis/file_handle.js";
+// Path to sf_eval helper (spawns local stockfish, parses its `eval`
+// verbose output). SF_EVAL_PATH env overrides the bundled tools/sf_eval/
+// directory.
+const SF_EVAL_SCRIPT = (() => {
+    const envPath = process.env.SF_EVAL_PATH?.trim();
+    if (envPath && existsSync(join(envPath, "sf_eval")))
+        return join(envPath, "sf_eval");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const bundled = join(here, "..", "tools", "sf_eval", "sf_eval");
+    return existsSync(bundled) ? bundled : null;
+})();
+const SF_EVAL_TIMEOUT_MS = 12_000;
+export async function runSfEval(fen) {
+    if (!SF_EVAL_SCRIPT) {
+        return {
+            found: false,
+            error: "sf_eval script not bundled; set SF_EVAL_PATH or install tools/sf_eval/",
+        };
+    }
+    const stdout = await new Promise((resolve, reject) => {
+        const p = spawn(SF_EVAL_SCRIPT, ["--fen", fen], { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        p.stdout.on("data", d => { out += d.toString("utf8"); });
+        p.stderr.on("data", d => { err += d.toString("utf8"); });
+        const to = setTimeout(() => {
+            try {
+                p.kill("SIGTERM");
+            }
+            catch { /* already dead */ }
+            reject(new Error(`sf_eval timed out after ${SF_EVAL_TIMEOUT_MS}ms`));
+        }, SF_EVAL_TIMEOUT_MS);
+        p.on("error", e => { clearTimeout(to); reject(e); });
+        p.on("close", code => {
+            clearTimeout(to);
+            if (code !== 0)
+                reject(new Error(`sf_eval exited ${code}: ${err.slice(0, 500)}`));
+            else
+                resolve(out);
+        });
+    });
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (e) {
+        throw new Error(`sf_eval returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
+    }
+}
+// Path resolution order (`FENFIND_PATH` env var overrides):
+//   1. $FENFIND_PATH/fenfind
+//   2. <package-root>/tools/fenfind/fenfind (ships with the npm package)
+// The bash wrapper picks a python interpreter with python-chess
+// available (venv at $here/.venv/bin/python preferred, then falls back
+// to system python3). DB path is resolved inside fenfind.py itself
+// (FENFIND_DB env, then ~/positions.db).
+const FENFIND_DIR = (() => {
+    const envPath = process.env.FENFIND_PATH?.trim();
+    if (envPath && existsSync(join(envPath, "fenfind")))
+        return envPath;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const bundled = join(here, "..", "tools", "fenfind");
+    return existsSync(join(bundled, "fenfind")) ? bundled : null;
+})();
+// Cap on how long we let the subprocess run. SQLite hash lookup returns
+// sub-second; PGN read from a course file is O(chapter size) and rarely
+// exceeds a second. 15s is a stuck-process backstop, not a real limit.
+const FENFIND_TIMEOUT_MS = 15_000;
+async function runFenfindScript(scriptName, args) {
+    if (!FENFIND_DIR) {
+        throw new Error("fenfind index not installed — set FENFIND_PATH or install the tools/fenfind bundle");
+    }
+    const script = join(FENFIND_DIR, scriptName);
+    return new Promise((resolve, reject) => {
+        const p = spawn(script, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        let err = "";
+        p.stdout.on("data", d => { out += d.toString("utf8"); });
+        p.stderr.on("data", d => { err += d.toString("utf8"); });
+        const to = setTimeout(() => {
+            try {
+                p.kill("SIGTERM");
+            }
+            catch { /* already dead */ }
+            reject(new Error(`${scriptName} timed out after ${FENFIND_TIMEOUT_MS}ms`));
+        }, FENFIND_TIMEOUT_MS);
+        p.on("error", e => { clearTimeout(to); reject(e); });
+        p.on("close", code => {
+            clearTimeout(to);
+            if (code !== 0)
+                reject(new Error(`${scriptName} exited ${code}: ${err.slice(0, 500)}`));
+            else
+                resolve(out);
+        });
+    });
+}
+function parseFenfindJson(scriptName, stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch (e) {
+        throw new Error(`${scriptName} returned non-JSON output (${e instanceof Error ? e.message : String(e)}): ${stdout.slice(0, 300)}`);
+    }
+}
+export async function findPositionInCourses(args) {
+    if (!FENFIND_DIR) {
+        return {
+            status: "not_available",
+            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind` script and positions.db, or install the tools/fenfind bundle shipped in the npm package.",
+        };
+    }
+    const resolved = await resolveFromNodeOrFen(args);
+    const cliArgs = [resolved.fen, "--json"];
+    if (typeof args.sort === "string" && (args.sort === "recency" || args.sort === "notes")) {
+        cliArgs.push("--sort", args.sort);
+    }
+    if (args.include_games)
+        cliArgs.push("--games");
+    if (args.chapters_mode)
+        cliArgs.push("--chapters");
+    if (typeof args.min_notes_chars === "number")
+        cliArgs.push("--min", String(args.min_notes_chars));
+    if (typeof args.limit === "number")
+        cliArgs.push("-n", String(args.limit));
+    const stdout = await runFenfindScript("fenfind", cliArgs);
+    return parseFenfindJson("fenfind", stdout);
+}
+export async function readCourseAtPosition(args) {
+    if (!FENFIND_DIR) {
+        return {
+            status: "not_available",
+            note: "fenfind index not installed on this server. Set FENFIND_PATH env var to the directory containing the `fenfind`/`readpgn` scripts and positions.db.",
+        };
+    }
+    const fileId = typeof args.course_file_id === "number" ? args.course_file_id : Number(args.course_file_id);
+    if (!Number.isFinite(fileId) || fileId <= 0) {
+        throw new Error("`course_file_id` is required — pass the value from a find_position_in_courses hit");
+    }
+    const cliArgs = ["--file-id", String(fileId)];
+    if (typeof args.fen === "string" && args.fen.trim() !== "")
+        cliArgs.push("--fen", args.fen.trim());
+    if (typeof args.moves === "string" && args.moves.trim() !== "")
+        cliArgs.push("--moves", args.moves.trim());
+    if (typeof args.chapter === "string" && args.chapter.trim() !== "")
+        cliArgs.push("--chapter", args.chapter.trim());
+    if (typeof args.max_plies_below === "number")
+        cliArgs.push("--max-plies-below", String(args.max_plies_below));
+    const stdout = await runFenfindScript("readpgn", cliArgs);
+    return parseFenfindJson("readpgn", stdout);
+}

package/dist/http.js

@@ -0,0 +1,150 @@
+// HTTP + PGN I/O layer for chessceo-mcp. Auth resolution, raw
+// `authedRequest` / `get`, response envelope helpers, and the
+// small typed wrappers every prep-file tool composes over
+// (`fetchGame` / `saveGame` / `createGame` / `deleteGame` /
+// `restoreGame`).
+//
+// Two auth flavours coexist:
+//   - Anonymous GETs (players, positions, prep, live) — no auth.
+//   - Authed tools (cloud engines, prep files) — `Authorization: Bearer mcp_...`.
+//
+// The token comes from one of two sources:
+//   - stdio: `CHESSCEO_TOKEN` env var, set by the MCP host config. Bare
+//     `mcp_...` — we prepend the `Bearer ` scheme when building the header.
+//   - streamable-http: the caller's `Authorization` header, forwarded
+//     per-request via AsyncLocalStorage so tool handlers can see it even
+//     though the MCP SDK's request handler doesn't know about HTTP.
+//
+// LLM-facing "prep file id" is always "<collection_id>:<game_id>" —
+// `makeFileId` to compose from a listing, `splitFileId` at the HTTP edge.
+// This is what makes every prep-file tool keep taking a single `id`
+// argument despite the backend paths needing both pieces.
+import { AsyncLocalStorage } from "node:async_hooks";
+const BASE = process.env.CHESSCEO_BASE_URL ?? "https://chess.ceo";
+const UA = `chessceo-mcp/${process.env.npm_package_version ?? "0.1.0"} (+https://chess.ceo)`;
+export const PGN_BASE = "/api/agent/pgns";
+// Streamable-HTTP transport binds the caller's Authorization header
+// into this context so per-request tool handlers can pick it up.
+// Stdio callers don't set this — they hit the env-var branch below.
+export const authContext = new AsyncLocalStorage();
+export function resolveAuthHeader() {
+    const store = authContext.getStore();
+    if (store?.authHeader)
+        return store.authHeader;
+    const env = process.env.CHESSCEO_TOKEN?.trim();
+    if (!env)
+        return undefined;
+    return env.toLowerCase().startsWith("bearer ") ? env : `Bearer ${env}`;
+}
+export async function get(path, params) {
+    const url = new URL(path, BASE);
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== null && v !== "")
+            url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url, { headers: { "User-Agent": UA, "Accept": "application/json" } });
+    if (!res.ok) {
+        // Bubble up the ProblemDetail body when the API returns one — LLM can
+        // then correct the query (e.g. wrong fideId) rather than retry blind.
+        let body;
+        try {
+            body = await res.text();
+        }
+        catch {
+            body = "";
+        }
+        throw new Error(`chess.ceo ${res.status}: ${body.slice(0, 500)}`);
+    }
+    return res.json();
+}
+// authedRequest is the shared code path for POST/GET/DELETE calls that need
+// an MCP token. Missing-token errors are surfaced early with a message the
+// LLM can act on (either configure CHESSCEO_TOKEN or generate a token in
+// user settings) rather than a generic 401 from the backend.
+export async function authedRequest(method, path, body) {
+    const auth = resolveAuthHeader();
+    if (!auth) {
+        throw new Error("No MCP token available. Set CHESSCEO_TOKEN env (stdio mode) or pass an " +
+            "Authorization: Bearer mcp_... header (streamable-http mode). Generate " +
+            "a token at chess.ceo → user settings → MCP tokens.");
+    }
+    const url = new URL(path, BASE);
+    const headers = {
+        "User-Agent": UA,
+        "Accept": "application/json",
+        "Authorization": auth,
+    };
+    const init = { method, headers };
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    if (res.status === 204)
+        return null;
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`chess.ceo ${res.status}: ${text.slice(0, 500)}`);
+    }
+    return text.length ? JSON.parse(text) : null;
+}
+// Browser handlers wrap successful responses as
+//   { success: true, message: "...", data: <actual thing> }
+// via handlers.RespondSuccess. Peel that off; leave anything without
+// the envelope unchanged (some endpoints return raw bodies).
+export function unwrap(raw) {
+    if (raw &&
+        typeof raw === "object" &&
+        "data" in raw &&
+        raw.success === true) {
+        return raw.data;
+    }
+    return raw;
+}
+export function makeFileId(collectionId, gameId) {
+    return `${collectionId}:${gameId}`;
+}
+export function splitFileId(id) {
+    const idx = id.indexOf(":");
+    if (idx <= 0 || idx === id.length - 1) {
+        throw new Error(`invalid prep file id "${id}" — expected "<collection_id>:<game_id>" ` +
+            `(get one from list_prep_files, search_prep_files, find_position_in_files, ` +
+            `or the create_prep_file return value)`);
+    }
+    return { collectionId: id.slice(0, idx), gameId: id.slice(idx + 1) };
+}
+// GET one game by composite id. Throws on 404.
+export async function fetchGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    const raw = await authedRequest("GET", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+    const g = unwrap(raw);
+    if (!g || typeof g.pgnContent !== "string") {
+        throw new Error("prep file missing pgnContent");
+    }
+    return g;
+}
+// PUT the game body. Returns the saved game (new version).
+export async function saveGame(id, pgn, expectedVersion) {
+    const { collectionId, gameId } = splitFileId(id);
+    const body = { pgnContent: pgn };
+    if (typeof expectedVersion === "number")
+        body.baseVersion = expectedVersion;
+    const raw = await authedRequest("PUT", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`, body);
+    return unwrap(raw);
+}
+// POST a new game into the given collection. Returns the created game.
+export async function createGame(collectionId, pgn) {
+    const raw = await authedRequest("POST", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games`, { pgnContent: pgn });
+    return unwrap(raw);
+}
+// DELETE (soft) a game by composite id.
+export async function deleteGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    await authedRequest("DELETE", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}`);
+}
+// Restore a previously soft-deleted game. Symmetric with deleteGame.
+export async function restoreGame(id) {
+    const { collectionId, gameId } = splitFileId(id);
+    const raw = await authedRequest("POST", `${PGN_BASE}/${encodeURIComponent(collectionId)}/games/${encodeURIComponent(gameId)}/restore`);
+    return unwrap(raw);
+}