sbox-mcp-server 1.3.2 → 1.5.0

package/dist/tools/diagnostics.js

@@ -0,0 +1,325 @@
+import { z } from "zod";
+import { existsSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+/**
+ * Diagnostic tools (Batch 24 — "let Claude see its own errors"): read s&box's
+ * editor log so Claude can check compile errors, exceptions, and Log.Info
+ * output directly — instead of flying blind or relying on the user to relay
+ * them.
+ *
+ * Deliberately reads the log FILE on the Node side (not over the bridge IPC),
+ * so it works even when the s&box editor has crashed and the bridge is down —
+ * which is exactly when you need the log most.
+ *
+ * Log path resolution:
+ *   1. SBOX_LOG_PATH env var (explicit override — use this on macOS/Linux or
+ *      non-Steam installs).
+ *   2. Windows Steam auto-detect: parse steamapps/libraryfolders.vdf for each
+ *      library, look for steamapps/common/sbox/logs/sbox-dev.log, pick newest.
+ */
+function locateSboxLog() {
+    const tried = [];
+    const env = process.env.SBOX_LOG_PATH;
+    if (env) {
+        tried.push(env);
+        if (existsSync(env))
+            return { path: env, tried };
+    }
+    if (process.platform === "win32") {
+        const steamRoots = [
+            "C:\\Program Files (x86)\\Steam",
+            "C:\\Program Files\\Steam",
+        ];
+        const libs = [];
+        for (const steam of steamRoots) {
+            const vdf = join(steam, "steamapps", "libraryfolders.vdf");
+            if (existsSync(vdf)) {
+                libs.push(steam);
+                try {
+                    const txt = readFileSync(vdf, "utf-8");
+                    for (const m of txt.matchAll(/"path"\s+"([^"]+)"/g)) {
+                        libs.push(m[1].replace(/\\\\/g, "\\"));
+                    }
+                }
+                catch {
+                    /* ignore unreadable vdf */
+                }
+            }
+        }
+        const candidates = [];
+        for (const lib of libs) {
+            const p = join(lib, "steamapps", "common", "sbox", "logs", "sbox-dev.log");
+            tried.push(p);
+            if (existsSync(p))
+                candidates.push(p);
+        }
+        if (candidates.length > 0) {
+            candidates.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+            return { path: candidates[0], tried };
+        }
+    }
+    return { path: null, tried };
+}
+function tailLines(text, n) {
+    const lines = text.split(/\r?\n/);
+    return lines.slice(Math.max(0, lines.length - n));
+}
+export function registerDiagnosticTools(server, bridge) {
+    // ── read_log ───────────────────────────────────────────────────────
+    server.tool("read_log", "Read s&box's editor log (sbox-dev.log) so Claude can see compile errors, exceptions, and Log.Info output directly. Reads the log file (not via the bridge), so it works even when the editor has crashed. If auto-detection fails (non-Windows / non-Steam install), set the SBOX_LOG_PATH environment variable to the full log path.", {
+        lines: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many lines from the end to return (default 80, max 1000)"),
+        filter: z
+            .string()
+            .optional()
+            .describe("Only return lines containing this substring (case-insensitive)"),
+    }, async (params) => {
+        const { path, tried } = locateSboxLog();
+        if (!path) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't locate sbox-dev.log. Set the SBOX_LOG_PATH environment variable to its full path.\nTried:\n" +
+                            tried.join("\n"),
+                    },
+                ],
+            };
+        }
+        let n = params.lines ?? 80;
+        if (n < 1)
+            n = 1;
+        if (n > 1000)
+            n = 1000;
+        let text;
+        try {
+            text = readFileSync(path, "utf-8");
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: `Error reading ${path}: ${e.message}` }],
+            };
+        }
+        let out = tailLines(text, n);
+        if (params.filter) {
+            const f = params.filter.toLowerCase();
+            out = out.filter((l) => l.toLowerCase().includes(f));
+        }
+        const header = `# ${path}\n# last ${n} lines${params.filter ? ` · filter "${params.filter}"` : ""}\n\n`;
+        return { content: [{ type: "text", text: header + out.join("\n") }] };
+    });
+    // ── get_compile_errors ─────────────────────────────────────────────
+    server.tool("get_compile_errors", "Scan the recent s&box log for compile errors and exceptions — the fast way for Claude to confirm whether its last script/addon edit actually compiled. Reads sbox-dev.log directly (works even if the editor is mid-crash). Returns the matching lines, or an all-clear.", {
+        lines: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many lines from the end to scan (default 400, max 4000)"),
+    }, async (params) => {
+        const { path } = locateSboxLog();
+        if (!path) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't locate sbox-dev.log. Set the SBOX_LOG_PATH environment variable.",
+                    },
+                ],
+            };
+        }
+        let n = params.lines ?? 400;
+        if (n < 1)
+            n = 1;
+        if (n > 4000)
+            n = 4000;
+        let text;
+        try {
+            text = readFileSync(path, "utf-8");
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: `Error reading ${path}: ${e.message}` }],
+            };
+        }
+        const recent = tailLines(text, n);
+        const re = /(error CS\d+|Compile of .* Failed|Exception|Couldn't add project|Broken Reference|StackTrace|^\s*at Sandbox\.)/i;
+        const hits = recent.filter((l) => re.test(l));
+        if (hits.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No compile errors or exceptions in the last ${n} log lines — looks clean.\n(${path})`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Found ${hits.length} error/exception line(s) in the last ${n} log lines:\n\n${hits.join("\n")}`,
+                },
+            ],
+        };
+    });
+    // ── frame_camera ─────────────────────────────────────────────────── (bridge)
+    server.tool("frame_camera", "Aim the s&box EDITOR viewport camera at a GameObject (by id) or a world point (position + optional radius), then call take_screenshot to capture that view. This is how Claude points its own screenshots at what it's working on — frame a spawned object, then screenshot to verify it actually looks right.", {
+        id: z.string().optional().describe("GUID of a GameObject to frame on"),
+        position: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("World point to frame on (use instead of id)"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Frame radius around the position, in units (default 128)"),
+    }, async (params) => {
+        const res = await bridge.send("frame_camera", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── screenshot_from ──────────────────────────────────────────────── (bridge)
+    server.tool("screenshot_from", "Take a screenshot from a chosen angle. take_screenshot is locked to the scene's main camera; this temporarily moves that camera to frame your target, captures, then restores it — so Claude can finally AIM its own screenshots. Pass id (frame an object) OR position {x,y,z} with optional lookAt {x,y,z} or rotation {pitch,yaw,roll}. After it returns, read the newest PNG in the editor's screenshots folder.", {
+        id: z.string().optional().describe("GUID of a GameObject to frame"),
+        position: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("Camera world position (use instead of id)"),
+        lookAt: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("World point to look at (pair with position)"),
+        rotation: z
+            .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+            .optional()
+            .describe("Explicit camera rotation (pair with position)"),
+        width: z.number().int().optional().describe("Screenshot width (default 1920)"),
+        height: z.number().int().optional().describe("Screenshot height (default 1080)"),
+    }, async (params) => {
+        const res = await bridge.send("screenshot_from", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── console_run ──────────────────────────────────────────────────── (bridge)
+    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp.", {
+        command: z.string().describe("The console command line to run"),
+    }, async (params) => {
+        const res = await bridge.send("console_run", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── execute_csharp ───────────────────────────────────────────────── (orchestrated)
+    let execCounter = 0;
+    server.tool("execute_csharp", "EXPERIMENTAL. Compile + run a C# snippet inside the s&box EDITOR (which is unsandboxed): writes a temp [ConCmd] into the project's Editor/ folder, hotloads, runs it, reads the result/exception from the log, then deletes the temp file. With expression:true, returns the JSON value of a single expression; otherwise runs statements. CAVEATS: each call triggers a hotload (~2-8s) and recompiles the project's editor assembly; a snippet that fails to compile is reported + cleaned up, but briefly taints the editor assembly until cleanup.", {
+        code: z
+            .string()
+            .describe("C# to run (editor-context, unsandboxed). With expression:true, a single expression; otherwise statements."),
+        expression: z
+            .boolean()
+            .optional()
+            .describe("Treat code as an expression and return its JSON value (default false)"),
+        timeoutMs: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max wait for compile + run, ms (default 20000)"),
+    }, async (params) => {
+        const id = `${Date.now().toString(36)}${++execCounter}`;
+        const cmd = `claude_exec_${id}`;
+        const filePath = `Editor/__Exec_${id}.cs`;
+        const marker = `[EXEC ${id}]`;
+        const inner = params.expression
+            ? `var __r = (${params.code});\n\t\t\tSandbox.Log.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
+            : `${params.code}\n\t\t\tSandbox.Log.Info( "${marker} DONE" );`;
+        const cs = `using Editor;\nusing Sandbox;\nusing System;\n\n` +
+            `public static class __Exec_${id}\n{\n` +
+            `\t[ConCmd( "${cmd}" )]\n\tpublic static void Run()\n\t{\n` +
+            `\t\ttry\n\t\t{\n\t\t\t${inner}\n\t\t}\n` +
+            `\t\tcatch ( System.Exception __e ) { Sandbox.Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
+            `\t}\n}\n`;
+        const timeout = params.timeoutMs ?? 20000;
+        const wr = await bridge.send("write_file", { path: filePath, content: cs });
+        if (!wr.success) {
+            return { content: [{ type: "text", text: `execute_csharp: failed to write temp file: ${wr.error}` }] };
+        }
+        await bridge.send("trigger_hotload", {});
+        const { path: logPath } = locateSboxLog();
+        const startedAt = Date.now();
+        let found = null;
+        let compileErr = null;
+        while (Date.now() - startedAt < timeout) {
+            await new Promise((r) => setTimeout(r, 1500));
+            await bridge.send("console_run", { command: cmd });
+            if (logPath) {
+                try {
+                    const txt = readFileSync(logPath, "utf-8");
+                    const tail = txt.slice(Math.max(0, txt.length - 30000));
+                    const mi = tail.lastIndexOf(marker);
+                    if (mi >= 0) {
+                        found = tail.slice(mi).split(/\r?\n/)[0];
+                        break;
+                    }
+                    if (/__Exec_/.test(tail) && /(error CS\d+|Compile of .* Failed)/i.test(tail)) {
+                        const errs = tail.split(/\r?\n/).filter((l) => /error CS\d+/i.test(l)).slice(-6).join("\n");
+                        if (errs) {
+                            compileErr = errs;
+                            break;
+                        }
+                    }
+                }
+                catch {
+                    /* log not ready yet */
+                }
+            }
+        }
+        // cleanup: remove the temp file + hotload back to a clean assembly
+        try {
+            await bridge.send("delete_script", { path: filePath });
+        }
+        catch {
+            /* best effort */
+        }
+        try {
+            await bridge.send("trigger_hotload", {});
+        }
+        catch {
+            /* best effort */
+        }
+        if (compileErr) {
+            return { content: [{ type: "text", text: `execute_csharp: compile error —\n${compileErr}` }] };
+        }
+        if (found) {
+            let out = found;
+            if (found.includes("RESULT="))
+                out = "RESULT = " + found.split("RESULT=")[1].trim();
+            else if (found.includes("ERROR="))
+                out = "Runtime exception: " + found.split("ERROR=")[1].trim();
+            else if (found.includes("DONE"))
+                out = "Executed (no return value).";
+            return { content: [{ type: "text", text: `execute_csharp ${id}: ${out}` }] };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `execute_csharp ${id}: no result captured within ${timeout}ms — the snippet may still be compiling, or the log marker wasn't found. Try read_log with filter "${marker}".`,
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/tools/docs.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerDocsTools(server: McpServer, _bridge: BridgeClient): void;
+//# sourceMappingURL=docs.d.ts.map

package/dist/tools/docs.js

@@ -0,0 +1,334 @@
+import { z } from "zod";
+/**
+ * Documentation tools (Batch 25 — "let Claude read the real s&box docs"): search
+ * and fetch the official s&box guide documentation so Claude can ground itself in
+ * Facepunch's own pages instead of guessing from possibly-stale training data.
+ *
+ * The s&box guide docs live in the PUBLIC GitHub repo Facepunch/sbox-docs
+ * (branch master): ~225 Markdown pages under docs/<category>/.../<page>.md, each
+ * starting with YAML frontmatter (title, icon, created, updated).
+ *
+ * Two HTTP sources, both fetched with Node 18+ built-in fetch (no npm deps):
+ *   1. INDEX (once, cached in memory): the GitHub git-tree API lists every file
+ *      in the repo. Requires a User-Agent header or GitHub returns 403. Honors an
+ *      optional GITHUB_TOKEN env var for a higher rate limit (never required).
+ *   2. PAGE CONTENT: raw.githubusercontent.com serves the Markdown as text/plain
+ *      with no rate limit and no UA needed.
+ *
+ * Per page we derive:
+ *   - category: the 2nd path segment (docs/networking/rpcs.md -> "networking")
+ *   - slug:     the path with leading "docs/" and trailing ".md" removed
+ *   - webUrl:   https://sbox.game/dev/doc/<slug> (a trailing "/index" is stripped)
+ *
+ * All three tools are read-only and never throw — fetch failures are caught and
+ * surfaced as a plain text error in the tool result.
+ */
+/** GitHub git-tree API for the docs repo (lists every file, recursive). */
+const TREE_URL = "https://api.github.com/repos/Facepunch/sbox-docs/git/trees/master?recursive=1";
+/** Base for raw Markdown page content (text/plain, no rate limit). */
+const RAW_BASE = "https://raw.githubusercontent.com/Facepunch/sbox-docs/master/";
+/** Public web home for a rendered doc page. */
+const WEB_BASE = "https://sbox.game/dev/doc/";
+/** Module-level cache so the index is fetched at most once per ~30 min. */
+let indexCache = null;
+let indexFetchedAt = 0;
+/** Re-fetch the index if it is older than this (handles long-lived processes). */
+const INDEX_TTL_MS = 30 * 60 * 1000;
+/** Compute slug/category/webUrl for a repo-relative docs path. */
+function buildEntry(path) {
+    // "docs/networking/rpcs.md" -> "networking/rpcs"
+    const slug = path.replace(/^docs\//, "").replace(/\.md$/i, "");
+    const segments = path.split("/");
+    // path[0] is "docs"; the category is the next segment (if any).
+    const category = segments.length > 2 ? segments[1] : "";
+    // A trailing "/index" doesn't appear in the public web URL.
+    const webSlug = slug.replace(/\/index$/i, "");
+    return { path, slug, category, webUrl: WEB_BASE + webSlug };
+}
+/**
+ * Ensure the doc index is loaded (fetching + building it once), reusing the
+ * module-level cache. Returns null on any fetch/parse failure so callers can
+ * report a clean error. Never throws.
+ */
+async function getIndex() {
+    const now = Date.now();
+    if (indexCache && now - indexFetchedAt < INDEX_TTL_MS) {
+        return indexCache;
+    }
+    try {
+        const headers = {
+            // GitHub API rejects requests without a User-Agent (403).
+            "User-Agent": "sbox-mcp-server",
+            Accept: "application/vnd.github+json",
+        };
+        const token = process.env.GITHUB_TOKEN;
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        const res = await fetch(TREE_URL, { headers });
+        if (!res.ok) {
+            return null;
+        }
+        const json = await res.json();
+        const tree = Array.isArray(json?.tree) ? json.tree : [];
+        const entries = [];
+        for (const node of tree) {
+            const p = node?.path ?? "";
+            // Keep only Markdown pages under docs/.
+            if (node?.type === "blob" &&
+                p.startsWith("docs/") &&
+                /\.md$/i.test(p)) {
+                entries.push(buildEntry(p));
+            }
+        }
+        if (entries.length === 0) {
+            // Empty tree almost certainly means an API hiccup, not a real result.
+            return null;
+        }
+        indexCache = entries;
+        indexFetchedAt = now;
+        return indexCache;
+    }
+    catch {
+        return null;
+    }
+}
+/** Tokenize a query into lowercased, non-empty words. */
+function tokenize(s) {
+    return s
+        .toLowerCase()
+        .split(/[^a-z0-9]+/i)
+        .filter((t) => t.length > 0);
+}
+/** Strip the leading YAML frontmatter block from a Markdown document. */
+function stripFrontmatter(md) {
+    return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+}
+/** Pull the `title:` value out of YAML frontmatter, if present. */
+function parseTitle(md) {
+    const fm = md.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    if (!fm)
+        return null;
+    const line = fm[1].match(/^\s*title\s*:\s*(.+?)\s*$/m);
+    if (!line)
+        return null;
+    // Drop surrounding quotes if the title was quoted.
+    return line[1].replace(/^["']|["']$/g, "").trim() || null;
+}
+/** Derive a human title for an entry without fetching its content. */
+function titleFromSlug(slug) {
+    const last = slug.split("/").pop() ?? slug;
+    return last.replace(/[-_]/g, " ");
+}
+export function registerDocsTools(server, _bridge) {
+    // ── search_docs ────────────────────────────────────────────────────
+    server.tool("search_docs", "Search the official s&box guide documentation (the Facepunch/sbox-docs pages rendered at sbox.game/dev/doc) by keyword. Returns the best-matching pages with their title, category, slug, and web URL — use the slug with get_doc_page to read one. The s&box API changes between SDK versions, so prefer these real docs over guessing. Read-only.", {
+        query: z
+            .string()
+            .describe("Keywords to match against page titles, slugs, and paths"),
+        category: z
+            .string()
+            .optional()
+            .describe('Optional category filter (the 2nd path segment, e.g. "networking", "ui"). Use list_doc_categories to see them.'),
+        limit: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max results to return (default 10, max 50)"),
+    }, async (params) => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        let limit = params.limit ?? 10;
+        if (limit < 1)
+            limit = 1;
+        if (limit > 50)
+            limit = 50;
+        const cat = params.category?.toLowerCase().trim();
+        let pages = index;
+        if (cat) {
+            pages = pages.filter((p) => p.category.toLowerCase() === cat);
+        }
+        const tokens = tokenize(params.query);
+        const scored = pages
+            .map((p) => {
+            const title = titleFromSlug(p.slug).toLowerCase();
+            const slug = p.slug.toLowerCase();
+            const path = p.path.toLowerCase();
+            let score = 0;
+            for (const t of tokens) {
+                // Title and slug are the strongest signals; path is a weak fallback.
+                if (title.includes(t))
+                    score += 5;
+                if (slug.includes(t))
+                    score += 4;
+                if (path.includes(t))
+                    score += 1;
+            }
+            return { p, score };
+        })
+            .filter((s) => s.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        if (scored.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No s&box docs matched "${params.query}"${cat ? ` in category "${params.category}"` : ""}. Try broader keywords, or call list_doc_categories.`,
+                    },
+                ],
+            };
+        }
+        const results = scored.map(({ p }) => ({
+            title: titleFromSlug(p.slug),
+            category: p.category,
+            slug: p.slug,
+            webUrl: p.webUrl,
+        }));
+        return {
+            content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+    });
+    // ── get_doc_page ───────────────────────────────────────────────────
+    server.tool("get_doc_page", "Fetch the full Markdown of one s&box guide page (from search_docs). Pass a slug like \"networking/rpcs\", a raw repo path like \"docs/networking/rpcs.md\", or a full sbox.game/dev/doc URL. YAML frontmatter is stripped. Long pages are paginated: pass chunk to read further (the footer tells you when there's more). Read-only.", {
+        slug: z
+            .string()
+            .describe('Page slug (e.g. "networking/rpcs"), a "docs/...md" path, or a full sbox.game/dev/doc URL'),
+        chunk: z
+            .number()
+            .int()
+            .optional()
+            .describe("1-based chunk index for long pages (default 1)"),
+        chunkSize: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max characters per chunk (default 8000)"),
+    }, async (params) => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        // Normalize the input into a slug: accept a full web URL, a raw repo path,
+        // or a bare slug.
+        let raw = params.slug.trim();
+        if (raw.startsWith("http")) {
+            const idx = raw.indexOf("/dev/doc/");
+            if (idx >= 0)
+                raw = raw.slice(idx + "/dev/doc/".length);
+        }
+        // Strip a leading "docs/" and a trailing ".md" if a path was passed.
+        const wanted = raw
+            .replace(/^\/+/, "")
+            .replace(/^docs\//, "")
+            .replace(/\.md$/i, "")
+            .replace(/\/+$/, "");
+        // Resolve against the index: exact slug, then a slug that points at the
+        // page's index file (e.g. "networking" -> "networking/index").
+        const entry = index.find((p) => p.slug.toLowerCase() === wanted.toLowerCase()) ??
+            index.find((p) => p.slug.toLowerCase() === `${wanted.toLowerCase()}/index`);
+        if (!entry) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: no s&box doc page matched "${params.slug}". Use search_docs to find a valid slug.`,
+                    },
+                ],
+            };
+        }
+        let md;
+        try {
+            const res = await fetch(RAW_BASE + entry.path);
+            if (!res.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Error: failed to fetch ${entry.path} (HTTP ${res.status}).`,
+                        },
+                    ],
+                };
+            }
+            md = await res.text();
+        }
+        catch (e) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error fetching ${entry.path}: ${e.message}`,
+                    },
+                ],
+            };
+        }
+        const title = parseTitle(md) ?? titleFromSlug(entry.slug);
+        const body = stripFrontmatter(md);
+        const header = `# ${title}\nSource: ${entry.webUrl}\n\n`;
+        let chunkSize = params.chunkSize ?? 8000;
+        if (chunkSize < 500)
+            chunkSize = 500;
+        // Short pages: return the whole body in one shot.
+        if (body.length <= chunkSize) {
+            return { content: [{ type: "text", text: header + body }] };
+        }
+        // Long pages: slice into chunks and return the requested 1-based chunk.
+        const total = Math.ceil(body.length / chunkSize);
+        let i = params.chunk ?? 1;
+        if (i < 1)
+            i = 1;
+        if (i > total)
+            i = total;
+        const start = (i - 1) * chunkSize;
+        const slice = body.slice(start, start + chunkSize);
+        let footer = `\n\n— chunk ${i}/${total}`;
+        if (i < total) {
+            footer += `; call get_doc_page again with chunk=${i + 1} for more —`;
+        }
+        else {
+            footer += " (end) —";
+        }
+        return { content: [{ type: "text", text: header + slice + footer }] };
+    });
+    // ── list_doc_categories ────────────────────────────────────────────
+    server.tool("list_doc_categories", "List the categories of the official s&box guide documentation, with how many pages each has. Use a category name to filter search_docs. Read-only.", {}, async () => {
+        const index = await getIndex();
+        if (!index) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: couldn't load the s&box docs index from GitHub (network error or rate limit). Try again shortly; set the GITHUB_TOKEN environment variable to raise the rate limit.",
+                    },
+                ],
+            };
+        }
+        const counts = new Map();
+        for (const p of index) {
+            const key = p.category || "(root)";
+            counts.set(key, (counts.get(key) ?? 0) + 1);
+        }
+        const result = Array.from(counts.entries())
+            .map(([category, pageCount]) => ({ category, pageCount }))
+            .sort((a, b) => b.pageCount - a.pageCount);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=docs.js.map

package/dist/tools/leveltools.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerLevelTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=leveltools.d.ts.map