breakpoint-mcp 1.21.1 → 1.23.0

package/README.md

@@ -3,7 +3,7 @@
 The MCP **host** for [Breakpoint MCP](https://github.com/jlivingston-Cipher/godot-breakpoint-mcp) —
 a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
 Godot game engine to AI coding assistants across four planes: headless CLI, the live
-editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **286 tools
+editor, Godot's own LSP + DAP, and a runtime bridge inside the running game. **289 tools
 + 6 MCP resources**, built against the stable `@modelcontextprotocol/sdk` 1.x API.
 Developed and tested with **Claude**; because MCP is an open protocol, other clients can
 connect too (currently untested — reports welcome).

package/dist/annotations.js

@@ -0,0 +1,225 @@
+/** Tools that mutate nothing. */
+const READ_ONLY = [
+    "anim_get_track_keys", "anim_list", "backend_detect", "class_reference", "classdb_get_class", "cs_code_action",
+    "cs_completion", "cs_dbg_scopes", "cs_dbg_stack_trace", "cs_dbg_variables", "cs_definition", "cs_diagnostics",
+    "cs_document_symbols", "cs_hover", "cs_references", "cs_signature_help", "cs_workspace_symbols", "dbg_scopes",
+    "dbg_stack_trace", "dbg_variables", "docs_search", "editor_get_state", "editor_ping", "example_snippet",
+    "filesystem_list", "find_symbol", "find_usages", "gd_call_hierarchy", "gd_code_action", "gd_completion",
+    "gd_declaration", "gd_definition", "gd_diagnostics", "gd_document_color", "gd_document_highlight",
+    "gd_document_link", "gd_document_symbols", "gd_folding_ranges", "gd_formatting", "gd_hover", "gd_implementation",
+    "gd_references", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition", "gd_workspace_symbols",
+    "godot_output", "godot_version", "inputmap_list", "node_find", "node_get_children", "node_get_path",
+    "node_get_property", "node_list_groups", "node_list_properties", "project_get_info", "project_get_setting",
+    "project_list_settings", "project_search", "resource_get_import_settings", "resource_get_property",
+    "resource_load", "runtime_anim_get_state", "runtime_assert_node_state", "runtime_assert_perf",
+    "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log",
+    "runtime_get_monitors", "runtime_get_property", "runtime_get_tree", "runtime_screenshot",
+    "runtime_peers_digest", "runtime_screenshot_diff", "runtime_state_digest", "scene_get_dependencies",
+    "scene_get_tree", "scene_list_open", "screenshot_editor", "selection_get", "signal_list",
+    "signal_list_connections", "test_detect", "test_list", "tilemap_get_cell", "vcs_blame", "vcs_branch_list",
+    "vcs_diff", "vcs_log", "vcs_show", "vcs_status",
+];
+/** Tools that may overwrite or discard state the caller did not supply. */
+const DESTRUCTIVE = [
+    "anim_delete", "anim_remove_key", "asset_gen_audio_sfx", "asset_gen_icon", "asset_gen_model",
+    "asset_gen_placeholder", "asset_gen_sprite", "asset_gen_texture", "audio_bus_set_volume", "audio_set_bus_layout",
+    "auth_scaffold", "backend_configure", "board_create", "board_tile_create", "card_template_create",
+    "cloudsave_scaffold", "cs_dbg_evaluate", "cs_dbg_set_variable", "cs_rename", "dbg_evaluate", "dbg_goto",
+    "dbg_set_variable", "editorsettings_get_set", "environment_create", "environment_set_sky", "filesystem_move",
+    "gd_rename", "godot_run_headless_script", "godot_stop", "inputmap_add_action", "inputmap_erase_action",
+    "interact_add_drop_zone", "interact_make_draggable", "leaderboard_scaffold", "mp_scaffold_lobby",
+    "mp_setup_enet_peer", "mp_setup_webrtc_peer", "mp_wire_rpc", "node_call_method", "node_change_type",
+    "node_delete", "node_remove_from_group", "physics_set_gravity", "piece_template_create", "primitive_mesh_create",
+    "project_add_autoload", "project_remove_autoload", "project_set_main_scene", "project_set_setting",
+    "resource_create", "resource_duplicate", "resource_save", "resource_set_import_settings",
+    "resource_set_property", "runtime_anim_play", "runtime_anim_stop", "runtime_call_method", "runtime_emit_signal",
+    "runtime_inject_input", "runtime_node_remove", "runtime_peer_stop", "runtime_seed_rng", "runtime_set_property",
+    "runtime_step_frames", "runtime_time_scale", "scene_close", "scene_new", "scene_pack", "scene_reload", "scene_save_as", "shader_create",
+    "shader_set_code", "shadermaterial_create", "shadermaterial_set_param", "shadermaterial_set_shader",
+    "signal_disconnect", "signal_emit", "theme_create", "theme_set_color", "theme_set_constant", "theme_set_font",
+    "theme_set_stylebox", "tilemap_clear", "tilemap_set_cell", "tilemap_set_cells_rect", "tileset_create",
+    "vcs_restore", "vcs_stash",
+];
+/** Tools where a repeat call with identical arguments adds no further effect. */
+const IDEMPOTENT = [
+    "anim_create", "anim_delete", "anim_get_track_keys", "anim_insert_key", "anim_list", "anim_set_length",
+    "anim_set_loop", "anim_statemachine_add_state", "anim_statemachine_add_transition", "anim_tree_add_node",
+    "area_set_gravity", "area_set_monitoring", "asset_gen_configure", "asset_gen_placeholder",
+    "audio_bus_set_volume", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold", "backend_configure",
+    "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
+    "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material", "card_template_create",
+    "class_reference", "classdb_get_class", "cloudsave_scaffold", "control_set_anchors", "control_set_layout_preset",
+    "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion", "cs_dbg_attach",
+    "cs_dbg_scopes", "cs_dbg_set_breakpoints", "cs_dbg_set_exception_breakpoints", "cs_dbg_set_variable",
+    "cs_dbg_stack_trace", "cs_dbg_variables", "cs_dbg_watch", "cs_definition", "cs_diagnostics",
+    "cs_document_symbols", "cs_hover", "cs_references", "cs_rename", "cs_signature_help", "cs_workspace_symbols",
+    "dbg_attach", "dbg_data_breakpoints", "dbg_goto", "dbg_scopes", "dbg_set_breakpoints",
+    "dbg_set_exception_breakpoints", "dbg_set_variable", "dbg_stack_trace", "dbg_variables", "dbg_watch",
+    "docs_search", "editor_get_state", "editor_ping", "editorsettings_get_set", "environment_create",
+    "environment_set_sky", "example_snippet", "filesystem_create_dir", "filesystem_list", "filesystem_move",
+    "filesystem_scan", "find_symbol", "find_usages", "gd_call_hierarchy", "gd_code_action", "gd_completion",
+    "gd_declaration", "gd_definition", "gd_diagnostics", "gd_document_color", "gd_document_highlight",
+    "gd_document_link", "gd_document_symbols", "gd_folding_ranges", "gd_formatting", "gd_hover", "gd_implementation",
+    "gd_references", "gd_rename", "gd_semantic_tokens", "gd_signature_help", "gd_type_definition",
+    "gd_workspace_symbols", "godot_export", "godot_import", "godot_output", "godot_stop", "godot_version",
+    "inputmap_add_action", "inputmap_erase_action", "inputmap_list", "joint_set_bodies", "leaderboard_scaffold",
+    "mesh_set_surface_material", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer",
+    "mp_setup_webrtc_peer", "mp_wire_rpc", "node_add_to_group", "node_change_type", "node_delete", "node_find",
+    "node_get_children", "node_get_path", "node_get_property", "node_list_groups", "node_list_properties",
+    "node_move_child", "node_remove_from_group", "node_rename", "node_reparent", "node_set_editable_instance",
+    "node_set_owner", "node_set_property", "particles_set_amount", "particles_set_emitting",
+    "particles_set_lifetime", "particles_set_process_material", "particles_set_texture", "physics_set_gravity",
+    "piece_template_create", "primitive_mesh_create", "project_add_autoload", "project_get_info",
+    "project_get_setting", "project_list_settings", "project_remove_autoload", "project_search",
+    "project_set_main_scene", "project_set_setting", "resource_create", "resource_duplicate",
+    "resource_get_import_settings", "resource_get_property", "resource_load", "resource_save",
+    "resource_set_import_settings", "resource_set_property", "rigidbody_set_properties", "runtime_anim_get_state",
+    "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf", "runtime_assert_scene_structure",
+    "runtime_assert_screen_text", "runtime_await_condition", "runtime_get_log", "runtime_get_monitors",
+    "runtime_get_property", "runtime_get_tree", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_state_digest", "runtime_time_scale", "scene_get_dependencies", "scene_get_tree", "scene_list_open", "scene_new", "scene_open",
+    "scene_pack", "scene_reload", "scene_save", "scene_save_as", "screenshot_editor", "selection_get",
+    "selection_set", "shader_create", "shader_set_code", "shadermaterial_create", "shadermaterial_set_param",
+    "shadermaterial_set_shader", "signal_add_user_signal", "signal_connect", "signal_disconnect", "signal_list",
+    "signal_list_connections", "test_detect", "test_list", "theme_create", "theme_set_color", "theme_set_constant",
+    "theme_set_font", "theme_set_stylebox", "tilemap_clear", "tilemap_get_cell", "tilemap_set_cell",
+    "tilemap_set_cells_rect", "tileset_add_tile", "tileset_create", "vcs_add", "vcs_blame", "vcs_branch_list",
+    "vcs_diff", "vcs_log", "vcs_restore", "vcs_show", "vcs_status", "vcs_switch",
+];
+/**
+ * Tools that reach outside this machine + this project. Empty by design — every
+ * bridge is loopback-only. A future networked tool must be listed here.
+ */
+const OPEN_WORLD = [];
+/**
+ * The complete annotated roster — every registered tool, listed explicitly.
+ *
+ * This CANNOT be derived as the union of the four lists above: 52 tools are
+ * all-false (mutating, non-destructive, non-idempotent, local — e.g. `node_add`,
+ * `dbg_step`, `vcs_commit`), so a derived union would silently omit them and the
+ * totality check below would pass while they shipped unannotated. Listing the
+ * roster explicitly is what makes "every tool is annotated" an assertion rather
+ * than a tautology.
+ */
+export const ALL_ANNOTATED = [
+    "anim_add_track", "anim_create", "anim_delete", "anim_get_track_keys", "anim_insert_key", "anim_list",
+    "anim_player_create", "anim_remove_key", "anim_set_length", "anim_set_loop", "anim_statemachine_add_state",
+    "anim_statemachine_add_transition", "anim_tree_add_node", "anim_tree_create", "area_set_gravity",
+    "area_set_monitoring", "asset_gen_audio_sfx", "asset_gen_configure", "asset_gen_icon", "asset_gen_model",
+    "asset_gen_placeholder", "asset_gen_sprite", "asset_gen_texture", "audio_bus_add", "audio_bus_add_effect",
+    "audio_bus_set_volume", "audio_player_create", "audio_set_bus_layout", "audio_set_stream", "auth_scaffold",
+    "backend_configure", "backend_detect", "board_create", "board_place", "board_tile_create", "board_tile_place",
+    "body_create", "body_set_collision_layer", "body_set_collision_mask", "body_set_physics_material",
+    "camera_create", "card_deck_from_table", "card_hand_layout", "card_instance", "card_set_face",
+    "card_template_create", "class_reference", "classdb_get_class", "cloudsave_scaffold", "collisionpolygon_add",
+    "collisionshape_add", "container_add_child", "control_create", "control_set_anchors",
+    "control_set_layout_preset", "control_set_size_flags", "control_set_theme", "cs_code_action", "cs_completion",
+    "cs_dbg_attach", "cs_dbg_continue", "cs_dbg_evaluate", "cs_dbg_launch", "cs_dbg_restart", "cs_dbg_scopes",
+    "cs_dbg_set_breakpoints", "cs_dbg_set_exception_breakpoints", "cs_dbg_set_variable", "cs_dbg_stack_trace",
+    "cs_dbg_step", "cs_dbg_variables", "cs_dbg_watch", "cs_definition", "cs_diagnostics", "cs_document_symbols",
+    "cs_hover", "cs_references", "cs_rename", "cs_signature_help", "cs_workspace_symbols", "csg_create",
+    "dbg_attach", "dbg_continue", "dbg_data_breakpoints", "dbg_evaluate", "dbg_goto", "dbg_launch", "dbg_restart",
+    "dbg_scopes", "dbg_set_breakpoints", "dbg_set_exception_breakpoints", "dbg_set_variable", "dbg_stack_trace",
+    "dbg_step", "dbg_variables", "dbg_watch", "docs_search", "editor_get_state", "editor_ping", "editor_redo",
+    "editor_undo", "editorsettings_get_set", "environment_create", "environment_set_sky", "example_snippet",
+    "filesystem_create_dir", "filesystem_list", "filesystem_move", "filesystem_scan", "find_symbol", "find_usages",
+    "gd_call_hierarchy", "gd_code_action", "gd_completion", "gd_declaration", "gd_definition", "gd_diagnostics",
+    "gd_document_color", "gd_document_highlight", "gd_document_link", "gd_document_symbols", "gd_folding_ranges",
+    "gd_formatting", "gd_hover", "gd_implementation", "gd_references", "gd_rename", "gd_semantic_tokens",
+    "gd_signature_help", "gd_type_definition", "gd_workspace_symbols", "godot_export", "godot_import",
+    "godot_launch_editor", "godot_output", "godot_run_headless_script", "godot_run_managed", "godot_run_project",
+    "godot_stop", "godot_version", "inputmap_add_action", "inputmap_add_event", "inputmap_erase_action",
+    "inputmap_list", "interact_add_drop_zone", "interact_make_draggable", "joint_create", "joint_set_bodies",
+    "leaderboard_scaffold", "light_create", "mesh_set_surface_material", "meshinstance_create", "mp_add_spawner",
+    "mp_add_synchronizer", "mp_scaffold_lobby", "mp_set_authority", "mp_setup_enet_peer", "mp_setup_webrtc_peer",
+    "mp_wire_rpc", "navagent_configure", "navregion_create", "node_add", "node_add_to_group", "node_call_method",
+    "node_change_type", "node_delete", "node_duplicate", "node_find", "node_get_children", "node_get_path",
+    "node_get_property", "node_instantiate_scene", "node_list_groups", "node_list_properties", "node_move_child",
+    "node_remove_from_group", "node_rename", "node_reparent", "node_set_editable_instance", "node_set_owner",
+    "node_set_property", "particles_create", "particles_set_amount", "particles_set_emitting",
+    "particles_set_lifetime", "particles_set_process_material", "particles_set_texture", "physics_set_gravity",
+    "piece_instance", "piece_move", "piece_template_create", "primitive_mesh_create", "project_add_autoload",
+    "project_add_export_preset", "project_get_info", "project_get_setting", "project_list_settings",
+    "project_remove_autoload", "project_search", "project_set_main_scene", "project_set_setting", "resource_create",
+    "resource_duplicate", "resource_get_import_settings", "resource_get_property", "resource_load", "resource_save",
+    "resource_set_import_settings", "resource_set_property", "rigidbody_set_properties", "runtime_anim_get_state",
+    "runtime_anim_play", "runtime_anim_stop", "runtime_assert_node_state", "runtime_assert_perf",
+    "runtime_assert_scene_structure", "runtime_assert_screen_text", "runtime_await_condition", "runtime_call_method",
+    "runtime_emit_signal", "runtime_get_log", "runtime_get_monitors", "runtime_get_property", "runtime_get_tree",
+    "runtime_inject_input", "runtime_node_add", "runtime_node_remove", "runtime_peer_stop", "runtime_peers_digest",
+    "runtime_screenshot", "runtime_screenshot_diff", "runtime_seed_rng", "runtime_set_property",
+    "runtime_spawn_peers", "runtime_state_digest", "runtime_step_frames", "runtime_time_scale", "scene_close",
+    "scene_get_dependencies", "scene_get_tree",
+    "scene_list_open", "scene_new", "scene_open", "scene_pack", "scene_reload", "scene_save", "scene_save_as",
+    "screenshot_editor", "selection_get", "selection_set", "shader_create", "shader_set_code",
+    "shadermaterial_create", "shadermaterial_set_param", "shadermaterial_set_shader", "signal_add_user_signal",
+    "signal_connect", "signal_disconnect", "signal_emit", "signal_list", "signal_list_connections", "test_detect",
+    "test_list", "theme_create", "theme_set_color", "theme_set_constant", "theme_set_font", "theme_set_stylebox",
+    "tilemap_clear", "tilemap_get_cell", "tilemap_set_cell", "tilemap_set_cells_rect", "tilemaplayer_create",
+    "tileset_add_source", "tileset_add_tile", "tileset_create", "tileset_set_tile_collision", "vcs_add", "vcs_blame",
+    "vcs_branch_create", "vcs_branch_list", "vcs_commit", "vcs_diff", "vcs_log", "vcs_restore", "vcs_show",
+    "vcs_stash", "vcs_status", "vcs_switch",
+];
+const readOnly = new Set(READ_ONLY);
+const destructive = new Set(DESTRUCTIVE);
+const idempotent = new Set(IDEMPOTENT);
+const openWorld = new Set(OPEN_WORLD);
+/**
+ * Guard the one way this table can rot silently: a name typo'd into READ_ONLY /
+ * DESTRUCTIVE / IDEMPOTENT that is not on the roster would otherwise annotate
+ * nothing and fail no test. Throwing at module load turns that into an
+ * immediate, obvious failure in every consumer, tests included.
+ */
+{
+    const roster = new Set(ALL_ANNOTATED);
+    const orphans = [...new Set([...READ_ONLY, ...DESTRUCTIVE, ...IDEMPOTENT, ...OPEN_WORLD])]
+        .filter((n) => !roster.has(n))
+        .sort();
+    if (orphans.length) {
+        throw new Error(`annotations.ts: name(s) in a hint list but absent from ALL_ANNOTATED: ${orphans.join(", ")}`);
+    }
+}
+/** Every tool name carrying an annotation entry — the totality set for the tests. */
+export const ANNOTATED_TOOLS = Object.freeze([...ALL_ANNOTATED].sort());
+/**
+ * The four hints for one tool. Every registered tool resolves to a complete
+ * block: absence from a list is a positive "false", never "unknown", so a
+ * consumer never has to fall back to guessing from the name.
+ */
+export function annotationsFor(name) {
+    return {
+        readOnlyHint: readOnly.has(name),
+        destructiveHint: destructive.has(name),
+        idempotentHint: idempotent.has(name),
+        openWorldHint: openWorld.has(name),
+    };
+}
+/**
+ * Wrap `server.registerTool` to inject the annotations block at registration.
+ * Mirrors `applyOutputSchemas` / `applyCapabilities`; call once, after
+ * `applyOutputSchemas` and before any `register*Tools()`. An explicit
+ * `annotations` already on the config wins, so a call site can override.
+ *
+ * `title` is left alone — the SDK already promotes the top-level `title` to the
+ * annotation of the same name, and duplicating it here would fight that.
+ */
+export function applyAnnotations(server) {
+    const inject = (raw) => (name, config, handler) => {
+        const cfg = config;
+        if (cfg && cfg.annotations === undefined) {
+            config = { ...cfg, annotations: annotationsFor(name) };
+        }
+        return raw(name, config, handler);
+    };
+    const s = server;
+    s.registerTool = inject(s.registerTool.bind(server));
+    // D2 task-model tools (godot_export / godot_import / godot_run_headless_script)
+    // register through experimental.tasks.registerToolTask, not registerTool —
+    // annotate that path too or three tools ship hint-less.
+    const tasks = s.experimental?.tasks;
+    if (tasks?.registerToolTask) {
+        tasks.registerToolTask = inject(tasks.registerToolTask.bind(tasks));
+    }
+}
+//# sourceMappingURL=annotations.js.map

package/dist/capabilities.js

@@ -2,7 +2,7 @@
 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.",
+    "code-execution": "Run arbitrary GDScript, invoke arbitrary methods, evaluate an expression in a paused debug frame, spawn headless child processes of the project, or run a local asset-gen command backend.",
     network: "Egress beyond loopback — the Group M backend SDK.",
 };
 /**
@@ -16,6 +16,10 @@ export const TOOL_CAPABILITIES = {
     godot_run_managed: ["code-execution"],
     node_call_method: ["code-execution"],
     runtime_call_method: ["code-execution"],
+    // F6: spawns headless Godot child processes of the project — the same class of
+    // trust as godot_run_managed, which is why it is privileged rather than merely
+    // confirmation-gated.
+    runtime_spawn_peers: ["code-execution"],
     dbg_evaluate: ["code-execution"],
     cs_dbg_evaluate: ["code-execution"],
     // asset generation — the local command backend (code-execution) is the only

package/dist/cli/doctor.js

@@ -193,7 +193,7 @@ export function checkCapabilities(config) {
             status: "ok",
             severity: "info",
             detail: dropped.length === 0
-                ? `${state} — full 286-tool surface`
+                ? `${state} — full 289-tool surface`
                 : `${state} (secure default) — ${dropped.length} higher-trust tool(s) dropped from the surface`,
             hint: dropped.length === 0
                 ? undefined

package/dist/cli/init.js

@@ -279,7 +279,7 @@ export async function runInit(argv, deps = {}) {
     // 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 286-tool surface loads.`);
+        say(`Higher-trust tool groups enabled: ${privilegedGroups} — the full 289-tool surface loads.`);
     }
     else {
         say("Higher-trust tool groups are OFF by default (the secure default). The assistant loads the");

package/dist/cli/tools.js

@@ -0,0 +1,193 @@
+/**
+ * `breakpoint-mcp tools` — export the tool surface as a stable, machine-readable
+ * artifact.
+ *
+ * Why this exists: third-party MCP catalogs, policy gateways, and security
+ * reviewers need to know what this server exposes and how risky each tool is.
+ * Without a published artifact their only options are to run the server and
+ * speak MCP at it, or to infer risk from tool NAMES. A public catalog did the
+ * latter in July 2026 and got it backwards in both directions — `tilemap_clear`
+ * filed as irreversible (it is undoable), `theme_set_color` not flagged at all
+ * (it rewrites a `.tres` in place). This command, plus the annotations shipped
+ * on `tools/list`, removes the need to guess.
+ *
+ * It reports the surface WITHOUT connecting to Godot: the registry is built
+ * against a recorder using the same `buildToolsets` path `index.ts` drives, with
+ * stub clients, and no handler is ever invoked. So it works in CI, in a
+ * container, and on a machine with no Godot installed.
+ *
+ * Two surfaces are reported, because the difference is the security story:
+ *   • `full`           — all 289 tools, what loads with BREAKPOINT_PRIVILEGED_GROUPS=all
+ *   • `secure-default` — 274, what an untouched install actually advertises
+ * `--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 { buildToolsets } from "../toolsets.js";
+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";
+    }
+}
+/**
+ * Register the whole surface against a recorder, exactly as `index.ts` does
+ * (`applyOutputSchemas` → `applyAnnotations` → every `register*Tools`), and
+ * capture each tool's config. Capability filtering is applied afterwards rather
+ * than via `applyCapabilities`, so a single pass can report both surfaces.
+ */
+function recordSurface() {
+    const recorded = [];
+    let current = "";
+    const push = (name, config) => {
+        recorded.push({ name, config, toolset: current });
+        return { name };
+    };
+    const server = {
+        registerTool: (name, config) => push(name, config),
+        registerResource: () => { },
+        experimental: {
+            tasks: { registerToolTask: (name, config) => push(name, config) },
+        },
+        server: { elicitInput: async () => ({ action: "decline" }) },
+    };
+    const mcp = server;
+    const stub = {};
+    applyOutputSchemas(mcp);
+    applyAnnotations(mcp);
+    for (const ts of buildToolsets({
+        server: mcp,
+        bridge: stub,
+        runtime: stub,
+        lsp: stub,
+        csLsp: stub,
+        dap: stub,
+        csDap: stub,
+        config: loadConfig(),
+    })) {
+        current = ts.id;
+        ts.run();
+    }
+    return recorded;
+}
+function toExported(r) {
+    const groups = [...(TOOL_CAPABILITIES[r.name] ?? [])];
+    const shape = r.config.inputSchema ?? {};
+    const params = Object.keys(shape);
+    return {
+        name: r.name,
+        title: typeof r.config.title === "string" ? r.config.title : null,
+        description: typeof r.config.description === "string" ? r.config.description : null,
+        toolset: r.toolset,
+        capabilityGroups: groups,
+        privileged: groups.length > 0,
+        confirmationGated: params.includes("confirm"),
+        params,
+        annotations: annotationsFor(r.name),
+    };
+}
+/** Build the report. Exported for the tests, which assert it against the registry. */
+export function buildToolsReport(surface) {
+    const all = recordSurface().map(toExported);
+    const secure = all.filter((t) => !t.privileged);
+    const shown = surface === "full" ? all : secure;
+    return {
+        server: { name: "breakpoint-mcp", version: packageVersion() },
+        // Deliberately null, not a timestamp: this artifact is a pure function of the
+        // source tree, so two runs of the same build must be byte-identical (a
+        // consumer can diff releases; CI can assert no drift).
+        generatedAt: null,
+        surface,
+        counts: {
+            full: all.length,
+            secureDefault: secure.length,
+            readOnly: shown.filter((t) => t.annotations.readOnlyHint).length,
+            destructive: shown.filter((t) => t.annotations.destructiveHint).length,
+            idempotent: shown.filter((t) => t.annotations.idempotentHint).length,
+            openWorld: shown.filter((t) => t.annotations.openWorldHint).length,
+            confirmationGated: shown.filter((t) => t.confirmationGated).length,
+            privileged: all.length - secure.length,
+        },
+        capabilityGroups: CAPABILITY_GROUPS.map((g) => ({
+            id: g,
+            describe: GROUP_DESCRIBE[g],
+            defaultEnabled: false,
+            tools: all.filter((t) => t.capabilityGroups.includes(g)).map((t) => t.name).sort(),
+        })),
+        tools: [...shown].sort((a, b) => a.name.localeCompare(b.name)),
+    };
+}
+function renderText(report) {
+    const c = report.counts;
+    const lines = [
+        `breakpoint-mcp ${report.server.version} — ${report.surface} surface`,
+        "",
+        `  tools                ${report.tools.length}` +
+            (report.surface === "secure-default" ? `  (of ${c.full} total; ${c.privileged} privileged, dropped)` : ""),
+        `  read-only            ${c.readOnly}`,
+        `  destructive          ${c.destructive}`,
+        `  idempotent           ${c.idempotent}`,
+        `  open-world (egress)  ${c.openWorld}`,
+        `  confirmation-gated   ${c.confirmationGated}`,
+        "",
+        "Capability groups (all OFF by default — enable with BREAKPOINT_PRIVILEGED_GROUPS):",
+    ];
+    for (const g of report.capabilityGroups) {
+        lines.push(`  ${g.id} (${g.tools.length} tools) — ${g.describe}`);
+    }
+    lines.push("", "Tools:");
+    for (const t of report.tools) {
+        const marks = [
+            t.annotations.readOnlyHint ? "read-only" : null,
+            t.annotations.destructiveHint ? "destructive" : null,
+            t.confirmationGated ? "gated" : null,
+            t.privileged ? `privileged:${t.capabilityGroups.join("+")}` : null,
+        ].filter(Boolean);
+        lines.push(`  ${t.name.padEnd(34)} ${marks.join(" · ")}`);
+    }
+    lines.push("", "Re-run with --json for the machine-readable form.", "");
+    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 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`);
+        return 2;
+    }
+    const report = buildToolsReport(raw);
+    process.stdout.write(flags.json ? `${JSON.stringify(report, null, 2)}\n` : renderText(report));
+    return 0;
+}
+//# sourceMappingURL=tools.js.map

package/dist/index.js

@@ -12,6 +12,7 @@ import { DapClient } from "./dap.js";
 import { buildToolsets } from "./toolsets.js";
 import { registerRecipes } from "./recipes.js";
 import { applyOutputSchemas } from "./schemas.js";
+import { applyAnnotations } from "./annotations.js";
 import { applyCapabilities, droppedTools, registerCapabilitiesResource, selectPrivilegedGroups, } from "./capabilities.js";
 import { taskStore, TASK_CAPABILITIES } from "./tasks.js";
 import { RESOURCE_CAPABILITIES, registerResourceSubscriptions } from "./subscriptions.js";
@@ -35,24 +36,31 @@ 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.21.1" }, { capabilities: { ...TASK_CAPABILITIES, ...RESOURCE_CAPABILITIES }, taskStore });
+    const server = new McpServer({ name: "breakpoint-mcp", version: "1.23.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);
+    // MCP tool annotations — publish readOnly/destructive/idempotent/openWorld
+    // hints on every tool so clients and policy catalogs read our risk posture
+    // instead of guessing it from tool names. Hints only; the enforcement stays
+    // in applyCapabilities (below) + confirm.ts. Wraps registerTool after the
+    // schema wrapper, before any register*Tools call.
+    applyAnnotations(server);
     // 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
+    // 289 − 15 = 274 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
+    // every group → the full 289-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;
+    let peers;
     const toolsets = buildToolsets({
         server,
         bridge,
@@ -65,6 +73,9 @@ async function main() {
         onProcesses: (h) => {
             processes = h;
         },
+        onPeers: (h) => {
+            peers = 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)
@@ -85,7 +96,7 @@ async function main() {
         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
+    // via prompts/list). Adds NO tools — the 289-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
@@ -117,6 +128,8 @@ async function main() {
         dap.close();
         csDap.close();
         processes?.killAll();
+        // F6: headless peers are children of this server — never outlive it.
+        peers?.stopAll();
         process.exit(0);
     };
     process.on("SIGINT", shutdown);
@@ -130,6 +143,7 @@ function printUsage() {
         "  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:",
@@ -147,6 +161,10 @@ function printUsage() {
         "  --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"));
@@ -160,6 +178,10 @@ void (async () => {
         const { runDoctor } = await import("./cli/doctor.js");
         process.exit(await runDoctor(process.argv.slice(3)));
     }
+    if (sub === "tools") {
+        const { runTools } = await import("./cli/tools.js");
+        process.exit(await runTools(process.argv.slice(3)));
+    }
     if (sub === "init") {
         const { runInit } = await import("./cli/init.js");
         process.exit(await runInit(process.argv.slice(3)));