breakpoint-mcp 1.0.0 → 1.2.0

package/dist/cli/clients.js

@@ -0,0 +1,74 @@
+/**
+ * MCP-client config targets for `breakpoint-mcp init`. Each client launches the
+ * server the same way — `npx -y breakpoint-mcp` over stdio — and differs only in
+ * the config file location and the wrapper key (`mcpServers`, except VS Code's
+ * `servers` which also needs an explicit `type: "stdio"`). Paths mirror the
+ * README "Compatibility" table.
+ */
+import os from "node:os";
+import path from "node:path";
+export const CLIENT_IDS = ["claude-code", "claude-desktop", "cursor", "windsurf", "vscode"];
+/** Resolve a client id to its config location + shape, or null if unknown. */
+export function clientInfo(id, projectPath) {
+    const home = os.homedir();
+    switch (id) {
+        case "claude-code":
+            return { id, label: "Claude Code", configPath: null, key: "mcpServers", needsType: false };
+        case "claude-desktop": {
+            let p;
+            if (process.platform === "darwin") {
+                p = path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            }
+            else if (process.platform === "win32") {
+                p = path.join(process.env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+            }
+            else {
+                p = path.join(home, ".config", "Claude", "claude_desktop_config.json");
+            }
+            return { id, label: "Claude Desktop", configPath: p, key: "mcpServers", needsType: false };
+        }
+        case "cursor":
+            return { id, label: "Cursor", configPath: path.join(home, ".cursor", "mcp.json"), key: "mcpServers", needsType: false };
+        case "windsurf":
+            return { id, label: "Windsurf", configPath: path.join(home, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers", needsType: false };
+        case "vscode":
+            // Project-scoped, so it lands next to the project the user is initialising.
+            return { id, label: "VS Code", configPath: path.join(projectPath, ".vscode", "mcp.json"), key: "servers", needsType: true };
+        default:
+            return null;
+    }
+}
+/** The stdio server entry a client config needs. GODOT_BIN is included only when non-default. */
+export function serverEntry(projectPath, godotBin, needsType) {
+    const env = { GODOT_PROJECT: projectPath };
+    if (godotBin && godotBin !== "godot")
+        env.GODOT_BIN = godotBin;
+    const base = { command: "npx", args: ["-y", "breakpoint-mcp"], env };
+    return needsType ? { type: "stdio", ...base } : base;
+}
+/**
+ * Merge the server entry into an existing config's `key` object, preserving every
+ * other server. Returns pretty JSON. Throws if `existing` is present but not valid
+ * JSON, so the caller can refuse to clobber a file it can't parse.
+ */
+export function mergeClientConfig(existing, key, serverName, entry) {
+    let obj = {};
+    if (existing && existing.trim()) {
+        const parsed = JSON.parse(existing);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            obj = parsed;
+        }
+    }
+    const existingSect = obj[key];
+    const sect = existingSect && typeof existingSect === "object" && !Array.isArray(existingSect)
+        ? existingSect
+        : {};
+    sect[serverName] = entry;
+    obj[key] = sect;
+    return JSON.stringify(obj, null, 2) + "\n";
+}
+/** A copy-pasteable single-server snippet for the "print, don't write" default. */
+export function snippet(key, serverName, entry) {
+    return JSON.stringify({ [key]: { [serverName]: entry } }, null, 2);
+}
+//# sourceMappingURL=clients.js.map

package/dist/cli/doctor.js

@@ -0,0 +1,269 @@
+/**
+ * `breakpoint-mcp doctor` — a verifiable health check for a Breakpoint MCP
+ * install, the CLI-side analogue of the planned in-editor status dock.
+ *
+ * It reports, for the configured project + environment:
+ *   - the Godot binary (GODOT_BIN) runs and its version               [required]
+ *   - the editor addon is installed + enabled in project.godot        [required, if a project is present]
+ *   - the four bridges are reachable: editor 9080, runtime 9081,
+ *     GDScript LSP 6005, GDScript DAP 6006                             [info; --require-live promotes to required]
+ *   - optionally, OmniSharp / netcoredbg are on PATH (C# planes)       [info; --include-csharp]
+ *
+ * The exit code is 0 iff no *required* check failed, so `doctor` doubles as a
+ * pre-flight gate. Bridges default to informational because the editor/game
+ * may legitimately not be running when a user checks their install; pass
+ * `--require-live` when you expect them up (e.g. after opening the editor).
+ *
+ * Configuration is read via loadConfig(), so the same env overrides the server
+ * honours (GODOT_BIN, GODOT_PROJECT, and the BREAKPOINT_ / GODOT_ ports) apply here.
+ */
+import net from "node:net";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { loadConfig } from "../config.js";
+import { parseArgs } from "./args.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). */
+function probeTcp(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ host, port });
+        let settled = false;
+        const done = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolve(ok);
+        };
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => done(true));
+        socket.once("timeout", () => done(false));
+        socket.once("error", () => done(false));
+    });
+}
+function readText(p) {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Is the Breakpoint MCP plugin listed in project.godot's [editor_plugins] enabled array? */
+export function isPluginEnabled(projectGodotText) {
+    const lines = projectGodotText.split(/\r?\n/);
+    let inPlugins = false;
+    for (const raw of lines) {
+        const s = raw.trim();
+        if (s.startsWith("[") && s.endsWith("]")) {
+            inPlugins = s === "[editor_plugins]";
+            continue;
+        }
+        if (inPlugins && s.startsWith("enabled") && s.includes(PLUGIN_CFG_RES))
+            return true;
+    }
+    return false;
+}
+function checkGodotBinary(bin, timeoutMs) {
+    const res = spawnSync(bin, ["--version"], { timeout: timeoutMs, encoding: "utf8" });
+    if (res.error) {
+        const code = res.error.code ?? res.error.message;
+        return {
+            name: "godot-binary",
+            status: "fail",
+            severity: "required",
+            detail: `'${bin}' is not runnable (${code})`,
+            hint: "Install Godot 4.2+ and put it on PATH, or set GODOT_BIN to its absolute path.",
+        };
+    }
+    const version = (res.stdout ?? "").trim().split(/\r?\n/)[0] || "(no version output)";
+    return {
+        name: "godot-binary",
+        status: "ok",
+        severity: "required",
+        detail: `${bin} → ${version}`,
+    };
+}
+function checkAddon(projectPath) {
+    const projText = readText(path.join(projectPath, "project.godot"));
+    if (projText === null) {
+        return [
+            {
+                name: "project",
+                status: "skip",
+                severity: "info",
+                detail: `no project.godot at ${projectPath}`,
+                hint: "Pass --project <dir> pointing at your Godot project, or run from the project root.",
+            },
+        ];
+    }
+    const checks = [];
+    const cfgText = readText(path.join(projectPath, ADDON_REL, "plugin.cfg"));
+    if (cfgText === null) {
+        checks.push({
+            name: "addon-installed",
+            status: "fail",
+            severity: "required",
+            detail: `not found at ${ADDON_REL}/plugin.cfg`,
+            hint: "Run 'breakpoint-mcp init' to install the editor addon into this project.",
+        });
+    }
+    else {
+        const m = /version\s*=\s*"([^"]*)"/.exec(cfgText);
+        checks.push({
+            name: "addon-installed",
+            status: "ok",
+            severity: "required",
+            detail: `${ADDON_REL} (version ${m ? m[1] : "?"})`,
+        });
+    }
+    checks.push(isPluginEnabled(projText)
+        ? {
+            name: "addon-enabled",
+            status: "ok",
+            severity: "required",
+            detail: "enabled in project.godot",
+        }
+        : {
+            name: "addon-enabled",
+            status: "fail",
+            severity: "required",
+            detail: "not listed under [editor_plugins] enabled",
+            hint: "Enable 'Breakpoint MCP' under Project → Project Settings → Plugins (or run 'breakpoint-mcp init').",
+        });
+    return checks;
+}
+/** Locate an executable on PATH without launching it (used for the C# info checks). */
+function whichSync(cmd) {
+    if (path.isAbsolute(cmd)) {
+        try {
+            fs.accessSync(cmd, fs.constants.X_OK);
+            return cmd;
+        }
+        catch {
+            return null;
+        }
+    }
+    const dirs = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    const exts = process.platform === "win32"
+        ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").map((e) => e.toLowerCase())
+        : [""];
+    for (const dir of dirs) {
+        for (const ext of exts) {
+            const full = path.join(dir, cmd + ext);
+            try {
+                fs.accessSync(full, fs.constants.X_OK);
+                return full;
+            }
+            catch {
+                /* keep scanning */
+            }
+        }
+    }
+    return null;
+}
+function checkCsharpTool(name, cmd) {
+    const found = whichSync(cmd);
+    return found
+        ? { name, status: "ok", severity: "info", detail: `${cmd} → ${found}` }
+        : {
+            name,
+            status: "skip",
+            severity: "info",
+            detail: `${cmd} not on PATH (C# plane inactive until installed)`,
+        };
+}
+export async function runDoctorChecks(config, opts) {
+    const checks = [];
+    // Godot binary (give the version probe a floor so a slow cold start isn't a false negative).
+    checks.push(checkGodotBinary(config.godotBin, Math.max(opts.timeoutMs, 3000)));
+    // Editor addon install + enable.
+    checks.push(...checkAddon(config.projectPath));
+    // The four bridges.
+    const severity = opts.requireLive ? "required" : "info";
+    const bridges = [
+        {
+            name: "editor-bridge",
+            host: config.bridgeHost,
+            port: config.bridgePort,
+            hint: 'Open the editor with the "Breakpoint MCP" plugin enabled.',
+        },
+        {
+            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.",
+        },
+        {
+            name: "gdscript-lsp",
+            host: config.lspHost,
+            port: config.lspPort,
+            hint: "Godot's language server runs while the editor is open (Editor → Editor Settings → Network → Language Server).",
+        },
+        {
+            name: "gdscript-dap",
+            host: config.dapHost,
+            port: config.dapPort,
+            hint: "Godot's debug adapter runs while the editor is open (Editor → Editor Settings → Network → Debug Adapter).",
+        },
+    ];
+    const bridgeChecks = await Promise.all(bridges.map(async (b) => {
+        const ok = await probeTcp(b.host, b.port, opts.timeoutMs);
+        return {
+            name: b.name,
+            status: ok ? "ok" : "fail",
+            severity,
+            detail: `${b.host}:${b.port} ${ok ? "reachable" : "unreachable"}`,
+            hint: ok ? undefined : b.hint,
+        };
+    }));
+    checks.push(...bridgeChecks);
+    // Optional C# tooling.
+    if (opts.includeCsharp) {
+        checks.push(checkCsharpTool("csharp-lsp", config.csLspCmd));
+        checks.push(checkCsharpTool("csharp-dap", config.csDapCmd));
+    }
+    const ok = checks.every((c) => c.severity !== "required" || c.status !== "fail");
+    return { checks, ok };
+}
+function glyph(status) {
+    return status === "ok" ? "✓" : status === "fail" ? "✗" : "–";
+}
+function printReport(report) {
+    const width = Math.max(...report.checks.map((c) => c.name.length));
+    const out = ["breakpoint-mcp doctor", ""];
+    for (const c of report.checks) {
+        out.push(`  ${glyph(c.status)} ${c.name.padEnd(width)}  ${c.detail}`);
+        if (c.status === "fail" && c.hint)
+            out.push(`      ↳ ${c.hint}`);
+    }
+    out.push("");
+    out.push(report.ok
+        ? "All required checks passed."
+        : "Some required checks failed — see the ↳ hints above.");
+    process.stdout.write(out.join("\n") + "\n");
+}
+/** 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"]);
+    if (typeof flags.project === "string")
+        process.env.GODOT_PROJECT = flags.project;
+    const timeoutRaw = typeof flags.timeout === "string" ? Number.parseInt(flags.timeout, 10) : NaN;
+    const timeoutMs = Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 1500;
+    const config = loadConfig();
+    const report = await runDoctorChecks(config, {
+        timeoutMs,
+        requireLive: flags["require-live"] === true,
+        includeCsharp: flags["include-csharp"] === true,
+    });
+    if (flags.json === true) {
+        process.stdout.write(JSON.stringify(report, null, 2) + "\n");
+    }
+    else {
+        printReport(report);
+    }
+    return report.ok ? 0 : 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/init.js

@@ -0,0 +1,199 @@
+/**
+ * `breakpoint-mcp init` — one-command onboarding. Installs the editor addon into
+ * a target Godot project, enables it in `project.godot`, and wires (or prints)
+ * the MCP-client config. Idempotent and non-destructive: an existing addon is
+ * skipped unless `--force`, an already-enabled plugin is a no-op, and a client
+ * config is backed up (`.bak`) before it is merged. `--dry-run` touches nothing.
+ *
+ * By default the client snippet is printed; pass `--client <id>` to write/merge
+ * it into that client's config file (see clients.ts for the id list + paths).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "./args.js";
+import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
+const PLUGIN_REL = "addons/breakpoint_mcp";
+const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
+const SERVER_NAME = "godot";
+/**
+ * Locate the addon shipped with this package. In the published tarball it lives
+ * at <pkg>/addon/breakpoint_mcp (staged there by scripts/stage-addon.mjs); in the
+ * dev tree the package root is host/, so the canonical repo-root addons/ copy is
+ * one level up. First match with a plugin.cfg wins.
+ */
+export function resolveBundledAddon() {
+    // Escape hatch / test hook: an explicit addon source dir wins when it has a plugin.cfg.
+    const override = process.env.BREAKPOINT_ADDON_SRC;
+    if (override && fs.existsSync(path.join(override, "plugin.cfg")))
+        return override;
+    const here = path.dirname(fileURLToPath(import.meta.url)); // dist/cli
+    const pkgRoot = path.join(here, "..", ".."); // dist/cli -> dist -> package root
+    const candidates = [
+        path.join(pkgRoot, "addon", "breakpoint_mcp"), // published tarball
+        path.join(pkgRoot, "..", "addons", "breakpoint_mcp"), // dev tree (host/../addons)
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, "plugin.cfg")))
+            return c;
+    }
+    return null;
+}
+/**
+ * Add `res://addons/breakpoint_mcp/plugin.cfg` to project.godot's
+ * `[editor_plugins] enabled=PackedStringArray(...)`, creating the section or the
+ * line if absent and preserving every other plugin. Pure — returns the new text.
+ */
+export function enablePlugin(projectGodotText) {
+    const RES = PLUGIN_CFG_RES;
+    const text = projectGodotText;
+    const lines = text.split("\n");
+    let sectionIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === "[editor_plugins]") {
+            sectionIdx = i;
+            break;
+        }
+    }
+    if (sectionIdx === -1) {
+        const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+        const block = `${sep}\n[editor_plugins]\n\nenabled=PackedStringArray("${RES}")\n`;
+        return { text: text + block, changed: true, alreadyEnabled: false };
+    }
+    let enabledIdx = -1;
+    for (let i = sectionIdx + 1; i < lines.length; i++) {
+        const s = lines[i].trim();
+        if (s.startsWith("[") && s.endsWith("]"))
+            break; // next section
+        if (s.startsWith("enabled")) {
+            enabledIdx = i;
+            break;
+        }
+    }
+    if (enabledIdx === -1) {
+        lines.splice(sectionIdx + 1, 0, `enabled=PackedStringArray("${RES}")`);
+        return { text: lines.join("\n"), changed: true, alreadyEnabled: false };
+    }
+    const line = lines[enabledIdx];
+    if (line.includes(RES)) {
+        return { text, changed: false, alreadyEnabled: true };
+    }
+    const m = /PackedStringArray\(([^)]*)\)/.exec(line);
+    if (!m) {
+        lines.splice(enabledIdx + 1, 0, `enabled=PackedStringArray("${RES}")`);
+        return { text: lines.join("\n"), changed: true, alreadyEnabled: false };
+    }
+    const inside = m[1].trim();
+    const newInside = inside.length === 0 ? `"${RES}"` : `${inside}, "${RES}"`;
+    lines[enabledIdx] = line.replace(/PackedStringArray\([^)]*\)/, `PackedStringArray(${newInside})`);
+    return { text: lines.join("\n"), changed: true, alreadyEnabled: false };
+}
+/** Copy the addon into <project>/addons/breakpoint_mcp; skip if present unless force. */
+export function installAddon(addonSource, projectPath, opts) {
+    const dest = path.join(projectPath, PLUGIN_REL);
+    const exists = fs.existsSync(path.join(dest, "plugin.cfg"));
+    if (exists && !opts.force)
+        return { action: "skipped", dest };
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.cpSync(addonSource, dest, { recursive: true });
+    return { action: exists ? "overwritten" : "installed", dest };
+}
+function claudeCodeCommand(projectPath) {
+    return `claude mcp add godot --env GODOT_PROJECT=${projectPath} -- npx -y breakpoint-mcp`;
+}
+/** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
+export async function runInit(argv) {
+    const { flags } = parseArgs(argv, ["force", "dry-run"]);
+    const projectPath = typeof flags.project === "string"
+        ? path.resolve(flags.project)
+        : process.env.GODOT_PROJECT ?? process.cwd();
+    const dryRun = flags["dry-run"] === true;
+    const force = flags.force === true;
+    const client = typeof flags.client === "string" ? flags.client : "none";
+    const godotBin = process.env.GODOT_BIN ?? "godot";
+    const projGodot = path.join(projectPath, "project.godot");
+    if (!fs.existsSync(projGodot)) {
+        process.stderr.write(`init: no project.godot at ${projectPath}\n` +
+            "  Pass --project <dir> pointing at your Godot project (the folder with project.godot).\n");
+        return 1;
+    }
+    const addonSource = resolveBundledAddon();
+    if (!addonSource) {
+        process.stderr.write("init: could not locate the bundled editor addon inside the package.\n");
+        return 1;
+    }
+    const out = [];
+    const say = (s = "") => {
+        out.push(s);
+    };
+    say(`Project: ${projectPath}${dryRun ? "  (dry run — no changes written)" : ""}`);
+    // 1. Install the addon.
+    const destHasAddon = fs.existsSync(path.join(projectPath, PLUGIN_REL, "plugin.cfg"));
+    if (dryRun) {
+        const verb = destHasAddon ? (force ? "overwrite" : "skip (already present; --force to overwrite)") : "install";
+        say(`  addon: would ${verb} → ${PLUGIN_REL}/`);
+    }
+    else {
+        const r = installAddon(addonSource, projectPath, { force });
+        say(`  addon: ${r.action} → ${PLUGIN_REL}/`);
+    }
+    // 2. Enable it in project.godot.
+    const before = fs.readFileSync(projGodot, "utf8");
+    const en = enablePlugin(before);
+    if (dryRun) {
+        say(`  plugin: would ${en.alreadyEnabled ? "leave enabled (already enabled)" : "enable in project.godot"}`);
+    }
+    else if (en.changed) {
+        fs.writeFileSync(projGodot, en.text);
+        say("  plugin: enabled in project.godot");
+    }
+    else {
+        say("  plugin: already enabled");
+    }
+    // 3. MCP-client config.
+    say("");
+    if (client === "claude-code") {
+        say("MCP client (Claude Code) — run:");
+        say(`  ${claudeCodeCommand(projectPath)}`);
+    }
+    else if (client === "none") {
+        say('MCP client — add this to your client config (wrapper key "mcpServers"):');
+        say(snippet("mcpServers", SERVER_NAME, serverEntry(projectPath, godotBin, false)));
+        say("");
+        say("Claude Code users can instead run:");
+        say(`  ${claudeCodeCommand(projectPath)}`);
+    }
+    else {
+        const info = clientInfo(client, projectPath);
+        if (!info || info.configPath === null) {
+            process.stderr.write(`init: unknown --client '${client}'. Known: ${CLIENT_IDS.join(", ")}.\n`);
+            return 1;
+        }
+        const entry = serverEntry(projectPath, godotBin, info.needsType);
+        if (dryRun) {
+            say(`MCP client (${info.label}): would write ${info.configPath}`);
+        }
+        else {
+            const existed = fs.existsSync(info.configPath);
+            const prev = existed ? fs.readFileSync(info.configPath, "utf8") : null;
+            let merged;
+            try {
+                merged = mergeClientConfig(prev, info.key, SERVER_NAME, entry);
+            }
+            catch {
+                process.stderr.write(`init: ${info.configPath} is not valid JSON — leaving it untouched.\n`);
+                return 1;
+            }
+            fs.mkdirSync(path.dirname(info.configPath), { recursive: true });
+            if (existed)
+                fs.copyFileSync(info.configPath, info.configPath + ".bak");
+            fs.writeFileSync(info.configPath, merged);
+            say(`MCP client (${info.label}): ${existed ? "updated" : "created"} ${info.configPath}${existed ? " (backup at .bak)" : ""}`);
+        }
+    }
+    say("");
+    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;
+}
+//# sourceMappingURL=init.js.map

package/dist/config.js

@@ -1,28 +1,4 @@
 import { pathToFileURL } from "node:url";
-import { log } from "./logger.js";
-/**
- * Env vars were renamed CLAUDE_* → BREAKPOINT_* as part of the project rebrand.
- * The old names still work for one deprecation cycle: BREAKPOINT_* takes
- * precedence, and a set CLAUDE_* is honoured as a fallback with a one-time
- * stderr deprecation warning. Drop the fallback (and this helper) once the
- * deprecation window closes. GODOT_* vars are unaffected.
- */
-const _warnedDeprecatedEnv = new Set();
-export function envCompat(newName, oldName) {
-    const current = process.env[newName];
-    if (current !== undefined)
-        return current;
-    const legacy = process.env[oldName];
-    if (legacy !== undefined) {
-        if (!_warnedDeprecatedEnv.has(oldName)) {
-            _warnedDeprecatedEnv.add(oldName);
-            log(`env ${oldName} is deprecated; use ${newName} instead ` +
-                `(${oldName} support will be removed in a future release)`);
-        }
-        return legacy;
-    }
-    return undefined;
-}
 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
@@ -32,9 +8,9 @@ export function loadConfig() {
         godotBin: process.env.GODOT_BIN ?? "godot",
         projectPath,
         projectUri: pathToFileURL(projectPath).href,
-        bridgeHost: envCompat("BREAKPOINT_BRIDGE_HOST", "CLAUDE_BRIDGE_HOST") ?? "127.0.0.1",
-        bridgePort: Number.parseInt(envCompat("BREAKPOINT_BRIDGE_PORT", "CLAUDE_BRIDGE_PORT") ?? "9080", 10),
-        bridgeTimeoutMs: Number.parseInt(envCompat("BREAKPOINT_BRIDGE_TIMEOUT_MS", "CLAUDE_BRIDGE_TIMEOUT_MS") ?? "15000", 10),
+        bridgeHost: process.env.BREAKPOINT_BRIDGE_HOST ?? "127.0.0.1",
+        bridgePort: Number.parseInt(process.env.BREAKPOINT_BRIDGE_PORT ?? "9080", 10),
+        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),
         lspTimeoutMs: Number.parseInt(process.env.GODOT_LSP_TIMEOUT_MS ?? "15000", 10),
@@ -58,9 +34,9 @@ export function loadConfig() {
         csDapTimeoutMs: Number.parseInt(process.env.GODOT_CSDAP_TIMEOUT_MS ?? "20000", 10),
         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: envCompat("BREAKPOINT_RUNTIME_HOST", "CLAUDE_RUNTIME_HOST") ?? "127.0.0.1",
-        runtimePort: Number.parseInt(envCompat("BREAKPOINT_RUNTIME_PORT", "CLAUDE_RUNTIME_PORT") ?? "9081", 10),
-        runtimeTimeoutMs: Number.parseInt(envCompat("BREAKPOINT_RUNTIME_TIMEOUT_MS", "CLAUDE_RUNTIME_TIMEOUT_MS") ?? "15000", 10),
+        runtimeHost: process.env.BREAKPOINT_RUNTIME_HOST ?? "127.0.0.1",
+        runtimePort: Number.parseInt(process.env.BREAKPOINT_RUNTIME_PORT ?? "9081", 10),
+        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",
         assetGenCommand: process.env.BREAKPOINT_ASSETGEN_CMD ?? "",

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { envCompat, loadConfig } from "./config.js";
+import { loadConfig } from "./config.js";
 import { BridgeClient } from "./bridge.js";
 import { LspClient } from "./lsp.js";
 import { CsLspClient } from "./cslsp.js";
@@ -43,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.0.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.2.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
     // B1: enforce frozen output schemas on every structured tool. Must run before
     // the register*Tools calls below — it wraps server.registerTool.
     applyOutputSchemas(server);
@@ -82,7 +82,7 @@ async function main() {
     // subscribed godot://… resource changes (editor selection / edited scene, or
     // the running game's live SceneTree). Rapid changes are coalesced per-URI; the
     // trailing window is overridable via BREAKPOINT_RESOURCE_COALESCE_MS.
-    const coalesceRaw = envCompat("BREAKPOINT_RESOURCE_COALESCE_MS", "CLAUDE_RESOURCE_COALESCE_MS");
+    const coalesceRaw = process.env.BREAKPOINT_RESOURCE_COALESCE_MS;
     const coalesceMs = coalesceRaw ? Number.parseInt(coalesceRaw, 10) : undefined;
     registerResourceSubscriptions(server, bridge, runtime, undefined, { coalesceMs });
     const transport = new StdioServerTransport();
@@ -103,7 +103,52 @@ async function main() {
     process.on("SIGINT", shutdown);
     process.on("SIGTERM", shutdown);
 }
-main().catch((err) => {
+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 --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.",
+        "",
+        "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.",
+        "",
+        "All runtime configuration is via environment variables; see the README.",
+        "",
+    ].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.
+void (async () => {
+    const sub = process.argv[2];
+    if (sub === "doctor") {
+        const { runDoctor } = await import("./cli/doctor.js");
+        process.exit(await runDoctor(process.argv.slice(3)));
+    }
+    if (sub === "init") {
+        const { runInit } = await import("./cli/init.js");
+        process.exit(await runInit(process.argv.slice(3)));
+    }
+    if (sub === "help" || sub === "--help" || sub === "-h") {
+        printUsage();
+        process.exit(0);
+    }
+    await main();
+})().catch((err) => {
     log("fatal:", err instanceof Error ? err.stack ?? err.message : String(err));
     process.exit(1);
 });