breakpoint-mcp 1.4.0 → 1.4.1

package/README.md

@@ -30,7 +30,9 @@ npx breakpoint-mcp doctor
 
 `init` copies the addon into `addons/breakpoint_mcp/`, enables it in `project.godot`, and
 prints — or, with `--client claude-code|claude-desktop|cursor|windsurf|vscode`, writes —
-the client config. `doctor` checks the Godot binary, the addon, and the four bridges
+the client config. By default it uses the addon bundled in this package; add
+`--from-github [ref]` to fetch the addon from GitHub instead (e.g. `--from-github main`).
+`doctor` checks the Godot binary, the addon, and the four bridges
 (add `--require-live` once the editor is open; `--json` for a machine-readable report).
 
 To install the `breakpoint-mcp` command globally instead of invoking it via `npx`:

package/dist/cli/github.js

@@ -0,0 +1,97 @@
+/**
+ * `--from-github` escape hatch for `breakpoint-mcp init`: fetch the editor addon
+ * (addons/breakpoint_mcp/**) straight from the GitHub repo at a chosen ref, as an
+ * alternative to the copy bundled in the npm tarball. Used when the bundled addon
+ * is missing/corrupt, or to install a different ref (e.g. `main`, or an older tag)
+ * than the one that shipped with the installed package.
+ *
+ * Dependency-free: one GitHub git/trees API call lists the addon's blobs at the ref,
+ * then each file is downloaded from raw.githubusercontent.com (a CDN that does not
+ * count against the REST rate limit). The fetch-shaped dependency is injectable, so
+ * the whole path is unit-testable offline.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const DEFAULT_REPO = "jlivingston-Cipher/godot-breakpoint-mcp";
+const ADDON_PREFIX = "addons/breakpoint_mcp/";
+const USER_AGENT = "breakpoint-mcp-cli";
+function defaultFetch() {
+    const f = globalThis.fetch;
+    if (typeof f !== "function") {
+        throw new Error("global fetch is unavailable — Node 18+ is required for --from-github.");
+    }
+    return f;
+}
+/** Validate and split an `owner/repo` slug; throws on anything else. */
+export function parseRepo(repo) {
+    const m = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/.exec(repo.trim());
+    if (!m)
+        throw new Error(`invalid --repo '${repo}' (expected owner/repo).`);
+    return { owner: m[1], name: m[2] };
+}
+function authHeaders() {
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    const h = { "User-Agent": USER_AGENT };
+    if (token)
+        h.Authorization = `Bearer ${token}`;
+    return h;
+}
+/**
+ * Fetch addons/breakpoint_mcp/** from `repo` at `ref` into `dest` (created if
+ * needed). Returns the written relative paths. Throws a clear Error on a bad
+ * repo/ref, a missing addon, rate-limiting, or a network failure.
+ */
+export async function fetchAddonFromGitHub(opts, fetchFn) {
+    const doFetch = fetchFn ?? defaultFetch();
+    const { owner, name } = parseRepo(opts.repo);
+    const ref = opts.ref;
+    const treeUrl = `https://api.github.com/repos/${owner}/${name}/git/trees/${ref}?recursive=1`;
+    let treeRes;
+    try {
+        treeRes = await doFetch(treeUrl, {
+            headers: { ...authHeaders(), Accept: "application/vnd.github+json" },
+        });
+    }
+    catch (err) {
+        throw new Error(`could not reach GitHub: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (treeRes.status === 404) {
+        throw new Error(`GitHub returned 404 for ${owner}/${name}@${ref} — check the repo and ref.`);
+    }
+    if (treeRes.status === 403) {
+        throw new Error("GitHub returned 403 (rate-limited or forbidden). Set GITHUB_TOKEN to raise the limit, or retry later.");
+    }
+    if (!treeRes.ok) {
+        throw new Error(`GitHub git/trees request failed (HTTP ${treeRes.status}).`);
+    }
+    const body = (await treeRes.json());
+    if (body.truncated) {
+        throw new Error(`the repository tree at ${ref} was too large to list in one request; --from-github can't be used for this ref.`);
+    }
+    const entries = Array.isArray(body.tree) ? body.tree : [];
+    const files = entries.filter((e) => e.type === "blob" && e.path.startsWith(ADDON_PREFIX));
+    if (files.length === 0) {
+        throw new Error(`no ${ADDON_PREFIX} found in ${owner}/${name}@${ref}.`);
+    }
+    const written = [];
+    for (const f of files) {
+        const rawUrl = `https://raw.githubusercontent.com/${owner}/${name}/${ref}/${f.path}`;
+        let res;
+        try {
+            res = await doFetch(rawUrl, { headers: { "User-Agent": USER_AGENT } });
+        }
+        catch (err) {
+            throw new Error(`could not download ${f.path}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (!res.ok) {
+            throw new Error(`could not download ${f.path} (HTTP ${res.status}).`);
+        }
+        const rel = f.path.slice(ADDON_PREFIX.length);
+        const outPath = path.join(opts.dest, rel);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        fs.writeFileSync(outPath, Buffer.from(await res.arrayBuffer()));
+        written.push(rel);
+    }
+    return written;
+}
+//# sourceMappingURL=github.js.map

package/dist/cli/init.js

@@ -9,10 +9,12 @@
  * it into that client's config file (see clients.ts for the id list + paths).
  */
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
+import { DEFAULT_REPO, fetchAddonFromGitHub } from "./github.js";
 const PLUGIN_REL = "addons/breakpoint_mcp";
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 const SERVER_NAME = "godot";
@@ -39,6 +41,23 @@ export function resolveBundledAddon() {
     }
     return null;
 }
+/** This package's own version, read from its package.json (null if unreadable). */
+function packageVersion() {
+    try {
+        const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", ".."); // dist/cli -> pkg
+        const v = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"))
+            .version;
+        return typeof v === "string" ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Default ref for --from-github: this package's version tag (vX.Y.Z), else main. */
+function defaultGitHubRef() {
+    const v = packageVersion();
+    return v ? `v${v}` : "main";
+}
 /**
  * Add `res://addons/breakpoint_mcp/plugin.cfg` to project.godot's
  * `[editor_plugins] enabled=PackedStringArray(...)`, creating the section or the
@@ -102,7 +121,7 @@ function claudeCodeCommand(projectPath) {
     return `claude mcp add godot --env GODOT_PROJECT=${projectPath} -- npx -y breakpoint-mcp`;
 }
 /** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
-export async function runInit(argv) {
+export async function runInit(argv, deps = {}) {
     const { flags } = parseArgs(argv, ["force", "dry-run"]);
     const projectPath = typeof flags.project === "string"
         ? path.resolve(flags.project)
@@ -111,30 +130,69 @@ export async function runInit(argv) {
     const force = flags.force === true;
     const client = typeof flags.client === "string" ? flags.client : "none";
     const godotBin = process.env.GODOT_BIN ?? "godot";
+    // --from-github [ref]: source the addon from GitHub instead of the bundled copy.
+    const fromGitHub = "from-github" in flags;
+    const fgVal = flags["from-github"];
+    const ref = typeof fgVal === "string" && fgVal.length > 0 ? fgVal : defaultGitHubRef();
+    const repo = typeof flags.repo === "string" && flags.repo.length > 0 ? flags.repo : DEFAULT_REPO;
     const projGodot = path.join(projectPath, "project.godot");
     if (!fs.existsSync(projGodot)) {
         process.stderr.write(`init: no project.godot at ${projectPath}\n` +
             "  Pass --project <dir> pointing at your Godot project (the folder with project.godot).\n");
         return 1;
     }
-    const addonSource = resolveBundledAddon();
-    if (!addonSource) {
-        process.stderr.write("init: could not locate the bundled editor addon inside the package.\n");
-        return 1;
-    }
     const out = [];
     const say = (s = "") => {
         out.push(s);
     };
     say(`Project: ${projectPath}${dryRun ? "  (dry run — no changes written)" : ""}`);
+    // Resolve the addon source: the bundled copy, or (--from-github) a temp dir
+    // fetched from GitHub. The temp dir is removed once the addon is installed.
+    let addonSource = null;
+    let tmpFetchDir = null;
+    if (fromGitHub) {
+        if (dryRun) {
+            say(`  addon source: would fetch ${repo}@${ref} from GitHub`);
+        }
+        else {
+            say(`  addon source: fetching ${repo}@${ref} from GitHub…`);
+            tmpFetchDir = fs.mkdtempSync(path.join(os.tmpdir(), "bpmcp-gh-"));
+            try {
+                const written = await fetchAddonFromGitHub({ repo, ref, dest: tmpFetchDir }, deps.fetchFn);
+                say(`  addon source: fetched ${written.length} file(s) from ${repo}@${ref}`);
+                addonSource = tmpFetchDir;
+            }
+            catch (err) {
+                fs.rmSync(tmpFetchDir, { recursive: true, force: true });
+                process.stderr.write(`init: --from-github failed: ${err instanceof Error ? err.message : String(err)}\n` +
+                    "  Omit --from-github to install the addon bundled with this package.\n");
+                return 1;
+            }
+        }
+    }
+    else {
+        addonSource = resolveBundledAddon();
+        if (!addonSource) {
+            process.stderr.write("init: could not locate the bundled editor addon inside the package.\n" +
+                "  Reinstall breakpoint-mcp, or pass --from-github to fetch the addon from GitHub.\n");
+            return 1;
+        }
+    }
     // 1. Install the addon.
     const destHasAddon = fs.existsSync(path.join(projectPath, PLUGIN_REL, "plugin.cfg"));
     if (dryRun) {
         const verb = destHasAddon ? (force ? "overwrite" : "skip (already present; --force to overwrite)") : "install";
-        say(`  addon: would ${verb} → ${PLUGIN_REL}/`);
+        const srcNote = fromGitHub ? ` (from ${repo}@${ref})` : "";
+        say(`  addon: would ${verb} → ${PLUGIN_REL}/${srcNote}`);
     }
     else {
+        if (!addonSource) {
+            process.stderr.write("init: internal error — no addon source resolved.\n");
+            return 1;
+        }
         const r = installAddon(addonSource, projectPath, { force });
+        if (tmpFetchDir)
+            fs.rmSync(tmpFetchDir, { recursive: true, force: true });
         say(`  addon: ${r.action} → ${PLUGIN_REL}/`);
     }
     // 2. Enable it in project.godot.

package/dist/index.js

@@ -43,7 +43,7 @@ async function main() {
     // so long jobs (export/import/headless script) support poll/await/cancel.
     // D3: also advertise resources.subscribe so clients can subscribe to
     // godot://… resources and receive notifications/resources/updated.
-    const server = new McpServer({ name: "breakpoint-mcp", version: "1.4.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.4.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // the register*Tools calls below — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -118,6 +118,8 @@ function printUsage() {
         "  --client <id>       Write the MCP config for a client: claude-code | claude-desktop | cursor | windsurf | vscode.",
         "  --force             Overwrite an addon that is already installed.",
         "  --dry-run           Print what would change without writing anything.",
+        "  --from-github [ref] Fetch the editor addon from GitHub at [ref] (default: this package's version tag) instead of the bundled copy.",
+        "  --repo <owner/repo> With --from-github, the source repo (default: jlivingston-Cipher/godot-breakpoint-mcp).",
         "",
         "doctor options:",
         "  --project <dir>     Project to check (default: $GODOT_PROJECT or the current directory).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "MCP server exposing Godot to AI coding assistants over the Model Context Protocol — developed and tested with Claude — across four planes (CLI, live editor, LSP+DAP, runtime) with elicitation-gated destructive tools, long jobs on the formal MCP task model, captured console output, and MCP resources.",
   "type": "module",
   "license": "MIT",