breakpoint-mcp 1.27.1 → 1.28.0

package/dist/bridge.js

@@ -70,6 +70,19 @@ export class BridgeClient {
     onResourceChanged(cb) {
         this.eventListeners.add(cb);
     }
+    /**
+     * The last socket-level error, held so the close path can name it.
+     *
+     * `socket.once("error")` below only rejects the CONNECT promise. Once the
+     * connection is up that handler is still armed, so a mid-flight ECONNRESET /
+     * EPIPE fires it, calls reject() on an already-settled promise — a silent
+     * no-op — and then `close` rejects every pending request with a generic
+     * "connection closed". The specific errno never reached the caller, which is
+     * the difference between "the editor crashed" and "something else is on that
+     * port". Cleared on a successful connect so a stale errno cannot be blamed
+     * for a later, unrelated drop.
+     */
+    lastSocketError = null;
     connect() {
         if (this.socket && !this.socket.destroyed)
             return Promise.resolve(this.socket);
@@ -81,6 +94,7 @@ export class BridgeClient {
             socket.once("connect", () => {
                 this.socket = socket;
                 this.connecting = null;
+                this.lastSocketError = null;
                 this.clearReconnect();
                 // Loopback-auth handshake: if a secret is available it MUST be the first
                 // line on the connection. TCP preserves order and the addon drains lines
@@ -98,6 +112,9 @@ export class BridgeClient {
             });
             socket.once("error", (err) => {
                 this.connecting = null;
+                // 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})`));
             });
             socket.on("data", (chunk) => this.onData(chunk));
@@ -200,9 +217,14 @@ export class BridgeClient {
     }
     onClose() {
         this.socket = null;
+        // Name the transport error when there was one. The CODE stays `bridge_closed`
+        // — callers and tests branch on it — but the message carries the errno.
+        const cause = this.lastSocketError;
+        this.lastSocketError = null;
+        const detail = cause ? ` (${cause.message})` : "";
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new BridgeError("bridge_closed", "Bridge connection closed before a response arrived"));
+            p.reject(new BridgeError("bridge_closed", `Bridge connection closed before a response arrived${detail}`));
         }
         this.pending.clear();
         // Keep the push channel alive across editor restarts while subscriptions want it.

package/dist/capabilities.js

@@ -1,9 +1,8 @@
-/** The two groups, in display order. */
-export const CAPABILITY_GROUPS = ["code-execution", "network"];
+/** The groups, in display order. */
+export const CAPABILITY_GROUPS = ["code-execution"];
 /** One-line human description per group (shown by `doctor` and the resource). */
 export const GROUP_DESCRIBE = {
     "code-execution": "Run arbitrary GDScript, invoke arbitrary methods, evaluate an expression in a paused debug frame, spawn headless child processes of the project, or run a local asset-gen command backend.",
-    network: "Egress beyond loopback — the Group M backend SDK.",
 };
 /**
  * Tool → capability group(s). A tool absent from this map is unprivileged and
@@ -32,9 +31,11 @@ export const TOOL_CAPABILITIES = {
     asset_gen_texture: ["code-execution"],
     asset_gen_model: ["code-execution"],
     asset_gen_audio_sfx: ["code-execution"],
-    // network — Group M backend SDK (egress to a backend provider)
-    backend_configure: ["network"],
-    backend_detect: ["network"],
+    // backend_detect / backend_configure are deliberately ABSENT: neither leaves
+    // this machine (see the header). They are unprivileged, which also puts
+    // backend_configure back in line with the three sibling codegen tools —
+    // leaderboard_scaffold / cloudsave_scaffold / auth_scaffold — that write the
+    // same kind of generated GDScript and were never privileged.
 };
 /**
  * Parse the raw BREAKPOINT_PRIVILEGED_GROUPS env into a normalized token list

package/dist/cli/doctor.js

@@ -24,6 +24,8 @@ 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 { BridgeClient } from "../bridge.js";
+import { resolveBridgeSecret } from "../secret.js";
 const ADDON_REL = "addons/breakpoint_mcp";
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 /** Resolve after a TCP connect succeeds (true) or the port is closed/times out (false). */
@@ -214,6 +216,28 @@ export function checkCapabilities(config) {
     }
     return checks;
 }
+/**
+ * Prove the thing on the far end is OUR bridge, not merely a listening socket.
+ *
+ * Sends an authenticated `ping` with the same secret resolution index.ts uses,
+ * so this fails exactly when a real call would: wrong process on the port, or a
+ * secret that no longer matches the one the addon minted. `probeTcp` can see
+ * neither, which is what made "editor-bridge reachable" a check that could pass
+ * while every tool failed.
+ */
+async function handshakeOk(config, b, timeoutMs) {
+    const client = new BridgeClient(b.host, b.port, timeoutMs, "bridge", undefined, () => resolveBridgeSecret(config.projectPath, b.secretEnv ?? []));
+    try {
+        await client.request("ping", {}, timeoutMs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        client.close();
+    }
+}
 export async function runDoctorChecks(config, opts) {
     const checks = [];
     // Capability groups — the secure-default surface + how to widen it (info only).
@@ -224,18 +248,24 @@ export async function runDoctorChecks(config, opts) {
     checks.push(...checkAddon(config.projectPath));
     // The four bridges.
     const severity = opts.requireLive ? "required" : "info";
+    // `secretEnv` marks the two bridges that speak OUR protocol, so a TCP connect
+    // is not the end of the story for them (see handshakeOk). The LSP and DAP
+    // entries have none: those ports belong to Godot, and anything we could send
+    // to prove liveness would be us implementing a foreign protocol inside doctor.
     const bridges = [
         {
             name: "editor-bridge",
             host: config.bridgeHost,
             port: config.bridgePort,
             hint: 'Open the editor with the "Breakpoint MCP" plugin enabled.',
+            secretEnv: ["BREAKPOINT_BRIDGE_SECRET"],
         },
         {
             name: "runtime-bridge",
             host: config.runtimeHost,
             port: config.runtimePort,
             hint: "Launch the project (godot_run_project / dbg_launch) with the plugin enabled — it auto-registers the runtime autoload.",
+            secretEnv: ["BREAKPOINT_RUNTIME_SECRET", "BREAKPOINT_BRIDGE_SECRET"],
         },
         {
             name: "gdscript-lsp",
@@ -252,12 +282,38 @@ export async function runDoctorChecks(config, opts) {
     ];
     const bridgeChecks = await Promise.all(bridges.map(async (b) => {
         const ok = await probeTcp(b.host, b.port, opts.timeoutMs);
+        if (!ok) {
+            return {
+                name: b.name,
+                status: "fail",
+                severity,
+                detail: `${b.host}:${b.port} unreachable`,
+                hint: b.hint,
+            };
+        }
+        // An open port is not a working bridge. A TCP connect succeeds for ANY
+        // process holding it, and never touches the shared secret — so the two
+        // failures that look most like success stayed invisible: a foreign
+        // process on 9080, and a stale secret (the addon regenerates it into
+        // res://.godot/, so a copied or long-lived config goes quietly wrong).
+        // Both then reported "reachable" here and failed on every real call.
+        if (b.secretEnv) {
+            const live = await handshakeOk(config, b, opts.timeoutMs);
+            if (!live) {
+                return {
+                    name: b.name,
+                    status: "fail",
+                    severity,
+                    detail: `${b.host}:${b.port} open, but no Breakpoint bridge answered`,
+                    hint: "Something holds that port without speaking the bridge protocol, or the shared secret is stale. Close other Godot instances, or delete res://.godot/breakpoint_mcp.secret and reopen the editor to remint it.",
+                };
+            }
+        }
         return {
             name: b.name,
-            status: ok ? "ok" : "fail",
+            status: "ok",
             severity,
-            detail: `${b.host}:${b.port} ${ok ? "reachable" : "unreachable"}`,
-            hint: ok ? undefined : b.hint,
+            detail: `${b.host}:${b.port} reachable${b.secretEnv ? " · bridge answered" : ""}`,
         };
     }));
     checks.push(...bridgeChecks);

package/dist/cli/tools.js

@@ -18,7 +18,7 @@
  *
  * Two surfaces are reported, because the difference is the security story:
  *   • `full`           — all 289 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
- *   • `secure-default` — 274, what an untouched install actually advertises
+ *   • `secure-default` — 276, 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.
  */

package/dist/csdap.js

@@ -49,12 +49,13 @@ export class CsDapClient extends EventEmitter {
         this.channel = channel;
         this.timeoutMs = timeoutMs;
         this.channel.onMessage((m) => this.onMessage(m));
-        this.channel.onClose(() => {
+        this.channel.onClose((cause) => {
             this.state = "terminated";
             this.configured = false;
+            const detail = cause ? ` (${cause.message})` : "";
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
-                p.reject(new DapError(p.command, "C# DAP connection closed"));
+                p.reject(new DapError(p.command, `C# DAP connection closed${detail}`));
             }
             this.pending.clear();
             this.emit("closed");

package/dist/cslsp.js

@@ -47,7 +47,7 @@ export class CsLspClient {
         }
         this.rootFsPath = root.replace(/[\\/]+$/, "");
         this.channel.onMessage((m) => this.onMessage(m));
-        this.channel.onClose(() => this.onClose());
+        this.channel.onClose((cause) => this.onClose(cause));
     }
     /**
      * Reduce any document URI to a stable, project-relative key (e.g. "Player.cs")
@@ -127,10 +127,10 @@ export class CsLspClient {
             void this.channel.send({ jsonrpc: "2.0", id, result: null });
         }
     }
-    onClose() {
+    onClose(cause) {
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", "C# LSP connection closed"));
+            p.reject(new LspError("closed", `C# LSP connection closed${cause ? ` (${cause.message})` : ""}`));
         }
         this.pending.clear();
         this.initialized = null;

package/dist/dap.js

@@ -41,12 +41,16 @@ export class DapClient extends EventEmitter {
         this.timeoutMs = timeoutMs;
         this.conn = new FramedConnection(host, port, "DAP", "Is the editor running with the Debug Adapter enabled (Editor Settings → Network → Debug Adapter, port 6006)?");
         this.conn.onMessage((m) => this.onMessage(m));
-        this.conn.onClose(() => {
+        this.conn.onClose((cause) => {
             this.state = "terminated";
             this.configured = false;
+            // `cause` is the socket-level error when the drop had one (ECONNRESET, EPIPE).
+            // Without it every pending request reported a generic close and the operator
+            // could not tell a crashed server from something else holding the port.
+            const detail = cause ? ` (${cause.message})` : "";
             for (const [, p] of this.pending) {
                 clearTimeout(p.timer);
-                p.reject(new DapError(p.command, "DAP connection closed"));
+                p.reject(new DapError(p.command, `DAP connection closed${detail}`));
             }
             this.pending.clear();
             this.emit("closed");

package/dist/framing.js

@@ -72,6 +72,8 @@ export class FramedConnection {
     decoder;
     messageCb = () => { };
     closeCb = () => { };
+    /** Last socket error, so the close path can name the errno (see connect()). */
+    lastError = null;
     constructor(host, port, label, unavailableHint) {
         this.host = host;
         this.port = port;
@@ -96,18 +98,25 @@ export class FramedConnection {
             socket.once("connect", () => {
                 this.socket = socket;
                 this.connecting = null;
+                this.lastError = null;
                 log(`${this.label} connected to ${this.host}:${this.port}`);
                 resolve(socket);
             });
             socket.once("error", (err) => {
                 this.connecting = null;
+                // Held for the close path: once the connection is up this reject() is a
+                // no-op on a settled promise, so without recording it the errno is lost
+                // and every pending request gets a generic "connection closed".
+                this.lastError = err;
                 reject(new Error(`${this.label} unavailable at ${this.host}:${this.port}. ${this.unavailableHint} (${err.message})`));
             });
             socket.on("data", (chunk) => this.decoder.push(chunk));
             socket.on("close", () => {
                 this.socket = null;
                 this.decoder.reset();
-                this.closeCb();
+                const cause = this.lastError;
+                this.lastError = null;
+                this.closeCb(cause ?? undefined);
             });
         });
         return this.connecting;

package/dist/index.js

@@ -41,7 +41,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.27.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.28.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -60,10 +60,10 @@ async function main() {
     // HANDLER (not the config), after applyAnnotations so the hints exist, before
     // applyCapabilities so a dropped tool is never wrapped.
     applyTimeoutCaveat(server);
-    // Capability groups — a risk-based axis over the toolsets. Both `code-execution`
-    // and `network` are OFF by default; a disabled group's tools are DROPPED at
+    // 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
-    // 289 − 15 = 274 tools. Enable via BREAKPOINT_PRIVILEGED_GROUPS. Wraps
+    // 289 − 13 = 276 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);

package/dist/lsp.js

@@ -47,7 +47,7 @@ export class LspClient {
         this.rootFsPath = root.replace(/[\\/]+$/, "");
         this.conn = new FramedConnection(host, port, "LSP", "Is the editor running with the GDScript language server enabled (Editor Settings → Network → Language Server, port 6005)?");
         this.conn.onMessage((m) => this.onMessage(m));
-        this.conn.onClose(() => this.onClose());
+        this.conn.onClose((cause) => this.onClose(cause));
     }
     /**
      * Reduce any document URI to a stable, project-relative key (e.g. "player.gd")
@@ -128,10 +128,14 @@ export class LspClient {
             void this.conn.send({ jsonrpc: "2.0", id, result: null });
         }
     }
-    onClose() {
+    onClose(cause) {
+        // `cause` is the socket-level error when the drop had one (ECONNRESET, EPIPE).
+        // Without it every pending request reported a generic close and the operator
+        // could not tell a crashed server from something else holding the port.
+        const detail = cause ? ` (${cause.message})` : "";
         for (const [, p] of this.pending) {
             clearTimeout(p.timer);
-            p.reject(new LspError("closed", "LSP connection closed"));
+            p.reject(new LspError("closed", `LSP connection closed${detail}`));
         }
         this.pending.clear();
         this.initialized = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "breakpoint-mcp",
-  "version": "1.27.1",
+  "version": "1.28.0",
   "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",