@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/tools/node.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+export const nodeTools = [
+    {
+        name: "node_get_property",
+        method: "node.get_property",
+        description: "Read a property from the node at path. Returns { value } (engine types are dict-wrapped).",
+        inputSchema: {
+            node_path: z.string(),
+            property: z
+                .string()
+                .describe("Property name. Use ':' to chain into sub-resources (e.g. 'material:shader_parameter/value')."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        successHint: "For available properties use node_get_property_list. For tree-wide overview use scene_get_tree with include_properties.",
+    },
+    // Deliberately detailed description: spelling out the editor-time vs runtime
+    // distinction and the anchors-preset pitfall materially reduces mis-calls.
+    {
+        name: "node_set_property",
+        method: "node.set_property",
+        description: "Set a property on a node in the EDITOR scene tree (saved to .tscn files). " +
+            "Does NOT affect the running game — for runtime property changes during playtesting, use runtime_set_property.\n\n" +
+            'Node paths are relative to the edited scene root: "." is root, "./Player" is a direct child, "./Player/Sprite2D" for deeper nodes.\n\n' +
+            "Engine types: {type:'Vector2',x,y}. Inline sub-resources: {type:'NewResource',class:'CircleShape2D',properties:{radius:50}}. " +
+            "External resources (textures, audio, tilesets, materials): {type:'Resource', path:'res://path/to/file.tres'}. " +
+            "Packed arrays: {type:'PackedVector2Array', values:[{type:'Vector2',x:0,y:0}, ...]}. " +
+            "Collision layers: {type:'LayerMask', layers:[1,4,6]} (by number) or {type:'LayerMask', layers:['player','walls']} (by name from layer_names_set); optional category defaults to '2d_physics'. " +
+            "All supported type tags: Vector2, Vector3, Vector4, Vector2i, Vector3i, Color, Rect2, Rect2i, " +
+            "Transform2D, Transform3D, NodePath, Resource, NewResource, PackedVector2Array, PackedVector3Array, PackedColorArray, LayerMask. " +
+            "Unknown type tags are rejected with an error listing supported types.\n\n" +
+            "Anchor presets: setting anchors_preset alone may not auto-apply underlying values. " +
+            "For reliable layout, set anchor_left/top/right/bottom and offset_left/top/right/bottom explicitly.\n\n" +
+            "Batch mode: pass batch:[{node_path, property, value, make_unique?}, ...] to set multiple properties at once.",
+        inputSchema: {
+            node_path: z.string().optional().describe("Single mode: path to target node"),
+            property: z
+                .string()
+                .optional()
+                .describe("Single mode: property name. Compound '/' paths supported. Use ':' for sub-resource chaining (e.g. 'material:shader_parameter/value')."),
+            value: z.unknown().optional(),
+            make_unique: z
+                .boolean()
+                .optional()
+                .describe("When true and the compound path targets an external (.tres) sub-resource, " +
+                "auto-duplicate it as an inline copy before setting. " +
+                "Equivalent to the Inspector's 'Make Unique'. Only needed for compound paths on external resources."),
+            batch: z
+                .array(z.object({
+                node_path: z.string(),
+                property: z.string(),
+                value: z.unknown(),
+                make_unique: z
+                    .boolean()
+                    .optional()
+                    .describe("Per-entry make_unique — auto-duplicate external sub-resource as inline copy."),
+            }))
+                .optional()
+                .describe("Batch mode: array of {node_path, property, value, make_unique?}. " +
+                "Omit for single-property operations. " +
+                "When present, top-level node_path/property/value are ignored."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Save changes with editor_save_scene. For batch edits, use the batch array in a single call.",
+    },
+    {
+        name: "node_get_property_list",
+        method: "node.get_property_list",
+        description: "Introspect node properties. mask: common (default), all, groups, script. 'script' returns all script variables with public/private label; use visibility param to filter.",
+        inputSchema: {
+            node_path: z.string(),
+            mask: z
+                .enum(["common", "all", "groups", "script"])
+                .optional()
+                .describe("Property filter. 'common' (default) returns 8-12 most-edited. 'all' returns full list. 'groups' returns names+usage only. 'script' returns script variables with visibility label. Prefer 'common' or node_get_property; 'all' returns the full list and is large."),
+            visibility: z
+                .enum(["public", "private", "all"])
+                .optional()
+                .default("all")
+                .describe("Filter for mask='script'. 'public' = no _ prefix, 'private' = _ prefix, 'all' = both."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        successHint: "For specific values use node_get_property. Filter with mask parameter (common/all/groups/script).",
+    },
+    {
+        name: "node_set_script",
+        method: "node.set_script",
+        description: "Attach a script (.gd/.cs) to a node. Returns @export properties exposed by the script. Empty script_path string detaches.",
+        inputSchema: {
+            node_path: z.string(),
+            script_path: z.string(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Write script content with script_write. View @export properties in the returned property list.",
+        // script_path is a res:// file path; node_path is a scene-tree path (not guarded).
+        // Empty script_path (detach) is skipped by checkPathGuard, deferring to the toolkit.
+        pathParams: [{ param: "script_path", guard: "project" }],
+    },
+    {
+        name: "control_set_layout",
+        method: "control.set_layout",
+        description: "Set anchor preset + optional margins on a Control node in one call. Uses set_anchors_and_offsets_preset(). Returns final_rect.",
+        inputSchema: {
+            node_path: z.string(),
+            preset: z
+                .string()
+                .describe("Layout preset: PRESET_TOP_LEFT, PRESET_TOP_RIGHT, PRESET_BOTTOM_LEFT, PRESET_BOTTOM_RIGHT, " +
+                "PRESET_CENTER_LEFT, PRESET_CENTER_TOP, PRESET_CENTER_RIGHT, PRESET_CENTER_BOTTOM, " +
+                "PRESET_CENTER, PRESET_LEFT_WIDE, PRESET_TOP_WIDE, PRESET_RIGHT_WIDE, PRESET_BOTTOM_WIDE, " +
+                "PRESET_VCENTER_WIDE, PRESET_HCENTER_WIDE, PRESET_FULL_RECT"),
+            resize_mode: z
+                .enum(["keep_size", "set_to_anchors"])
+                .optional()
+                .describe("keep_size (default) preserves size; set_to_anchors resizes to anchor region."),
+            margins: z
+                .object({
+                left: z.coerce.number().optional(),
+                right: z.coerce.number().optional(),
+                top: z.coerce.number().optional(),
+                bottom: z.coerce.number().optional(),
+            })
+                .optional()
+                .describe("Additive offsets applied after the preset (in pixels)."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Margins are applied AFTER the preset. For Container children, layout is overridden by the parent.",
+    },
+    // node_call_method can call arbitrary methods — risk communicated via
+    // destructiveHint annotation. Agent-side filtering recommended for
+    // untrusted contexts (see security-recommendations.md).
+    {
+        name: "node_call_method",
+        method: "node.call_method",
+        description: "Call method with args on an edited-scene node (editor-only; for runtime nodes use execute_code).",
+        inputSchema: {
+            node_path: z.string(),
+            method_name: z.string(),
+            args: z.array(z.unknown()).optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, nodeTools, allowedTools);
+}

package/dist/tools/nodeManagement.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { coercedBoolean, jsonCoerce } from "../shared/schemaCoercion.js";
+export const nodeManagementTools = [
+    // Deliberately detailed description: this action-consolidated tool needs
+    // per-action param documentation.
+    {
+        name: "node_manage",
+        method: "node.manage",
+        description: "Structural node operations on the edited scene tree.\n\n" +
+            "action: rename — requires new_name.\n" +
+            "action: reparent — requires new_parent_path, optional keep_global_transform (default true).\n" +
+            "action: reorder — requires new_index (0-based sibling index).\n" +
+            "action: duplicate — optional new_name, parent_path, properties (overrides like {position:{x,y}}).",
+        inputSchema: {
+            action: z.enum(["rename", "reparent", "reorder", "duplicate"]),
+            node_path: z.string(),
+            new_name: z.string().optional().describe("Required for rename; optional for duplicate."),
+            new_parent_path: z.string().optional().describe("Required for reparent."),
+            keep_global_transform: coercedBoolean()
+                .optional()
+                .describe("For reparent: preserve world transform. Default true."),
+            new_index: z.coerce.number().int().optional().describe("For reorder: 0-based sibling index."),
+            parent_path: z.string().optional().describe("For duplicate: target parent. Defaults to same parent."),
+            properties: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("For duplicate: property overrides on the copy (e.g. {position:{x:100,y:200}})."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+        successHint: "After rename/reparent/reorder, scripts using $Path, get_node() paths, or %UniqueNames referencing the affected node may break. Check scripts on the moved node and its immediate neighbors.",
+    },
+    {
+        name: "node_groups",
+        method: "node.groups",
+        description: "Manage node group membership. Groups are the idiomatic Godot way to tag and query game objects " +
+            "(e.g. 'coins', 'enemies').\n\n" +
+            "Single mode: node_path + group (node_path required for add/remove/list). " +
+            "Batch mode: entries array of {node_path, group} carries per-item paths, and the top-level " +
+            "node_path/group are ignored.\n\n" +
+            "action: add — requires group. action: remove — requires group. action: list — returns all groups (single only).",
+        inputSchema: {
+            action: z.enum(["add", "remove", "list"]),
+            node_path: z
+                .string()
+                .optional()
+                .describe("Single mode: target node path. Required for single add/remove/list; omit in batch mode (provide entries instead)."),
+            group: z.string().optional().describe("Group name. Required for single add/remove."),
+            persistent: coercedBoolean().optional().describe("For add: save to .tscn. Default true."),
+            entries: z
+                .preprocess(jsonCoerce, z.array(z.record(z.string(), z.unknown())))
+                .optional()
+                .describe("Batch mode (add/remove only): array of {node_path, group}. " +
+                "When present, processes all entries as a batch." +
+                "node_path and group params are ignored in batch mode."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+    },
+    {
+        name: "autoload_manage",
+        method: "autoload.manage",
+        description: "Manage project autoload singletons (GameManager, AudioManager, etc.). " +
+            "Writes to project.godot; takes effect on next game launch.\n\n" +
+            "action: register — requires name + script_path. action: unregister — requires name. action: list — returns all.",
+        inputSchema: {
+            action: z.enum(["register", "unregister", "list"]),
+            name: z.string().optional().describe("Autoload name (e.g. 'GameManager'). Required for register/unregister."),
+            script_path: z
+                .string()
+                .optional()
+                .describe("Script path (e.g. 'res://scripts/game_manager.gd'). Required for register."),
+            enabled: coercedBoolean().optional().describe("For register: auto-initialize on startup. Default true."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, nodeManagementTools, allowedTools);
+}

package/dist/tools/particles.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+const vec3 = z.object({ x: z.number(), y: z.number(), z: z.number() });
+const vec2 = z.object({ x: z.number(), y: z.number() });
+const color = z.object({
+    r: z.number(),
+    g: z.number(),
+    b: z.number(),
+    a: z.number().optional(),
+});
+const rangeOrFixed = z.union([z.number(), z.object({ min: z.number(), max: z.number() })]);
+const colorRampPoint = z.object({
+    offset: z.number(),
+    color,
+});
+const curvePoint = z.object({
+    x: z.number(),
+    y: z.number(),
+});
+export const particleTools = [
+    {
+        name: "particles_create",
+        method: "particles.create",
+        description: "Create GPU particle system (2D/3D) with presets: fire, smoke, sparks, rain, snow, explosion, magic, dust. Inline color_ramp/scale_curve/alpha_curve. One call replaces 7+ manual steps.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path"),
+            name: z.string().optional().describe("Node name"),
+            type: z.enum(["2d", "3d"]).describe("GPUParticles2D or GPUParticles3D"),
+            preset: z
+                .enum(["fire", "smoke", "sparks", "rain", "snow", "explosion", "magic", "dust"])
+                .optional()
+                .describe("Effect preset (overridable with explicit params)"),
+            amount: z.number().int().optional().describe("Particle count"),
+            lifetime: z.number().optional().describe("Particle lifetime (seconds)"),
+            one_shot: z.boolean().optional().describe("Single burst then stop"),
+            explosiveness: z.number().optional().describe("0-1, burst factor"),
+            speed_scale: z.number().optional().describe("Simulation speed"),
+            local_coords: z.boolean().optional().describe("Emit in local space"),
+            texture_path: z.string().optional().describe("Particle texture (2D, res:// path)"),
+            mesh: z.enum(["quad", "box", "sphere"]).optional().describe("3D draw pass mesh"),
+            emission_shape: z
+                .enum(["point", "sphere", "sphere_surface", "box", "ring"])
+                .optional()
+                .describe("Emission shape"),
+            emission_sphere_radius: z.number().optional(),
+            emission_box_extents: vec3.optional().describe("Box emission half-extents"),
+            direction: vec3.optional().describe("Emission direction"),
+            spread: z.number().optional().describe("Spread angle (degrees, 0-180)"),
+            initial_velocity: rangeOrFixed.optional().describe("Initial speed (fixed or {min,max})"),
+            gravity: vec3.optional().describe("Gravity vector"),
+            damping: rangeOrFixed.optional(),
+            orbit_velocity: rangeOrFixed.optional(),
+            scale_range: rangeOrFixed.optional().describe("Particle scale"),
+            angle: rangeOrFixed.optional(),
+            angular_velocity: rangeOrFixed.optional(),
+            color: color.optional().describe("Flat particle color"),
+            hue_variation: rangeOrFixed.optional(),
+            color_ramp: z
+                .union([
+                z.string().describe("Path to Gradient .tres"),
+                z.object({
+                    points: z.array(colorRampPoint),
+                    interpolation: z.enum(["linear", "cubic", "constant"]).optional(),
+                }),
+            ])
+                .optional()
+                .describe("Color gradient over lifetime"),
+            alpha_curve: z
+                .union([z.string(), z.object({ points: z.array(curvePoint) })])
+                .optional()
+                .describe("Alpha curve over lifetime"),
+            scale_curve: z
+                .union([z.string(), z.object({ points: z.array(curvePoint) })])
+                .optional()
+                .describe("Scale curve over lifetime"),
+            turbulence_enabled: z.boolean().optional(),
+            turbulence_noise_strength: z.number().optional(),
+            particle_flag_align_y: z.boolean().optional(),
+            position: z.union([vec2, vec3]).optional().describe("Node position"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Customize with procedural_edit_curve (velocity/emission), procedural_edit_gradient (color over lifetime).",
+    },
+];

package/dist/tools/path.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+export const pathTools = [
+    {
+        name: "path2d_edit_curve",
+        method: "path2d.edit_curve",
+        description: "Edit a Path2D node's Curve2D — set, add, or remove points with bezier control handles. For patrol routes, moving platforms, projectile curves, and camera rails.",
+        inputSchema: {
+            node_path: z.string().describe("Path2D node path in the scene tree"),
+            action: z
+                .enum(["set", "add", "remove", "clear"])
+                .describe("set=replace all, add=append/insert, remove=delete at index, clear=remove all"),
+            points: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                position: z.object({ x: z.number(), y: z.number() }),
+                in_handle: z.object({ x: z.number(), y: z.number() }).optional(),
+                out_handle: z.object({ x: z.number(), y: z.number() }).optional(),
+            })))
+                .optional()
+                .describe("Curve points with optional bezier handles"),
+            index: z.number().int().optional().describe("Insert position (add) or point index to remove"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, pathTools, allowedTools);
+}

package/dist/tools/playtest.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { callAndWrap } from "../registration/toolDispatch.js";
+import { coercedBoolean } from "../shared/schemaCoercion.js";
+import { isGroupLoaded } from "../groups/groupState.js";
+export const playtestTools = [
+    {
+        name: "game_start",
+        method: "game.start",
+        description: "Start playtest. Blocks until runtime is ready by default; wait_for_runtime:false launches without blocking. scene_path:'main'|'current'(default)|res://path. if_running:'return' for idempotent mode.",
+        inputSchema: {
+            scene_path: z.string().optional(),
+            wait_for_runtime: coercedBoolean()
+                .default(true)
+                .describe("Defaults true — blocks until runtime connects (or times out) so runtime tools are immediately available. Pass wait_for_runtime:false to launch without blocking."),
+            runtime_poll: coercedBoolean()
+                .optional()
+                .describe("With if_running:'return', re-check whether the already-running game's runtime has since connected. Default false."),
+            if_running: z.enum(["return", "fail"]).optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+    {
+        name: "game_stop",
+        method: "game.stop",
+        description: "Stop the currently-playing scene (idempotent — returns was_running:false if nothing was running). No params.",
+        inputSchema: {},
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    const handlers = new Map();
+    handlers.set("game_start", async (input) => {
+        const result = await callAndWrap(bridge, "game.start", input);
+        // Inject hint if game started successfully and runtime group not loaded.
+        if (!isGroupLoaded("runtime") && result.content?.[0]?.type === "text") {
+            try {
+                const payload = JSON.parse(result.content[0].text);
+                if (payload.success && !result.isError) {
+                    payload.group_hint =
+                        "Game started. To interact with the running game, call " +
+                            "discover_tools({request: 'runtime'}) to access runtime tools.";
+                    result.content[0].text = JSON.stringify(payload);
+                }
+            }
+            catch {
+                /* parse failure — pass through unchanged */
+            }
+        }
+        // Nudge: the caller opted out of blocking (wait_for_runtime:false) but the
+        // runtime isn't ready yet — point them at the blocking and polling paths.
+        if (!input.wait_for_runtime && result.content?.[0]?.type === "text" && !result.isError) {
+            try {
+                const payload = JSON.parse(result.content[0].text);
+                if (payload.success && payload.runtime_ready === false) {
+                    payload.hint =
+                        "runtime_ready is false — runtime tools are not yet available. " +
+                            "Call game_start with wait_for_runtime:true to block until ready, " +
+                            "or poll with game_start(if_running:'return', runtime_poll:true).";
+                    result.content[0].text = JSON.stringify(payload);
+                }
+            }
+            catch {
+                /* parse failure — pass through unchanged */
+            }
+        }
+        // Server-side wait-for-runtime: absorb the async gap so agents get
+        // single-call game launch instead of a two-step dance.
+        if (input.wait_for_runtime && result.content?.[0]?.type === "text" && !result.isError) {
+            try {
+                const payload = JSON.parse(result.content[0].text);
+                if (payload.runtime_discovery === "bridge" && bridge.waitForRuntimeConnection) {
+                    const runtime = await bridge.waitForRuntimeConnection(10_000);
+                    if (runtime) {
+                        // Success — merge runtime info, drop the bridge-discovery marker.
+                        payload.runtime_ready = true;
+                        payload.runtime_port = runtime.port;
+                        delete payload.runtime_discovery;
+                        delete payload.hint;
+                    }
+                    else {
+                        // Timeout — add fallback hint (toolkit hint is suppressed when
+                        // wait_for_runtime=true, so the agent needs guidance here).
+                        payload.hint =
+                            "Game launched but runtime did not connect within 10s. " +
+                                "Follow up with game_start(if_running:'return', runtime_poll:true) " +
+                                "to retry, or check editor_get_console for startup errors.";
+                    }
+                    result.content[0].text = JSON.stringify(payload);
+                }
+            }
+            catch {
+                /* parse failure — pass through unchanged */
+            }
+        }
+        return result;
+    });
+    registerTools(server, bridge, playtestTools, allowedTools, { handlers });
+}

package/dist/tools/procedural.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+const colorSchema = z.object({
+    r: z.number().optional(),
+    g: z.number().optional(),
+    b: z.number().optional(),
+    a: z.number().optional(),
+});
+export const proceduralTools = [
+    {
+        name: "procedural_edit_gradient",
+        method: "procedural.edit_gradient",
+        description: "Create/edit a Gradient resource (.tres). Set color stops with offsets, add/remove points. For particles, sky, and visual effects.",
+        inputSchema: {
+            file_path: z.string().describe("Path for the .tres file (e.g. 'res://materials/sky_gradient.tres')"),
+            action: z
+                .enum(["set", "add_point", "remove_point"])
+                .optional()
+                .describe("set=replace all, add_point=add one, remove_point=delete by index (default: set)"),
+            points: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                offset: z.number().describe("Position 0.0-1.0"),
+                color: z.preprocess(jsonCoerce, colorSchema).describe("Color {r,g,b,a?}"),
+            })))
+                .optional()
+                .describe("Gradient color stops"),
+            index: z.number().int().optional().describe("Point index (for remove_point)"),
+            interpolation_mode: z.enum(["linear", "cubic", "constant"]).optional().describe("Interpolation between stops"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "procedural_edit_curve",
+        method: "procedural.edit_curve",
+        description: "Create/edit a Curve resource (.tres). Set control points with tangents for easing, falloff, and value mapping.",
+        inputSchema: {
+            file_path: z.string().describe("Path for the .tres file"),
+            action: z
+                .enum(["set", "add_point", "remove_point", "clear"])
+                .optional()
+                .describe("set=replace all, add_point=add one, remove_point=delete, clear=remove all (default: set)"),
+            points: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                position: z.object({ x: z.number(), y: z.number() }).describe("x=input 0-1, y=output value"),
+                left_tangent: z.number().optional(),
+                right_tangent: z.number().optional(),
+                left_mode: z.enum(["free", "linear"]).optional(),
+                right_mode: z.enum(["free", "linear"]).optional(),
+            })))
+                .optional()
+                .describe("Curve control points"),
+            index: z.number().int().optional().describe("Point index (for remove_point)"),
+            min_value: z.number().optional().describe("Curve minimum Y value"),
+            max_value: z.number().optional().describe("Curve maximum Y value"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "procedural_edit_noise",
+        method: "procedural.edit_noise",
+        description: "Create/edit a FastNoiseLite resource (.tres). Configure noise type, fractal, cellular, and domain warp for procedural generation.",
+        inputSchema: {
+            file_path: z.string().describe("Path for the .tres file"),
+            noise_type: z
+                .enum(["simplex", "simplex_smooth", "cellular", "perlin", "value", "value_cubic"])
+                .optional()
+                .describe("Noise algorithm"),
+            seed: z.number().int().optional().describe("Random seed"),
+            frequency: z.number().optional().describe("Base frequency (default 0.01)"),
+            octaves: z.number().int().optional().describe("Fractal octaves 1-10"),
+            lacunarity: z.number().optional().describe("Octave frequency multiplier"),
+            gain: z.number().optional().describe("Octave amplitude multiplier"),
+            fractal_type: z.enum(["none", "fbm", "ridged", "ping_pong"]).optional().describe("Fractal type"),
+            cellular_distance_function: z.enum(["euclidean", "euclidean_squared", "manhattan", "hybrid"]).optional(),
+            cellular_return_type: z
+                .enum([
+                "cell_value",
+                "distance",
+                "distance2",
+                "distance2_add",
+                "distance2_sub",
+                "distance2_mul",
+                "distance2_div",
+            ])
+                .optional(),
+            domain_warp_enabled: z.boolean().optional(),
+            domain_warp_amplitude: z.number().optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        pathParams: [PROJECT_FILE_PATH],
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, proceduralTools, allowedTools);
+}

package/dist/tools/resource.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+export const resourceTools = [
+    {
+        name: "resource_load",
+        method: "resource.load",
+        description: "Load a res:// resource and return { class, path, properties, metadata }. Heavy fields (image, mesh_arrays) pruned; Texture2D gets size in metadata.",
+        inputSchema: { file_path: z.string() },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "resource_write",
+        method: "resource.write",
+        description: "Write/create a .tres/.res resource. If file exists, updates properties. If not, 'type' (class name) is required to create it. " +
+            "For TileSets, use tileset_create instead (handles atlas + physics setup).",
+        inputSchema: {
+            file_path: z.string(),
+            properties: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Property values. Sub-resources in dicts: use {type:'NewResource', class:'ClassName', properties:{...}}."),
+            type: z.string().optional().describe("Resource class name. Required when creating a new resource."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        successHint: "Verify with resource_load. Assign to node via node_set_property with Resource type tag.",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "resource_delete",
+        method: "resource.delete",
+        description: "Delete the .tres/.res and its .uid companion at file_path. No active-use guard (Godot refs survive file deletion; detect orphans via editor_get_console).",
+        inputSchema: { file_path: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+        successHint: "For scenes use scene_delete. For scripts use script_delete. Non-resource files: file_delete. " +
+            "On Windows/OneDrive a transient lock can leave the .tres on disk despite deindexed:true — retry the delete to clear it.",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+];
+// resource_load `properties` is already <untrusted>-wrapped at origin by the
+// toolkit (resource_commands.gd wraps the whole JSON.stringify(properties) in
+// one envelope). Do NOT re-wrap here: the wrapper scrubs inner envelope tags,
+// so double-wrapping corrupts the envelope.
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, resourceTools, allowedTools);
+}