@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/tools/signals.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { coercedBoolean, jsonCoerce } from "../shared/schemaCoercion.js";
+// signal_emit selects its channel: default routes to the editor-side
+// edited scene; `channel: "runtime"` routes to the running game for
+// emitting on live nodes. list / manage are editor-only.
+export const signalTools = [
+    {
+        name: "signal_list",
+        method: "signal.list",
+        description: "List signals on a node. include_connections=true adds targets ({target_path, method_name, flags}). flags & 2 = CONNECT_PERSIST (saved in .tscn).",
+        inputSchema: {
+            node_path: z.string(),
+            include_connections: coercedBoolean().optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "signal_manage",
+        method: "signal.manage",
+        description: "Connect or disconnect a signal (editor-time, CONNECT_PERSIST — saved in .tscn, survives save/load). Idempotent connect (status 'returned' on collision).",
+        inputSchema: {
+            action: z.enum(["connect", "disconnect"]),
+            node_path: z.string(),
+            signal_name: z.string(),
+            target_path: z.string(),
+            method_name: z.string(),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+    },
+    {
+        name: "signal_emit",
+        method: "signal.emit",
+        description: "Emit signal_name on node with optional args. channel='editor' (default, edited scene) or channel='runtime' (the running game).",
+        inputSchema: {
+            node_path: z.string(),
+            signal_name: z.string(),
+            args: z.preprocess(jsonCoerce, z.array(z.unknown())).optional(),
+            // "game" is accepted as a hidden alias for "runtime" (mapped before the
+            // enum, not advertised) — z.toJSONSchema surfaces only the inner enum.
+            channel: z.preprocess((v) => (v === "game" ? "runtime" : v), z.enum(["editor", "runtime"])).optional(),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+];
+// NOTE: All signal tools are in the "signals" group (GROUP_TOOL_NAMES), so the
+// group's activation path (groupActivation → createGroupToolHandler) builds the
+// channel-routed signal_emit handler. This register() is unused on that path but
+// remains as a fallback for direct-call scenarios.
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, signalTools, allowedTools);
+}

package/dist/tools/sound.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { assetWriteFields } from "./assetWrite.js";
+export const soundTools = [
+    {
+        name: "sound_generate",
+        method: "sound.generate",
+        description: "Generate a placeholder sound effect (mono WAV): waveform sine/square/triangle/sawtooth/noise, frequency, duration <=5s, volume, optional pitch sweep + fade/decay envelope. SFX only, no music.",
+        inputSchema: {
+            file_path: z.string().describe("res:// destination ending in .wav"),
+            waveform: z.enum(["sine", "square", "triangle", "sawtooth", "noise"]).optional(),
+            frequency: z.coerce.number().optional().describe("Hz (default 440; ignored for noise)"),
+            end_frequency: z.coerce
+                .number()
+                .optional()
+                .describe("If set, pitch sweeps frequency -> end_frequency over the duration"),
+            duration: z.coerce.number().optional().describe("Seconds, max 5 (default 0.3)"),
+            volume: z.coerce.number().optional().describe("Peak amplitude 0-1 (default 0.8)"),
+            fade_in: z.coerce.number().optional().describe("Fade-in seconds (default ~0.003 de-click)"),
+            fade_out: z.coerce.number().optional().describe("Fade-out seconds (default ~0.003 de-click)"),
+            decay: z.coerce.number().optional().describe("Exponential decay time-constant in seconds (>0 = pluck/bell)"),
+            ...assetWriteFields,
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
+        successHint: "Assign the stream: node_set_property on AudioStreamPlayer / AudioStreamPlayer2D / AudioStreamPlayer3D .stream.",
+        pathParams: [{ param: "file_path", guard: "project" }],
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, soundTools, allowedTools);
+}

package/dist/tools/spatial.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+import { paginationDoc } from "../shared/pagination.js";
+export const spatialTools = [
+    {
+        name: "scene_spatial_map",
+        method: "scene.spatial_map",
+        description: "Spatial layout of the current scene: per-node world position, bounds (2D Rect2 / 3D AABB), size, plus computed overlaps/gaps/containment. Call before placing or moving nodes to find clear space. " +
+            paginationDoc("nodes", {
+                resumable: false,
+                cursorlessNav: "narrow with subtree/class/region/radius or raise max_nodes",
+            }),
+        inputSchema: {
+            detail: z
+                .enum(["brief", "normal", "full"])
+                .optional()
+                .describe("brief = position/size only; normal = + bounds + overlaps; full = + containment + nearest-neighbour gaps"),
+            class: z.string().optional().describe("Only include nodes of this class (ancestry-aware)"),
+            subtree: z
+                .string()
+                .optional()
+                .describe("Map only this node and its descendants (node path relative to the scene root)"),
+            region: z
+                .preprocess(jsonCoerce, z.array(z.number()))
+                .optional()
+                .describe("Only nodes intersecting this box: [x,y,w,h] (2D) or [x,y,z,sx,sy,sz] (3D)"),
+            radius: z.coerce.number().optional().describe("Only nodes within this distance of center"),
+            center: z
+                .preprocess(jsonCoerce, z.array(z.number()))
+                .optional()
+                .describe("Center for radius filter: [x,y] (2D) or [x,y,z] (3D)"),
+            max_nodes: z.coerce.number().optional().describe("Response cap (default 200, max 1000)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        successHint: "Reason about a clear position from the overlaps/gaps, then place or move nodes with node_set_property (position / global_position).",
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, spatialTools, allowedTools);
+}

package/dist/tools/spriteframes.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+const frameSchema = z.object({
+    texture_path: z.string().describe("res:// path to frame texture"),
+    atlas: z
+        .object({
+        x: z.number().int(),
+        y: z.number().int(),
+        width: z.number().int(),
+        height: z.number().int(),
+    })
+        .optional()
+        .describe("Atlas region within the texture"),
+    duration: z.number().optional().describe("Per-frame duration multiplier (default 1.0)"),
+});
+const animationSchema = z.object({
+    name: z.string().describe("Animation name (e.g. 'idle', 'run')"),
+    fps: z.number().optional().describe("Frames per second (default 5.0)"),
+    loop: z.boolean().optional().describe("Loop animation (default true)"),
+    frames: z.array(frameSchema).describe("Frame textures"),
+});
+export const spriteframesTools = [
+    {
+        name: "spriteframes_create",
+        method: "spriteframes.create",
+        description: "Create a SpriteFrames resource (.tres) with named animations and frame textures. For AnimatedSprite2D character/effect animation.",
+        inputSchema: {
+            file_path: z.string().describe("Output .tres file path (res://)"),
+            animations: z.array(animationSchema).min(1).describe("Animations with their frames"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        successHint: "Add/modify frames with spriteframes_edit. For spritesheets use spriteframes_from_spritesheet.",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "spriteframes_edit",
+        method: "spriteframes.edit",
+        description: "Edit an existing SpriteFrames resource: add/remove animations, add/remove/reorder frames, adjust fps/loop. 'list' returns all animations.",
+        inputSchema: {
+            file_path: z.string().describe("Path to existing SpriteFrames .tres"),
+            action: z
+                .enum([
+                "add_animation",
+                "remove_animation",
+                "add_frame",
+                "remove_frame",
+                "set_fps",
+                "set_loop",
+                "reorder_frames",
+                "list",
+            ])
+                .describe("Edit operation"),
+            animation_name: z.string().optional().describe("Target animation name"),
+            fps: z.number().optional().describe("New FPS value (for set_fps)"),
+            loop: z.boolean().optional().describe("New loop value (for set_loop)"),
+            frames: z.array(frameSchema).optional().describe("Frames to add"),
+            frame_index: z.number().int().optional().describe("Frame index (for remove/reorder)"),
+            new_index: z.number().int().optional().describe("New position (for reorder)"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "spriteframes_from_spritesheet",
+        method: "spriteframes.from_spritesheet",
+        description: "Auto-slice a spritesheet into SpriteFrames animations by grid. Each animation maps to a row/column range in the sheet.",
+        inputSchema: {
+            file_path: z.string().describe("Output .tres file path"),
+            texture_path: z.string().describe("Spritesheet texture path (res://)"),
+            frame_size: z
+                .object({
+                x: z.number().int().describe("Frame width in pixels"),
+                y: z.number().int().describe("Frame height in pixels"),
+            })
+                .describe("Size of each frame in the grid"),
+            animations: z
+                .array(z.object({
+                name: z.string().describe("Animation name"),
+                row: z.number().int().optional().describe("Row in spritesheet (0-indexed, default 0)"),
+                start_col: z.number().int().optional().describe("Starting column (default 0)"),
+                frame_count: z.number().int().describe("Number of frames"),
+                fps: z.number().optional().describe("Frames per second"),
+                loop: z.boolean().optional().describe("Loop this animation"),
+            }))
+                .min(1)
+                .describe("Animation definitions mapping to spritesheet regions"),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        // file_path is guarded; texture_path is NOT (toolkit calls load(), which is
+        // res://-scoped — guarding it server-side could false-reject).
+        pathParams: [PROJECT_FILE_PATH],
+    },
+];

package/dist/tools/texture.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+import { assetWriteFields } from "./assetWrite.js";
+/** A colour: a hex/named string ("#ff0000", "red") or an [r,g,b(,a)] array
+ *  (0-1 or 0-255). Alpha 0 / omitted = that layer is absent. */
+const colorField = z.preprocess(jsonCoerce, z.union([z.string(), z.array(z.number())]));
+export const textureTools = [
+    {
+        name: "texture_generate",
+        method: "texture.generate",
+        description: "Generate a placeholder PNG (imports as Texture2D): a shape (solid/circle/triangle/diamond/arrow/checkerboard/grid) with fill/outline/background colours + an optional text label. Dimensions <=1024px.",
+        inputSchema: {
+            file_path: z.string().describe("res:// destination ending in .png"),
+            shape: z.enum(["solid", "circle", "triangle", "diamond", "arrow", "checkerboard", "grid"]).optional(),
+            width: z.coerce.number().optional().describe("Pixels, 1-1024 (default 64)"),
+            height: z.coerce.number().optional().describe("Pixels, 1-1024 (default 64)"),
+            fill_color: colorField.optional().describe("Interior colour; transparent = hollow shape"),
+            outline_color: colorField.optional().describe("Border colour; transparent/omitted = no border"),
+            outline_width: z.coerce.number().optional().describe("Border thickness in pixels (default 1)"),
+            background_color: colorField.optional().describe("Canvas colour behind the shape (default transparent)"),
+            label: z.string().optional().describe("Optional text overlaid centred on any shape"),
+            label_color: colorField.optional(),
+            direction: z.enum(["up", "down", "left", "right"]).optional().describe("Arrow direction"),
+            cell_size: z.coerce.number().optional().describe("Cell size for checkerboard/grid"),
+            ...assetWriteFields,
+        },
+        annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
+        successHint: "Assign the texture: node_set_property on Sprite2D.texture / TextureRect.texture / Button.icon, or feed spriteframes_create.",
+        pathParams: [{ param: "file_path", guard: "project" }],
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, textureTools, allowedTools);
+}

package/dist/tools/theme.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+export const themeTools = [
+    {
+        name: "theme_edit",
+        method: "theme.edit",
+        description: "Create or modify a Godot Theme resource (.tres). Batch-edit colors, constants, fonts, font sizes, icons, and styleboxes for any control type.",
+        inputSchema: {
+            file_path: z.string().describe("Theme resource path, e.g. 'res://themes/ui_theme.tres'. Created if missing."),
+            edits: z
+                .preprocess(jsonCoerce, z.array(z.object({
+                type_name: z.string().describe("Control type name, e.g. 'Button', 'Label', 'Panel'"),
+                property_type: z
+                    .enum(["color", "constant", "font", "font_size", "icon", "stylebox"])
+                    .describe("Theme property category"),
+                property: z.string().describe("Property name, e.g. 'font_color', 'font_size', 'panel'"),
+                value: z
+                    .unknown()
+                    .describe("Value — shape depends on property_type: " +
+                    "color: {r,g,b,a?}; constant/font_size: number; " +
+                    "font/icon: res:// path string; " +
+                    "stylebox: {type:'StyleBoxFlat'|'StyleBoxTexture'|'StyleBoxLine', ...props}"),
+            })))
+                .describe("Array of theme property edits to apply"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Apply theme to Control via node_set_property (theme property with Resource type tag).",
+        pathParams: [PROJECT_FILE_PATH],
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, themeTools, allowedTools);
+}

package/dist/tools/threeD.js

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+const vec3Schema = z.object({
+    x: z.number().optional().describe("X component"),
+    y: z.number().optional().describe("Y component"),
+    z: z.number().optional().describe("Z component"),
+});
+const colorSchema = z.object({
+    r: z.number().optional().describe("Red 0-1"),
+    g: z.number().optional().describe("Green 0-1"),
+    b: z.number().optional().describe("Blue 0-1"),
+    a: z.number().optional().describe("Alpha 0-1"),
+});
+export const threeDTools = [
+    {
+        name: "3d_create_primitive",
+        method: "3d.create_primitive",
+        description: "Create a 3D mesh primitive (box, sphere, cylinder, capsule, plane, prism) as a MeshInstance3D node. Optionally set size, material, and position.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path (e.g. '.' for scene root)"),
+            primitive: z.enum(["box", "sphere", "cylinder", "capsule", "plane", "prism"]).describe("Mesh primitive type"),
+            name: z.string().optional().describe("Node name (default: 'MeshInstance3D')"),
+            size: z
+                .preprocess(jsonCoerce, vec3Schema)
+                .optional()
+                .describe("Size as {x,y,z}. Interpretation depends on primitive: box→size, sphere→x=diameter/y=height, etc."),
+            material: z
+                .preprocess(jsonCoerce, z.object({
+                type: z.literal("StandardMaterial3D").optional().describe("Material type (only StandardMaterial3D)"),
+                albedo_color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Base color {r,g,b,a?}"),
+                metallic: z.number().optional().describe("Metallic factor 0-1"),
+                roughness: z.number().optional().describe("Roughness factor 0-1"),
+            }))
+                .optional()
+                .describe("Material to apply: {type:'StandardMaterial3D', albedo_color?, metallic?, roughness?}"),
+            position: z.preprocess(jsonCoerce, vec3Schema).optional().describe("World position {x,y,z}"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Set material via node_set_property. Add lighting with 3d_create_light, camera with 3d_create_camera.",
+    },
+    {
+        name: "3d_setup_environment",
+        method: "3d.setup_environment",
+        description: "Create a WorldEnvironment node with sky, ambient light, tonemapping, and fog. Sets up a complete 3D rendering environment.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path (e.g. '.' for scene root)"),
+            name: z.string().optional().describe("Node name (default: 'WorldEnvironment')"),
+            sky: z
+                .preprocess(jsonCoerce, z.object({
+                type: z.string().optional().describe("Sky material type (default: ProceduralSkyMaterial)"),
+                sky_top_color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Sky top color {r,g,b}"),
+                sky_horizon_color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Sky horizon color {r,g,b}"),
+                ground_bottom_color: z
+                    .preprocess(jsonCoerce, colorSchema)
+                    .optional()
+                    .describe("Ground bottom color {r,g,b}"),
+            }))
+                .optional()
+                .describe("Sky configuration"),
+            ambient_light: z
+                .preprocess(jsonCoerce, z.object({
+                color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Ambient light color {r,g,b}"),
+                energy: z.number().optional().describe("Ambient light energy"),
+            }))
+                .optional()
+                .describe("Ambient light: {color?, energy?}"),
+            tonemap: z.enum(["linear", "reinhardt", "filmic", "aces"]).optional().describe("Tonemapping mode"),
+            fog: z
+                .preprocess(jsonCoerce, z.object({
+                enabled: z.boolean().optional().describe("Enable fog (default true)"),
+                color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Fog color {r,g,b}"),
+                density: z.number().optional().describe("Fog density"),
+            }))
+                .optional()
+                .describe("Fog settings: {enabled?, color?, density?}"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Add lights with 3d_create_light, camera with 3d_create_camera.",
+    },
+    {
+        name: "3d_create_light",
+        method: "3d.create_light",
+        description: "Create a 3D light node (DirectionalLight3D, OmniLight3D, or SpotLight3D). Optionally set color, energy, shadow, position, and rotation.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path (e.g. '.' for scene root)"),
+            light_type: z.enum(["directional", "omni", "spot"]).describe("Light type"),
+            name: z.string().optional().describe("Node name (default: type-specific, e.g. 'DirectionalLight3D')"),
+            color: z.preprocess(jsonCoerce, colorSchema).optional().describe("Light color {r,g,b}"),
+            energy: z.number().optional().describe("Light energy/intensity"),
+            shadow: z.boolean().optional().describe("Enable shadow casting"),
+            position: z.preprocess(jsonCoerce, vec3Schema).optional().describe("World position {x,y,z}"),
+            rotation: z.preprocess(jsonCoerce, vec3Schema).optional().describe("Rotation in Euler degrees {x,y,z}"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+    {
+        name: "3d_create_camera",
+        method: "3d.create_camera",
+        description: "Create a Camera3D node. Set projection mode (perspective/orthogonal), FOV, position, rotation, and whether it's the current camera.",
+        inputSchema: {
+            parent_path: z.string().describe("Parent node path (e.g. '.' for scene root)"),
+            name: z.string().optional().describe("Node name (default: 'Camera3D')"),
+            projection: z.enum(["perspective", "orthogonal"]).optional().describe("Projection mode (default: perspective)"),
+            fov: z.number().optional().describe("Field of view in degrees (perspective mode)"),
+            size: z.number().optional().describe("Viewport size (orthogonal mode)"),
+            position: z.preprocess(jsonCoerce, vec3Schema).optional().describe("World position {x,y,z}"),
+            rotation: z.preprocess(jsonCoerce, vec3Schema).optional().describe("Rotation in Euler degrees {x,y,z}"),
+            current: z.boolean().optional().describe("Set as the current active camera"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, threeDTools, allowedTools);
+}

package/dist/tools/tilemap.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { jsonCoerce } from "../shared/schemaCoercion.js";
+import { paginationDoc } from "../shared/pagination.js";
+export const tilemapTools = [
+    {
+        name: "tilemap_read_cells",
+        method: "tilemap.read_cells",
+        description: "Read placed tile data from a TileMapLayer (4.3+) or deprecated TileMap. Returns cell coords, source_id, atlas_coords. 500-cell cap. " +
+            paginationDoc("cells", { resumable: false, cursorlessNav: "narrow with region/source_id" }),
+        inputSchema: {
+            node_path: z.string().describe("Path to TileMapLayer or TileMap node"),
+            region: z
+                .object({
+                x: z.coerce.number().int(),
+                y: z.coerce.number().int(),
+                width: z.coerce.number().int().positive(),
+                height: z.coerce.number().int().positive(),
+            })
+                .optional()
+                .describe("Spatial filter: only cells within {x, y, width, height}"),
+            source_id: z.coerce.number().int().optional().describe("Filter to cells from this atlas source"),
+            layer: z.coerce.number().int().optional().describe("Layer index for deprecated TileMap (default 0)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "tilemap_set_cells",
+        method: "tilemap.set_cells",
+        description: "Batch-set cells on TileMap or TileMapLayer. Returns cells_written + cells_unchanged. " +
+            "source_id:-1 clears a cell. Use 'regions' for bulk rectangular fills (far more efficient than listing individual cells).",
+        inputSchema: {
+            node_path: z.string(),
+            layer: z.coerce.number().optional(),
+            cells: z
+                .preprocess(jsonCoerce, z.array(z.record(z.string(), z.unknown())))
+                .optional()
+                .describe("Array of {x, y, source_id, atlas_x, atlas_y, alternative_tile?}. source_id:-1 clears."),
+            regions: z
+                .preprocess(jsonCoerce, z.array(z.record(z.string(), z.unknown())))
+                .optional()
+                .describe("Array of rectangular fills: [{x, y, width, height, source_id, atlas_x, atlas_y, alternative_tile?}]. " +
+                "Each region expands into width*height cells. Far more efficient than listing individual cells for room-scale fills. " +
+                "Can be combined with 'cells' — regions are appended to cells."),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, tilemapTools, allowedTools);
+}