breakpoint-mcp 1.73.4 → 1.74.1

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **291 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **292 tools
 + 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).

package/dist/annotations.js

@@ -1,6 +1,6 @@
 /** Tools that mutate nothing. */
 const READ_ONLY = [
-    "anim_get_track_keys", "anim_list", "backend_detect", "class_reference", "classdb_get_class", "cs_code_action",
+    "anim_get_track_keys", "anim_list", "backend_detect", "breakpoint_doctor", "class_reference", "classdb_get_class", "cs_code_action",
     "cs_completion", "cs_dbg_scopes", "cs_dbg_stack_trace", "cs_dbg_variables", "cs_definition", "cs_diagnostics",
     "cs_document_symbols", "cs_hover", "cs_references", "cs_signature_help", "cs_workspace_symbols", "dbg_scopes",
     "dbg_stack_trace", "dbg_variables", "docs_search", "editor_get_state", "editor_ping", "example_snippet",
@@ -47,7 +47,7 @@ const IDEMPOTENT = [
     "area_set_gravity", "area_set_monitoring", "asset_gen_configure", "asset_gen_placeholder",
     "audio_bus_set_volume", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold", "backend_configure",
     "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
-    "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material", "card_template_create",
+    "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material", "breakpoint_doctor", "card_template_create",
     "class_reference", "classdb_get_class", "cloudsave_scaffold", "control_set_anchors", "control_set_layout_preset",
     "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion", "cs_dbg_attach",
     "cs_dbg_scopes", "cs_dbg_set_breakpoints", "cs_dbg_set_exception_breakpoints", "cs_dbg_set_variable",
@@ -111,7 +111,7 @@ export const ALL_ANNOTATED = [
     "audio_bus_set_volume", "audio_player_create", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold",
     "backend_configure", "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
     "body_create", "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material",
-    "camera_create", "card_deck_from_table", "card_hand_layout", "card_instance", "card_set_face",
+    "breakpoint_doctor", "camera_create", "card_deck_from_table", "card_hand_layout", "card_instance", "card_set_face",
     "card_template_create", "class_reference", "classdb_get_class", "cloudsave_scaffold", "collisionpolygon_add",
     "collisionshape_add", "container_add_child", "control_create", "control_set_anchors",
     "control_set_layout_preset", "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion",

package/dist/bridge.js

@@ -2,6 +2,7 @@ import net from "node:net";
 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";
 export class BridgeError extends Error {
     code;
     constructor(code, message) {
@@ -38,7 +39,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
@@ -201,7 +212,28 @@ export class BridgeClient {
         this.pending.delete(id);
         clearTimeout(p.timer);
         if (msg.ok) {
-            p.resolve(msg.result ?? {});
+            // 🔴 THE ONE PLACE A NON-FINITE ENGINE FLOAT CAN ENTER THE HOST. Godot stringifies
+            // INF as `1e99999`, which is valid JSON, so `JSON.parse` above hands back a real
+            // `Infinity` — accepted by zod 3, refused by zod 4, and turned into `null` by our
+            // own re-serialisation to the client either way.
+            //
+            // 🔴 226 §2: THE POLICY IS PER-METHOD AND IT IS NOT A NULL. Two methods report a
+            // partial reading and prune; every other method REFUSES, naming the path and the
+            // value. Writing `null` into a `z.number()` slot — which is what the first
+            // containment did on 91 tools that never declared it — fails the schema with a
+            // message about the shape, and takes the roster that would have explained it down
+            // with the parse. See finiteness.ts for the population and the measurement.
+            const result = msg.result ?? {};
+            if (TOLERANT_METHODS.has(p.method)) {
+                p.resolve(tolerate(result));
+            }
+            else {
+                const hits = findNonFinite(result);
+                if (hits.length)
+                    p.reject(new BridgeError("non_finite", describeNonFinite(hits)));
+                else
+                    p.resolve(result);
+            }
         }
         else {
             const e = msg.error ?? { code: "unknown", message: "Unknown bridge error" };
@@ -246,7 +278,7 @@ export class BridgeClient {
                 this.ledger.note(id, method, timeoutMs);
                 reject(new BridgeError("timeout", `Bridge request '${method}' timed out after ${timeoutMs}ms`));
             }, timeoutMs);
-            this.pending.set(id, { resolve: resolve, reject, timer });
+            this.pending.set(id, { resolve: resolve, reject, timer, method });
             socket.write(payload, (err) => {
                 if (err) {
                     clearTimeout(timer);

package/dist/capabilities.js

@@ -37,6 +37,17 @@ export const TOOL_CAPABILITIES = {
     // leaderboard_scaffold / cloudsave_scaffold / auth_scaffold — that write the
     // same kind of generated GDScript and were never privileged.
 };
+/**
+ * How many tools the secure default drops, DERIVED rather than restated.
+ *
+ * 🔴 `breakpoint-mcp init` printed "drops the 14 code-execution + network tools"
+ * for as long as this group has had thirteen members — a wrong number in the first
+ * thing a new user reads, on the subject the secure default exists to explain.
+ * Check 25 reads three-digit numerals and this one is two digits; check 11 claims
+ * tool TOTALS and this is a subset of one. NO READER OWNED IT, which is 222 §2's
+ * finding arriving one instrument over, in a string we print to a terminal.
+ */
+export const PRIVILEGED_TOOL_COUNT = Object.keys(TOOL_CAPABILITIES).length;
 /**
  * Parse the raw BREAKPOINT_PRIVILEGED_GROUPS env into a normalized token list
  * (or null for "unset" → no groups → the safe-default surface). Comma/whitespace

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

package/dist/cli/doctor.js

@@ -23,7 +23,8 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../config.js";
 import { CAPABILITY_GROUPS, droppedTools, selectPrivilegedGroups } from "../capabilities.js";
-import { parseArgs } from "./args.js";
+import { parseArgs, preflight } from "./args.js";
+import { DOCTOR_FLAGS, DOCTOR_USAGE } from "./usage.js";
 import { BridgeClient } from "../bridge.js";
 import { resolveBridgeSecret } from "../secret.js";
 const ADDON_REL = "addons/breakpoint_mcp";
@@ -195,7 +196,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 291-tool surface`
+                ? `${state} — full 292-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
             hint: dropped.length === 0
                 ? undefined
@@ -257,7 +258,7 @@ export async function runDoctorChecks(config, opts) {
             name: "editor-bridge",
             host: config.bridgeHost,
             port: config.bridgePort,
-            hint: 'Open the editor with the "Breakpoint MCP" plugin enabled.',
+            hint: 'Open the editor with the "Breakpoint MCP" plugin enabled — and 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).',
             secretEnv: ["BREAKPOINT_BRIDGE_SECRET"],
         },
         {
@@ -344,7 +345,11 @@ function printReport(report) {
 }
 /** Entry point for `breakpoint-mcp doctor`. Returns the process exit code. */
 export async function runDoctor(argv) {
-    const { flags } = parseArgs(argv, ["json", "require-live", "include-csharp"]);
+    const parsed = parseArgs(argv, ["json", "require-live", "include-csharp", "help", "h"], DOCTOR_FLAGS);
+    const pre = preflight(parsed, "doctor", DOCTOR_USAGE);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     if (typeof flags.project === "string")
         process.env.GODOT_PROJECT = flags.project;
     const timeoutRaw = typeof flags.timeout === "string" ? Number.parseInt(flags.timeout, 10) : NaN;

package/dist/cli/init.js

@@ -12,10 +12,11 @@ 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 { parseArgs, preflight } from "./args.js";
+import { INIT_FLAGS, INIT_USAGE } from "./usage.js";
 import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
 import { DEFAULT_REPO, fetchAddonFromGitHub } from "./github.js";
-import { CAPABILITY_GROUPS, parsePrivilegedGroups, selectPrivilegedGroups } from "../capabilities.js";
+import { CAPABILITY_GROUPS, PRIVILEGED_TOOL_COUNT, parsePrivilegedGroups, selectPrivilegedGroups, } from "../capabilities.js";
 /**
  * Resolve the guided trust preset into a validated BREAKPOINT_PRIVILEGED_GROUPS
  * value ("" = the safe default — `code-execution` + `network` off). Accepts either
@@ -147,7 +148,11 @@ function claudeCodeCommand(projectPath, privilegedGroups) {
 }
 /** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
 export async function runInit(argv, deps = {}) {
-    const { flags } = parseArgs(argv, ["force", "dry-run"]);
+    const parsed = parseArgs(argv, ["force", "dry-run", "help", "h"], INIT_FLAGS);
+    const pre = preflight(parsed, "init", INIT_USAGE);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     const projectPath = typeof flags.project === "string"
         ? path.resolve(flags.project)
         : process.env.GODOT_PROJECT ?? process.cwd();
@@ -279,11 +284,11 @@ export async function runInit(argv, deps = {}) {
     // Trust groups — surface the secure default so even a bare `init` teaches it.
     say("");
     if (privilegedGroups) {
-        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 291-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 292-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");
-        say("everyday authoring/debug surface and drops the 14 code-execution + network tools (e.g.");
+        say(`everyday authoring/debug surface and drops the ${PRIVILEGED_TOOL_COUNT} code-execution + network tools (e.g.`);
         say("godot_run_headless_script, the *_call_method / dbg_evaluate tools, asset-gen, backend_*).");
         say("Enable them by re-running with `--trust full` (or `--privileged-groups code-execution,network`),");
         say("or set BREAKPOINT_PRIVILEGED_GROUPS in the server env. The `godot://capabilities` resource and");
@@ -292,7 +297,21 @@ export async function runInit(argv, deps = {}) {
     if (privilegedWarn)
         say(`  note: ${privilegedWarn}`);
     say("");
-    say("Next: open the project in Godot, then run `breakpoint-mcp doctor --require-live` to verify.");
+    // 🔴 THE REOPEN TRAP. Godot reads project.godot's [editor_plugins] at project load and
+    // does not reload it, so an editor that was already running when we wrote the section
+    // keeps the plugin DISABLED — the bridge never starts and every editor-plane tool is
+    // dark, with nothing on screen saying why. The line is conditioned on `en.changed`
+    // because a project whose plugin was already enabled has nothing to reopen for, and a
+    // warning printed on every run is a warning nobody reads.
+    if (!dryRun && en.changed) {
+        say("Next: open the project in Godot — and if it is ALREADY OPEN, close and reopen it.");
+        say("  Godot reads project.godot's [editor_plugins] at project load and does not reload");
+        say("  it, so an editor that was already running keeps the plugin disabled.");
+        say("Then run `breakpoint-mcp doctor --require-live` to verify.");
+    }
+    else {
+        say("Next: open the project in Godot, then run `breakpoint-mcp doctor --require-live` to verify.");
+    }
     process.stdout.write(out.join("\n") + "\n");
     return 0;
 }

package/dist/cli/tools.js

@@ -17,12 +17,13 @@
  * container, and on a machine with no Godot installed.
  *
  * Two surfaces are reported, because the difference is the security story:
- *   • `full`           — all 291 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
- *   • `secure-default` — 278, what an untouched install actually advertises
+ *   • `full`           — all 292 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
+ *   • `secure-default` — 279, what an untouched install actually advertises
  * `--surface` picks which one populates `tools[]`; both counts are always in the
  * header so a consumer cannot report one as the other by accident.
  */
-import { parseArgs } from "./args.js";
+import { parseArgs, preflight } from "./args.js";
+import { TOOLS_FLAGS, TOOLS_USAGE } from "./usage.js";
 import { buildToolsets } from "../toolsets.js";
 import { applyOutputSchemas } from "../schemas.js";
 import { applyAnnotations, annotationsFor } from "../annotations.js";
@@ -148,20 +149,16 @@ function renderText(report) {
     return lines.join("\n");
 }
 export async function runTools(argv) {
-    const { flags } = parseArgs(argv, ["json", "help", "h"]);
-    if (flags.help || flags.h) {
-        process.stdout.write([
-            "breakpoint-mcp tools — export the tool surface (name, risk annotations, capability group).",
-            "",
-            "  --json                Emit JSON (stable, no timestamp — safe to diff between releases).",
-            "  --surface <which>     full | secure-default   (default: secure-default, what an",
-            "                        untouched install actually advertises).",
-            "",
-            "Reads no Godot install and starts no server — the registry is built statically.",
-            "",
-        ].join("\n"));
-        return 0;
-    }
+    const parsed = parseArgs(argv, ["json", "help", "h"], TOOLS_FLAGS);
+    const pre = preflight(parsed, "tools", [
+        ...TOOLS_USAGE,
+        "",
+        "Reads no Godot install and starts no server — the registry is built statically.",
+        "",
+    ]);
+    if (pre !== null)
+        return pre;
+    const { flags } = parsed;
     const raw = typeof flags.surface === "string" ? flags.surface : "secure-default";
     if (raw !== "full" && raw !== "secure-default") {
         process.stderr.write(`unknown --surface "${raw}" (expected: full | secure-default)\n`);

package/dist/cli/usage.js

@@ -0,0 +1,102 @@
+/**
+ * The CLI's help text, in ONE place, split by subcommand.
+ *
+ * It lived in `index.ts`'s `printUsage` as a single flat array, which was fine
+ * while `--help` was the only thing that printed it. It stopped being fine the
+ * moment `breakpoint-mcp init --help` had to print the init section and nothing
+ * else: the alternative to this module is the same twelve lines written twice,
+ * and a help text that disagrees with itself is worse than one that is merely
+ * long. `index.ts` composes the whole document from these parts, so a flag
+ * documented for a subcommand is documented in the top-level help by
+ * construction.
+ *
+ * 🔴 THE ROSTERS BELOW ARE NOT DOCUMENTATION — THEY ARE THE PARSER'S INPUT.
+ * `parseArgs` takes them as `knownFlags` and reports anything else as unknown,
+ * so a flag added to a subcommand and not added here is refused at the command
+ * line rather than silently ignored. That is the whole point of keeping the
+ * prose and the roster in the same file: the pressure to update both is the
+ * same edit.
+ */
+export const HEADLINE = "breakpoint-mcp — MCP server exposing Godot to AI coding assistants.";
+export const SYNOPSIS = [
+    "Usage:",
+    "  breakpoint-mcp             Start the MCP server on stdio (default; how MCP clients launch it).",
+    "  breakpoint-mcp init        Install + enable the editor addon in a project and wire the MCP client.",
+    "  breakpoint-mcp doctor      Check the Godot binary, the editor addon, and the four bridges.",
+    "  breakpoint-mcp tools       Export the tool surface + risk annotations (for catalogs / reviews).",
+    "  breakpoint-mcp --help      Show this help.",
+    "  breakpoint-mcp --version   Print the installed version and exit.",
+    "",
+    "Every subcommand also accepts --help.",
+];
+export const INIT_USAGE = [
+    "Usage: breakpoint-mcp init [options]",
+    "",
+    "Install + enable the editor addon in a Godot project and wire the MCP client.",
+    "",
+    "init options:",
+    "  --project <dir>     Target Godot project (default: $GODOT_PROJECT or the current directory).",
+    "  --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).",
+    "  --trust <level>     secure | full. `full` enables every higher-trust group (default: secure).",
+    "  --privileged-groups <a,b>  Enable named higher-trust groups instead of all of them.",
+];
+export const DOCTOR_USAGE = [
+    "Usage: breakpoint-mcp doctor [options]",
+    "",
+    "Check the Godot binary, the editor addon, and the four bridges.",
+    "",
+    "doctor options:",
+    "  --project <dir>     Project to check (default: $GODOT_PROJECT or the current directory).",
+    "  --require-live      Also require the editor/runtime/LSP/DAP bridges to be reachable.",
+    "  --include-csharp    Also probe OmniSharp / netcoredbg on PATH (the C# planes).",
+    "  --timeout <ms>      Per-bridge connect timeout (default 1500).",
+    "  --json              Emit the report as JSON.",
+];
+export const TOOLS_USAGE = [
+    "Usage: breakpoint-mcp tools [options]",
+    "",
+    "Export the tool surface + risk annotations (for catalogs / reviews).",
+    "",
+    "tools options:",
+    "  --surface <which>   full | secure-default (default: secure-default, what an untouched install advertises).",
+    "  --json              Emit the surface as JSON — stable and timestamp-free, so releases can be diffed.",
+];
+/** Every flag `init` accepts. Booleans are declared at the call site. */
+export const INIT_FLAGS = [
+    "project",
+    "client",
+    "from-github",
+    "repo",
+    "trust",
+    "privileged-groups",
+];
+/** Every flag `doctor` accepts. */
+export const DOCTOR_FLAGS = ["project", "timeout"];
+/** Every flag `tools` accepts. */
+export const TOOLS_FLAGS = ["surface"];
+/** The whole document, composed — what `breakpoint-mcp --help` prints. */
+export function fullUsage() {
+    // Each subcommand block contributes only its own `<name> options:` tail; the
+    // per-subcommand synopsis above it would read as four competing headlines in
+    // a single document.
+    const tail = (block) => block.slice(block.findIndex((l) => l.endsWith("options:")));
+    return [
+        HEADLINE,
+        "",
+        ...SYNOPSIS,
+        "",
+        ...tail(INIT_USAGE),
+        "",
+        ...tail(DOCTOR_USAGE),
+        "",
+        ...tail(TOOLS_USAGE),
+        "",
+        "All runtime configuration is via environment variables; see the README.",
+        "",
+    ];
+}
+//# sourceMappingURL=usage.js.map

package/dist/finiteness.js

@@ -0,0 +1,175 @@
+/**
+ * Non-finite engine floats, contained at the one place they enter the host.
+ *
+ * 🔴 224 §7.3 ASKED WHETHER GODOT'S PERFORMANCE MONITORS CAN EMIT `INF` THROUGH
+ * `runtime_get_monitors`, and called it "the only item that can break a working tool
+ * silently in production rather than loudly in CI". Measured on Godot 4.7 headless in
+ * session 225, every hop:
+ *
+ *   Godot `JSON.stringify(INF)`  ->  `1e99999`   — VALID JSON, so `JSON.parse` gives Infinity
+ *   Godot `JSON.stringify(NAN)`  ->  `null`      — plus a one-shot engine warning
+ *   zod 3 `z.number()`           ->  ACCEPTS ±Infinity, REJECTS NaN
+ *   zod 4 `z.number()`           ->  REJECTS both
+ *   host -> MCP client           ->  `JSON.stringify(Infinity)` is `null`
+ *
+ * The answer is yes, and it needs no engine edge case at all: a client sending
+ * `"baseline": 1e999` to `runtime_assert_perf` round-trips through the addon as `inf`.
+ *
+ * 🔴 226 §2 — AND THE FIRST CONTAINMENT WAS SCOPED TO A ROSTER OF TWO. Session 225 put
+ * this walk at the single `JSON.parse` in `bridge.ts`, which is the right place, and then
+ * widened exactly the two schemas it had been thinking about. Measured off the shipped
+ * wire rather than the roster:
+ *
+ *     bridge-routed tools carrying >=1 non-nullable number field    93
+ *     their non-nullable number field paths                        243
+ *     of those, declaring `non_finite`                                2
+ *
+ * Replacing a non-finite reading with `null` on the other 91 turns a silent wrong value
+ * into a HARD SCHEMA REFUSAL whose message blames the shape — `current: Expected number,
+ * received null` — and the `non_finite` roster that would have explained it is destroyed
+ * by the very parse that fails, because those 91 schemas do not declare the key. That is
+ * 225 §5's own finding one layer out: a coherent, specific message about the wrong cause.
+ *
+ * SO THE POLICY IS SPLIT, AND BOTH HALVES ARE DERIVED RATHER THAN CHOSEN:
+ *
+ *  - DEFAULT — REFUSE, NAMING THE PATH AND THE VALUE. A non-finite number anywhere in a
+ *    bridge reply rejects the call with code `non_finite` and a message that says which
+ *    dotted path carried it and what it was. Loud, accurate, and — because no schema
+ *    moves — invisible to `tools/list`. This is a strictly better failure than either
+ *    1.73.4 (silent `null` on the wire) or the first containment (a shape complaint).
+ *
+ *  - TOLERANT — PRUNE AND ROSTER, for the tools whose whole job is a partial reading.
+ *    `NON_FINITE_TOLERANT` below is the only place that set is written down, and
+ *    `finiteness.test.ts` asserts it equals the set of shipped schemas declaring
+ *    `non_finite`, in BOTH directions. A tool cannot join one without joining the other.
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO: widen a number to `number | null`. 225's note said
+ * "the numeric contract is not redefined … older clients are unaffected"; `wire_diff.mjs`
+ * classified that same change MAJOR at four field paths. The prose and the classifier
+ * disagreed and the classifier was right. Nothing here moves a declared type — every
+ * shipped `outputSchema` is byte-identical to v1.73.4 except for the OPTIONAL
+ * `non_finite` roster added to the two tolerant tools, which is what took the cut's
+ * classification from MAJOR back to MINOR.
+ */
+/** The key a tolerant reply carries when something was pruned. Optional in the schemas. */
+export const NON_FINITE_KEY = "non_finite";
+/**
+ * The tools that report a PARTIAL reading rather than refusing, keyed to the addon method
+ * `bridge.ts` matches on.
+ *
+ * 🔴 THIS IS THE ONLY WRITTEN-DOWN COPY OF THAT SET. `finiteness.test.ts` asserts, both
+ * ways, that its keys are exactly the shipped schemas declaring `non_finite` and that
+ * every method value is actually called by `tools/runtime.ts` — so the set cannot drift
+ * from the wire, and a rename cannot orphan an entry. 225 §9's carried finding is that
+ * every scope is prose until something derives it; this one is asserted against two
+ * independent readers.
+ */
+export const NON_FINITE_TOLERANT = new Map([
+    ["runtime_get_monitors", "runtime.get_monitors"],
+    ["runtime_assert_perf", "runtime.assert_perf"],
+]);
+/** The addon methods whose replies are pruned instead of refused. */
+export const TOLERANT_METHODS = new Set(NON_FINITE_TOLERANT.values());
+/** How deep the walk goes. Bridge replies are shallow; the cap is a runaway guard, and it
+ *  is asserted rather than assumed — see `finiteness.test.ts`'s depth case. */
+const MAX_DEPTH = 64;
+/** `Infinity` / `-Infinity` / `NaN` as a word. `String(NaN)` is already "NaN". */
+function word(n) {
+    return Number.isNaN(n) ? "NaN" : n > 0 ? "Infinity" : "-Infinity";
+}
+/**
+ * Every non-finite number in `value`, in encounter order. Pure: allocates one array and
+ * never copies the input, so the normal path — which is every real reply — costs one walk
+ * and returns the empty list.
+ */
+export function findNonFinite(value) {
+    const hits = [];
+    const walk = (v, path, depth) => {
+        if (typeof v === "number") {
+            if (!Number.isFinite(v))
+                hits.push({ path: path || "(root)", value: word(v) });
+            return;
+        }
+        if (v === null || typeof v !== "object" || depth >= MAX_DEPTH)
+            return;
+        if (Array.isArray(v)) {
+            v.forEach((item, i) => walk(item, `${path}[${i}]`, depth + 1));
+            return;
+        }
+        for (const [k, item] of Object.entries(v)) {
+            walk(item, path ? `${path}.${k}` : k, depth + 1);
+        }
+    };
+    walk(value, "", 0);
+    return hits;
+}
+/**
+ * The refusal message. It names the paths and the values, because the whole point of
+ * refusing here rather than at the schema is that the schema cannot say either.
+ * Capped so a pathological reply cannot produce an unbounded error string; the cap is
+ * asserted in `finiteness.test.ts` rather than trusted.
+ */
+export const MESSAGE_CAP = 8;
+export function describeNonFinite(hits) {
+    const shown = hits.slice(0, MESSAGE_CAP).map((h) => `${h.path}=${h.value}`).join(", ");
+    const rest = hits.length > MESSAGE_CAP ? ` (+${hits.length - MESSAGE_CAP} more)` : "";
+    return (`The engine returned ${hits.length} non-finite number(s) this reply: ${shown}${rest}. ` +
+        `JSON cannot carry them — Godot stringifies INF as 1e99999 and NAN as null — so the ` +
+        `call is refused rather than reported as a success with the value silently missing.`);
+}
+/**
+ * Drop every non-finite value from a flat monitor record, returning what survived and the
+ * keys that did not. The declared type of the record does not move: a reading that is not
+ * a number is ABSENT, not `null`, and `non_finite` is where it says so.
+ */
+export function pruneRecord(rec) {
+    const kept = {};
+    const dropped = [];
+    if (rec === null || typeof rec !== "object" || Array.isArray(rec))
+        return { kept, dropped };
+    for (const [k, v] of Object.entries(rec)) {
+        if (typeof v === "number" && Number.isFinite(v))
+            kept[k] = v;
+        else
+            dropped.push(k);
+    }
+    return { kept, dropped };
+}
+/**
+ * The tolerant policy for the two partial-reading tools: prune `monitors`, drop any
+ * comparison row that cannot be compared, and roster every key that left.
+ *
+ * 🔴 A DROPPED COMPARISON IS NOT A PASSED ONE. `ok` and `checked` are left exactly as the
+ * addon computed them — this host does not re-decide the assertion — but a key that could
+ * not be read appears in `non_finite`, so a caller reading `ok: true` alongside a
+ * non-empty roster can see that the two statements are about different key sets.
+ */
+export function tolerate(result) {
+    if (result === null || typeof result !== "object" || Array.isArray(result))
+        return result;
+    const src = result;
+    const roster = new Set();
+    const out = { ...src };
+    if ("monitors" in src) {
+        const { kept, dropped } = pruneRecord(src.monitors);
+        if (dropped.length) {
+            out.monitors = kept;
+            dropped.forEach((k) => roster.add(k));
+        }
+    }
+    if (Array.isArray(src.regressions)) {
+        const rows = src.regressions;
+        const survivors = rows.filter((row) => {
+            const bad = ["baseline", "current"].some((f) => typeof row?.[f] === "number" && !Number.isFinite(row[f]));
+            if (bad)
+                roster.add(typeof row?.key === "string" ? row.key : "(unnamed)");
+            return !bad;
+        });
+        if (survivors.length !== rows.length)
+            out.regressions = survivors;
+    }
+    if (roster.size === 0)
+        return result;
+    return { ...out, [NON_FINITE_KEY]: [...roster] };
+}
+//# sourceMappingURL=finiteness.js.map

package/dist/index.js

@@ -9,6 +9,7 @@ import { CsLspClient } from "./cslsp.js";
 import { CsDapClient } from "./csdap.js";
 import { StdioChannel } from "./stdio.js";
 import { DapClient } from "./dap.js";
+import { fullUsage } from "./cli/usage.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
 import { applyWireDefaults } from "./wire-defaults.js";
@@ -42,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.73.4" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.74.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // 208 §7.1 — delete from the wire what the protocol already says: the SDK's
     // draft-07 `$schema` inside every input/output schema (MCP's default dialect is
     // 2020-12, and declaring another is an explicit switch a peer may reject), and
@@ -73,14 +74,14 @@ async function main() {
     // Capability groups — a risk-based axis over the toolsets. `code-execution` is
     // OFF by default; a disabled group's tools are DROPPED at
     // registration (omitted from tools/list), so the secure-default surface is
-    // 291 − 13 = 278 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
+    // 292 − 13 = 279 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
     // server.registerTool AFTER applyOutputSchemas (schema wrapper stays innermost).
     const privilegedGroups = selectPrivilegedGroups(config.privilegedGroups, (unknown) => log(`ignoring unknown BREAKPOINT_PRIVILEGED_GROUPS token(s): ${unknown.join(", ")}`));
     applyCapabilities(server, privilegedGroups);
     // The A/B/C/D planes ARE the grouping. Build the ordered toolset registry
     // (the single source of truth, shared with the registration tests) and
     // register only the selected groups. Default (BREAKPOINT_TOOLSETS unset) =
-    // every group → the full 291-tool surface, byte-identical to before. A filter
+    // every group → the full 292-tool surface, byte-identical to before. A filter
     // lets a client that can't defer tools, or a user who wants a smaller default
     // menu, load only the planes a project needs (GitHub-MCP `--toolsets` style).
     let processes;
@@ -120,7 +121,7 @@ async function main() {
         log(`toolsets enabled: ${[...enabled].sort().join(", ")} (${enabled.size}/${toolsets.length} groups)`);
     }
     // Recipes: a free, curated task-recipe layer exposed as MCP prompts (discoverable
-    // via prompts/list). Adds NO tools — the 291-tool count is unchanged — and drives
+    // via prompts/list). Adds NO tools — the 292-tool count is unchanged — and drives
     // the enforced tools above, so it's a skill-pack layer over typed/undoable tools.
     registerRecipes(server);
     // Always-on capability affordance — never behind a toolset or a privileged
@@ -160,42 +161,26 @@ async function main() {
     process.on("SIGTERM", shutdown);
 }
 function printUsage() {
-    process.stdout.write([
-        "breakpoint-mcp — MCP server exposing Godot to AI coding assistants.",
-        "",
-        "Usage:",
-        "  breakpoint-mcp             Start the MCP server on stdio (default; how MCP clients launch it).",
-        "  breakpoint-mcp init        Install + enable the editor addon in a project and wire the MCP client.",
-        "  breakpoint-mcp doctor      Check the Godot binary, the editor addon, and the four bridges.",
-        "  breakpoint-mcp tools       Export the tool surface + risk annotations (for catalogs / reviews).",
-        "  breakpoint-mcp --help      Show this help.",
-        "",
-        "init options:",
-        "  --project <dir>     Target Godot project (default: $GODOT_PROJECT or the current directory).",
-        "  --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).",
-        "  --require-live      Also require the editor/runtime/LSP/DAP bridges to be reachable.",
-        "  --include-csharp    Also probe OmniSharp / netcoredbg on PATH (the C# planes).",
-        "  --timeout <ms>      Per-bridge connect timeout (default 1500).",
-        "  --json              Emit the report as JSON.",
-        "",
-        "tools options:",
-        "  --surface <which>   full | secure-default (default: secure-default, what an untouched install advertises).",
-        "  --json              Emit the surface as JSON — stable and timestamp-free, so releases can be diffed.",
-        "",
-        "All runtime configuration is via environment variables; see the README.",
-        "",
-    ].join("\n"));
+    process.stdout.write(fullUsage().join("\n"));
 }
-// Subcommand dispatch. Anything that isn't a recognized subcommand — including
-// no arguments at all, which is how every MCP client launches this — falls
-// through to the stdio server, so the server's launch contract is unchanged.
+// Subcommand dispatch. NO arguments at all is how every MCP client launches
+// this — every invocation in the README, the user guide and `init`'s own
+// emitted config passes the binary an empty argv — so that case, and only that
+// case, starts the stdio server. The launch contract is unchanged.
+//
+// 🔴 WHAT CHANGED IS THE FALL-THROUGH, WHICH USED TO SWALLOW EVERYTHING ELSE.
+// `breakpoint-mcp --version` started a server. So did `-v`, `version`, and any
+// mistyped flag: the process printed one ready line and then sat on a stdin
+// nobody was going to speak MCP into, which in a terminal is a hang. The two
+// halves of that are separate defects and both are user-facing:
+//
+//   * There was NO WAY TO ASK THIS BINARY ITS VERSION. `--version` is the most
+//     universal convention a CLI has, and the first thing anyone filing a bug
+//     report is asked for. A project with 0 issues against ~3,700 downloads
+//     cannot afford a version query that hangs the terminal instead.
+//   * An unrecognized token is a TYPO, and the only useful thing to do with one
+//     is name it. Falling through spends the user's next twenty minutes on the
+//     wrong question.
 void (async () => {
     const sub = process.argv[2];
     if (sub === "doctor") {
@@ -214,6 +199,20 @@ void (async () => {
         printUsage();
         process.exit(0);
     }
+    if (sub === "version" || sub === "--version" || sub === "-v" || sub === "-V") {
+        // Bare, so `breakpoint-mcp --version` is usable in a shell substitution.
+        // Read from package.json rather than written here: see version.ts on the
+        // twenty releases that announced 0.2.0 to every LSP server they met.
+        const { packageVersion } = await import("./version.js");
+        process.stdout.write(`${packageVersion()}\n`);
+        process.exit(0);
+    }
+    if (sub !== undefined) {
+        process.stderr.write(`breakpoint-mcp: unknown argument '${sub}'.\n` +
+            "  Run `breakpoint-mcp --help` for the subcommands and their options.\n" +
+            "  To start the MCP server, run it with no arguments — that is how MCP clients launch it.\n");
+        process.exit(2);
+    }
     await main();
 })().catch((err) => {
     log("fatal:", err instanceof Error ? err.stack ?? err.message : String(err));

package/dist/peers.js

@@ -6,7 +6,7 @@ import { portFree } from "./ports.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
- * Four, not the eight a rival offers. Four headless Godot instances is already a
+ * Four, not the eight an alternative offers. Four headless Godot instances is already a
  * heavy CI runner, the convergence cases that matter are covered at four, and
  * every extra instance multiplies the flake surface of the one feature whose
  * entire selling point is that it does NOT flake. Raise it on evidence, never

package/dist/recipes.js

@@ -7,7 +7,7 @@
  * it's **free** (MIT, shipped in the server), and it sits **over typed,
  * schema-validated, undoable tools** — so the contract is executed by the
  * server, not merely described in prose the model might misapply. Recipes are
- * discoverable via MCP `prompts/list`; they add **no tools** (the 291-tool
+ * discoverable via MCP `prompts/list`; they add **no tools** (the 292-tool
  * count is unchanged) and cost nothing until a client pulls one.
  */
 import { z } from "zod";

package/dist/schemas.js

@@ -71,6 +71,17 @@ const engineLog = {
 /** name -> ZodRawShape describing that tool's structuredContent. */
 export const outputSchemas = {
     // ---- Plane B: headless CLI (tools/cli.ts) ----
+    breakpoint_doctor: {
+        ok: z.boolean(),
+        failed: z.number(),
+        checks: z.array(z.object({
+            name: z.string(),
+            status: z.string(),
+            severity: z.string(),
+            detail: z.string(),
+            hint: z.string().optional(),
+        })),
+    },
     godot_version: { version: z.string(), raw: capturedRaw },
     godot_launch_editor: { launched: z.boolean(), pid: z.number().nullable(), project: z.string() },
     godot_run_project: { running: z.boolean(), pid: z.number().nullable(), scene: z.string().nullable() },
@@ -203,7 +214,7 @@ export const outputSchemas = {
     resource_duplicate: { duplicated: z.string(), from: z.string(), deep: z.boolean() },
     resource_get_property: { path: z.string(), property: z.string(), value: encodedValue },
     resource_set_property: { path: z.string(), property: z.string(), value: encodedValue },
-    resource_get_import_settings: { path: z.string(), imported: z.boolean(), importer: z.string(), settings: z.record(encodedValue) },
+    resource_get_import_settings: { path: z.string(), imported: z.boolean(), importer: z.string(), settings: z.record(z.string(), encodedValue) },
     // `changed` (1.46.0) is narrower than `settings`: `settings` lists every key the call
     // SET, `changed` only those whose stored value actually moved. Setting a key to the
     // value it already held reported `reimported: true` with the sidecar's bytes unmoved
@@ -506,7 +517,15 @@ export const outputSchemas = {
     runtime_call_method: { ...engineLog, return: encodedValue },
     runtime_emit_signal: { ...engineLog, emitted: z.boolean() },
     runtime_inject_input: { ...engineLog, injected: z.boolean(), kind: z.string() },
-    runtime_get_monitors: { ...engineLog, monitors: z.record(z.number()) },
+    // `monitors` values are `Performance.get_monitor()` readings, so they are engine floats
+    // and can be non-finite. 🔴 226 §2: a reading that is not a number is ABSENT from
+    // `monitors` and named in `non_finite` — it is NOT `null`. The value type does not move,
+    // so this schema is byte-identical to v1.73.4 apart from the optional roster, and
+    // arithmetic over `Object.values(monitors)` keeps working on every key it can see.
+    runtime_get_monitors: { ...engineLog,
+        monitors: z.record(z.string(), z.number()),
+        non_finite: z.array(z.string()).optional(),
+    },
     runtime_get_log: { ...engineLog,
         entries: z.array(z.object({ seq: z.number(), level: z.string(), message: z.string() })),
         latest_seq: z.number(),
@@ -530,6 +549,14 @@ export const outputSchemas = {
             actual: encodedValue.optional(),
         })),
     },
+    // Same source as runtime_get_monitors for `current`/`monitors`. 🔴 `baseline` was the
+    // CLIENT's own number echoed back through the addon (`float(baseline[key])` in
+    // runtime_bridge.gd), and `1e999` in a request parses to `inf` in GDScript — the field
+    // reachable from a well-formed call with no engine edge case at all. 226 §2 closes that
+    // at the DOOR instead: the input schema now takes `z.number().finite()`, which refuses
+    // `1e999` on the way in and emits an identical JSON Schema, so neither side of this
+    // tool's wire moves. A row that cannot be compared is DROPPED and its key named in
+    // `non_finite`; `ok` and `checked` stay exactly as the addon computed them.
     runtime_assert_perf: { ...engineLog,
         ok: z.boolean(),
         checked: z.number(),
@@ -539,7 +566,8 @@ export const outputSchemas = {
             current: z.number(),
             direction: z.string(),
         })),
-        monitors: z.record(z.number()),
+        monitors: z.record(z.string(), z.number()),
+        non_finite: z.array(z.string()).optional(),
     },
     runtime_assert_screen_text: { ...engineLog,
         ok: z.boolean(),
@@ -574,7 +602,7 @@ export const outputSchemas = {
     // F4 additions: deterministic playtesting (time control / frame stepping / state digest / RNG seed).
     runtime_time_scale: { ...engineLog, previous: z.number(), current: z.number() },
     runtime_step_frames: { ...engineLog, frames_advanced: z.number(), frame_index: z.number() },
-    runtime_state_digest: { ...engineLog, digest: z.record(z.record(encodedValue)), node_count: z.number() },
+    runtime_state_digest: { ...engineLog, digest: z.record(z.string(), z.record(z.string(), encodedValue)), node_count: z.number() },
     runtime_seed_rng: { ...engineLog, seed: z.number() },
     // F6 additions: multi-peer deterministic playtesting (spawn / stop / converge).
     runtime_spawn_peers: {
@@ -589,7 +617,7 @@ export const outputSchemas = {
     },
     runtime_peer_stop: { stopped: z.array(z.string()) },
     runtime_peers_digest: {
-        digests: z.array(z.object({ id: z.string(), digest: z.record(z.record(encodedValue)), node_count: z.number() })),
+        digests: z.array(z.object({ id: z.string(), digest: z.record(z.string(), z.record(z.string(), encodedValue)), node_count: z.number() })),
         converged: z.boolean(),
         diverged_at: z.array(z.string()).nullable(),
     },

package/dist/tasks.js

@@ -8,7 +8,7 @@ import { log } from "./logger.js";
  * Long, run-to-completion tools (headless export / import / script runs) used to
  * emit ad-hoc `notifications/progress`. They now register under the spec's task
  * model: a call creates a task, returns a handle immediately, and the client
- * drives it with tasks/get (poll), tasks/result (await), and tasks/cancel
+ * drives it with tasks/get (poll) and tasks/cancel
  * (stop). Plain, non-task clients are unaffected — the SDK auto-creates a task,
  * polls it to completion, and returns the result synchronously.
  */
@@ -20,6 +20,18 @@ export const TASK_POLL_INTERVAL_MS = 500;
  * Server capabilities advertising the task-execution model for tools/call.
  * Passed to the McpServer constructor so the SDK installs the tasks/get,
  * tasks/result, tasks/list and tasks/cancel request handlers.
+ *
+ * Revision 2026-07-28 removes all four from CORE: tasks/result and tasks/list have
+ * no successor anywhere, while tasks/get and tasks/cancel survive only inside the
+ * io.modelcontextprotocol/tasks extension. The handlers stay while we negotiate
+ * 2025-11-25 — they are the SDK's, and this comment is not shipped to a client.
+ *
+ * 🔴 THIS COMMENT USED TO ASSERT "no shipped tool description advertises them".
+ * Nothing checked that, and it was ALREADY FALSE for tasks/get and tasks/cancel on
+ * the day it was written — three descriptions in tools/cli.ts named both. An
+ * exemption a gate cannot verify is a promise. scripts/spec_conformance.py now
+ * measures the claim instead of restating it, and refuses on a shipped string that
+ * names a method the current revision removed.
  */
 export const TASK_CAPABILITIES = {
     tasks: { requests: { tools: { call: {} } } },
@@ -70,7 +82,8 @@ function errorResult(message) {
  * ToolTaskHandler. createTask registers the task, launches the work in the
  * background, and returns the handle immediately; the background settle stores
  * the result — which the SDK turns into a notifications/tasks/status update and
- * uses to satisfy any pending tasks/result long-poll.
+ * uses to satisfy any pending tasks/result long-poll. Both names are 2025-11-25's;
+ * see TASK_CAPABILITIES above for what 2026-07-28 does to them.
  */
 function makeTaskHandler(name, worker) {
     const shape = outputSchemas[name];

package/dist/tools/cli.js

@@ -6,6 +6,7 @@ import { registerTaskTool } from "../tasks.js";
 import { ok, failPath } from "./lsp-common.js";
 import { resolveInsideProject } from "../paths.js";
 import { portFree, portConflictMessage } from "../ports.js";
+import { runDoctorChecks } from "../cli/doctor.js";
 const execFileAsync = promisify(execFile);
 /** Run the Godot binary to completion, capturing stdout/stderr. */
 async function runCaptured(cfg, args, timeoutMs, signal) {
@@ -102,7 +103,7 @@ export function registerCliTools(server, cfg) {
     registerTaskTool(server, "godot_export", {
         title: "Export project",
         description: "Headless export using an export preset. Runs to completion and returns exit code + logs. Can be slow — " +
-            "exposed as an MCP task, so task-aware clients can poll, await, or cancel it (tasks/get, tasks/result, tasks/cancel).",
+            "exposed as an MCP task, so a task-aware client can poll it or cancel it while it runs.",
         inputSchema: {
             preset: z.string().describe("Export preset name as defined in export_presets.cfg"),
             output_path: z.string().describe("Output file path for the exported build"),
@@ -137,7 +138,7 @@ export function registerCliTools(server, cfg) {
     registerTaskTool(server, "godot_import", {
         title: "Import assets",
         description: "Headless (re)import of project assets. Runs to completion and returns exit code + logs. " +
-            "Exposed as an MCP task (poll/await/cancel via tasks/get, tasks/result, tasks/cancel).",
+            "Exposed as an MCP task, so a task-aware client can poll it or cancel it while it runs.",
         inputSchema: {
             timeout_ms: z.number().int().positive().optional().describe("Max run time (default 600000)"),
         },
@@ -149,7 +150,7 @@ export function registerCliTools(server, cfg) {
         title: "Run headless script",
         description: "Run a GDScript in headless mode (godot --headless -s <script>). Use this to invoke test runners " +
             "(GdUnit4 / GUT) or any batch tool. Returns exit code + logs. Exposed as an MCP task, so a long test " +
-            "run can be polled, awaited, or cancelled (tasks/get, tasks/result, tasks/cancel).",
+            "run can be polled or cancelled while it is in flight.",
         inputSchema: {
             script_path: z.string().describe("Script to execute, e.g. res://addons/gdUnit4/bin/GdUnitCmdTool.gd"),
             args: z.array(z.string()).optional().describe("Extra CLI args passed after the script"),
@@ -176,5 +177,45 @@ export function registerCliTools(server, cfg) {
             stderr: tail(r.stderr),
         });
     });
+    // 🔴 D4, CARRIED SINCE 205 — THE DIAGNOSTIC THE PERSON WHO NEEDS IT CANNOT REACH.
+    // `breakpoint-mcp doctor` has shipped for many versions and answers exactly this
+    // question. It is a TERMINAL command, and a user whose bridge is not running is
+    // not in a terminal — they are in a conversation, watching an editor_* tool fail
+    // with a connect error and no idea which of the addon, the editor, the port or
+    // the secret is the one that is wrong. The assistant could not look. Now it can.
+    //
+    // Same `runDoctorChecks` the CLI drives, so the two can never disagree. It takes
+    // the ALREADY-LOADED server Config rather than calling loadConfig() — `runDoctor`
+    // mutates process.env.GODOT_PROJECT before loading, and doing that inside a tool
+    // handler would reconfigure the live server out from under every other tool.
+    server.registerTool("breakpoint_doctor", {
+        title: "Diagnose the setup",
+        description: "Check this Breakpoint MCP setup end to end: the Godot binary, the editor addon's install and " +
+            "enable state, the capability groups in force, and the editor/runtime/LSP/DAP bridges. Returns a " +
+            "per-check status with a hint for anything wrong. Read-only — run it first when an editor_*, " +
+            "runtime_*, gd_* or dbg_* tool fails to connect.",
+        inputSchema: {
+            require_live: z
+                .boolean()
+                .optional()
+                .describe("Treat an unreachable bridge as a failure rather than information (default false)"),
+            include_csharp: z
+                .boolean()
+                .optional()
+                .describe("Also probe OmniSharp / netcoredbg on PATH (the C# planes)"),
+            timeout_ms: z.number().int().positive().optional().describe("Per-bridge connect timeout (default 1500)"),
+        },
+    }, async ({ require_live, include_csharp, timeout_ms }) => {
+        const report = await runDoctorChecks(cfg, {
+            timeoutMs: timeout_ms ?? 1500,
+            requireLive: require_live ?? false,
+            includeCsharp: include_csharp ?? false,
+        });
+        return ok({
+            ok: report.ok,
+            failed: report.checks.filter((c) => c.status === "fail").length,
+            checks: report.checks,
+        });
+    });
 }
 //# sourceMappingURL=cli.js.map

package/dist/tools/editor/resource.js

@@ -14,7 +14,7 @@ export function registerResourceTools(server, call, guard) {
         inputSchema: {
             class_name: z.string().describe("Resource subclass to instantiate, e.g. StyleBoxFlat, Theme, GDScript"),
             to_path: z.string().describe("Destination res:// path, e.g. res://styles/panel.tres"),
-            properties: z.record(z.any()).optional().describe("Initial property values (JSON scalars or __type__-tagged Variants)"),
+            properties: z.record(z.string(), z.any()).optional().describe("Initial property values (JSON scalars or __type__-tagged Variants)"),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },
     }, async ({ class_name, to_path, properties, confirm }) => {
@@ -130,7 +130,7 @@ export function registerResourceTools(server, call, guard) {
         description: "Update import parameters in an asset's .import metadata and trigger a reimport. DESTRUCTIVE (rewrites metadata + reimports) — gated by confirmation. Errors not_found when the path is not a file, not_imported when the file has no .import sidecar. `settings` echoes every key set; `changed` lists only those whose stored value actually moved, so a no-op is distinguishable from a real edit.",
         inputSchema: {
             path: z.string().describe("Asset res:// path"),
-            settings: z.record(z.any()).describe("Import params to set (name -> JSON scalar or __type__-tagged Variant)"),
+            settings: z.record(z.string(), z.any()).describe("Import params to set (name -> JSON scalar or __type__-tagged Variant)"),
             reimport: z.boolean().optional().describe("Reimport after writing (default true)"),
             confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
         },

package/dist/tools/runtime.js

@@ -228,7 +228,7 @@ export function registerRuntimeTools(server, runtime, peers, config) {
         inputSchema: {
             path: z.string().describe("Node path (relative to the current scene; '/root/...' absolute allowed)"),
             expect: z
-                .record(z.any())
+                .record(z.string(), z.any())
                 .describe("Map of property name -> expected value (JSON; use the tagged-Variant form for complex types like Vector2/Color)"),
             tolerance: z
                 .number()
@@ -259,8 +259,14 @@ export function registerRuntimeTools(server, runtime, peers, config) {
             "Capture the baseline earlier with runtime_get_monitors and pass it back inline. Pass direction is inferred " +
             "(time/fps is higher-better; every other monitor is lower-better) unless overridden per key.",
         inputSchema: {
+            // 🔴 226 §2 — `.finite()` REFUSES `1e999` AT THE DOOR AND MOVES NO BYTE ON THE
+            // WIRE. `zodToJsonSchema` emits `{"type":"number"}` for both forms, measured, so
+            // this narrows what the host accepts without changing what it advertises. Before
+            // it, a well-formed call carrying `1e999` reached `float(baseline[key])` in
+            // runtime_bridge.gd as `inf` and came back as `1e99999` — the one non-finite path
+            // in this tree that needed no engine edge case at all.
             baseline: z
-                .record(z.number())
+                .record(z.string(), z.number().finite())
                 .describe("Monitor key -> baseline value (capture earlier via runtime_get_monitors)"),
             tolerance: z
                 .number()
@@ -268,7 +274,7 @@ export function registerRuntimeTools(server, runtime, peers, config) {
                 .optional()
                 .describe("Fractional tolerance applied to each comparison (default 0 = exact)"),
             direction: z
-                .record(z.enum(["higher_better", "lower_better"]))
+                .record(z.string(), z.enum(["higher_better", "lower_better"]))
                 .optional()
                 .describe("Per-key override of the pass direction (defaults: time/fps higher_better, else lower_better)"),
             ...peerField,

package/dist/tools/tabletop.js

@@ -1526,7 +1526,7 @@ export function registerTabletopTools(server, bridge, config) {
         inputSchema: {
             template_path: z.string().describe("Card template scene, e.g. res://ui/cards/Card.tscn"),
             parent: z.string().describe("Node path to parent the instance under (in the open scene); \".\" for the root"),
-            data: z.record(z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value; a texture slot takes a res:// path"),
+            data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value; a texture slot takes a res:// path"),
             position: z.object({ x: z.number(), y: z.number() }).optional().describe("Local position of the instance"),
             face_up: z.boolean().optional().describe("Show the face (default true); false shows the back on two-sided cards"),
             name: z.string().optional().describe("Optional node name for the instance"),
@@ -1556,7 +1556,7 @@ export function registerTabletopTools(server, bridge, config) {
             template_path: z.string().describe("Card template scene, e.g. res://ui/cards/Card.tscn"),
             parent: z.string().describe("Container node path the cards are instanced under; \".\" for the root"),
             cards: z.array(z.object({
-                data: z.record(z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value for this card"),
+                data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value for this card"),
                 face_up: z.boolean().optional().describe("Show the face (default true)"),
             })).min(1).describe("One entry per card to instance"),
             mode: z.enum(["row", "fan", "stack", "grid"]).describe("Arrangement mode"),
@@ -1589,7 +1589,7 @@ export function registerTabletopTools(server, bridge, config) {
             parent: z.string().describe("Container node path the cards are instanced under; \".\" for the root"),
             table_path: z.string().describe("CSV or JSON table on disk (res:// or absolute); format auto-detected by extension unless `format` set"),
             format: z.enum(["csv", "json"]).optional().describe("Override the table format"),
-            column_map: z.record(z.string()).describe("Slot name → column expression (a bare {column} or a composed \"{a} · {b}\")"),
+            column_map: z.record(z.string(), z.string()).describe("Slot name → column expression (a bare {column} or a composed \"{a} · {b}\")"),
             filter: z.object({
                 column: z.string(),
                 equals: z.union([z.string(), z.number(), z.boolean()]),
@@ -1869,7 +1869,7 @@ export function registerTabletopTools(server, bridge, config) {
         inputSchema: {
             template_path: z.string().describe("Piece template scene, e.g. res://ui/pieces/Piece.tscn"),
             parent: z.string().describe("Node path to parent the instance under (in the open scene); \".\" for the root"),
-            data: z.record(z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value (art takes a res:// path; color a #RRGGBB; label a string)"),
+            data: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("Slot name → value (art takes a res:// path; color a #RRGGBB; label a string)"),
             position: z.object({ x: z.number(), y: z.number() }).optional().describe("Local position of the instance (ignored when place_on snaps it to a cell)"),
             face_up: z.boolean().optional().describe("Show the face (default true); false shows the back on two-sided pieces"),
             name: z.string().optional().describe("Optional node name for the instance"),
@@ -1933,7 +1933,7 @@ export function registerTabletopTools(server, bridge, config) {
             node: z.string().describe("Node path (in the open scene) to make draggable; \".\" for the root"),
             script_path: z.string().describe("Where to save the generated drag script, e.g. res://ui/interact/Draggable.gd"),
             mode: z.enum(["control", "node2d"]).describe("control→Control _get_drag_data DnD; node2d→Area2D hit region + pointer handler"),
-            payload: z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe("Neutral data the drag carries (bound into the script as a Dictionary); default empty"),
+            payload: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional().describe("Neutral data the drag carries (bound into the script as a Dictionary); default empty"),
             preview: z.boolean().optional().describe("control mode: show a translucent drag preview (default false)"),
             button: z.number().int().nonnegative().optional().describe("node2d mode: mouse button index that begins the drag (default 1 = left)"),
             action: z.string().optional().describe("node2d mode: input action name registered for the drag button (default \"drag\")"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.73.4",
+  "version": "1.74.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",
@@ -55,8 +55,8 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.17.0",
-    "zod": "^3.23.8"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",