@chessceo/mcp 0.44.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);
+}