breakpoint-mcp 1.14.0 → 1.19.0

package/dist/capabilities.js

@@ -0,0 +1,150 @@
+/** The two groups, in display order. */
+export const CAPABILITY_GROUPS = ["code-execution", "network"];
+/** 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, 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
+ * always registered. This is the single source of truth for the risk tagging,
+ * asserted total-and-correct by `capabilities.test.ts`.
+ */
+export const TOOL_CAPABILITIES = {
+    // code-execution — arbitrary execution / invocation / paused-frame evaluation
+    godot_run_headless_script: ["code-execution"],
+    godot_run_managed: ["code-execution"],
+    node_call_method: ["code-execution"],
+    runtime_call_method: ["code-execution"],
+    dbg_evaluate: ["code-execution"],
+    cs_dbg_evaluate: ["code-execution"],
+    // asset generation — the local command backend (code-execution) is the only
+    // privileged path. Formerly also tagged `network` for an external provider
+    // backend, but that backend is not implemented, so the network tag is dropped
+    // until it ships — keeps the advertised capability matching the real surface.
+    asset_gen_configure: ["code-execution"],
+    asset_gen_icon: ["code-execution"],
+    asset_gen_sprite: ["code-execution"],
+    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"],
+};
+/**
+ * Parse the raw BREAKPOINT_PRIVILEGED_GROUPS env into a normalized token list
+ * (or null for "unset" → no groups → the safe-default surface). Comma/whitespace
+ * separated, lower-cased. Mirrors `parseToolsets`.
+ */
+export function parsePrivilegedGroups(raw) {
+    if (raw == null)
+        return null;
+    const toks = raw
+        .split(/[,\s]+/)
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean);
+    return toks.length ? toks : null;
+}
+/**
+ * Resolve normalized tokens to the enabled group set. Unknown tokens are
+ * reported via `onUnknown` and ignored (a typo never silently enables a group).
+ * `null`/empty → the empty set (safe default). `all` enables every group.
+ */
+export function selectPrivilegedGroups(tokens, onUnknown) {
+    const enabled = new Set();
+    if (!tokens)
+        return enabled;
+    const known = new Set(CAPABILITY_GROUPS);
+    const unknown = [];
+    for (const t of tokens) {
+        if (t === "all") {
+            for (const g of CAPABILITY_GROUPS)
+                enabled.add(g);
+        }
+        else if (known.has(t)) {
+            enabled.add(t);
+        }
+        else {
+            unknown.push(t);
+        }
+    }
+    if (unknown.length && onUnknown)
+        onUnknown(unknown);
+    return enabled;
+}
+/** Is a tool allowed given the enabled groups? Untagged tools are always allowed. */
+export function toolAllowed(name, enabled) {
+    const groups = TOOL_CAPABILITIES[name];
+    if (!groups || groups.length === 0)
+        return true;
+    return groups.some((g) => enabled.has(g));
+}
+/** The sorted set of privileged tool names dropped when `enabled` groups are active. */
+export function droppedTools(enabled) {
+    return Object.keys(TOOL_CAPABILITIES)
+        .filter((name) => !toolAllowed(name, enabled))
+        .sort();
+}
+/**
+ * Wrap `server.registerTool` to DROP any tool whose capability group isn't
+ * enabled, so a disabled group's tools never reach `tools/list`. Mirrors
+ * `applyOutputSchemas`' wrapping; call once, right AFTER `applyOutputSchemas`
+ * (so the schema-injection wrapper stays innermost) and before any
+ * `register*Tools()` call. A dropped tool returns a harmless stub handle so the
+ * calling register* code proceeds unchanged.
+ */
+export function applyCapabilities(server, enabled) {
+    const gate = (raw) => (name, config, handler) => {
+        if (!toolAllowed(name, enabled)) {
+            // Not registered — omitted from tools/list entirely (least-privilege).
+            return { name };
+        }
+        return raw(name, config, handler);
+    };
+    const s = server;
+    s.registerTool = gate(s.registerTool.bind(server));
+    // D2 task-model tools (long jobs like `godot_run_headless_script`) register
+    // through server.experimental.tasks.registerToolTask, NOT registerTool — gate
+    // that path too, or a privileged task tool would slip past the drop filter.
+    const tasks = s.experimental?.tasks;
+    if (tasks?.registerToolTask) {
+        tasks.registerToolTask = gate(tasks.registerToolTask.bind(tasks));
+    }
+}
+/**
+ * Register the always-on `godot://capabilities` resource: a read-only listing of
+ * the capability groups, their enabled/disabled state, exactly which tools each
+ * gates, the dropped set, and the env one-liner to enable them. Registered
+ * UNCONDITIONALLY (not behind the `resources` toolset), so the dropped privileged
+ * tools are never a silent gap — an agent can always see what exists-but-is-
+ * disabled and how to turn it on.
+ */
+export function registerCapabilitiesResource(server, enabled) {
+    server.registerResource("capabilities", "godot://capabilities", {
+        title: "Capability groups",
+        description: "Higher-trust tool groups, their enabled/disabled state, the tools each gates, and how to enable them.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const groups = CAPABILITY_GROUPS.map((g) => ({
+            id: g,
+            enabled: enabled.has(g),
+            describe: GROUP_DESCRIBE[g],
+            tools: Object.keys(TOOL_CAPABILITIES)
+                .filter((name) => (TOOL_CAPABILITIES[name] ?? []).includes(g))
+                .sort(),
+        }));
+        const payload = {
+            summary: "Two higher-trust tool groups are OFF by default. A disabled group's tools are not registered (omitted from tools/list). Enable a group to load its tools.",
+            default_secure: enabled.size === 0,
+            enabled_groups: [...enabled].sort(),
+            dropped_tools: droppedTools(enabled),
+            how_to_enable: "Set BREAKPOINT_PRIVILEGED_GROUPS in the MCP server env (comma-separated): 'code-execution', 'network', 'code-execution,network', or 'all'. Or re-run `npx breakpoint-mcp init` for a guided setup.",
+            groups,
+        };
+        return {
+            contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(payload, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/cli/clients.js

@@ -38,11 +38,14 @@ export function clientInfo(id, projectPath) {
             return null;
     }
 }
-/** The stdio server entry a client config needs. GODOT_BIN is included only when non-default. */
-export function serverEntry(projectPath, godotBin, needsType) {
+/** The stdio server entry a client config needs. GODOT_BIN is included only when
+ * non-default; BREAKPOINT_PRIVILEGED_GROUPS only when higher-trust groups are opted in. */
+export function serverEntry(projectPath, godotBin, needsType, privilegedGroups) {
     const env = { GODOT_PROJECT: projectPath };
     if (godotBin && godotBin !== "godot")
         env.GODOT_BIN = godotBin;
+    if (privilegedGroups)
+        env.BREAKPOINT_PRIVILEGED_GROUPS = privilegedGroups;
     const base = { command: "npx", args: ["-y", "breakpoint-mcp"], env };
     return needsType ? { type: "stdio", ...base } : base;
 }

package/dist/cli/doctor.js

@@ -22,6 +22,7 @@ import fs from "node:fs";
 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";
 const ADDON_REL = "addons/breakpoint_mcp";
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
@@ -175,8 +176,48 @@ function checkCsharpTool(name, cmd) {
             detail: `${cmd} not on PATH (C# plane inactive until installed)`,
         };
 }
+/**
+ * Report the capability-group state (`code-execution` / `network`), how many
+ * higher-trust tools the current setting drops, and how to change it — plus a
+ * signal hint when an asset-gen backend is configured but its group is off (so
+ * the "why won't asset-gen run?" gap the drop model can create is surfaced, not
+ * silent). Informational only — never a required failure.
+ */
+export function checkCapabilities(config) {
+    const enabled = selectPrivilegedGroups(config.privilegedGroups);
+    const dropped = droppedTools(enabled);
+    const state = CAPABILITY_GROUPS.map((g) => `${g} ${enabled.has(g) ? "on" : "off"}`).join(" · ");
+    const checks = [
+        {
+            name: "capability-groups",
+            status: "ok",
+            severity: "info",
+            detail: dropped.length === 0
+                ? `${state} — full 276-tool surface`
+                : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
+            hint: dropped.length === 0
+                ? undefined
+                : "Enable with BREAKPOINT_PRIVILEGED_GROUPS=code-execution,network (or `breakpoint-mcp init --trust full`). See the godot://capabilities resource for the exact tool list.",
+        },
+    ];
+    const assetGenConfigured = (config.assetGenBackend && config.assetGenBackend !== "none") ||
+        Boolean(config.assetGenCommand) ||
+        Boolean(config.assetGenProvider);
+    if (assetGenConfigured && !enabled.has("code-execution")) {
+        checks.push({
+            name: "capability-assetgen",
+            status: "ok",
+            severity: "info",
+            detail: "asset-gen backend configured, but code-execution is off — the asset_gen_* tools are not loaded",
+            hint: "Enable it: BREAKPOINT_PRIVILEGED_GROUPS=code-execution (the local command backend is the only privileged asset-gen path).",
+        });
+    }
+    return checks;
+}
 export async function runDoctorChecks(config, opts) {
     const checks = [];
+    // Capability groups — the secure-default surface + how to widen it (info only).
+    checks.push(...checkCapabilities(config));
     // 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.

package/dist/cli/init.js

@@ -15,6 +15,30 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "./args.js";
 import { CLIENT_IDS, clientInfo, mergeClientConfig, serverEntry, snippet } from "./clients.js";
 import { DEFAULT_REPO, fetchAddonFromGitHub } from "./github.js";
+import { CAPABILITY_GROUPS, parsePrivilegedGroups, selectPrivilegedGroups } from "../capabilities.js";
+/**
+ * Resolve the guided trust preset into a validated BREAKPOINT_PRIVILEGED_GROUPS
+ * value ("" = the safe default — `code-execution` + `network` off). Accepts either
+ * `--trust safe|full` (friendly presets) or `--privileged-groups <list>`
+ * (`code-execution`, `network`, `all`, comma-separated). Unknown tokens are dropped
+ * with a warning so a typo never silently enables a group.
+ */
+export function resolvePrivilegedGroups(flags) {
+    const trustAlias = { safe: "", none: "", off: "", full: "all", all: "all" };
+    const raw = typeof flags["privileged-groups"] === "string"
+        ? flags["privileged-groups"]
+        : typeof flags.trust === "string"
+            ? (trustAlias[flags.trust.toLowerCase()] ?? flags.trust)
+            : "";
+    if (!raw)
+        return { value: "" };
+    let warn;
+    const enabled = selectPrivilegedGroups(parsePrivilegedGroups(raw), (unknown) => {
+        warn = `ignoring unknown trust group(s): ${unknown.join(", ")} (valid: ${CAPABILITY_GROUPS.join(", ")}, all)`;
+    });
+    const value = [...enabled].sort().join(",");
+    return warn ? { value, warn } : { value };
+}
 const PLUGIN_REL = "addons/breakpoint_mcp";
 const PLUGIN_CFG_RES = "res://addons/breakpoint_mcp/plugin.cfg";
 const SERVER_NAME = "godot";
@@ -117,8 +141,9 @@ export function installAddon(addonSource, projectPath, opts) {
     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`;
+function claudeCodeCommand(projectPath, privilegedGroups) {
+    const groups = privilegedGroups ? ` --env BREAKPOINT_PRIVILEGED_GROUPS=${privilegedGroups}` : "";
+    return `claude mcp add godot --env GODOT_PROJECT=${projectPath}${groups} -- npx -y breakpoint-mcp`;
 }
 /** Entry point for `breakpoint-mcp init`. Returns the process exit code. */
 export async function runInit(argv, deps = {}) {
@@ -130,6 +155,8 @@ export async function runInit(argv, deps = {}) {
     const force = flags.force === true;
     const client = typeof flags.client === "string" ? flags.client : "none";
     const godotBin = process.env.GODOT_BIN ?? "godot";
+    // Guided trust preset → BREAKPOINT_PRIVILEGED_GROUPS ("" = safe default).
+    const { value: privilegedGroups, warn: privilegedWarn } = resolvePrivilegedGroups(flags);
     // --from-github [ref]: source the addon from GitHub instead of the bundled copy.
     const fromGitHub = "from-github" in flags;
     const fgVal = flags["from-github"];
@@ -212,14 +239,14 @@ export async function runInit(argv, deps = {}) {
     say("");
     if (client === "claude-code") {
         say("MCP client (Claude Code) — run:");
-        say(`  ${claudeCodeCommand(projectPath)}`);
+        say(`  ${claudeCodeCommand(projectPath, privilegedGroups)}`);
     }
     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(snippet("mcpServers", SERVER_NAME, serverEntry(projectPath, godotBin, false, privilegedGroups)));
         say("");
         say("Claude Code users can instead run:");
-        say(`  ${claudeCodeCommand(projectPath)}`);
+        say(`  ${claudeCodeCommand(projectPath, privilegedGroups)}`);
     }
     else {
         const info = clientInfo(client, projectPath);
@@ -227,7 +254,7 @@ export async function runInit(argv, deps = {}) {
             process.stderr.write(`init: unknown --client '${client}'. Known: ${CLIENT_IDS.join(", ")}.\n`);
             return 1;
         }
-        const entry = serverEntry(projectPath, godotBin, info.needsType);
+        const entry = serverEntry(projectPath, godotBin, info.needsType, privilegedGroups);
         if (dryRun) {
             say(`MCP client (${info.label}): would write ${info.configPath}`);
         }
@@ -249,6 +276,21 @@ export async function runInit(argv, deps = {}) {
             say(`MCP client (${info.label}): ${existed ? "updated" : "created"} ${info.configPath}${existed ? " (backup at .bak)" : ""}`);
         }
     }
+    // Trust groups — surface the secure default so even a bare `init` teaches it.
+    say("");
+    if (privilegedGroups) {
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 276-tool surface loads.`);
+    }
+    else {
+        say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");
+        say("everyday authoring/debug surface and drops the 14 code-execution + network tools (e.g.");
+        say("godot_run_headless_script, the *_call_method / dbg_evaluate tools, asset-gen, backend_*).");
+        say("Enable them by re-running with `--trust full` (or `--privileged-groups code-execution,network`),");
+        say("or set BREAKPOINT_PRIVILEGED_GROUPS in the server env. The `godot://capabilities` resource and");
+        say("`breakpoint-mcp doctor` list exactly what each group gates.");
+    }
+    if (privilegedWarn)
+        say(`  note: ${privilegedWarn}`);
     say("");
     say("Next: open the project in Godot, then run `breakpoint-mcp doctor --require-live` to verify.");
     process.stdout.write(out.join("\n") + "\n");

package/dist/config.js

@@ -1,4 +1,5 @@
 import { pathToFileURL } from "node:url";
+import { parsePrivilegedGroups } from "./capabilities.js";
 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
@@ -42,6 +43,69 @@ export function loadConfig() {
         assetGenCommand: process.env.BREAKPOINT_ASSETGEN_CMD ?? "",
         assetGenProvider: process.env.BREAKPOINT_ASSETGEN_PROVIDER ?? "",
         assetGenTimeoutMs: Number.parseInt(process.env.BREAKPOINT_ASSETGEN_TIMEOUT_MS ?? "120000", 10),
+        toolsets: parseToolsets(process.env.BREAKPOINT_TOOLSETS),
+        privilegedGroups: parsePrivilegedGroups(process.env.BREAKPOINT_PRIVILEGED_GROUPS),
     };
 }
+/** Parse the raw BREAKPOINT_TOOLSETS env into a normalized token list (or null
+ *  for "unset" → full surface). Comma/whitespace separated, lower-cased. */
+export function parseToolsets(raw) {
+    if (raw == null)
+        return null;
+    const toks = raw
+        .split(/[,\s]+/)
+        .map((t) => t.trim().toLowerCase())
+        .filter(Boolean);
+    return toks.length ? toks : null;
+}
+/**
+ * Plane/convenience aliases → concrete toolset ids. Kept here (not in
+ * `toolsets.ts`) so selection has no dependency on the register* functions and
+ * stays trivially unit-testable.
+ */
+export const TOOLSET_ALIASES = {
+    a: ["editor"],
+    b: ["cli"],
+    c: ["runtime"],
+    d: ["lsp", "cslsp", "dap", "csdap"],
+    csharp: ["cslsp", "csdap"],
+    semantic: ["lsp", "cslsp", "dap", "csdap"],
+};
+/**
+ * Resolve a requested toolset list against the known ids.
+ *  - `requested == null`  → every id (the default full surface).
+ *  - aliases expand to their ids; unknown tokens are dropped (reported via
+ *    `onUnknown`, so `index.ts` can warn without this being impure).
+ *  - if nothing valid resolves, fall back to the full surface (a misconfigured
+ *    filter must never silently yield an empty, useless server).
+ * Returns a Set preserving membership only; the caller iterates the ordered
+ * toolset list, so registration order is unaffected.
+ */
+export function selectToolsets(allIds, requested, onUnknown) {
+    const known = new Set(allIds);
+    if (requested == null)
+        return new Set(allIds);
+    const out = new Set();
+    const unknown = [];
+    for (const tok of requested) {
+        if (tok === "all") {
+            for (const id of allIds)
+                out.add(id);
+        }
+        else if (TOOLSET_ALIASES[tok]) {
+            for (const id of TOOLSET_ALIASES[tok])
+                if (known.has(id))
+                    out.add(id);
+        }
+        else if (known.has(tok)) {
+            out.add(tok);
+        }
+        else {
+            unknown.push(tok);
+        }
+    }
+    if (unknown.length && onUnknown)
+        onUnknown(unknown);
+    return out.size ? out : new Set(allIds);
+}
 //# sourceMappingURL=config.js.map

package/dist/confirm.js

@@ -1,3 +1,4 @@
+import { pauseLatch } from "./pause.js";
 /**
  * Gate a destructive action behind MCP elicitation (a client-side confirmation
  * prompt). Returns `null` when the action may proceed, or a blocking tool result
@@ -9,6 +10,26 @@
  * executed silently on a client that can't ask.
  */
 export async function gate(server, confirm, summary) {
+    // Track 2 — global-pause overlay. Coarser than the per-tool elicitation below
+    // (which stays the lead control): while the operator has the agent paused, hold
+    // ENTRY to this mutating action until they resume or the wait times out — then
+    // block rather than act. In-flight ops and read-only tools are never affected.
+    if (pauseLatch.isPaused()) {
+        const resumed = await pauseLatch.awaitResumed();
+        if (!resumed) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: `Paused — the agent is currently paused, so "${summary}" was held and NOT executed. ` +
+                            `Resume the agent (SIGUSR2), then re-run the tool.`,
+                    },
+                ],
+            };
+        }
+    }
+    pauseLatch.record(summary);
     if (confirm === true)
         return null;
     try {

package/dist/index.js

@@ -1,36 +1,26 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, selectToolsets } from "./config.js";
 import { BridgeClient } from "./bridge.js";
+import { resolveBridgeSecret } from "./secret.js";
 import { LspClient } from "./lsp.js";
 import { CsLspClient } from "./cslsp.js";
 import { CsDapClient } from "./csdap.js";
 import { StdioChannel } from "./stdio.js";
 import { DapClient } from "./dap.js";
-import { registerCliTools } from "./tools/cli.js";
-import { registerEditorTools } from "./tools/editor.js";
-import { registerLspTools } from "./tools/lsp.js";
-import { registerCsLspTools } from "./tools/cslsp.js";
-import { registerDapTools } from "./tools/dap.js";
-import { registerCsDapTools } from "./tools/csdap.js";
-import { registerRuntimeTools } from "./tools/runtime.js";
-import { registerProcessTools } from "./tools/processes.js";
-import { registerKnowledgeTools } from "./tools/knowledge.js";
-import { registerVcsTools } from "./tools/vcs.js";
-import { registerAssetGenTools } from "./tools/assetgen.js";
-import { registerNetcodeTools } from "./tools/netcode.js";
-import { registerBackendTools } from "./tools/backend.js";
-import { registerTabletopTools } from "./tools/tabletop.js";
-import { registerResources } from "./tools/resources.js";
+import { buildToolsets } from "./toolsets.js";
+import { registerRecipes } from "./recipes.js";
 import { applyOutputSchemas } from "./schemas.js";
+import { applyCapabilities, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
+import { pauseLatch, installPauseSignalHandlers } from "./pause.js";
 import { log } from "./logger.js";
 async function main() {
     const config = loadConfig();
-    const bridge = new BridgeClient(config.bridgeHost, config.bridgePort, config.bridgeTimeoutMs);
-    const runtime = new BridgeClient(config.runtimeHost, config.runtimePort, config.runtimeTimeoutMs, "runtime bridge", "Is the project running? Launch it (godot_run_project or dbg_launch) with the Breakpoint MCP plugin enabled — it auto-registers the runtime autoload.");
+    const bridge = new BridgeClient(config.bridgeHost, config.bridgePort, config.bridgeTimeoutMs, "editor bridge", undefined, () => resolveBridgeSecret(config.projectPath, ["BREAKPOINT_BRIDGE_SECRET"]));
+    const runtime = new BridgeClient(config.runtimeHost, config.runtimePort, config.runtimeTimeoutMs, "runtime bridge", "Is the project running? Launch it (godot_run_project or dbg_launch) with the Breakpoint MCP plugin enabled — it auto-registers the runtime autoload.", () => resolveBridgeSecret(config.projectPath, ["BREAKPOINT_RUNTIME_SECRET", "BREAKPOINT_BRIDGE_SECRET"]));
     const lsp = new LspClient(config.lspHost, config.lspPort, config.projectUri, config.lspTimeoutMs);
     // D4 C2: the C# semantic plane. OmniSharp is spawned over stdio (lazily, on the
     // first cs_* call) against the C# project root — so a host without OmniSharp
@@ -45,58 +35,75 @@ 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.11.0" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.19.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.
+    // any register*Tools call — it wraps server.registerTool.
     applyOutputSchemas(server);
-    // Plane B (headless CLI): works without the editor running.
-    registerCliTools(server, config);
-    // Plane A (live editor): requires the editor open with the Breakpoint MCP plugin.
-    registerEditorTools(server, bridge);
-    // Plane D (semantic): connects to Godot's GDScript language server (LSP, 6005).
-    registerLspTools(server, lsp, config);
-    // Plane D (C# semantic, D4 C2): drives OmniSharp over stdio for the cs_* tools.
-    registerCsLspTools(server, csLsp, config);
-    // Plane D (debugging): connects to Godot's Debug Adapter (DAP, 6006).
-    registerDapTools(server, dap, config);
-    // Plane D (C# debugging, D4 C3): drives netcoredbg over stdio for the cs_dbg_* tools.
-    registerCsDapTools(server, csDap, config);
-    // Plane C (runtime): connects to the in-game runtime autoload (9081).
-    registerRuntimeTools(server, runtime);
-    // Phase 4: managed run + captured console output (transparent print() logs).
-    const processes = registerProcessTools(server, config);
-    // Group K: host-side knowledge & search (project grep, symbol/usage index, idiom lookup).
-    registerKnowledgeTools(server, config);
-    // Group L: host-side version control (vcs_*). Read-only core over the `git` binary
-    // (status/log/diff/show/branches/blame) rooted at the project path — no editor, no
-    // language server, so it answers whenever the project is a git work tree. Mutating
-    // git tools are deferred pending a scope steer and will reuse the elicitation gate.
-    registerVcsTools(server, config);
-    // Group J: AI asset generation (delegated backend / connected client; degrades
-    // to a request spec when no backend is configured). Writes + imports via the bridge.
-    registerAssetGenTools(server, bridge, config);
-    // Group M: native multiplayer & backend scaffolding (mp_*). Pure authoring —
-    // undoable node ops (spawner/synchronizer/authority) + gated GDScript codegen
-    // (enet/webrtc peer, @rpc wiring, lobby). Hosts nothing; scaffolds everything.
-    registerNetcodeTools(server, bridge, config);
-    // Group M (second half): backend-SDK integration scaffolding (backend_* / *_scaffold).
-    // Detects the installed SDK (SilentWolf/Nakama/PlayFab/Photon) and generates gated
-    // GDScript against it; degrades cleanly when the SDK is absent or lacks the feature.
-    registerBackendTools(server, bridge, config);
-    // Group N: card/board/piece authoring composites (card_*). Host-side scripted
-    // sequences of existing editor-bridge primitives (scene/control/node/theme/
-    // resource) — they build + data-bind scenes, add no addon method, and invent
-    // no game rules or data.
-    registerTabletopTools(server, bridge, config);
-    // Phase 4: MCP resources (scene tree, editor state, runtime tree/log, ClassDB docs).
-    registerResources(server, bridge, runtime);
+    // 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
+    // registration (omitted from tools/list), so the secure-default surface is
+    // 276 − 14 = 262 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);
+    // The A/B/C/D planes ARE the grouping. Build the ordered toolset registry
+    // (the single source of truth, shared with the registration tests) and
+    // register only the selected groups. Default (BREAKPOINT_TOOLSETS unset) =
+    // every group → the full 276-tool surface, byte-identical to before. A filter
+    // lets a client that can't defer tools, or a user who wants a smaller default
+    // menu, load only the planes a project needs (GitHub-MCP `--toolsets` style).
+    let processes;
+    const toolsets = buildToolsets({
+        server,
+        bridge,
+        runtime,
+        lsp,
+        csLsp,
+        dap,
+        csDap,
+        config,
+        onProcesses: (h) => {
+            processes = h;
+        },
+    });
+    const enabled = selectToolsets(toolsets.map((t) => t.id), config.toolsets, (unknown) => log(`ignoring unknown BREAKPOINT_TOOLSETS token(s): ${unknown.join(", ")}`));
+    for (const ts of toolsets)
+        if (enabled.has(ts.id))
+            ts.run();
     // D3: resource subscriptions — push notifications/resources/updated when a
     // 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.
+    // the running game's live SceneTree). Adds no tools (pure notification
+    // plumbing), so it's wired here rather than as a toolset, gated on `resources`.
+    // Rapid changes are coalesced per-URI; the trailing window is overridable via
+    // BREAKPOINT_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 });
+    if (enabled.has("resources")) {
+        registerResourceSubscriptions(server, bridge, runtime, undefined, { coalesceMs });
+    }
+    if (config.toolsets) {
+        log(`toolsets enabled: ${[...enabled].sort().join(", ")} (${enabled.size}/${toolsets.length} groups)`);
+    }
+    // Recipes: a free, curated task-recipe layer exposed as MCP prompts (discoverable
+    // via prompts/list). Adds NO tools — the 276-tool count is unchanged — and drives
+    // the enforced tools above, so it's a skill-pack layer over typed/undoable tools.
+    registerRecipes(server);
+    // Always-on capability affordance — never behind a toolset or a privileged
+    // group — so the dropped high-trust tools are never a silent gap: an agent can
+    // read godot://capabilities to see what exists-but-is-disabled and how to
+    // enable it. Registered directly (not via the `resources` toolset).
+    registerCapabilitiesResource(server, privilegedGroups);
+    if (config.privilegedGroups) {
+        const on = [...privilegedGroups].sort().join(", ") || "(none)";
+        log(`privileged groups enabled: ${on}; dropped ${droppedTools(privilegedGroups).length} tool(s) from the surface`);
+    }
+    // Track 2 — global-pause latch (prototype). A coarse overlay on the destructive
+    // gate: SIGUSR1 pauses, SIGUSR2 resumes; BREAKPOINT_START_PAUSED starts held.
+    // Per-tool elicitation gating stays the lead control (see src/pause.ts).
+    installPauseSignalHandlers();
+    if (pauseLatch.isPaused()) {
+        log("[pause] started PAUSED (BREAKPOINT_START_PAUSED) — send SIGUSR2 to resume");
+    }
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log(`ready · godotBin=${config.godotBin} · project=${config.projectPath} · ` +
@@ -109,7 +116,7 @@ async function main() {
         csLsp.close();
         dap.close();
         csDap.close();
-        processes.killAll();
+        processes?.killAll();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);