breakpoint-mcp 1.3.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/addon/breakpoint_mcp/README.md

@@ -9,9 +9,16 @@ Loopback TCP/JSON bridge that exposes the live Godot editor (and, via the runtim
 
 Requires **Godot 4.2+** (uses the `EditorInterface` singleton; 4.4+ recommended).
 
+## Status dock
+On enable, a **Breakpoint MCP** panel is added to the editor dock. It reports the health of
+the editor / runtime / GDScript-LSP / DAP bridges, shows the configured ports and project
+path, and offers a one-click **Copy MCP-client config**. Connection / status / config only —
+not a chat UI; the AI assistant runs in your MCP client.
+
 ## Files
-- `plugin.gd` — `EditorPlugin` entry point; starts/stops the server.
+- `plugin.gd` — `EditorPlugin` entry point; starts/stops the server and adds the status dock.
 - `bridge_server.gd` — `TCPServer` polled from `_process`; newline-delimited JSON framing.
+- `status_dock.gd` — in-editor status/config dock (bridge health, ports, copy client config).
 - `operations.gd` — request handlers; every mutation is wrapped in `EditorUndoRedoManager`.
 - `variant_json.gd` — Variant ⇄ JSON codec (tagged rich types).
 

package/addon/breakpoint_mcp/bridge_server.gd

@@ -48,6 +48,19 @@ func shutdown() -> void:
 		_server = null
 
 
+## Read-only snapshot for the in-editor status dock. Pure — never mutates state.
+## `listening` reflects the live TCPServer; `clients` is the current peer count.
+## The dock lives inside this same process, so this is authoritative for the
+## editor-bridge plane (no TCP self-probe needed).
+func get_status() -> Dictionary:
+	return {
+		"listening": _server != null and _server.is_listening(),
+		"host": "127.0.0.1",
+		"port": _port,
+		"clients": _clients.size(),
+	}
+
+
 func _process(_delta: float) -> void:
 	if _server == null:
 		return

package/addon/breakpoint_mcp/operations.gd

@@ -7,7 +7,7 @@ extends RefCounted
 ## wrapped in the EditorUndoRedoManager so a human can Ctrl-Z anything the assistant did.
 
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
-const ADDON_VERSION := "1.0.0"
+const ADDON_VERSION := "1.4.0"
 
 var _plugin: EditorPlugin
 

package/addon/breakpoint_mcp/plugin.cfg

@@ -3,5 +3,5 @@
 name="Breakpoint MCP"
 description="Exposes the live Godot editor and the running game to an MCP host so an AI assistant can drive them: scene/node/resource CRUD with full undo/redo, project settings, ClassDB, editor + in-game screenshots, and an in-game runtime bridge (live SceneTree, property get/set, method calls, signals, input injection, Performance monitors). Pairs with the breakpoint-mcp MCP host."
 author="James Livingston"
-version="1.3.0"
+version="1.4.0"
 script="plugin.gd"

package/addon/breakpoint_mcp/plugin.gd

@@ -12,10 +12,12 @@ extends EditorPlugin
 ## subscribed MCP host can emit notifications/resources/updated.
 
 const BridgeServer := preload("res://addons/breakpoint_mcp/bridge_server.gd")
+const StatusDock := preload("res://addons/breakpoint_mcp/status_dock.gd")
 const RUNTIME_AUTOLOAD := "BreakpointRuntimeBridge"
 const RUNTIME_SCRIPT := "res://addons/breakpoint_mcp/runtime_bridge.gd"
 
 var _server: Node = null
+var _dock: Control = null
 var _selection: EditorSelection = null
 
 
@@ -24,6 +26,13 @@ func _enter_tree() -> void:
 	_server.name = "BreakpointBridgeServer"
 	_server.setup(self)
 	add_child(_server)
+	# Phase-4 status/config dock: a thin panel that reports bridge health across
+	# the editor/runtime/LSP/DAP planes and offers a one-click MCP-client config.
+	# Connection/status/config only — not a chat UI. Reads the server in-process.
+	var dock := StatusDock.new()
+	dock.set_server(_server)
+	add_control_to_dock(DOCK_SLOT_RIGHT_UL, dock)
+	_dock = dock
 	# Inject the runtime bridge into every run of the project so the runtime_*
 	# tools work as soon as the game starts. Removed cleanly on disable.
 	add_autoload_singleton(RUNTIME_AUTOLOAD, RUNTIME_SCRIPT)
@@ -38,6 +47,10 @@ func _enter_tree() -> void:
 
 
 func _exit_tree() -> void:
+	if _dock:
+		remove_control_from_docks(_dock)
+		_dock.queue_free()
+		_dock = null
 	if _selection and _selection.selection_changed.is_connected(_on_selection_changed):
 		_selection.selection_changed.disconnect(_on_selection_changed)
 	_selection = null

package/addon/breakpoint_mcp/status_dock.gd

@@ -0,0 +1,312 @@
+@tool
+extends VBoxContainer
+## Breakpoint MCP — in-editor status/config dock (Phase-4 adoption item).
+##
+## The GUI twin of `breakpoint-mcp doctor` + `init`: it surfaces the four bridge
+## planes' health, the configured ports, the project path, and a one-click
+## "Copy MCP-client config" yielding the exact snippet `init` prints. Scope is
+## connection / status / config ONLY — it is NOT a chat UI. The AI assistant
+## still lives in the user's MCP client; this dock only wires it up and reports.
+##
+## The editor-bridge plane is read directly from the in-process bridge server
+## (server.get_status()); the runtime / LSP / DAP planes are checked with short,
+## non-blocking StreamPeerTCP probes ticked from _process, so the editor main
+## thread never stalls. LSP/DAP ports are read from EditorSettings, so the dock
+## reflects the user's actual configuration, not just the defaults.
+
+const DEFAULT_BRIDGE_PORT := 9080
+const DEFAULT_RUNTIME_PORT := 9081
+const DEFAULT_LSP_PORT := 6005
+const DEFAULT_DAP_PORT := 6006
+const SERVER_NAME := "godot"
+const REFRESH_INTERVAL_SEC := 2.0
+const PROBE_DEADLINE_MSEC := 1500
+
+const COLOR_OK := Color(0.38, 0.85, 0.45)
+const COLOR_FAIL := Color(0.92, 0.47, 0.40)
+const COLOR_PENDING := Color(0.62, 0.62, 0.62)
+
+const PLANES := [
+	{"key": "editor", "name": "editor-bridge"},
+	{"key": "runtime", "name": "runtime-bridge"},
+	{"key": "lsp", "name": "gdscript-lsp"},
+	{"key": "dap", "name": "gdscript-dap"},
+]
+
+
+# --- pure helpers: editor-free, socket-free, unit-tested --------------------
+
+## The stdio server entry an MCP client config needs, matching the host's
+## clients.ts serverEntry() default (GODOT_BIN omitted when it is the default).
+static func server_entry(project_path: String) -> Dictionary:
+	return {
+		"command": "npx",
+		"args": ["-y", "breakpoint-mcp"],
+		"env": {"GODOT_PROJECT": project_path},
+	}
+
+## Copy-pasteable single-server snippet (wrapper key "mcpServers"), pretty JSON
+## with 2-space indent and insertion order preserved (sort_keys=false) so it is
+## the same shape `breakpoint-mcp init` prints — dock and CLI never drift.
+static func client_snippet(project_path: String) -> String:
+	var obj := {"mcpServers": {SERVER_NAME: server_entry(project_path)}}
+	return JSON.stringify(obj, "  ", false)
+
+## Status glyph, mirroring doctor's check / cross / dash vocabulary.
+static func plane_glyph(status: String) -> String:
+	match status:
+		"ok":
+			return "✓"
+		"fail":
+			return "✗"
+		_:
+			return "–"
+
+## One plane row's text: "<glyph> <name>  <detail>".
+static func plane_line(pname: String, status: String, detail: String) -> String:
+	return "%s %s  %s" % [plane_glyph(status), pname, detail]
+
+
+# --- state -----------------------------------------------------------------
+
+var _server: Node = null       # bridge_server.gd instance, injected by plugin.gd
+var _rows := {}                # plane key -> Label
+var _probes := {}              # plane key -> {peer, deadline, port}
+var _config_label: Label = null
+var _copy_feedback: Label = null
+var _timer: Timer = null
+
+
+## plugin.gd injects the live bridge server so the editor-bridge plane is read
+## in-process (authoritative) instead of self-probing the loopback port.
+func set_server(server: Node) -> void:
+	_server = server
+
+
+func _ready() -> void:
+	_build_ui()
+	_timer = Timer.new()
+	_timer.wait_time = REFRESH_INTERVAL_SEC
+	_timer.autostart = true
+	_timer.timeout.connect(_refresh)
+	add_child(_timer)
+	set_process(true)
+	_refresh()
+
+
+func _exit_tree() -> void:
+	for key in _probes:
+		var pr: Dictionary = _probes[key]
+		if pr["peer"] != null:
+			pr["peer"].disconnect_from_host()
+	_probes.clear()
+
+
+# --- UI --------------------------------------------------------------------
+
+func _build_ui() -> void:
+	name = "Breakpoint"
+	add_theme_constant_override("separation", 6)
+
+	var header := Label.new()
+	header.text = "Breakpoint MCP"
+	header.add_theme_font_size_override("font_size", 15)
+	add_child(header)
+
+	var sub := Label.new()
+	sub.text = "bridge status · ports · client setup"
+	sub.modulate = Color(1, 1, 1, 0.6)
+	add_child(sub)
+
+	add_child(HSeparator.new())
+
+	var bridges_hdr := Label.new()
+	bridges_hdr.text = "Bridges"
+	bridges_hdr.modulate = Color(1, 1, 1, 0.75)
+	add_child(bridges_hdr)
+
+	for p in PLANES:
+		var row := Label.new()
+		row.add_theme_font_size_override("font_size", 13)
+		_rows[p["key"]] = row
+		add_child(row)
+		_set_plane(p["key"], "pending", "…")
+	add_child(HSeparator.new())
+
+	var cfg_hdr := Label.new()
+	cfg_hdr.text = "Config"
+	cfg_hdr.modulate = Color(1, 1, 1, 0.75)
+	add_child(cfg_hdr)
+
+	_config_label = Label.new()
+	_config_label.add_theme_font_size_override("font_size", 12)
+	_config_label.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	add_child(_config_label)
+
+	add_child(HSeparator.new())
+
+	var copy_btn := Button.new()
+	copy_btn.text = "Copy MCP-client config"
+	copy_btn.tooltip_text = "Copy the mcpServers snippet for this project to the clipboard."
+	copy_btn.pressed.connect(_on_copy_pressed)
+	add_child(copy_btn)
+
+	var refresh_btn := Button.new()
+	refresh_btn.text = "Refresh"
+	refresh_btn.pressed.connect(_refresh)
+	add_child(refresh_btn)
+
+	_copy_feedback = Label.new()
+	_copy_feedback.add_theme_font_size_override("font_size", 12)
+	_copy_feedback.modulate = Color(1, 1, 1, 0.7)
+	_copy_feedback.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	add_child(_copy_feedback)
+
+	var foot := Label.new()
+	foot.text = "Status/config only — the assistant runs in your MCP client, not here."
+	foot.modulate = Color(1, 1, 1, 0.5)
+	foot.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART
+	add_child(foot)
+
+
+func _display_name(key: String) -> String:
+	for p in PLANES:
+		if p["key"] == key:
+			return String(p["name"])
+	return key
+
+
+func _set_plane(key: String, status: String, detail: String) -> void:
+	var row: Label = _rows.get(key)
+	if row == null:
+		return
+	row.text = plane_line(_display_name(key), status, detail)
+	var col := COLOR_PENDING
+	if status == "ok":
+		col = COLOR_OK
+	elif status == "fail":
+		col = COLOR_FAIL
+	row.add_theme_color_override("font_color", col)
+
+
+# --- refresh ---------------------------------------------------------------
+
+func _refresh() -> void:
+	_update_editor_plane()
+	_start_probe("runtime", _runtime_port())
+	_start_probe("lsp", _lsp_port())
+	_start_probe("dap", _dap_port())
+	_update_config_line()
+
+
+func _update_editor_plane() -> void:
+	if _server != null and _server.has_method("get_status"):
+		var s: Dictionary = _server.get_status()
+		if bool(s.get("listening", false)):
+			var n := int(s.get("clients", 0))
+			var host := String(s.get("host", "127.0.0.1"))
+			var suffix := "client" if n == 1 else "clients"
+			_set_plane("editor", "ok", "%s:%d · %d %s" % [host, int(s.get("port", DEFAULT_BRIDGE_PORT)), n, suffix])
+		else:
+			_set_plane("editor", "fail", "not listening")
+	else:
+		_set_plane("editor", "fail", "server unavailable")
+
+
+func _update_config_line() -> void:
+	if _config_label == null:
+		return
+	_config_label.text = "project  %s\neditor %d · runtime %d · lsp %d · dap %d" % [
+		_project_path(), _bridge_port(), _runtime_port(), _lsp_port(), _dap_port(),
+	]
+
+
+func _on_copy_pressed() -> void:
+	DisplayServer.clipboard_set(client_snippet(_project_path()))
+	if _copy_feedback != null:
+		_copy_feedback.text = "Copied the mcpServers snippet to the clipboard."
+
+
+# --- ports -----------------------------------------------------------------
+
+func _project_path() -> String:
+	return ProjectSettings.globalize_path("res://").trim_suffix("/")
+
+
+func _bridge_port() -> int:
+	if _server != null and _server.has_method("get_status"):
+		var s: Dictionary = _server.get_status()
+		return int(s.get("port", DEFAULT_BRIDGE_PORT))
+	return _env_port("BREAKPOINT_BRIDGE_PORT", DEFAULT_BRIDGE_PORT)
+
+
+func _runtime_port() -> int:
+	return _env_port("BREAKPOINT_RUNTIME_PORT", DEFAULT_RUNTIME_PORT)
+
+
+func _env_port(var_name: String, fallback: int) -> int:
+	var env := OS.get_environment(var_name)
+	if env != "" and env.is_valid_int():
+		return int(env)
+	return fallback
+
+
+func _editor_setting_int(key: String, fallback: int) -> int:
+	var es := EditorInterface.get_editor_settings()
+	if es != null and es.has_setting(key):
+		var v: Variant = es.get_setting(key)
+		if typeof(v) == TYPE_INT or typeof(v) == TYPE_FLOAT:
+			return int(v)
+	return fallback
+
+
+func _lsp_port() -> int:
+	return _editor_setting_int("network/language_server/remote_port", DEFAULT_LSP_PORT)
+
+
+func _dap_port() -> int:
+	return _editor_setting_int("network/debug_adapter/remote_port", DEFAULT_DAP_PORT)
+
+
+# --- non-blocking TCP probes -----------------------------------------------
+# The editor-bridge plane is read in-process (see _update_editor_plane); only
+# runtime / LSP / DAP are probed. connect_to_host is non-blocking; the socket is
+# polled from _process across frames, so a slow/closed port never stalls the UI.
+
+func _start_probe(key: String, port: int) -> void:
+	if _probes.has(key):
+		var old: Dictionary = _probes[key]
+		if old["peer"] != null:
+			old["peer"].disconnect_from_host()
+		_probes.erase(key)
+	var peer := StreamPeerTCP.new()
+	var err := peer.connect_to_host("127.0.0.1", port)
+	if err != OK:
+		_set_plane(key, "fail", "127.0.0.1:%d unreachable" % port)
+		return
+	_set_plane(key, "pending", "127.0.0.1:%d checking…" % port)
+	_probes[key] = {"peer": peer, "deadline": Time.get_ticks_msec() + PROBE_DEADLINE_MSEC, "port": port}
+
+
+func _process(_delta: float) -> void:
+	if _probes.is_empty():
+		return
+	var done: Array = []
+	for key in _probes:
+		var pr: Dictionary = _probes[key]
+		var peer: StreamPeerTCP = pr["peer"]
+		peer.poll()
+		var st := peer.get_status()
+		if st == StreamPeerTCP.STATUS_CONNECTED:
+			_set_plane(key, "ok", "127.0.0.1:%d reachable" % int(pr["port"]))
+			peer.disconnect_from_host()
+			done.append(key)
+		elif st == StreamPeerTCP.STATUS_ERROR:
+			_set_plane(key, "fail", "127.0.0.1:%d unreachable" % int(pr["port"]))
+			done.append(key)
+		elif Time.get_ticks_msec() > int(pr["deadline"]):
+			_set_plane(key, "fail", "127.0.0.1:%d no response" % int(pr["port"]))
+			peer.disconnect_from_host()
+			done.append(key)
+	for key in done:
+		_probes.erase(key)

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.3.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.3.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",