breakpoint-mcp 1.23.0 → 1.24.0

package/dist/config.js

@@ -1,5 +1,30 @@
 import { pathToFileURL } from "node:url";
 import { parsePrivilegedGroups } from "./capabilities.js";
+/**
+ * A TCP port from the environment, falling back to `fallback` when the variable
+ * is absent, empty, non-numeric or out of range.
+ *
+ * `?? "9081"` alone does not cover this: an env var set to `""` or `"nope"`
+ * reaches `Number.parseInt` and yields `NaN`, which then propagates into every
+ * dial and bind as a port nothing can use. The addon has guarded this since it
+ * shipped — `runtime_bridge.gd:75` requires `is_valid_int()` before overriding
+ * and otherwise keeps the default — and the host simply never matched it. The
+ * mismatch was harmless while a bad port merely failed to connect; it stopped
+ * being harmless once `godot_run_managed` began *refusing* on an unbindable
+ * port, which would have read as "127.0.0.1:NaN is already bound".
+ */
+function port(raw, fallback) {
+    // Deliberately NOT Number.parseInt on its own: it stops at the first
+    // non-digit, so "80a80" parses to 80. The host would then dial port 80 while
+    // the addon — whose `is_valid_int()` rejects the whole string — bound the
+    // default, which is precisely the host/addon disagreement this guard exists
+    // to prevent. The pattern mirrors GDScript's `is_valid_int()`.
+    const t = (raw ?? "").trim();
+    if (!/^[+-]?\d+$/.test(t))
+        return fallback;
+    const n = Number(t);
+    return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : fallback;
+}
 export function loadConfig() {
     const projectPath = process.env.GODOT_PROJECT ?? process.cwd();
     // The C# project defaults to the main project, but is usually pointed at a
@@ -10,10 +35,10 @@ export function loadConfig() {
         projectPath,
         projectUri: pathToFileURL(projectPath).href,
         bridgeHost: process.env.BREAKPOINT_BRIDGE_HOST ?? "127.0.0.1",
-        bridgePort: Number.parseInt(process.env.BREAKPOINT_BRIDGE_PORT ?? "9080", 10),
+        bridgePort: port(process.env.BREAKPOINT_BRIDGE_PORT, 9080),
         bridgeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_BRIDGE_TIMEOUT_MS ?? "15000", 10),
         lspHost: process.env.GODOT_LSP_HOST ?? "127.0.0.1",
-        lspPort: Number.parseInt(process.env.GODOT_LSP_PORT ?? "6005", 10),
+        lspPort: port(process.env.GODOT_LSP_PORT, 6005),
         lspTimeoutMs: Number.parseInt(process.env.GODOT_LSP_TIMEOUT_MS ?? "15000", 10),
         csLspCmd: process.env.GODOT_CSLSP_CMD ?? "OmniSharp",
         csLspArgs: (process.env.GODOT_CSLSP_ARGS ?? "-lsp").split(/\s+/).filter(Boolean),
@@ -21,7 +46,7 @@ export function loadConfig() {
         csLspProjectUri: pathToFileURL(csLspProjectPath).href,
         csLspTimeoutMs: Number.parseInt(process.env.GODOT_CSLSP_TIMEOUT_MS ?? "30000", 10),
         dapHost: process.env.GODOT_DAP_HOST ?? "127.0.0.1",
-        dapPort: Number.parseInt(process.env.GODOT_DAP_PORT ?? "6006", 10),
+        dapPort: port(process.env.GODOT_DAP_PORT, 6006),
         dapTimeoutMs: Number.parseInt(process.env.GODOT_DAP_TIMEOUT_MS ?? "20000", 10),
         dapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_DAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
         dapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_DAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
@@ -36,7 +61,7 @@ export function loadConfig() {
         csDapSetVarTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_SETVAR_TIMEOUT_MS ?? "8000", 10),
         csDapEvaluateTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_EVALUATE_TIMEOUT_MS ?? "8000", 10),
         runtimeHost: process.env.BREAKPOINT_RUNTIME_HOST ?? "127.0.0.1",
-        runtimePort: Number.parseInt(process.env.BREAKPOINT_RUNTIME_PORT ?? "9081", 10),
+        runtimePort: port(process.env.BREAKPOINT_RUNTIME_PORT, 9081),
         runtimeTimeoutMs: Number.parseInt(process.env.BREAKPOINT_RUNTIME_TIMEOUT_MS ?? "15000", 10),
         // Group J: asset generation is OFF by default (backend "none" → tools degrade).
         assetGenBackend: process.env.BREAKPOINT_ASSETGEN_BACKEND ?? "none",

package/dist/index.js

@@ -36,7 +36,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.23.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.24.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);

package/dist/peers.js

@@ -1,8 +1,8 @@
-import net from "node:net";
 import { BridgeClient, BridgeError } from "./bridge.js";
 import { ProcessRegistry } from "./tools/processes.js";
 import { ensureProjectSecret, readProjectSecret } from "./secret.js";
 import { log } from "./logger.js";
+import { portFree } from "./ports.js";
 /**
  * Hard ceiling on simultaneously live peers.
  *
@@ -15,20 +15,6 @@ import { log } from "./logger.js";
 export const MAX_PEERS = 4;
 /** How far above the default runtime port the allocator will scan. */
 const PORT_SCAN_SPAN = 200;
-/** Is `port` bindable on `host` right now? */
-function portFree(host, port) {
-    return new Promise((resolve) => {
-        const srv = net.createServer();
-        srv.once("error", () => resolve(false));
-        srv.once("listening", () => srv.close(() => resolve(true)));
-        try {
-            srv.listen(port, host);
-        }
-        catch {
-            resolve(false);
-        }
-    });
-}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class PeerRegistry {
     cfg;
@@ -83,12 +69,13 @@ export class PeerRegistry {
      * runtime port so a peer never collides with a developer's already-running
      * game. Ports held by live peers are skipped even if the probe would pass.
      *
-     * Probe-then-release is a TOCTOU window by construction: another process could
-     * take the port between the probe and the child's bind. Allocation is
+     * The probe is TOCTOU by construction (see `ports.ts`), but allocation is
      * sequential and the window is sub-millisecond, and the failure mode is
      * benign — the child logs "could not listen" and the readiness wait below
      * reports it with that line attached, rather than the peer silently
-     * half-existing.
+     * half-existing. The DEFAULT runtime port has no such readiness wait, which
+     * is why `godot_run_managed` and `godot_run_project` refuse a held port
+     * outright rather than reporting it after the fact.
      */
     async allocatePorts(count) {
         const taken = new Set([this.cfg.runtimePort, ...this.live().map((p) => p.port)]);

package/dist/ports.js

@@ -0,0 +1,68 @@
+import net from "node:net";
+/**
+ * Loopback port probing, shared by the two callers that must not collide.
+ *
+ * It lives in its own module because `peers.ts` imports `ProcessRegistry` from
+ * `tools/processes.ts`, so `processes.ts` importing the probe back out of
+ * `peers.ts` would close an import cycle. Nothing here imports anything local.
+ */
+/**
+ * Is `port` bindable on `host` right now?
+ *
+ * Probe-then-release is a TOCTOU window by construction: another process could
+ * take the port between this answer and whoever acts on it. Every caller here
+ * treats a `true` as "nothing is holding it as of now", never as a lease.
+ *
+ * SO_REUSEADDR (which Node sets by default) does NOT let two live listeners
+ * share an address on Linux or macOS — that needs SO_REUSEPORT, which Node does
+ * not set — so a bound port answers `false` rather than being silently joinable.
+ */
+export function portFree(host, port) {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.once("error", () => resolve(false));
+        srv.once("listening", () => srv.close(() => resolve(true)));
+        try {
+            srv.listen(port, host);
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/**
+ * The refusal text shared by `godot_run_managed` and `godot_run_project`.
+ *
+ * Both tools start a game whose runtime autoload binds `BREAKPOINT_RUNTIME_PORT`
+ * (`runtime_bridge.gd:74`). When that port is already held, the autoload's
+ * `listen()` returns non-OK, it `push_error`s, and **the game keeps running
+ * without a bridge** — while the host's runtime client, which dials the same
+ * fixed port, connects to whichever process got there first. Every subsequent
+ * `runtime_*` call then answers confidently about the WRONG process, and `ping`
+ * carries no pid or boot nonce that could tell them apart.
+ *
+ * That is why this refuses rather than warns: a determinism feature returning a
+ * correct-looking answer from the wrong game is worse than one that will not
+ * start.
+ *
+ * Note what is deliberately NOT offered as a remedy: stopping peers. A peer can
+ * never hold this port — `allocatePorts` seeds its `taken` set with
+ * `cfg.runtimePort` and scans from `runtimePort + 1`, so whatever holds it is
+ * something else. `runtime_spawn_peers` is named below as the way to drive
+ * several games at once, which is true; `runtime_peer_stop` as a way to free
+ * THIS port would not be, and a remedy that cannot work is worse than one fewer
+ * suggestion.
+ */
+export function portConflictMessage(host, port) {
+    return (`${host}:${port} is already bound, so a game started now could not host the runtime bridge. ` +
+        `Its autoload would fail to listen and keep running anyway, and every runtime_* call would ` +
+        `silently address the process that already holds the port instead of the one you just started. ` +
+        `Stop the running game first — godot_stop if godot_run_managed started it, otherwise quit it in ` +
+        `the game window or end the debug session that launched it (a detached godot_run_project game is ` +
+        `not stoppable by any tool) — or point this server at a free port with ` +
+        `BREAKPOINT_RUNTIME_PORT. Pass allow_port_conflict:true to start it anyway — reasonable only if ` +
+        `you want the process for its console output or its side effects and will not use any runtime_* ` +
+        `tool against it. To drive more than one game at once, use runtime_spawn_peers, which allocates ` +
+        `a distinct port per peer.`);
+}
+//# sourceMappingURL=ports.js.map

package/dist/recipes.js

@@ -114,8 +114,8 @@ export function registerRecipes(server) {
         return recipe("Golden-image regression check for a scene.", [
             `Goal: lock a scene's look to a golden image at ${ref} and catch visual drift.`,
             "",
-            `1. Establish the golden (first run only): godot_run_project, drive the game to the state under test (runtime_inject_input / runtime_call_method), then runtime_screenshot and save the frame to ${ref}. Commit it (vcs_add) so it's the reference.`,
-            `2. Regression run (every time after): godot_run_project, reproduce the same state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} (pass a region to ignore volatile HUD areas). ok:true means no meaningful drift.`,
+            `1. Establish the golden (first run only): godot_run_managed, drive the game to the state under test (runtime_inject_input / runtime_call_method), then runtime_screenshot and save the frame to ${ref}. Commit it (vcs_add) so it's the reference, then godot_stop — this recipe runs the game more than once, and a game left running holds the runtime bridge port, so the next run is refused.`,
+            `2. Regression run (every time after): godot_run_managed, reproduce the same state, then runtime_screenshot_diff against ${ref} with tolerance ${tol} (pass a region to ignore volatile HUD areas). ok:true means no meaningful drift. godot_stop when the diff is in hand.`,
             "3. On failure: the diff returns diff_ratio + differing_pixels — don't just eyeball it. runtime_get_tree / runtime_assert_node_state to find the node that changed, or dbg_* to break where the offending value is set. Update the golden deliberately (re-do step 1) only once you've confirmed the change is intended.",
             "",
             "The whole diff runs engine-side (Image), so there's no OCR/image dependency and it stays read-only and ungated.",
@@ -138,7 +138,7 @@ export function registerRecipes(server) {
             `1. Understand: gd_document_symbols for the file's shape; gd_definition / gd_references before touching a symbol so you know every call site; find_usages across the project for wider blast radius.`,
             "2. Edit with help: while writing, use gd_completion and gd_hover to get exact API names and signatures (this is where a generic 'call any method' tool hallucinates — the LSP gives you the truth). gd_rename to rename safely across the project.",
             "3. Gate: run gd_diagnostics and do not proceed until it's clean. gd_code_action for quick-fixes it suggests.",
-            "4. Prove behavior: godot_run_project and a runtime_assert_* that the change did what you intended. If it didn't, dbg_* into it.",
+            "4. Prove behavior: godot_run_managed and a runtime_assert_* that the change did what you intended, then godot_stop — leaving it running holds the runtime bridge port and the next run of this recipe is refused. If the assert didn't pass, dbg_* into it.",
             "",
             "Every mutation is on the undo stack — editor_undo reverts a bad edit instantly.",
             "",

package/dist/tools/cli.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { log } from "../logger.js";
 import { registerTaskTool } from "../tasks.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 const execFileAsync = promisify(execFile);
 /** Run the Godot binary to completion, capturing stdout/stderr. */
 async function runCaptured(cfg, args, timeoutMs, signal) {
@@ -62,11 +63,23 @@ export function registerCliTools(server, cfg) {
     });
     server.registerTool("godot_run_project", {
         title: "Run project",
-        description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id.",
+        description: "Run the project (detached). Optionally start from a specific scene path (res://...). Returns the process id. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
+            "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
+            "than one game at once.",
         inputSchema: {
             scene: z.string().optional().describe("Optional scene to run, e.g. res://levels/test.tscn"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
+                "bridge will NOT be reachable — use only when you want the process for its side effects and will not " +
+                "call any runtime_* tool against it."),
         },
-    }, async ({ scene }) => {
+    }, async ({ scene, allow_port_conflict }) => {
+        if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
+        }
         const args = ["--path", cfg.projectPath];
         if (scene)
             args.push(scene);

package/dist/tools/processes.js

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import { z } from "zod";
 import { log } from "../logger.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 const LINE_CAP = 5000;
 /**
  * Runs Godot as a MANAGED child (piped stdio) so the host captures ALL stdout/
@@ -83,9 +84,23 @@ export function registerProcessTools(server, cfg) {
     server.registerTool("godot_run_managed", {
         title: "Run project (managed, captured output)",
         description: "Run the project as a managed child process with captured stdout/stderr, so godot_output can read ALL print()/error output. " +
-            "Returns a process id. Use this instead of godot_run_project when you want the game's console log.",
-        inputSchema: { scene: z.string().optional().describe("Optional res:// scene to run") },
-    }, async ({ scene }) => {
+            "Returns a process id. Use this instead of godot_run_project when you want the game's console log. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, and every " +
+            "runtime_* call would address the process already holding the port. Use runtime_spawn_peers to drive more " +
+            "than one game at once.",
+        inputSchema: {
+            scene: z.string().optional().describe("Optional res:// scene to run"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Start even though the runtime bridge port is already bound (default false). The new game's runtime " +
+                "bridge will NOT be reachable — use only when you want the process for its console output or side " +
+                "effects and will not call any runtime_* tool against it."),
+        },
+    }, async ({ scene, allow_port_conflict }) => {
+        if (!allow_port_conflict && !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return { isError: true, content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort) }] };
+        }
         const m = registry.run(cfg, scene ? [scene] : []);
         return ok({ id: m.id, pid: m.child.pid ?? null, running: true, scene: scene ?? null });
     });

package/package.json

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