breakpoint-mcp 1.74.0 → 1.74.1

package/dist/bridge.js

@@ -39,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

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";
@@ -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,7 +12,8 @@ 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, PRIVILEGED_TOOL_COUNT, parsePrivilegedGroups, selectPrivilegedGroups, } from "../capabilities.js";
@@ -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();
@@ -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

@@ -22,7 +22,8 @@
  * `--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/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.74.0" }, { 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
@@ -160,44 +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).",
-        "  --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.",
-        "",
-        "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") {
@@ -216,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/package.json

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