breakpoint-mcp 1.74.0 → 1.75.0

package/addon/breakpoint_mcp/bridge_server.gd

@@ -5,7 +5,10 @@ extends Node
 ## Wire format (both directions), one JSON object per line ("\n" terminated):
 ##   request:  {"id": "<string>", "method": "<name>", "params": { ... }}
 ##   response: {"id": "<string>", "ok": true,  "result": { ... }}
-##             {"id": "<string>", "ok": false, "error": {"code": ..., "message": ...}}
+##             {"id": "<string>", "ok": false, "error": {"code": ..., "message": ..., "remedy": ...}}
+##   `remedy` is the next action for that code (error_remedies.gd) and is omitted
+##   when the plane has nothing to say — the pre-auth denial below carries none by
+##   design, because it must not tell an unauthenticated peer anything at all.
 ##
 ## Binds to 127.0.0.1 only. The port comes from the BREAKPOINT_BRIDGE_PORT env
 ## var (default 9080). The socket is polled from `_process`, so all request

package/addon/breakpoint_mcp/error_remedies.gd

@@ -0,0 +1,113 @@
+@tool
+extends RefCounted
+## The next action, keyed by the error code the bridge already returns.
+##
+## 🔴 WHAT THIS FILE EXISTS TO FIX, MEASURED BEFORE IT WAS WRITTEN (session 254):
+## 525 `_err()` sites across the two engine-facing planes emitted 216 distinct
+## message templates, and 451 of those sites named NO next action. The three most
+## emitted messages in the addon were "No scene is open" (90 sites), "Node not
+## found: %s" (53) and "ResourceSaver.save() returned %d" (35) — a state report, a
+## rejection with no way to discover the legal values, and a bare engine return
+## code. Every one is a true sentence and none of them tells the reader what to do,
+## which is the whole of what a failing tool owes an agent that cannot see the
+## editor.
+##
+## 🔴 WHY THE REMEDY HANGS OFF THE CODE AND NOT THE MESSAGE. 216 message templates
+## would be 216 hand-written remedies to keep true; the code vocabulary is 50, it is
+## already machine-owned (contract_check reads it on both sides of the wire), and it
+## is the axis the message VARIES within — every "X not found: %s" is one `not_found`
+## with the same next action. So the remedy is attached where the join is checkable
+## and the message keeps carrying the particulars.
+##
+## 🔴 AND THE TWO PLANES DO NOT SHARE ONE TABLE, DELIBERATELY. `bad_path` on the
+## editor plane is answered by `scene_get_tree`; on the runtime plane by
+## `runtime_get_tree`. A single table with a fallback would have to be wrong on one
+## plane or vague on both, and the exact per-plane join is what lets the gate refuse
+## a code with no remedy and a remedy no code raises — in both directions, per file.
+##
+## Every tool name written here is compared to the live `registerTool(..)` surface by
+## contract_check check 28: a remedy naming a tool that was renamed or never existed
+## is a dead instruction, and it is the failure this table would otherwise invite.
+
+const EDITOR := "editor"
+const RUNTIME := "runtime"
+
+## operations.gd — the editor plane. Keys are exactly the codes `_err()` raises there.
+const EDITOR_REMEDIES := {
+	"bad_params": "Fix the parameter named above and call again — the message carries the accepted shape.",
+	"no_scene": "Open a scene first: call `scene_open` with a res:// .tscn path, or `scene_list_open` to see what the editor already has open.",
+	"bad_path": "Call `scene_get_tree` for the live node paths — they are relative to the open scene root — or `node_find` to search by name.",
+	"not_found": "Check the name or res:// path exists: `filesystem_list` for files, `scene_get_tree` for nodes in the open scene.",
+	"bad_type": "Pass a node or resource of the type named above — `scene_get_tree` reports each node's class and `classdb_get_class` describes it.",
+	"save_failed": "Check the target path is inside the project and writable, then call again; the number is a Godot Error code.",
+	"refused": "Act on a different node — this is refused by design, the message names the invariant, and no flag lifts it.",
+	"unsupported": "Check the engine version with `godot_version` — this Godot build does not expose the API the tool needs.",
+	"exists": "Choose a different name, or remove the existing one first.",
+	"load_failed": "Call `filesystem_scan` to re-import, then call again — the path exists but did not load.",
+	"no_signal": "Call `signal_list` for the signals the node actually declares.",
+	"bad_track": "Call `anim_get_track_keys` for the animation's tracks and their indices.",
+	"bad_root": "Create the right root first — `anim_tree_create` builds a blend tree or a state machine to add nodes to.",
+	"no_history": "Make an edit through the bridge first — undo history exists per scope only once something has been recorded into it.",
+	"pack_failed": "Call `node_set_owner` on the strays, then call again — every node in the branch must be owned by the scene root.",
+	"no_method": "Call `classdb_get_class` for the methods the node's class declares.",
+	"duplicate_failed": "Duplicate a node that is saved into the open scene, or call `resource_save` on the resource first.",
+	"create_failed": "Check the parent and the name in the message, then call again.",
+	"mkdir_failed": "Check the parent directory is inside the project and writable; `filesystem_create_dir` creates intermediate directories, and the number is a Godot Error code.",
+	"bad_source": "Create an atlas source first with `tileset_add_source`; the id above is not one.",
+	"unknown_method": "Re-run `breakpoint-mcp init --force`, then reopen the project — the addon installed here is older than the host and plain `init` skips an addon that is already present.",
+	"bad_request": "Send the request again with the field the message names — it was empty or unparseable.",
+	"no_viewport": "Switch the editor to the tab that owns that viewport with `main_screen_set`, then call again.",
+	"no_texture": "Call `main_screen_set` to open the matching editor tab and let it draw, then call again.",
+	"no_image": "Open the matching editor tab with `main_screen_set` so a frame is drawn, then call again.",
+	"instantiate_failed": "Call `classdb_get_class` to check the class is instantiable before constructing it.",
+	"bad_index": "Pass an index inside the range the message carries.",
+	"not_current": "Call `scene_open` on the scene you mean first — only the current scene can be closed.",
+	"bad_class": "Call `classdb_get_class` to check the class exists and is an instantiable Resource.",
+	"not_imported": "Call `filesystem_scan` and try again with an asset the editor imported — only imported assets carry .import metadata.",
+	"fs_error": "Check the project path is intact, then call `filesystem_scan` — the project filesystem could not be read.",
+	"move_failed": "Check the destination directory exists and nothing is already at the target path; the number is a Godot Error code.",
+	"bad_key": "Call `anim_get_track_keys` for the keys the track actually has.",
+	"bad_texture": "Pass a res:// path that loads as a Texture2D — `resource_load` reports what a path loads as.",
+	"no_tile_data": "Create the tile first with `tileset_add_tile`; there is none at that coordinate.",
+	"too_large": "Split the call into smaller regions — the message carries the limit.",
+	"write_failed": "Check the target path is inside the project and not read-only; the number is a Godot Error code.",
+}
+
+## runtime_bridge.gd — the running game. Keys are exactly the codes `_err()` raises
+## there; the tools named are the `runtime_*` ones, because the editor's are answered
+## by a different process.
+const RUNTIME_REMEDIES := {
+	"bad_path": "Call `runtime_get_tree` for the live node paths — they are relative to the running scene root.",
+	"async_only": "Call this one through the async lane; `runtime_step_frames` and `runtime_await_condition` are dispatched there.",
+	"no_viewport": "Call `godot_run_project`, then wait for `runtime_get_tree` to answer before capturing — the game has no viewport yet.",
+	"no_texture": "Call `runtime_step_frames` to advance at least one frame, then call again.",
+	"no_image": "Call `runtime_step_frames` to advance a frame, then call again — nothing has been rendered to read back.",
+	"unknown_method": "Re-run `breakpoint-mcp init --force`, then relaunch the project — the addon running in the game is older than the host and plain `init` skips an addon that is already present.",
+	"no_scene": "Set a main scene with `project_set_main_scene`, then run the project again — it is running with no current scene.",
+	"no_method": "Call `runtime_get_property` or `godot://class` for what the running node's class declares.",
+	"no_signal": "Call `runtime_get_tree` for the node, then `godot://class` for the signals its class declares.",
+	"emit_failed": "Check the argument count and types against the signal's declaration, then emit again.",
+	"bad_action": "Call `inputmap_list` for the actions the project declares before injecting one.",
+	"bad_kind": "Pass one of the kinds the message lists to `runtime_inject_input`.",
+	"bad_regex": "Simplify the pattern and call again — it did not compile as a Godot RegEx.",
+	"bad_reference": "Pass a reference image the project can load — `runtime_screenshot` writes one you can diff against later.",
+	"not_animation_player": "Call `runtime_get_tree` and pass the path of an AnimationPlayer node.",
+	"no_animation": "Call `runtime_anim_get_state` for the animations the player actually holds.",
+	"bad_scene": "Pass a res:// .tscn path that loads in the running project; `scene_get_dependencies` reports what a scene needs.",
+	"bad_args": "Send the arguments the message names and call again.",
+	"bad_type": "Pass a node of the type named above — `runtime_get_tree` reports each running node's class.",
+	"not_a_node": "Call `runtime_get_tree` for the node paths — the one passed resolves to something that is not a Node.",
+	"instantiate_failed": "Check the class or scene loads in the editor first — it would not instantiate in the running game.",
+	"cannot_remove_root": "Call `runtime_node_remove` on a child instead, or `godot_stop` to end the run — the running scene root cannot be removed.",
+	"no_tree": "Call `godot_run_project` and wait for it to bind, then call again — the game is not running.",
+}
+
+
+## The next action for `code` on `plane`, or "" when the plane raises no such code.
+##
+## Returning "" rather than a placeholder is deliberate: `_err` omits the field
+## entirely when there is nothing to say, so a remedy that never arrives is visible
+## as an absent key rather than as an empty instruction a reader has to judge.
+static func remedy(code: String, plane: String) -> String:
+	var table: Dictionary = RUNTIME_REMEDIES if plane == RUNTIME else EDITOR_REMEDIES
+	return table.get(code, "")

package/addon/breakpoint_mcp/operations.gd

@@ -7,7 +7,8 @@ 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.9.9"
+const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
+const ADDON_VERSION := "1.11.0"
 
 var _plugin: EditorPlugin
 
@@ -340,7 +341,14 @@ func _ok(result: Variant) -> Dictionary:
 
 
 func _err(code: String, message: String) -> Dictionary:
-	return {"ok": false, "error": {"code": code, "message": message}}
+	# 254: the message says what went wrong; the remedy says what to do about it. It is
+	# attached HERE, at the one place every editor-plane failure passes through, so no
+	# call site can forget it and none has to repeat it.
+	var e := {"code": code, "message": message}
+	var r := Remedies.remedy(code, Remedies.EDITOR)
+	if r != "":
+		e["remedy"] = r
+	return {"ok": false, "error": e}
 
 
 func _edited_root() -> Node:

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.9.9"
+version="1.11.0"
 script="plugin.gd"

package/addon/breakpoint_mcp/runtime_bridge.gd

@@ -11,7 +11,18 @@ extends Node
 ## NOTE: this script is intentionally NOT @tool — it must run in the game, not
 ## the editor. All handlers run on the main thread (socket polled from _process).
 
+## The addon version this GAME is running, answered on `ping`.
+##
+## 🔴 THE EDITOR PLANE HAS ANSWERED WITH ONE SINCE IT HAD ONE AND THIS PLANE NEVER DID
+## (258 §2). The runtime table's own `unknown_method` remedy says *the addon running in
+## the game is older than the host* — a claim about a version the game could not report,
+## on the one plane where disk and memory diverge most: `init --force` rewrites the files
+## and the process that is already running keeps the addon it loaded. Held in lockstep
+## with `plugin.cfg` and with `operations.gd`'s copy by contract_check check 14, which
+## exists because two of those literals disagreed for two releases.
+const ADDON_VERSION := "1.11.0"
 const Codec := preload("res://addons/breakpoint_mcp/variant_json.gd")
+const Remedies := preload("res://addons/breakpoint_mcp/error_remedies.gd")
 const DEFAULT_PORT := 9081
 const LOG_CAP := 1000
 # D1a: how many error/warning entries one response may carry. A cap and not the
@@ -369,7 +380,7 @@ func _attach_engine_log(response: Dictionary, seq_before: int) -> void:
 func _dispatch(method: String, params: Dictionary) -> Dictionary:
 	match method:
 		"ping":
-			return _ok({"pong": true, "runtime": true, "godot": Engine.get_version_info().get("string", ""), "log_capture": _log_capture != null})
+			return _ok({"pong": true, "runtime": true, "addon_version": ADDON_VERSION, "godot": Engine.get_version_info().get("string", ""), "log_capture": _log_capture != null})
 		"runtime.get_tree":
 			return _get_tree(params)
 		"runtime.get_property":
@@ -428,7 +439,14 @@ func _ok(result: Variant) -> Dictionary:
 
 
 func _err(code: String, message: String) -> Dictionary:
-	return {"ok": false, "error": {"code": code, "message": message}}
+	# 254: the message says what went wrong; the remedy says what to do about it. It is
+	# attached HERE, at the one place every runtime-plane failure passes through, so no
+	# call site can forget it and none has to repeat it.
+	var e := {"code": code, "message": message}
+	var r := Remedies.remedy(code, Remedies.RUNTIME)
+	if r != "":
+		e["remedy"] = r
+	return {"ok": false, "error": e}
 
 
 func _base() -> Node:

package/dist/addon-version.js

@@ -0,0 +1,113 @@
+/**
+ * The addon's version, read from the artifact rather than believed.
+ *
+ * 🔴 WHY THIS FILE EXISTS, MEASURED BEFORE IT WAS WRITTEN (session 258 §2). The
+ * addon is the half of this product npm cannot version — `registry_bytes.py` says
+ * so in its own comment: *the only name npm has for that artifact is the HOST
+ * version*. It ships inside the host tarball, it moves on its own cadence, and
+ * until this file nothing anywhere compared the copy a user is RUNNING to the copy
+ * their host SHIPPED. Four things compounded:
+ *
+ *   1. `installAddon` tested `fs.existsSync(dest/plugin.cfg)` and skipped. The
+ *      destination's `version=` was never opened, so upgrading the host and
+ *      re-running `init` printed `addon: skipped` and pinned the old addon
+ *      FOREVER. Walked live at 258: install 1.74.1 → addon 1.9.9; upgrade the
+ *      host to 1.75.0, whose bundled addon is 1.10.0; `init` → still 1.9.9.
+ *   2. `doctor` regexed the version out of `plugin.cfg`, interpolated it into a
+ *      display string and hardcoded `status: "ok"` — a green line carrying the
+ *      number that proves it should be red.
+ *   3. Nothing crossed the wire. `operations.gd`'s `ping` put `addon_version` in
+ *      its reply and all four consumers discarded it; the runtime plane's `ping`
+ *      did not carry one at all.
+ *   4. The remedy that names this failure shipped only in the addon that is not
+ *      stale — `error_remedies.gd` was ADDED in 1.10.0.
+ *
+ * So the comparison is spelled ONCE, here, and the three readers that need it —
+ * `init` on skip, `doctor` on both pairs, and the host's own fallback remedy —
+ * import it rather than each growing a regex. A version comparison written three
+ * times is two of them wrong the first time the format changes.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/** Where the addon lives inside a Godot project, relative to the project root. */
+export const ADDON_REL = "addons/breakpoint_mcp";
+/**
+ * The one sentence that turns a skew into an instruction, spelled once because
+ * four places print it: `doctor`'s on-disk check, `doctor`'s running-addon check,
+ * `init`'s warning when it skips, and the host's fallback remedy for a stale
+ * addon's `unknown_method`.
+ *
+ * 🔴 IT NAMES `--force` AND THAT IS THE WHOLE POINT. `installAddon` skips a
+ * destination that already has a `plugin.cfg`, so a remedy that says re-run
+ * `breakpoint-mcp init` is an instruction that does nothing in the one state it
+ * is ever read in — the addon is already there, which is why it is stale. Two
+ * rows in `error_remedies.gd` said exactly that from the day the table shipped:
+ * 254's rule joined every backticked TOOL NAME in a remedy to the live registry,
+ * and nobody joined `init` to what `init` does.
+ *
+ * 🔴 AND IT SAYS RESTART. Godot reads the enabled-plugin list and the addon
+ * scripts at project load, so overwriting the files changes nothing in a session
+ * that is already open — a remedy stopping at `--force` sends a user to a command
+ * that appears not to have worked.
+ */
+export const ADDON_SKEW_HINT = "Run 'breakpoint-mcp init --force' to overwrite it with the addon this host ships, then close and reopen the project in Godot. Plain 'init' skips an addon that is already installed, which is why the old one persisted.";
+/**
+ * The `version="…"` line of a `plugin.cfg`, or null if the file or the key is
+ * unreadable.
+ *
+ * Null and not `"unknown"`: a caller comparing two versions must be able to tell
+ * *I could not read this* from *this is a version that happens to differ*, and a
+ * sentinel string collapses those into a false skew report.
+ */
+export function readAddonVersion(addonDir) {
+    try {
+        const text = fs.readFileSync(path.join(addonDir, "plugin.cfg"), "utf8");
+        const m = /^\s*version\s*=\s*"([^"]*)"/m.exec(text);
+        return m && m[1] !== "" ? m[1] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The addon installed in `projectPath`, or null if there isn't one. */
+export function installedAddonVersion(projectPath) {
+    return readAddonVersion(path.join(projectPath, ADDON_REL));
+}
+/**
+ * Compare two addon versions the way a user would need them compared.
+ *
+ * Dotted numeric segments, compared left to right, missing segments read as 0 —
+ * enough for a `MAJOR.MINOR.PATCH` line that has never carried a pre-release
+ * suffix. Anything that does not parse as digits is `"unknown"` rather than a
+ * guess: 254's rule is that a remedy is an instruction somebody will execute, and
+ * *your addon is older* is an instruction. Being wrong about the direction sends
+ * a user to overwrite a newer addon with an older one.
+ */
+export function compareAddonVersions(installed, bundled) {
+    if (installed === null || bundled === null)
+        return "unknown";
+    const parse = (v) => {
+        const parts = v.split(".");
+        const out = [];
+        for (const p of parts) {
+            if (!/^\d+$/.test(p))
+                return null;
+            out.push(Number(p));
+        }
+        return out.length > 0 ? out : null;
+    };
+    const a = parse(installed);
+    const b = parse(bundled);
+    if (a === null || b === null)
+        return "unknown";
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x < y)
+            return "older";
+        if (x > y)
+            return "newer";
+    }
+    return "same";
+}
+//# sourceMappingURL=addon-version.js.map

package/dist/annotations.js

@@ -38,6 +38,15 @@ const DESTRUCTIVE = [
     "shader_set_code", "shadermaterial_create", "shadermaterial_set_param", "shadermaterial_set_shader",
     "signal_disconnect", "signal_emit", "theme_create", "theme_set_color", "theme_set_constant", "theme_set_font",
     "theme_set_stylebox", "tilemap_clear", "tilemap_set_cell", "tilemap_set_cells_rect", "tileset_create",
+    // 🆕 252 — the one row of 251's twenty-one where the DOCUMENT was right and this
+    // list was wrong. 251 gated the catalog's ✔ against this roster and found eight
+    // tools carrying ✔ that are not here; seven were plainly additive and the ✔ came
+    // off them. `tileset_set_tile_collision` REPLACES a tile's existing collision
+    // shape, which is this list's own sentence — *may overwrite or discard state the
+    // caller did not supply*. It was split out and decided on its own rather than
+    // moved inside a copy fix, because this is what a client shows a human BEFORE it
+    // runs the tool, and that is a behaviour change, not a wording one.
+    "tileset_set_tile_collision",
     "vcs_restore", "vcs_stash",
 ];
 /** Tools where a repeat call with identical arguments adds no further effect. */
@@ -95,7 +104,7 @@ const OPEN_WORLD = [];
 /**
  * The complete annotated roster — every registered tool, listed explicitly.
  *
- * This CANNOT be derived as the union of the four lists above: 52 tools are
+ * This CANNOT be derived as the union of the four lists above: 51 tools are
  * all-false (mutating, non-destructive, non-idempotent, local — e.g. `node_add`,
  * `dbg_step`, `vcs_commit`), so a derived union would silently omit them and the
  * totality check below would pass while they shipped unannotated. Listing the

package/dist/bridge.js

@@ -3,14 +3,57 @@ import { randomUUID } from "node:crypto";
 import { log } from "./logger.js";
 import { OverdueLedger } from "./late-reply.js";
 import { findNonFinite, describeNonFinite, tolerate, TOLERANT_METHODS } from "./finiteness.js";
+import { remedyForWireError } from "./remedies.js";
 export class BridgeError extends Error {
     code;
-    constructor(code, message) {
+    /**
+     * The next action the addon attached to this code (254). Optional by
+     * construction: the addon omits it for codes it has nothing to say about, and
+     * every failure the host raises itself — timeout, closed socket, non-finite —
+     * arrives without one, because the remedy for those is not the addon's to give.
+     */
+    remedy;
+    constructor(code, message, remedy) {
         super(message);
         this.name = "BridgeError";
         this.code = code;
+        if (remedy)
+            this.remedy = remedy;
     }
 }
+/**
+ * The code `connect()` raises when nothing is listening on the bridge port.
+ *
+ * Spelled once, because two callers now branch on it — `connect()` which raises
+ * it and `runtime_await_condition` which retries past it — and a string literal
+ * in two files is a rename away from a waiting tool that silently stops waiting.
+ */
+export const BRIDGE_UNAVAILABLE = "bridge_unavailable";
+/**
+ * Is this the transport saying *not yet*, rather than the peer saying *no*?
+ *
+ * 🔴 THE DISTINCTION IS THE WHOLE OF 249's REMEDY C. A caller that asked to wait
+ * should keep waiting through an unbound port, and should NOT keep waiting
+ * through a missing node or an unknown property — those are answers, and
+ * retrying an answer only makes it slower.
+ */
+export function isTransportUnavailable(err) {
+    return err?.code === BRIDGE_UNAVAILABLE;
+}
+/**
+ * The remedy clause every plane's `fail()` appends, rendered once.
+ *
+ * 🔴 FIVE RENDERERS, ONE CLAUSE. `tools/editor/common.ts`, `tools/runtime.ts`,
+ * `tools/tabletop.ts`, `tools/netcode.ts` and `tools/backend.ts` each turn a
+ * `Partial<BridgeError>` into MCP text under their own label. A remedy pasted into
+ * five templates is five places to drift; this is the one place it is spelled, and
+ * contract_check check 26 asserts every renderer of a `Partial<BridgeError>` calls
+ * it — a sixth plane added without it would ship a silent failure message again.
+ */
+export function remedyClause(err) {
+    const r = err?.remedy;
+    return typeof r === "string" && r !== "" ? ` — ${r}` : "";
+}
 /**
  * TCP client for the in-editor Breakpoint MCP addon. Speaks newline-delimited
  * JSON. Requests are correlated to responses by `id`. Connects lazily and
@@ -39,7 +82,17 @@ export class BridgeClient {
     eventListeners = new Set();
     wantConnected = false;
     reconnectTimer = null;
-    constructor(host, port, defaultTimeoutMs, label = "editor bridge", hint = 'Is the editor open with the "Breakpoint MCP" plugin enabled?', 
+    constructor(host, port, defaultTimeoutMs, label = "editor bridge", 
+    // 🔴 THE SECOND SENTENCE IS THE ONE THAT EARNS ITS PLACE. The first asks a
+    // question whose answer, for the user most likely to be reading this line,
+    // is YES: the editor IS open and the plugin IS listed in project.godot.
+    // Godot reads `[editor_plugins]` at project load and never re-reads it, so
+    // an editor that was already running when `init` wrote the section keeps
+    // the plugin disabled — the bridge never starts, every editor-plane tool is
+    // dark, and the remedy agrees with everything the user can see. `init` now
+    // warns at the point it writes; this is the same fact told to the person
+    // who did not read that line, or who read it a week ago.
+    hint = 'Is the editor open with the "Breakpoint MCP" plugin enabled? If it was ALREADY open when you ran `breakpoint-mcp init`, close and reopen the project — Godot reads the enabled-plugin list only at project load.', 
     /**
      * Loopback-auth secret provider, read lazily on each connect. When it
      * returns a non-empty string the client sends it as the FIRST line on the
@@ -116,7 +169,7 @@ export class BridgeClient {
                 // Recorded for onClose(): if the connection was already up, this reject()
                 // is a no-op on a settled promise and the errno would otherwise be lost.
                 this.lastSocketError = err;
-                reject(new BridgeError("bridge_unavailable", `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}. ${this.hint} (${err.message})`));
+                reject(new BridgeError(BRIDGE_UNAVAILABLE, `Cannot reach the Godot ${this.label} at ${this.host}:${this.port}. ${this.hint} (${err.message})`));
             });
             socket.on("data", (chunk) => this.onData(chunk));
             socket.on("close", () => this.onClose());
@@ -227,7 +280,13 @@ export class BridgeClient {
         }
         else {
             const e = msg.error ?? { code: "unknown", message: "Unknown bridge error" };
-            p.reject(new BridgeError(e.code, e.message));
+            // 🔴 THE FALLBACK IS FOR THE ADDON THAT CANNOT ANSWER FOR ITSELF (258 §2).
+            // A current addon attaches its own remedy and wins outright; an addon old
+            // enough to raise `unknown_method` predates `error_remedies.gd` entirely,
+            // so the only side that can name its next action is the host it is skewed
+            // against. See remedies.ts for why that table has exactly one row.
+            const wire = typeof e.remedy === "string" ? e.remedy : undefined;
+            p.reject(new BridgeError(e.code, e.message, remedyForWireError(e.code, wire)));
         }
     }
     /**

package/dist/capabilities.js

@@ -1,3 +1,4 @@
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
 /** The groups, in display order. */
 export const CAPABILITY_GROUPS = ["code-execution"];
 /** One-line human description per group (shown by `doctor` and the resource). */
@@ -128,6 +129,83 @@ export function applyCapabilities(server, enabled) {
         tasks.registerToolTask = gate(tasks.registerToolTask.bind(tasks));
     }
 }
+/**
+ * The JSON-RPC method `McpServer` registers its tool dispatcher under. Written as
+ * a literal because the SDK does not export the method string, and PINNED by
+ * `capabilities.test.ts`, which builds a real server and asserts the handler map
+ * carries exactly this key — so an SDK that renamed the method reddens a test
+ * rather than silently un-installing the refusal below.
+ */
+export const CALL_TOOL_METHOD = "tools/call";
+/**
+ * The message a withheld tool answers with, in place of the SDK's `not found`.
+ *
+ * 🔴 THE READER OF THIS SENTENCE IS USUALLY NOT A HUMAN. `mcp.js` throws
+ * `Tool <name> not found` for any name absent from its registry, and a dropped
+ * tool is absent for exactly that reason — so a deliberate configuration reads,
+ * to the assistant relaying it, as a feature this package does not have. It will
+ * report that absence to the user as fact. Every remedy is therefore named here
+ * and named *derived*: the group, the env var, the `init` preset and the resource
+ * that lists the rest. `not a missing feature` is in the first line because it is
+ * the sentence the reader is about to get wrong.
+ */
+export function droppedToolMessage(name) {
+    const groups = TOOL_CAPABILITIES[name] ?? [];
+    const list = groups.join(", ");
+    return (`Tool ${name} exists in this server but is WITHHELD BY POLICY — it is not a missing feature. ` +
+        `It belongs to the higher-trust capability group${groups.length === 1 ? "" : "s"} ` +
+        `'${list}', which ${groups.length === 1 ? "is" : "are"} OFF by default. ` +
+        `Enable it by setting BREAKPOINT_PRIVILEGED_GROUPS=${list} in this server's env, ` +
+        `or by re-running \`npx breakpoint-mcp init --trust full\`. ` +
+        `Read the godot://capabilities resource for every group, its state, and the full withheld list.`);
+}
+/**
+ * Make a call to a DROPPED tool answer with the policy instead of the SDK's
+ * `Tool <name> not found`. Call ONCE, after every `register*Tools()` — the
+ * dispatcher does not exist until the first `registerTool`, and wrapping it
+ * earlier would wrap nothing.
+ *
+ * 🔴 THIS DELIBERATELY DOES NOT REGISTER THE TOOL. Least-privilege by
+ * construction is the point of the drop: `tools/list` stays at 279 and no
+ * withheld schema crosses the wire, so `wire_diff`, `token-cost` and every floor
+ * over the advertised surface are unmoved. The ONLY thing that changes is the
+ * sentence a caller gets back when it asks for one by name — which is the whole
+ * defect, because the tool was never the problem.
+ *
+ * Wrapping the map entry rather than calling `setRequestHandler` is not a
+ * shortcut: the SDK stores an already-parsed wrapper there, so re-registering
+ * would mean re-implementing dispatch. This preserves it and adds one branch in
+ * front, the same monkeypatch idiom `applyCapabilities` uses one function up.
+ */
+export function applyDroppedToolRefusal(server, enabled) {
+    const dropped = new Set(droppedTools(enabled));
+    if (dropped.size === 0)
+        return;
+    const proto = server.server;
+    const handlers = proto?._requestHandlers;
+    const inner = handlers?.get(CALL_TOOL_METHOD);
+    // No dispatcher means no tool was ever registered — nothing to guard, and
+    // installing a handler here would answer for a surface that does not exist.
+    if (!handlers || !inner)
+        return;
+    handlers.set(CALL_TOOL_METHOD, async (request, extra) => {
+        const name = request?.params?.name;
+        if (typeof name === "string" && dropped.has(name)) {
+            // 🔴 THE SAME SHAPE `not found` ALREADY HAD, AND ONLY THE SENTENCE CHANGED.
+            // `mcp.js` catches its own `McpError` and answers with an isError
+            // CallToolResult — it does NOT throw — so a refusal that threw would be a
+            // protocol error where every other failure on this surface is a tool
+            // error, and clients treat the two differently. The defect was one
+            // sentence; the fix is one sentence. The code is carried for the client
+            // that reads it, and it is InvalidParams for the same reason the SDK's is.
+            return {
+                content: [{ type: "text", text: `MCP error ${ErrorCode.InvalidParams}: ${droppedToolMessage(name)}` }],
+                isError: true,
+            };
+        }
+        return inner(request, extra);
+    });
+}
 /**
  * Register the always-on `godot://capabilities` resource: a read-only listing of
  * the capability groups, their enabled/disabled state, exactly which tools each
@@ -150,12 +228,23 @@ export function registerCapabilitiesResource(server, enabled) {
                 .filter((name) => (TOOL_CAPABILITIES[name] ?? []).includes(g))
                 .sort(),
         }));
+        // 🔴 BOTH OF THESE ARE DERIVED FROM `CAPABILITY_GROUPS`, AND THAT IS THE
+        // FIX RATHER THAN A TIDY-UP. Until 250 this resource announced "Two
+        // higher-trust tool groups" and offered `'network'` — a group deleted from
+        // this file's own header, whose token `selectPrivilegedGroups` reports as
+        // unknown and ignores. The always-on affordance that exists so a withheld
+        // tool is never a silent gap was telling its reader to type something the
+        // parser refuses. A restated count goes stale in silence; a derived one
+        // cannot, which is 198 §36's rule applied to a sentence instead of a floor.
+        const groupList = CAPABILITY_GROUPS.map((g) => `'${g}'`).join(", ");
         const payload = {
-            summary: "Two higher-trust tool groups are OFF by default. A disabled group's tools are not registered (omitted from tools/list). Enable a group to load its tools.",
+            summary: `${CAPABILITY_GROUPS.length} higher-trust tool group(s) — ${CAPABILITY_GROUPS.join(", ")} — are OFF by default. ` +
+                "A disabled group's tools are not registered (omitted from tools/list), and calling one by name is refused with a message naming this resource — never with `not found`. Enable a group to load its tools.",
             default_secure: enabled.size === 0,
             enabled_groups: [...enabled].sort(),
             dropped_tools: droppedTools(enabled),
-            how_to_enable: "Set BREAKPOINT_PRIVILEGED_GROUPS in the MCP server env (comma-separated): 'code-execution', 'network', 'code-execution,network', or 'all'. Or re-run `npx breakpoint-mcp init` for a guided setup.",
+            how_to_enable: `Set BREAKPOINT_PRIVILEGED_GROUPS in the MCP server env (comma-separated), from: ${groupList}, or 'all'. ` +
+                "Or re-run `npx breakpoint-mcp init --trust full` for a guided setup.",
             groups,
         };
         return {

package/dist/cli/args.js

@@ -1,4 +1,4 @@
-export function parseArgs(argv, booleanFlags = []) {
+export function parseArgs(argv, booleanFlags = [], knownFlags) {
     const bool = new Set(booleanFlags);
     const positionals = [];
     const flags = {};
@@ -35,6 +35,36 @@ export function parseArgs(argv, booleanFlags = []) {
         }
         positionals.push(a);
     }
-    return { positionals, flags };
+    // Computed AFTER the loop rather than inside it, so `--flag=value`,
+    // `--flag value` and the bare boolean forms are all judged by the same rule —
+    // the key that landed in `flags`, however it got there.
+    const known = knownFlags === undefined ? null : new Set([...knownFlags, ...booleanFlags]);
+    const unknown = known === null ? [] : Object.keys(flags).filter((k) => !known.has(k));
+    return { positionals, flags, unknown };
+}
+/**
+ * The two questions every subcommand must answer before it does any work: was
+ * `--help` asked for, and was it handed something it does not accept. Returns
+ * the exit code to return, or `null` to carry on.
+ *
+ * Shared rather than written per subcommand, because written per subcommand it
+ * was answered by exactly ONE of the three. `tools` handled `--help` and kept
+ * its own copy of the text; `doctor` ignored it and ran the checks; `init`
+ * ignored it and fell through to the project check, reporting a missing
+ * `project.godot` — an error about the user's directory in answer to a
+ * question about flags.
+ */
+export function preflight(parsed, subcommand, usage) {
+    if (parsed.flags.help === true || parsed.flags.h === true) {
+        process.stdout.write(usage.join("\n") + "\n");
+        return 0;
+    }
+    if (parsed.unknown.length > 0) {
+        const named = parsed.unknown.map((u) => (u.length === 1 ? `-${u}` : `--${u}`)).join(", ");
+        process.stderr.write(`${subcommand}: unknown ${parsed.unknown.length === 1 ? "option" : "options"} ${named}.\n` +
+            `  Run \`breakpoint-mcp ${subcommand} --help\` for the options this subcommand accepts.\n`);
+        return 2;
+    }
+    return null;
 }
 //# sourceMappingURL=args.js.map