breakpoint-mcp 1.0.0 → 1.2.0

package/dist/tools/editor/animation.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+import { gate } from "../../confirm.js";
+/** AnimationPlayer / Animation authoring + AnimationTree state machines. */
+export function registerAnimationTools(server, call) {
+    server.registerTool("anim_player_create", {
+        title: "Create AnimationPlayer",
+        description: "Add an AnimationPlayer node under a parent (undoable). Seeds an empty default animation library so anim_create works immediately.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path relative to the scene root; \".\" for the root"),
+            name: z.string().optional().describe("Node name (default \"AnimationPlayer\")"),
+        },
+    }, async ({ parent_path, name }) => call("anim.player_create", { parent_path, name }));
+    server.registerTool("anim_create", {
+        title: "Create animation",
+        description: "Create an empty Animation in an AnimationPlayer's library (undoable). Creates the library if it does not exist yet.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path relative to the scene root"),
+            name: z.string().describe("Animation name (unique within its library)"),
+            library: z.string().optional().describe("Animation library name (default \"\", the player's default library)"),
+        },
+    }, async ({ player_path, name, library }) => call("anim.create", { player_path, name, library: library ?? "" }));
+    server.registerTool("anim_delete", {
+        title: "Delete animation",
+        description: "Delete an Animation from an AnimationPlayer's library (undoable). DESTRUCTIVE — gated by confirmation.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path relative to the scene root"),
+            name: z.string().describe("Animation name"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ player_path, name, library, confirm }) => {
+        const blocked = await gate(server, confirm, `Delete animation "${name}"`);
+        if (blocked)
+            return blocked;
+        return call("anim.delete", { player_path, name, library: library ?? "" });
+    });
+    server.registerTool("anim_add_track", {
+        title: "Add animation track",
+        description: "Add a track to an Animation and set its target path (undoable). Returns the new track index.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            path: z.string().describe("Track target: a node path, or \"Node:property\" for value tracks (e.g. \"Sprite2D:position\")"),
+            type: z
+                .string()
+                .optional()
+                .describe("Track type: value (default), position_3d, rotation_3d, scale_3d, blend_shape, method, bezier, audio, animation"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, path, type, library }) => call("anim.add_track", { player_path, name, path, type: type ?? "value", library: library ?? "" }));
+    server.registerTool("anim_insert_key", {
+        title: "Insert animation key",
+        description: "Insert a keyframe on a track at a given time (undoable). A key already at that exact time is overwritten.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            track: z.number().int().describe("Track index"),
+            time: z.number().describe("Key time in seconds"),
+            value: z.any().describe("Key value (JSON scalar, array, object, or a __type__-tagged Variant matching the track type)"),
+            transition: z.number().optional().describe("Transition curve exponent (default 1.0)"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, track, time, value, transition, library }) => call("anim.insert_key", { player_path, name, track, time, value, transition: transition ?? 1.0, library: library ?? "" }));
+    server.registerTool("anim_remove_key", {
+        title: "Remove animation key",
+        description: "Remove a keyframe by index from a track (undoable).",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            track: z.number().int().describe("Track index"),
+            key: z.number().int().describe("Key index within the track"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, track, key, library }) => call("anim.remove_key", { player_path, name, track, key, library: library ?? "" }));
+    server.registerTool("anim_set_length", {
+        title: "Set animation length",
+        description: "Set an Animation's length in seconds (undoable).",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            length: z.number().describe("New length in seconds (> 0)"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, length, library }) => call("anim.set_length", { player_path, name, length, library: library ?? "" }));
+    server.registerTool("anim_set_loop", {
+        title: "Set animation loop mode",
+        description: "Set an Animation's loop mode (undoable).",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            mode: z.string().describe("Loop mode: none, linear, or pingpong"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, mode, library }) => call("anim.set_loop", { player_path, name, mode, library: library ?? "" }));
+    server.registerTool("anim_get_track_keys", {
+        title: "Get animation track keys",
+        description: "List all keyframes on a track (index, time, value, transition). Read-only.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+            name: z.string().describe("Animation name"),
+            track: z.number().int().describe("Track index"),
+            library: z.string().optional().describe("Animation library name (default \"\")"),
+        },
+    }, async ({ player_path, name, track, library }) => call("anim.get_track_keys", { player_path, name, track, library: library ?? "" }));
+    server.registerTool("anim_list", {
+        title: "List animations",
+        description: "List all animations in an AnimationPlayer across its libraries, with length, loop mode, and track count. Read-only.",
+        inputSchema: {
+            player_path: z.string().describe("AnimationPlayer node path"),
+        },
+    }, async ({ player_path }) => call("anim.list", { player_path }));
+    server.registerTool("anim_tree_create", {
+        title: "Create AnimationTree",
+        description: "Add an AnimationTree node under a parent (undoable) with a fresh tree_root graph. root_type \"blend_tree\" (AnimationNodeBlendTree) or \"state_machine\" (AnimationNodeStateMachine). Created inactive by default; set anim_player_path to the AnimationPlayer it should drive.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path relative to the scene root; \".\" for the root"),
+            name: z.string().optional().describe("Node name (default \"AnimationTree\")"),
+            root_type: z.enum(["blend_tree", "state_machine"]).optional().describe("tree_root graph type (default blend_tree)"),
+            anim_player_path: z.string().optional().describe("NodePath to the AnimationPlayer this tree drives, relative to the AnimationTree node"),
+            active: z.boolean().optional().describe("Whether the tree processes immediately (default false)"),
+        },
+    }, async ({ parent_path, name, root_type, anim_player_path, active }) => call("anim.tree_create", { parent_path, name, root_type: root_type ?? "blend_tree", anim_player_path: anim_player_path ?? "", active: active ?? false }));
+    server.registerTool("anim_tree_add_node", {
+        title: "Add AnimationTree graph node",
+        description: "Add a node to an AnimationTree's tree_root graph (AnimationNodeBlendTree or AnimationNodeStateMachine), undoable. node_type is any AnimationNode subclass (e.g. AnimationNodeAnimation, AnimationNodeBlend2, AnimationNodeStateMachine). For AnimationNodeAnimation, pass animation to bind a clip.",
+        inputSchema: {
+            tree_path: z.string().describe("AnimationTree node path relative to the scene root"),
+            node_name: z.string().describe("Unique node name within the graph"),
+            node_type: z.string().describe("AnimationNode subclass to instantiate (e.g. AnimationNodeAnimation)"),
+            animation: z.string().optional().describe("For AnimationNodeAnimation: the animation name to play"),
+            position: z.array(z.number()).optional().describe("Graph editor position [x, y] (default [0, 0])"),
+        },
+    }, async ({ tree_path, node_name, node_type, animation, position }) => call("anim.tree_add_node", { tree_path, node_name, node_type, animation, position }));
+    server.registerTool("anim_statemachine_add_state", {
+        title: "Add state machine state",
+        description: "Add a state to an AnimationNodeStateMachine (undoable). Targets the AnimationTree's tree_root when it is a state machine, or a nested state-machine node via state_machine. Defaults the state to an AnimationNodeAnimation; pass animation to bind a clip.",
+        inputSchema: {
+            tree_path: z.string().describe("AnimationTree node path relative to the scene root"),
+            state_name: z.string().describe("Unique state name within the state machine"),
+            animation: z.string().optional().describe("For an AnimationNodeAnimation state: the animation name to play"),
+            node_type: z.string().optional().describe("AnimationNode subclass for the state (default AnimationNodeAnimation)"),
+            state_machine: z.string().optional().describe("Name of a nested AnimationNodeStateMachine node within tree_root; omit to target tree_root itself"),
+            position: z.array(z.number()).optional().describe("Graph editor position [x, y] (default [0, 0])"),
+        },
+    }, async ({ tree_path, state_name, animation, node_type, state_machine, position }) => call("anim.statemachine_add_state", { tree_path, state_name, animation, node_type: node_type ?? "AnimationNodeAnimation", state_machine: state_machine ?? "", position }));
+    server.registerTool("anim_statemachine_add_transition", {
+        title: "Add state machine transition",
+        description: "Add a transition between two states in an AnimationNodeStateMachine (undoable). from_state/to_state must exist (or be the built-in \"Start\"/\"End\"). switch_mode: immediate|sync|at_end; advance_mode: disabled|enabled|auto.",
+        inputSchema: {
+            tree_path: z.string().describe("AnimationTree node path relative to the scene root"),
+            from_state: z.string().describe("Source state name (or \"Start\")"),
+            to_state: z.string().describe("Destination state name (or \"End\")"),
+            state_machine: z.string().optional().describe("Name of a nested AnimationNodeStateMachine node within tree_root; omit to target tree_root itself"),
+            xfade_time: z.number().optional().describe("Cross-fade time in seconds (default 0)"),
+            switch_mode: z.enum(["immediate", "sync", "at_end"]).optional().describe("Switch mode (default immediate)"),
+            advance_mode: z.enum(["disabled", "enabled", "auto"]).optional().describe("Advance mode (default enabled)"),
+            advance_condition: z.string().optional().describe("Advance condition parameter name (used with advance_mode auto)"),
+            priority: z.number().int().optional().describe("Transition priority (lower wins when multiple are valid)"),
+        },
+    }, async ({ tree_path, from_state, to_state, state_machine, xfade_time, switch_mode, advance_mode, advance_condition, priority }) => call("anim.statemachine_add_transition", { tree_path, from_state, to_state, state_machine: state_machine ?? "", xfade_time: xfade_time ?? 0.0, switch_mode: switch_mode ?? "immediate", advance_mode: advance_mode ?? "enabled", advance_condition: advance_condition ?? "", priority }));
+}
+//# sourceMappingURL=animation.js.map

package/dist/tools/editor/audio.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { gate } from "../../confirm.js";
+/** AudioStreamPlayer nodes + audio bus layout / effects. */
+export function registerAudioTools(server, call) {
+    server.registerTool("audio_player_create", {
+        title: "Create audio player",
+        description: "Add an AudioStreamPlayer / AudioStreamPlayer2D / AudioStreamPlayer3D node under a parent in the edited scene (undoable). `dim` selects \"none\" (default, non-positional AudioStreamPlayer), \"2d\", or \"3d\". Optional initial stream_path (res:// AudioStream), autoplay, volume_db, bus. In-scene and undoable — not gated.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path relative to the scene root; \".\" for the root"),
+            dim: z.enum(["none", "2d", "3d"]).optional().describe("Player kind: \"none\" (default, AudioStreamPlayer), \"2d\" (AudioStreamPlayer2D), or \"3d\" (AudioStreamPlayer3D)"),
+            name: z.string().optional().describe("Node name (default matches the player class)"),
+            stream_path: z.string().optional().describe("res:// path to an AudioStream to assign to the new player"),
+            autoplay: z.boolean().optional().describe("Whether the player starts automatically on scene load"),
+            volume_db: z.number().optional().describe("Player volume in dB"),
+            bus: z.string().optional().describe("Target audio bus name (default \"Master\")"),
+        },
+    }, async ({ parent_path, dim, name, stream_path, autoplay, volume_db, bus }) => {
+        const params = { parent_path };
+        if (dim !== undefined)
+            params.dim = dim;
+        if (name !== undefined)
+            params.name = name;
+        if (stream_path !== undefined)
+            params.stream_path = stream_path;
+        if (autoplay !== undefined)
+            params.autoplay = autoplay;
+        if (volume_db !== undefined)
+            params.volume_db = volume_db;
+        if (bus !== undefined)
+            params.bus = bus;
+        return call("audio.player_create", params);
+    });
+    server.registerTool("audio_set_stream", {
+        title: "Set audio stream",
+        description: "Load an AudioStream from a res:// path and assign it as stream on an AudioStreamPlayer/2D/3D in the edited scene (undoable). In-scene and undoable — not gated.",
+        inputSchema: {
+            path: z.string().describe("AudioStreamPlayer/2D/3D node path relative to the scene root"),
+            stream_path: z.string().describe("res:// path to an AudioStream resource"),
+        },
+    }, async ({ path, stream_path }) => call("audio.set_stream", { path, stream_path }));
+    server.registerTool("audio_bus_add", {
+        title: "Add audio bus",
+        description: "Add a bus to the project's global AudioServer layout, optionally naming it, positioning it (at_position), and setting its send bus. DESTRUCTIVE (project-wide audio state) — gated by confirmation.",
+        inputSchema: {
+            name: z.string().optional().describe("Name for the new bus"),
+            at_position: z.number().optional().describe("Insert index (default -1 = append at end)"),
+            send: z.string().optional().describe("Name of the bus this bus sends its output to"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ name, at_position, send, confirm }) => {
+        const blocked = await gate(server, confirm, `Add audio bus${name ? ` "${name}"` : ""}`);
+        if (blocked)
+            return blocked;
+        const params = {};
+        if (name !== undefined)
+            params.name = name;
+        if (at_position !== undefined)
+            params.at_position = at_position;
+        if (send !== undefined)
+            params.send = send;
+        return call("audio.bus_add", params);
+    });
+    server.registerTool("audio_bus_add_effect", {
+        title: "Add audio bus effect",
+        description: "Instantiate an AudioEffect subclass (by class name, e.g. \"AudioEffectReverb\") and add it to a named bus on the global AudioServer, optionally at a position in the bus's effect chain. DESTRUCTIVE (project-wide audio state) — gated by confirmation.",
+        inputSchema: {
+            bus: z.string().describe("Target bus name"),
+            effect: z.string().describe("AudioEffect subclass name, e.g. \"AudioEffectReverb\", \"AudioEffectDelay\""),
+            at_position: z.number().optional().describe("Insert index within the bus's effect chain (default -1 = append)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ bus, effect, at_position, confirm }) => {
+        const blocked = await gate(server, confirm, `Add ${effect} to audio bus "${bus}"`);
+        if (blocked)
+            return blocked;
+        const params = { bus, effect };
+        if (at_position !== undefined)
+            params.at_position = at_position;
+        return call("audio.bus_add_effect", params);
+    });
+    server.registerTool("audio_bus_set_volume", {
+        title: "Set audio bus volume",
+        description: "Set the volume (in dB) of a named bus on the global AudioServer. DESTRUCTIVE (project-wide audio state) — gated by confirmation.",
+        inputSchema: {
+            bus: z.string().describe("Bus name"),
+            volume_db: z.number().describe("Volume in dB"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ bus, volume_db, confirm }) => {
+        const blocked = await gate(server, confirm, `Set audio bus "${bus}" volume to ${volume_db} dB`);
+        if (blocked)
+            return blocked;
+        return call("audio.bus_set_volume", { bus, volume_db });
+    });
+    server.registerTool("audio_set_bus_layout", {
+        title: "Save audio bus layout",
+        description: "Save the current AudioServer bus layout (buses, effects, volumes) to a .tres resource on disk (default res://default_bus_layout.tres) via generate_bus_layout + ResourceSaver.save. DESTRUCTIVE (writes a file) — gated by confirmation.",
+        inputSchema: {
+            to_path: z.string().optional().describe("Destination res:// path (default res://default_bus_layout.tres)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ to_path, confirm }) => {
+        const blocked = await gate(server, confirm, `Save audio bus layout to ${to_path ?? "res://default_bus_layout.tres"}`);
+        if (blocked)
+            return blocked;
+        return call("audio.set_bus_layout", to_path !== undefined ? { to_path } : {});
+    });
+}
+//# sourceMappingURL=audio.js.map

package/dist/tools/editor/common.js

@@ -0,0 +1,31 @@
+import { ok } from "../lsp-common.js";
+/**
+ * MCP error envelope for a failed editor-bridge call (never throws to the
+ * caller). Distinct from lsp-common's `fail` (which labels errors "LSP error");
+ * this one labels them "Bridge error".
+ */
+export function fail(err) {
+    const be = err;
+    const code = be?.code ?? "error";
+    const message = be?.message ?? String(err);
+    return {
+        isError: true,
+        content: [{ type: "text", text: `Bridge error [${code}]: ${message}` }],
+    };
+}
+/**
+ * Build the shared bridge-call helper used by every editor tool group: forward
+ * a method to the in-editor addon over TCP and wrap the result in the standard
+ * MCP success envelope, or a friendly Bridge-error envelope when unreachable.
+ */
+export function makeCall(bridge) {
+    return async (method, params = {}) => {
+        try {
+            return ok(await bridge.request(method, params));
+        }
+        catch (err) {
+            return fail(err);
+        }
+    };
+}
+//# sourceMappingURL=common.js.map

package/dist/tools/editor/core.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { gate } from "../../confirm.js";
+/** Editor session + core project settings (editor_* / project get/set). */
+export function registerCoreTools(server, call) {
+    server.registerTool("editor_ping", { title: "Ping editor bridge", description: "Check that the editor is running with the Breakpoint MCP plugin enabled.", inputSchema: {} }, async () => call("ping"));
+    server.registerTool("editor_get_state", { title: "Editor state", description: "Return the currently edited scene, its root type/path, and the current node selection.", inputSchema: {} }, async () => call("editor.get_state"));
+    server.registerTool("editor_undo", {
+        title: "Undo last edit",
+        description: "Undo the most recent edit in the editor's undo history (like Ctrl-Z). Defaults to the edited scene's history; pass scope='global' for the editor-wide history. Returns whether an action was undone, its name, and the remaining undo/redo depth.",
+        inputSchema: {
+            scope: z
+                .enum(["scene", "global"])
+                .optional()
+                .describe("Which history to step: 'scene' (default, the edited scene) or 'global' (editor-wide)"),
+        },
+    }, async ({ scope }) => call("edit.undo", scope ? { scope } : {}));
+    server.registerTool("editor_redo", {
+        title: "Redo last undone edit",
+        description: "Re-apply the most recently undone edit in the editor's undo history (like Ctrl-Shift-Z). Defaults to the edited scene's history; pass scope='global' for the editor-wide history.",
+        inputSchema: {
+            scope: z
+                .enum(["scene", "global"])
+                .optional()
+                .describe("Which history to step: 'scene' (default, the edited scene) or 'global' (editor-wide)"),
+        },
+    }, async ({ scope }) => call("edit.redo", scope ? { scope } : {}));
+    server.registerTool("project_get_info", { title: "Project info", description: "Return project name, main scene, project root path, Godot version, and feature tags.", inputSchema: {} }, async () => call("project.get_info"));
+    server.registerTool("project_get_setting", {
+        title: "Get project setting",
+        description: "Read a single ProjectSettings value by dotted key (e.g. application/config/name).",
+        inputSchema: { name: z.string().describe("ProjectSettings key") },
+    }, async ({ name }) => call("project.get_setting", { name }));
+    server.registerTool("project_set_setting", {
+        title: "Set project setting",
+        description: "Write a ProjectSettings value. Set save=true to persist to project.godot. DESTRUCTIVE — gated by confirmation.",
+        inputSchema: {
+            name: z.string().describe("ProjectSettings key"),
+            value: z.any().describe("New value; rich types use the {\"__type__\":...} tagging convention"),
+            save: z.boolean().optional().describe("Persist to disk (default false)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ name, value, save, confirm }) => {
+        const blocked = await gate(server, confirm, `Set project setting "${name}"${save ? " and save project.godot" : ""}`);
+        if (blocked)
+            return blocked;
+        return call("project.set_setting", { name, value, save: save ?? false });
+    });
+}
+//# sourceMappingURL=core.js.map

package/dist/tools/editor/filesystem.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { gate } from "../../confirm.js";
+/** Project FileSystem dock ops: list / scan / move / mkdir. */
+export function registerFilesystemTools(server, call) {
+    server.registerTool("filesystem_list", {
+        title: "List project directory",
+        description: "List the subdirectories and files of a directory in the project filesystem (hidden entries like .godot are skipped). Read-only.",
+        inputSchema: { path: z.string().optional().describe("Directory res:// path (default res://)") },
+    }, async ({ path }) => call("filesystem.list", path !== undefined ? { path } : {}));
+    server.registerTool("filesystem_scan", {
+        title: "Rescan filesystem",
+        description: "Trigger an editor rescan of the project filesystem so newly added or externally-changed files are picked up. Read-only side effect.",
+        inputSchema: {},
+    }, async () => call("filesystem.scan"));
+    server.registerTool("filesystem_move", {
+        title: "Move / rename file",
+        description: "Move or rename a file or directory within the project (carrying its .import sidecar), then rescan. DESTRUCTIVE (moves on disk; does NOT remap references in other resources) — gated by confirmation.",
+        inputSchema: {
+            from_path: z.string().describe("Source res:// path (file or directory)"),
+            to_path: z.string().describe("Destination res:// path"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ from_path, to_path, confirm }) => {
+        const blocked = await gate(server, confirm, `Move ${from_path} to ${to_path}`);
+        if (blocked)
+            return blocked;
+        return call("filesystem.move", { from_path, to_path });
+    });
+    server.registerTool("filesystem_create_dir", {
+        title: "Create directory",
+        description: "Create a directory (recursively) in the project filesystem, then rescan. No-op if it already exists.",
+        inputSchema: { path: z.string().describe("Directory res:// path to create") },
+    }, async ({ path }) => call("filesystem.create_dir", { path }));
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/tools/editor/introspection.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { fail } from "./common.js";
+/** Editor selection, ClassDB / docs lookups, and viewport screenshot. */
+export function registerIntrospectionTools(server, call, bridge) {
+    server.registerTool("selection_get", { title: "Get selection", description: "Return the paths of the nodes currently selected in the editor.", inputSchema: {} }, async () => call("selection.get"));
+    server.registerTool("selection_set", {
+        title: "Set selection",
+        description: "Replace the editor's node selection with the given node paths.",
+        inputSchema: { paths: z.array(z.string()).describe("Node paths relative to the scene root") },
+    }, async ({ paths }) => call("selection.set", { paths }));
+    server.registerTool("classdb_get_class", {
+        title: "Introspect class",
+        description: "Return the parent class, methods, properties, and signals of an engine class via ClassDB.",
+        inputSchema: {
+            class_name: z.string().describe("Engine class name, e.g. AudioStreamPlayer3D"),
+            include_inherited: z.boolean().optional().describe("Include inherited members (default false)"),
+        },
+    }, async ({ class_name, include_inherited }) => call("classdb.get_class", { class_name, include_inherited: include_inherited ?? false }));
+    server.registerTool("class_reference", {
+        title: "Class reference",
+        description: "Full engine-class reference via ClassDB: method SIGNATURES (return type + typed args), signal " +
+            "signatures, and typed properties — the detailed view classdb_get_class summarises as bare names. " +
+            "Read-only. Includes the canonical online docs URL. Pass member to filter to a single method/property/signal.",
+        inputSchema: {
+            class_name: z.string().describe("Engine class name, e.g. AudioStreamPlayer3D"),
+            include_inherited: z.boolean().optional().describe("Include inherited members (default false)"),
+            member: z.string().optional().describe("Only return members whose name contains this substring"),
+        },
+    }, async ({ class_name, include_inherited, member }) => call("classdb.reference", {
+        class_name,
+        include_inherited: include_inherited ?? false,
+        member: member ?? "",
+    }));
+    server.registerTool("docs_search", {
+        title: "Search the class reference",
+        description: "Search the Godot class reference (ClassDB) by keyword — matching class names and, unless a scope narrows " +
+            "it, their methods/properties/signals — and return each hit with its canonical docs URL. Read-only. " +
+            "Use kind to restrict to one member type, class_name to scope to a single class, and limit to bound results.",
+        inputSchema: {
+            query: z.string().describe("Case-insensitive substring to match against class / member names"),
+            kind: z.enum(["any", "class", "method", "property", "signal"]).optional().describe("Restrict to one result kind (default any)"),
+            class_name: z.string().optional().describe("Scope the member search to a single class (still returns class-name matches project-wide)"),
+            limit: z.number().int().positive().optional().describe("Max results before truncation (default 40)"),
+            deep: z.boolean().optional().describe("Also scan members, not just class names (default true)"),
+        },
+    }, async ({ query, kind, class_name, limit, deep }) => call("docs.search", {
+        query,
+        kind: kind ?? "any",
+        class_name: class_name ?? "",
+        limit: limit ?? 40,
+        deep: deep ?? true,
+    }));
+    server.registerTool("screenshot_editor", {
+        title: "Screenshot editor viewport",
+        description: "Capture the 2D or 3D editor viewport as a PNG and return it as image content so the assistant can see the scene. " +
+            "Requires the matching editor tab (2D/3D) to be active and rendered.",
+        inputSchema: { viewport: z.enum(["2d", "3d"]).optional().describe("Which viewport (default 3d)") },
+    }, async ({ viewport }) => {
+        try {
+            const r = (await bridge.request("screenshot.editor_viewport", { viewport: viewport ?? "3d" }));
+            return {
+                content: [
+                    { type: "image", data: r.base64, mimeType: r.mime },
+                    { type: "text", text: `Captured ${r.viewport} viewport (${r.width}x${r.height}).` },
+                ],
+            };
+        }
+        catch (err) {
+            return fail(err);
+        }
+    });
+}
+//# sourceMappingURL=introspection.js.map

package/dist/tools/editor/node.js

@@ -0,0 +1,171 @@
+import { z } from "zod";
+import { gate } from "../../confirm.js";
+/** Scene-tree node authoring: add / delete / reparent / property / group ops. */
+export function registerNodeTools(server, call) {
+    server.registerTool("node_add", {
+        title: "Add node",
+        description: "Instance a node of the given class under a parent path (undoable). Returns the new node's path.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path relative to the scene root; \".\" for the root"),
+            type: z.string().describe("Node class to instance, e.g. Sprite2D, AudioStreamPlayer3D"),
+            name: z.string().optional().describe("Node name (defaults to the class name)"),
+        },
+    }, async ({ parent_path, type, name }) => call("node.add", { parent_path, type, name }));
+    server.registerTool("node_delete", {
+        title: "Delete node",
+        description: "Delete a node (undoable). DESTRUCTIVE — gated by confirmation. Refuses to delete the scene root.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ path, confirm }) => {
+        const blocked = await gate(server, confirm, `Delete node "${path}"`);
+        if (blocked)
+            return blocked;
+        return call("node.delete", { path });
+    });
+    server.registerTool("node_rename", {
+        title: "Rename node",
+        description: "Rename a node (undoable).",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            new_name: z.string().describe("New node name"),
+        },
+    }, async ({ path, new_name }) => call("node.rename", { path, new_name }));
+    server.registerTool("node_reparent", {
+        title: "Reparent node",
+        description: "Move a node under a new parent (undoable).",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            new_parent_path: z.string().describe("New parent path; \".\" for the root"),
+            keep_global_transform: z.boolean().optional().describe("Preserve global transform (default true)"),
+        },
+    }, async ({ path, new_parent_path, keep_global_transform }) => call("node.reparent", { path, new_parent_path, keep_global_transform: keep_global_transform ?? true }));
+    server.registerTool("node_set_property", {
+        title: "Set node property",
+        description: "Set a property on a node (undoable). Rich types use the {\"__type__\":\"Vector3\",\"x\":..} convention. " +
+            "Example value for position: {\"__type__\":\"Vector3\",\"x\":1,\"y\":0,\"z\":2}.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            property: z.string().describe("Property name, e.g. position, modulate, text"),
+            value: z.any().describe("New value (JSON scalar, array, object, or a __type__-tagged Variant)"),
+        },
+    }, async ({ path, property, value }) => call("node.set_property", { path, property, value }));
+    server.registerTool("node_get_property", {
+        title: "Get node property",
+        description: "Read a single property from a node. Rich types come back __type__-tagged.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            property: z.string().describe("Property name"),
+        },
+    }, async ({ path, property }) => call("node.get_property", { path, property }));
+    server.registerTool("node_duplicate", {
+        title: "Duplicate node",
+        description: "Duplicate a node and its children under the same parent (undoable). Returns the new node's path.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            name: z.string().optional().describe("Name for the duplicate (defaults to Godot's auto-numbered name)"),
+        },
+    }, async ({ path, name }) => call("node.duplicate", name !== undefined ? { path, name } : { path }));
+    server.registerTool("node_get_children", {
+        title: "Get node children",
+        description: "List the direct children of a node (name, type, path). Read-only.",
+        inputSchema: { path: z.string().describe("Node path relative to the scene root; \".\" for the root") },
+    }, async ({ path }) => call("node.get_children", { path }));
+    server.registerTool("node_find", {
+        title: "Find nodes",
+        description: "Search a node's descendants by class and/or name substring (case-insensitive). Read-only.",
+        inputSchema: {
+            root_path: z.string().optional().describe("Where to search from; \".\" or omitted for the scene root"),
+            type: z.string().optional().describe("Only match nodes of this class (is_class), e.g. Sprite2D"),
+            name_contains: z.string().optional().describe("Only match nodes whose name contains this substring"),
+            limit: z.number().int().positive().optional().describe("Max matches to return (default 200)"),
+        },
+    }, async ({ root_path, type, name_contains, limit }) => call("node.find", {
+        root_path: root_path ?? ".",
+        type: type ?? "",
+        name_contains: name_contains ?? "",
+        limit: limit ?? 200,
+    }));
+    server.registerTool("node_list_groups", {
+        title: "List node groups",
+        description: "List the groups a node belongs to. Read-only.",
+        inputSchema: { path: z.string().describe("Node path relative to the scene root") },
+    }, async ({ path }) => call("node.list_groups", { path }));
+    server.registerTool("node_add_to_group", {
+        title: "Add node to group",
+        description: "Add a node to a group (persistent, undoable). No-op if already a member.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            group: z.string().describe("Group name"),
+        },
+    }, async ({ path, group }) => call("node.add_to_group", { path, group }));
+    server.registerTool("node_remove_from_group", {
+        title: "Remove node from group",
+        description: "Remove a node from a group (undoable). No-op if not a member.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            group: z.string().describe("Group name"),
+        },
+    }, async ({ path, group }) => call("node.remove_from_group", { path, group }));
+    server.registerTool("node_instantiate_scene", {
+        title: "Instance scene under node",
+        description: "Instance an external PackedScene (res:// path) as an editable child of a parent node (undoable). Returns the new node's path.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path relative to the scene root; \".\" for the root"),
+            scene_path: z.string().describe("Scene to instance, e.g. res://actors/enemy.tscn"),
+            name: z.string().optional().describe("Node name (defaults to the instanced scene's root name)"),
+        },
+    }, async ({ parent_path, scene_path, name }) => call("node.instantiate_scene", name !== undefined ? { parent_path, scene_path, name } : { parent_path, scene_path }));
+    server.registerTool("node_move_child", {
+        title: "Move child",
+        description: "Reorder a node among its siblings by index (undoable). Negative indices count from the end (-1 = last).",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            to_index: z.number().int().describe("New sibling index (0-based; negative counts from the end)"),
+        },
+    }, async ({ path, to_index }) => call("node.move_child", { path, to_index }));
+    server.registerTool("node_change_type", {
+        title: "Change node type",
+        description: "Replace a node with a new node of a different class, carrying over compatible properties, children, and groups (undoable). Refuses the scene root.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            type: z.string().describe("New node class, e.g. Sprite2D, StaticBody3D"),
+        },
+    }, async ({ path, type }) => call("node.change_type", { path, type }));
+    server.registerTool("node_set_owner", {
+        title: "Set node owner",
+        description: "Set a node's owner (undoable). Owner must be an ancestor; \".\" or omitted sets the scene root. Ownership determines which scene a node is saved into.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            owner_path: z.string().optional().describe("Ancestor to own the node; \".\" or omitted for the scene root"),
+        },
+    }, async ({ path, owner_path }) => call("node.set_owner", owner_path !== undefined ? { path, owner_path } : { path }));
+    server.registerTool("node_call_method", {
+        title: "Call node method (edit-time)",
+        description: "Invoke a method on a node in the EDITED scene. DESTRUCTIVE (arbitrary invocation, not undoable) — gated by confirmation. " +
+            "Args use the tagged-Variant convention; the return value comes back tagged.",
+        inputSchema: {
+            path: z.string().describe("Node path relative to the scene root"),
+            method: z.string().describe("Method name"),
+            args: z.array(z.any()).optional().describe("Positional arguments (JSON scalars or __type__-tagged Variants)"),
+            confirm: z.boolean().optional().describe("Auto-approve this destructive action (skip the confirmation prompt)"),
+        },
+    }, async ({ path, method, args, confirm }) => {
+        const blocked = await gate(server, confirm, `Call ${path}.${method}() in the edited scene`);
+        if (blocked)
+            return blocked;
+        return call("node.call_method", { path, method, args: args ?? [] });
+    });
+    server.registerTool("node_get_path", {
+        title: "Get node path",
+        description: "Return a node's scene-relative path, class, sibling index, parent path, and child count. Read-only.",
+        inputSchema: { path: z.string().describe("Node path relative to the scene root; \".\" for the root") },
+    }, async ({ path }) => call("node.get_path", { path }));
+    server.registerTool("node_list_properties", {
+        title: "List node properties",
+        description: "List a node's inspector-visible properties (name, Variant type, class_name, usage flags). Read-only. Use node_get_property to read a value.",
+        inputSchema: { path: z.string().describe("Node path relative to the scene root") },
+    }, async ({ path }) => call("node.list_properties", { path }));
+}
+//# sourceMappingURL=node.js.map