breakpoint-mcp 1.24.0 → 1.26.0

package/dist/cli/tools.js

@@ -28,26 +28,7 @@ import { applyOutputSchemas } from "../schemas.js";
 import { applyAnnotations, annotationsFor } from "../annotations.js";
 import { TOOL_CAPABILITIES, CAPABILITY_GROUPS, GROUP_DESCRIBE } from "../capabilities.js";
 import { loadConfig } from "../config.js";
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-/**
- * Read the version from package.json at runtime rather than hardcoding it.
- * Deliberate: the version already has to be bumped in `package.json`, the
- * `serverInfo` literal, both `plugin.cfg`s, and the doctor/init surface strings
- * — this command must not become a sixth place to forget. package.json ships in
- * the npm tarball, so the read is safe in an installed package; if it ever
- * isn't, an unknown version is better than a stale one.
- */
-function packageVersion() {
-    try {
-        const here = dirname(fileURLToPath(import.meta.url));
-        return JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf8")).version ?? "unknown";
-    }
-    catch {
-        return "unknown";
-    }
-}
+import { packageVersion } from "../version.js";
 /**
  * Register the whole surface against a recorder, exactly as `index.ts` does
  * (`applyOutputSchemas` → `applyAnnotations` → every `register*Tools`), and

package/dist/cslsp.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { LspError } from "./lsp.js";
+import { packageVersion } from "./version.js";
 /**
  * Minimal LSP client for the C#/.NET semantic plane (D4 C2). Transport-agnostic:
  * it drives any `JsonRpcChannel`, so production spawns OmniSharp over stdio
@@ -164,7 +165,7 @@ export class CsLspClient {
                         workspace: { symbol: {}, workspaceFolders: true },
                     },
                     workspaceFolders: [{ uri: this.rootUri, name: "csharp-project" }],
-                    clientInfo: { name: "breakpoint-mcp", version: "0.2.0" },
+                    clientInfo: { name: "breakpoint-mcp", version: packageVersion() },
                 }));
                 this.serverCapabilities = result?.capabilities ?? {};
                 await this.notify("initialized", {});

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.24.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.26.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/lsp.js

@@ -1,5 +1,6 @@
 import { fileURLToPath } from "node:url";
 import { FramedConnection } from "./framing.js";
+import { packageVersion } from "./version.js";
 export class LspError extends Error {
     code;
     constructor(code, message) {
@@ -165,7 +166,7 @@ export class LspClient {
                         workspace: { symbol: {}, workspaceFolders: true },
                     },
                     workspaceFolders: [{ uri: this.rootUri, name: "godot-project" }],
-                    clientInfo: { name: "breakpoint-mcp", version: "0.2.0" },
+                    clientInfo: { name: "breakpoint-mcp", version: packageVersion() },
                 }));
                 this.serverCapabilities = result?.capabilities ?? {};
                 await this.notify("initialized", {});

package/dist/ports.js

@@ -31,15 +31,16 @@ export function portFree(host, port) {
     });
 }
 /**
- * The refusal text shared by `godot_run_managed` and `godot_run_project`.
+ * The refusal text shared by every tool that starts a game.
  *
- * 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.
+ * All of them launch a project whose runtime autoload binds
+ * `BREAKPOINT_RUNTIME_PORT` (`runtime_bridge.gd:74` reads it, `:79` binds it).
+ * 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
@@ -52,11 +53,44 @@ export function portFree(host, port) {
  * 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.
+ *
+ * The `debugger` variant differs in one way that matters. A DAP session is
+ * addressed by SESSION, not by port, so `dbg_*` keeps working perfectly against
+ * a second game even with the port held — only `runtime_*` is corrupted. The
+ * override is therefore a legitimate everyday choice on that plane rather than a
+ * last resort, and the text says so instead of over-warning. Over-warning is how
+ * a check earns the reputation that gets it disabled.
+ *
+ * What NEITHER variant may do is claim to know WHAT is holding the port. All the
+ * probe learns is that something is. The holder may be a `godot_run_managed`
+ * child (`godot_stop` clears it), a game already under the debugger (`dbg_attach`
+ * reaches it), or a window the developer opened themselves (only they can close
+ * it) — and the two planes contend for the SAME port, so a debugger refusal is
+ * often about a run-plane holder and vice versa. An earlier draft of the
+ * debugger text asserted "a debugger-launched game is owned by the editor, so no
+ * tool here can stop it" and withheld `godot_stop` on that basis; it was wrong
+ * whenever the holder was a managed child, which is the commonest case of all.
+ * Both variants now list every remedy with the condition under which it applies,
+ * and assert nothing about which one is live.
  */
-export function portConflictMessage(host, port) {
-    return (`${host}:${port} is already bound, so a game started now could not host the runtime bridge. ` +
+export function portConflictMessage(host, port, launcher = "run") {
+    const why = `${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. ` +
+        `silently address the process that already holds the port instead of the one you just started. `;
+    if (launcher === "debugger") {
+        return (why +
+            `Deal with whatever is already holding it — which remedy applies depends on what it is: ` +
+            `godot_stop if godot_run_managed started it, dbg_attach / cs_dbg_attach to debug the running ` +
+            `game instead of launching a second one (that works only if it is already under the ` +
+            `debugger — a plain godot_run_project or godot_run_managed game is not), or quit it in the ` +
+            `game window or the editor. You can also point this server at a free port with ` +
+            `BREAKPOINT_RUNTIME_PORT. Pass allow_port_conflict:true to launch anyway: breakpoints, ` +
+            `stepping and variable inspection will all work normally, because a DAP session is addressed ` +
+            `by session rather than by port — but every runtime_* call would go to the process holding ` +
+            `the port, not to the game you just launched. To drive more than one game at once, use ` +
+            `runtime_spawn_peers, which allocates a distinct port per peer.`);
+    }
+    return (why +
         `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 ` +

package/dist/tools/csdap.js

@@ -3,6 +3,7 @@ import { DapError } from "../dap.js";
 import { toFsPath } from "../paths.js";
 import { gate } from "../confirm.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 // How long step/continue wait for the program to settle (hit a breakpoint,
 // finish a step, or terminate) before returning. On timeout the tool reports
 // the current state — e.g. `continue` with no further breakpoint stays running.
@@ -54,12 +55,41 @@ export function registerCsDapTools(server, dap, cfg) {
             args: z.array(z.string()).optional().describe("Program arguments (default: ['--path', <C# project>])"),
             stop_on_entry: z.boolean().optional().describe("Break at entry (default false)"),
             just_my_code: z.boolean().optional().describe("Restrict stepping/breakpoints to user code (netcoredbg justMyCode; default true)"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Launch even though the runtime bridge port is already bound (default false). Only consulted when " +
+                "this looks like a Godot launch — the program is named godot, or the args carry Godot's --path " +
+                "project flag. Debugging some other .NET program is never gated. Breakpoints and stepping still " +
+                "work; runtime_* tools would talk to the process holding the port."),
         },
-    }, async ({ program, args, stop_on_entry, just_my_code }) => {
+    }, async ({ program, args, stop_on_entry, just_my_code, allow_port_conflict }) => {
+        const resolvedProgram = program ?? cfg.csDapProgram;
+        const resolvedArgs = args ?? ["--path", cfg.csDapProjectPath];
+        // Does this launch a Godot game — i.e. one whose autoload wants the runtime
+        // port — or some other .NET program netcoredbg is being pointed at?
+        //
+        // DEFAULT TO YES, and skip the gate only when the caller has clearly aimed
+        // elsewhere. Comparing the resolved program against `cfg.csDapProgram` was
+        // the obvious-looking test and is wrong: that is equality against the
+        // DEFAULT, so passing the real Mono binary explicitly — the way config.ts
+        // documents pointing at it — skipped the gate on the mainline path this
+        // whole change exists to cover. `--path <project>` is Godot's own project
+        // flag and appears in the default args; a program not called godot and not
+        // given --path is the one case we are confident is not a game.
+        const looksLikeGodot = /godot/i.test(resolvedProgram.split(/[\\/]/).pop() ?? "") || resolvedArgs.includes("--path");
+        if (looksLikeGodot &&
+            !allow_port_conflict &&
+            !(await portFree(cfg.runtimeHost, cfg.runtimePort))) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: portConflictMessage(cfg.runtimeHost, cfg.runtimePort, "debugger") }],
+            };
+        }
         try {
             await dap.start("launch", {
-                program: program ?? cfg.csDapProgram,
-                args: args ?? ["--path", cfg.csDapProjectPath],
+                program: resolvedProgram,
+                args: resolvedArgs,
                 cwd: cfg.csDapProjectPath,
                 stopAtEntry: stop_on_entry ?? false,
                 justMyCode: just_my_code ?? true,
@@ -70,6 +100,8 @@ export function registerCsDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately — see dbg_attach: attaching to the process that
+    // already holds the port is the remedy, not the problem.
     server.registerTool("cs_dbg_attach", {
         title: "Attach C# debug session",
         description: "Attach netcoredbg to an already-running .NET process (e.g. a C# Godot game launched separately) by its OS process id. " +
@@ -345,6 +377,8 @@ export function registerCsDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately — see dbg_restart: the session's own game still
+    // holds the port at check time, so a probe here false-positives every restart.
     server.registerTool("cs_dbg_restart", {
         title: "Restart C# debug session",
         description: "Restart the current C# debug session. Uses the DAP `restart` request when the adapter advertises `supportsRestartRequest`, " +

package/dist/tools/dap.js

@@ -3,6 +3,7 @@ import { DapError } from "../dap.js";
 import { toFsPath } from "../paths.js";
 import { gate } from "../confirm.js";
 import { ok } from "./lsp-common.js";
+import { portFree, portConflictMessage } from "../ports.js";
 // How long step/continue wait for the program to settle (hit a breakpoint,
 // finish a step, or terminate) before returning. On timeout the tool reports
 // the current state — e.g. `continue` with no further breakpoint stays running.
@@ -55,12 +56,28 @@ export function registerDapTools(server, dap, cfg) {
     server.registerTool("dbg_launch", {
         title: "Launch debug session",
         description: "Start the game under the debugger. scene may be 'main', 'current', or a res:// scene path. " +
-            "Any breakpoints set beforehand are applied during the handshake.",
+            "Any breakpoints set beforehand are applied during the handshake. " +
+            "Refuses if the runtime bridge port is already bound — the new game could not host the bridge, so " +
+            "runtime_* would address the process already holding the port. Clear the holder (godot_stop, or quit " +
+            "it), or dbg_attach onto it if it is already under the debugger, or pass allow_port_conflict " +
+            "(dbg_* is unaffected either way; only runtime_* is).",
         inputSchema: {
             scene: z.string().optional().describe("'main' (default), 'current', or res://scene.tscn"),
             stop_on_entry: z.boolean().optional().describe("Break at entry (default false)"),
+            allow_port_conflict: z
+                .boolean()
+                .optional()
+                .describe("Launch even though the runtime bridge port is already bound (default false). Breakpoints and " +
+                "stepping still work — a DAP session is addressed by session, not by port — but runtime_* " +
+                "tools would talk to the process holding the port, not to this game."),
         },
-    }, async ({ scene, stop_on_entry }) => {
+    }, async ({ scene, stop_on_entry, 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, "debugger") }],
+            };
+        }
         try {
             await dap.start("launch", {
                 project: cfg.projectPath,
@@ -73,6 +90,9 @@ export function registerDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately: attaching to the game that already holds the
+    // port is the REMEDY dbg_launch's refusal points at. Gating it would close the
+    // exit and leave the caller with nowhere to go.
     server.registerTool("dbg_attach", {
         title: "Attach debug session",
         description: "Attach to an already-running Godot debug session.",
@@ -367,6 +387,14 @@ export function registerDapTools(server, dap, cfg) {
             return fail(err);
         }
     });
+    // NOT port-gated, deliberately, and this one is a trap worth naming: at the
+    // moment of the check the session's OWN game still holds the runtime port and
+    // is about to be terminated. A probe here would fire on the very process it is
+    // about to replace — a guaranteed false positive on the happy path, every
+    // single time. The relaunch reuses the launch parameters, so if some THIRD
+    // process holds the port the fresh game lands bridgeless exactly as before;
+    // that residue is accepted knowingly rather than traded for a check that cries
+    // wolf on every restart.
     server.registerTool("dbg_restart", {
         title: "Restart debug session",
         description: "Restart the current debug session. Uses the DAP `restart` request when the adapter advertises `supportsRestartRequest`, " +

package/dist/version.js

@@ -0,0 +1,32 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+/**
+ * The package version, read at runtime rather than hardcoded.
+ *
+ * Every literal version string in the source is a place a release can forget,
+ * and `contract_check.py` check 14 exists because two consecutive releases did.
+ * The best outcome is not a gated literal but no literal at all — so anything
+ * that merely needs to *report* the version should call this instead of being
+ * added to the roster.
+ *
+ * This was not academic. `lsp.ts` and `cslsp.ts` announced
+ * `clientInfo: { version: "0.2.0" }` to Godot's language server and to
+ * OmniSharp from the initial commit until 1.26.0 — the project shipped
+ * twenty-odd releases telling every LSP server it was 0.2.0, and nothing
+ * noticed, because a literal nobody compares to anything cannot go stale
+ * loudly.
+ *
+ * `package.json` ships in the npm tarball, so the read is safe in an installed
+ * package; if it ever isn't, an unknown version is better than a stale one.
+ */
+export function packageVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        return JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8")).version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=version.js.map

package/package.json

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