@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/startup/reconcile.js

@@ -0,0 +1,81 @@
+import { MODULE_ALLOWED } from "./serverMode.js";
+import { isReadOnly } from "../security/profiles.js";
+import * as registrars from "./registrars.js";
+import { readMcpJsonEnv, applyEnvUpdate } from "./configReload.js";
+import { batchToolRegistration } from "../registration/toolRegistry.js";
+import { removeAllToolRefs, toolRefCount } from "../registration/toolRefs.js";
+import { resetLoadedGroups } from "../groups/groups.js";
+/**
+ * Construct the reconciler. discover is injected (the ExtensionManager's
+ * discoverExtensions) so this module does not import extensions.ts — keeping the
+ * dependency graph acyclic and the construction order linear.
+ */
+export function createReconciler(deps) {
+    const { server, bridge, projectPath, discover } = deps;
+    // Debounce config_reloaded to prevent rapid config changes from causing
+    // overlapping remove+rebuild cycles that leave the tool list empty.
+    let configReloadTimer = undefined;
+    // One-shot latch for the startup reconcile. Set by armStartupReconcile,
+    // cleared on the first effective reconcile.
+    let needsStartupReconcile = false;
+    function removeAllTools() {
+        removeAllToolRefs();
+        resetLoadedGroups();
+    }
+    function handleConfigReload() {
+        // Re-read .mcp.json for env changes (READ_ONLY, limits, etc.).
+        const newEnv = readMcpJsonEnv(projectPath);
+        if (newEnv) {
+            applyEnvUpdate(newEnv);
+        }
+        // Collapse the remove+rebuild into a SINGLE tools/list_changed. The SDK
+        // auto-emits on every ref.remove() (in removeAllTools) and every registerTool
+        // (in registrars.registerBuiltinModules/registerGroups); batching suppresses those per-op
+        // notifications and fires exactly one when the rebuild completes, so the
+        // client never observes the transient empty/partial tool list mid-reload.
+        batchToolRegistration(server, () => {
+            removeAllTools();
+            registrars.registerBuiltinModules(server, bridge, MODULE_ALLOWED);
+            registrars.registerGroups(server, bridge, isReadOnly());
+        });
+        process.stderr.write(`[godot-mcp] config reloaded — ${toolRefCount()} tools registered\n`);
+        // Re-discover extensions + register discover_tools. Runs AFTER and OUTSIDE
+        // the batch above: it is async (batchToolRegistration is synchronous and would
+        // restore sendToolListChanged before the async work ran), and it batches its
+        // bulk (ungrouped) extension registrations internally — so it reconciles the
+        // extension surface with only a few discrete notifications (the ungrouped
+        // batch, the discover_tools update, the extensions_refresh re-add), never a
+        // per-registration burst.
+        discover().catch(() => { });
+    }
+    function scheduleConfigReload() {
+        if (configReloadTimer)
+            clearTimeout(configReloadTimer);
+        configReloadTimer = setTimeout(() => {
+            configReloadTimer = undefined;
+            handleConfigReload();
+        }, 300);
+    }
+    // ── Startup reconcile ──────────────────────────────────
+    // The eagerly-registered tool surface is INCOMPLETE when the Godot version was
+    // unknown at eager registration (version-gated tools like scene_close were
+    // filtered out) or extension discovery timed out (extension tools never
+    // registered) — the classic server-before-editor cold start. Complete it
+    // EXACTLY ONCE: immediately if the version is already known (slow/timed-out
+    // discovery), or when it resolves later via the version-resolved hook
+    // (server-before-editor). In the common dogfood case the surface is already
+    // complete (version pre-populated + discovery succeeded) → needsStartupReconcile
+    // is false → this is a strict no-op: no reconcile, no extra tools/list_changed.
+    function armStartupReconcile(opts) {
+        needsStartupReconcile = opts.versionNullAtEagerRegistration || opts.extDiscoveryTimedOut;
+        function maybeStartupReconcile() {
+            if (!needsStartupReconcile || bridge.getGodotVersion() == null)
+                return;
+            needsStartupReconcile = false; // one-shot; also dedups reconnect re-deliveries
+            handleConfigReload(); // re-register (known version) + re-discover, already batched
+        }
+        maybeStartupReconcile(); // version already known (slow/timed-out discovery)
+        bridge.onGodotVersionKnown(maybeStartupReconcile); // version known later (server-before-editor)
+    }
+    return { handleConfigReload, scheduleConfigReload, armStartupReconcile };
+}

package/dist/startup/registrars.js

@@ -0,0 +1,59 @@
+import { registerGroupSystem } from "../groups/groups.js";
+import * as animation from "../tools/animation.js";
+import * as asset from "../tools/asset.js";
+import * as diff from "../tools/diff.js";
+import * as editor from "../tools/editor.js";
+import * as file from "../tools/file.js";
+import * as folder from "../tools/folder.js";
+import * as inputMap from "../tools/inputMap.js";
+import * as node from "../tools/node.js";
+import * as playtest from "../tools/playtest.js";
+import * as resource from "../tools/resource.js";
+import * as runtime from "../tools/runtime.js";
+import * as scene from "../tools/scene.js";
+import * as script from "../tools/script.js";
+import * as signal from "../tools/signals.js";
+import * as save from "../tools/save.js";
+import * as tilemap from "../tools/tilemap.js";
+import * as tileset from "../tools/tileset.js";
+import * as classdb from "../tools/classdb.js";
+import * as nodeManagement from "../tools/nodeManagement.js";
+import * as sceneQuery from "../tools/sceneQuery.js";
+import * as spatial from "../tools/spatial.js";
+import * as texture from "../tools/texture.js";
+import * as sound from "../tools/sound.js";
+/** Register every built-in tool module onto the server (scene, node, script, … sound — 23 modules). */
+export function registerBuiltinModules(server, bridge, moduleAllowed) {
+    scene.register(server, bridge, moduleAllowed);
+    node.register(server, bridge, moduleAllowed);
+    script.register(server, bridge, moduleAllowed);
+    editor.register(server, bridge, moduleAllowed);
+    resource.register(server, bridge, moduleAllowed);
+    folder.register(server, bridge, moduleAllowed);
+    diff.register(server, bridge, moduleAllowed);
+    playtest.register(server, bridge, moduleAllowed);
+    tilemap.register(server, bridge, moduleAllowed);
+    tileset.register(server, bridge, moduleAllowed);
+    asset.register(server, bridge, moduleAllowed);
+    runtime.register(server, bridge, moduleAllowed);
+    signal.register(server, bridge, moduleAllowed);
+    animation.register(server, bridge, moduleAllowed);
+    inputMap.register(server, bridge, moduleAllowed);
+    file.register(server, bridge, moduleAllowed);
+    save.register(server, bridge, moduleAllowed);
+    classdb.register(server, bridge, moduleAllowed);
+    nodeManagement.register(server, bridge, moduleAllowed);
+    sceneQuery.register(server, bridge, moduleAllowed);
+    spatial.register(server, bridge, moduleAllowed);
+    texture.register(server, bridge, moduleAllowed);
+    sound.register(server, bridge, moduleAllowed);
+}
+/** Register the discover_tools group system (idempotent; re-callable to refresh its description). */
+export function registerGroups(server, bridge, readOnly) {
+    // Register discover_tools with built-in groups BEFORE transport
+    // connects, so it's in the initial tools/list response — no extra
+    // notification needed for the common case (no extensions).
+    // If extensions are later discovered, registerGroupSystem is called
+    // again (idempotent) which updates the description.
+    registerGroupSystem(server, bridge, readOnly);
+}

package/dist/startup/serverMode.js

@@ -0,0 +1,19 @@
+/**
+ * Server mode — the static registration inputs.
+ *
+ * Read-only state is read live via profiles.isReadOnly() at each use site: the
+ * env mutates only through applyEnvUpdate (config-reload), called synchronously
+ * before any read, so a live read is always current — no cache needed. The
+ * module-allowed set (eager tools minus group-managed tools) is constant
+ * across reloads (resolveAllowedTools() is the fixed EAGER_TOOLS set;
+ * GROUP_TOOL_NAMES is immutable), so it is computed once here.
+ */
+import { resolveAllowedTools } from "../security/profiles.js";
+import { GROUP_TOOL_NAMES } from "../groups/groups.js";
+/** Eager tools minus group-managed tools — the set passed to registerBuiltinModules. Constant across reloads. */
+export const MODULE_ALLOWED = (() => {
+    const mod = new Set(resolveAllowedTools());
+    for (const name of GROUP_TOOL_NAMES)
+        mod.delete(name);
+    return mod;
+})();

package/dist/startup/startupEnv.js

@@ -0,0 +1,142 @@
+// ── Startup environment preflight ────────────────────────────────────
+//
+// One-shot boot-environment resolution + validation for the composition
+// root (index.ts). Each function here is a stateless preflight: it reads
+// process.env / the static catalogue, emits stderr (or stdout) diagnostics,
+// and — for the exit gates — may process.exit. No subsystem state lives
+// here; the root calls these in sequence before constructing the bridge.
+// Port resolution lives in its own collaborator (portConfig.ts).
+import { ALL_TOOL_DEFS, META_TOOL_NAMES } from "../registration/catalogue.js";
+import { countBuiltinOperations } from "../registration/operations.js";
+import { GROUP_TOOL_NAMES, GROUPS } from "../groups/groups.js";
+import { MODULE_ALLOWED } from "./serverMode.js";
+import { formatHelp } from "./cliArgs.js";
+/** Hard-exit (code 1) if the Node runtime is below the engines.node floor (>=22). */
+export function enforceNodeVersion() {
+    const [nodeMajor] = process.versions.node.split(".").map(Number);
+    if (nodeMajor < 22) {
+        process.stderr.write(`[godot-mcp] Error: requires Node.js >= 22 (found ${process.version}).\n` +
+            `Download the latest LTS from https://nodejs.org\n`);
+        process.exit(1);
+    }
+}
+/**
+ * Build the static built-in tool manifest by name, deterministically sorted.
+ *
+ * The eager set is derived from `MODULE_ALLOWED` — the same set index.ts hands to
+ * `registerBuiltinModules` — so the manifest reflects the names registered
+ * eagerly rather than a parallel list. Meta names come from `META_TOOL_NAMES` and
+ * group membership from `GROUPS`, the same sources `--tools-count` counts.
+ *
+ * @returns the manifest; every array and every `groups` key ascending-sorted so
+ *   the serialization is byte-stable across turns
+ * @remarks Names only, and only the static built-in surface — per-project
+ *   extension tools are dynamic and excluded, matching `--tools-count`.
+ */
+export function buildEagerManifest() {
+    const eager = [...MODULE_ALLOWED].sort();
+    const meta = [...META_TOOL_NAMES].sort();
+    const groups = {};
+    for (const group of [...GROUPS].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
+        groups[group.name] = [...group.tools].sort();
+    }
+    return { eager, meta, groups };
+}
+/** Print the eager+meta tool manifest as pretty JSON to stdout — a pre-transport
+ *  CLI report. Names only; a clean early-exit emit before any MCP wiring. */
+function printEagerList() {
+    process.stdout.write(JSON.stringify(buildEagerManifest(), null, 2) + "\n");
+}
+/** Print the static tool-count summary to stdout — a pre-transport CLI report,
+ *  derived from the canonical ALL_TOOL_DEFS (excludes dynamic extension tools). */
+function printToolCount() {
+    const total = ALL_TOOL_DEFS.length;
+    const onDemand = GROUP_TOOL_NAMES.size;
+    const eager = total - onDemand;
+    process.stdout.write(`Total tools:  ${total}\n` +
+        `  Eager:      ${eager}\n` +
+        `  On-demand:  ${onDemand}\n` +
+        `Meta:         ${META_TOOL_NAMES.length} (also eager — always in tools/list)\n` +
+        `Groups:       ${GROUPS.length}\n` +
+        `Operations (built-in): ${countBuiltinOperations(ALL_TOOL_DEFS)}\n` +
+        `Startup surface (eager + meta): ${eager + META_TOOL_NAMES.length}\n`);
+}
+/**
+ * Apply the CLI meta gates that print-and-exit before any bridge/WebSocket/
+ * transport setup (all editor-independent):
+ *   - `--help` → usage on **stdout**, exit 0 (a CLI invocation, not an MCP session)
+ *   - a parse error → the message + usage on **stderr**, exit 1 (fail loud)
+ *   - `--tools-count` → the static count on **stdout**, exit 0
+ *   - `--list-eager` → the static tool manifest as JSON on **stdout**, exit 0
+ *
+ * No-op when argv carries none of these. `--help` wins over a parse error so a
+ * bad flag alongside `--help` still prints usage rather than erroring.
+ */
+export function applyCliMetaGates(cli) {
+    if (cli.help) {
+        process.stdout.write(formatHelp());
+        process.exit(0);
+    }
+    if (cli.error) {
+        process.stderr.write(`[godot-mcp] ${cli.error}\n\n${formatHelp()}`);
+        process.exit(1);
+    }
+    if (cli.toolsCount) {
+        printToolCount();
+        process.exit(0);
+    }
+    if (cli.listEager) {
+        printEagerList();
+        process.exit(0);
+    }
+}
+// Defaults match the plugin-side ProjectSettings defaults.
+const SCRIPT_READ_LIMIT_DEFAULT = 262144; // 256 KB
+const WS_BUFFER_LIMIT_DEFAULT = 1048576; // 1 MB
+const SCRIPT_READ_LIMIT_FLOOR = 65536; // 64 KB
+const WS_BUFFER_LIMIT_FLOOR = 262144; // 256 KB
+function parseCapEnv(envName, defaultVal, floor) {
+    const raw = process.env[envName];
+    if (!raw)
+        return defaultVal;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        process.stderr.write(`[godot-mcp] WARNING: ${envName}=${raw} is not a valid positive number; using default ${defaultVal}\n`);
+        return defaultVal;
+    }
+    if (parsed < floor) {
+        process.stderr.write(`[godot-mcp] WARNING: ${envName}=${parsed} is below minimum ${floor}; clamping to ${floor}\n`);
+        return floor;
+    }
+    return parsed;
+}
+/** Parse + clamp GODOT_MCP_SCRIPT_READ_LIMIT / _WS_BUFFER_LIMIT against their floors/defaults. */
+export function resolveResponseCaps() {
+    const scriptReadLimitBytes = parseCapEnv("GODOT_MCP_SCRIPT_READ_LIMIT", SCRIPT_READ_LIMIT_DEFAULT, SCRIPT_READ_LIMIT_FLOOR);
+    const wsBufferLimitBytes = parseCapEnv("GODOT_MCP_WS_BUFFER_LIMIT", WS_BUFFER_LIMIT_DEFAULT, WS_BUFFER_LIMIT_FLOOR);
+    return { scriptReadLimitBytes, wsBufferLimitBytes };
+}
+// ── Config version check ─────────────────────────────────────────────
+const EXPECTED_CONFIG_VERSION = 1;
+/** Warn (stderr) if GODOT_MCP_CONFIG_VERSION is missing / non-numeric / older / newer than EXPECTED. */
+export function warnConfigVersion() {
+    const rawConfigVersion = process.env.GODOT_MCP_CONFIG_VERSION;
+    if (rawConfigVersion == null || rawConfigVersion === "") {
+        process.stderr.write("[godot-mcp] WARNING: no GODOT_MCP_CONFIG_VERSION in env. " +
+            "Config may be from a pre-release build — regenerate .mcp.json from the toolkit dock.\n");
+    }
+    else {
+        const configVersion = Number(rawConfigVersion);
+        if (!Number.isFinite(configVersion)) {
+            process.stderr.write(`[godot-mcp] WARNING: GODOT_MCP_CONFIG_VERSION="${rawConfigVersion}" is not a valid number.\n`);
+        }
+        else if (configVersion < EXPECTED_CONFIG_VERSION) {
+            process.stderr.write(`[godot-mcp] WARNING: config version ${configVersion} is outdated (expected ${EXPECTED_CONFIG_VERSION}). ` +
+                `Regenerate .mcp.json from the toolkit dock.\n`);
+        }
+        else if (configVersion > EXPECTED_CONFIG_VERSION) {
+            process.stderr.write(`[godot-mcp] WARNING: config version ${configVersion} is newer than this server understands (max ${EXPECTED_CONFIG_VERSION}). ` +
+                `Consider updating the server (npm update).\n`);
+        }
+    }
+}

package/dist/tools/animation.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+export const animationTools = [
+    {
+        name: "animation_keyframe",
+        method: "animation.keyframe",
+        description: "Add/remove a keyframe on an existing animation's track. animation must already exist; action='add' auto-creates the track only. Idempotent on exact-time dup.",
+        inputSchema: {
+            action: z.enum(["add", "remove"]),
+            player_path: z.string(),
+            animation_name: z.string(),
+            track_path: z.string(),
+            time: z.coerce.number(),
+            value: z.unknown().optional().describe("Required for action='add'."),
+            track_type: z.enum(["value"]).optional().describe("Track type; only 'value' supported currently."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        operationParam: "action",
+        successHint: "Verify keys with animation_get_keys. Configure AnimationTree with animationtree_edit.",
+    },
+    {
+        name: "animation_get_keys",
+        method: "animation.get_keys",
+        description: "List keys on an AnimationPlayer track: { time, value, transition }. Read-only; no auto-track-create.",
+        inputSchema: {
+            player_path: z.string(),
+            animation_name: z.string(),
+            track_path: z.string(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "animationtree_edit",
+        method: "animationtree.edit",
+        description: "Configure AnimationTree state machines: set root, add/remove nodes and transitions, or set properties.",
+        inputSchema: {
+            node_path: z.string().describe("Path to an AnimationTree node in the edited scene."),
+            action: z
+                .enum(["set_root", "add_node", "remove_node", "add_transition", "remove_transition", "set_property"])
+                .describe("Operation to perform on the AnimationTree."),
+            root_type: z
+                .enum(["AnimationNodeStateMachine", "AnimationNodeBlendTree"])
+                .optional()
+                .describe("For set_root: type of root node to create."),
+            node_name: z.string().optional().describe("For add_node/remove_node: name of the state machine node."),
+            node_type: z
+                .string()
+                .optional()
+                .describe("For add_node: AnimationNode subclass (e.g. AnimationNodeAnimation, AnimationNodeBlendSpace2D)."),
+            animation_name: z
+                .string()
+                .optional()
+                .describe("For add_node with AnimationNodeAnimation: which animation to play."),
+            position: z
+                .object({ x: z.number(), y: z.number() })
+                .optional()
+                .describe("For add_node: graph position { x, y }."),
+            from: z.string().optional().describe("For transitions: source node name."),
+            to: z.string().optional().describe("For transitions: destination node name."),
+            switch_mode: z
+                .enum(["immediate", "sync", "at_end"])
+                .optional()
+                .describe("For add_transition: when the transition fires."),
+            advance_condition: z.string().optional().describe("For add_transition: condition name for conditional advance."),
+            advance_mode: z
+                .enum(["disabled", "enabled", "auto"])
+                .optional()
+                .describe("For add_transition: advance mode (disabled=0, enabled=1, auto=2)."),
+            target_node: z.string().optional().describe("For set_property: node name in the state machine."),
+            property: z.string().optional().describe("For set_property: property name to set."),
+            value: z.unknown().optional().describe("For set_property: value to assign."),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: true },
+        operationParam: "action",
+    },
+    {
+        name: "animationtree_list",
+        method: "animationtree.list",
+        description: "List an AnimationTree state machine's structure: root type, nodes, and transitions. Read-only; no mutation.",
+        inputSchema: {
+            node_path: z.string().describe("Path to an AnimationTree node in the edited scene."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, animationTools, allowedTools);
+}

package/dist/tools/asset.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { coercedBoolean, jsonCoerce } from "../shared/schemaCoercion.js";
+import { PROJECT_FILE_PATH } from "../security/pathGuard.js";
+import { assetWriteFields } from "./assetWrite.js";
+import { paginationDoc } from "../shared/pagination.js";
+export const assetTools = [
+    {
+        name: "asset_list",
+        method: "asset.list",
+        description: "Enumerate res:// assets with filters (path_prefix, name_glob, class_filter ancestry-aware, extension_filter). Returns [{path,class,modified_unix}]. " +
+            paginationDoc("assets", { resumable: false, cursorlessNav: "narrow filters or raise limit" }) +
+            "limit caps at 2000 (default 500); a request above 2000 is clamped and limit_clamped is set (a non-positive limit is rejected).",
+        inputSchema: {
+            path_prefix: z.string().optional(),
+            name_glob: z.string().optional(),
+            class_filter: z.string().optional(),
+            extension_filter: z.preprocess(jsonCoerce, z.array(z.string())).optional(),
+            limit: z.coerce.number().optional().describe("Max assets returned (default 500, clamped to 2000)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        successHint: "A just-deindexed asset (e.g. after resource_delete) can linger in this list until EditorFileSystem re-scans — call editor_refresh to force a rescan if a deleted asset still appears.",
+        pathParams: [{ param: "path_prefix", guard: "project" }],
+    },
+    {
+        name: "asset_get_dependencies",
+        method: "asset.get_dependencies",
+        description: "Forward dependencies of a res:// resource/scene via EditorFileSystem cache. include_transitive walks deps-of-deps. Returns [{path,raw_path,class}]. " +
+            paginationDoc("dependencies", { resumable: false, cursorlessNav: "narrow the query or raise limit" }),
+        inputSchema: {
+            file_path: z.string(),
+            include_transitive: coercedBoolean().optional(),
+            limit: z.coerce.number().optional().describe("Max dependencies returned (default 200)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        pathParams: [PROJECT_FILE_PATH],
+    },
+    {
+        name: "asset_import",
+        method: "asset.import",
+        description: "Import binary asset (image/audio/font/3D) into res:// via exactly one of source_path (absolute or res:// path) or base64_data. Triggers EditorFileSystem scan. if_exists:return|fail|replace.",
+        inputSchema: {
+            source_path: z.string().optional(),
+            base64_data: z.string().optional(),
+            dest_path: z.string(),
+            ...assetWriteFields,
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: false, destructiveHint: false },
+        successHint: "Verify import with resource_load. Check file system with asset_list.",
+        // Only dest_path is guarded. source_path is deliberately NOT declared: it is
+        // an absolute filesystem path to an external asset (the toolkit reads it raw,
+        // guarding only dest_path) — guarding it would false-reject intended use.
+        pathParams: [{ param: "dest_path", guard: "project" }],
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, assetTools, allowedTools);
+}

package/dist/tools/assetWrite.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * Shared file-write fields for the tools that write a res:// asset and settle
+ * its import through the toolkit's `write_asset_with_settle` bracket:
+ * asset_import, texture_generate, sound_generate.
+ *
+ * The path parameter itself is declared per-tool (asset_import uses `dest_path`;
+ * the generators use `path`), so only the two identical fields live here.
+ *
+ * @internal Folder-internal to `tools/` — shared only among the sibling
+ * asset-write tool modules, not part of the public surface.
+ */
+export const assetWriteFields = {
+    if_exists: z.enum(["return", "fail", "replace"]).optional(),
+    wait_for_scan_ms: z.coerce.number().optional(),
+};

package/dist/tools/audio.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+export const audioTools = [
+    {
+        name: "audiobus_edit",
+        method: "audiobus.edit",
+        description: "Manage audio buses: add/remove buses, set volume/send/solo/mute, add/remove effects. bus_name takes priority over bus_index. Effect type: full class (AudioEffectReverb) or suffix (Reverb).",
+        inputSchema: {
+            action: z.enum(["add_bus", "remove_bus", "set_bus", "add_effect", "remove_effect"]).describe("Bus operation"),
+            bus_name: z.string().optional().describe("Bus name"),
+            bus_index: z.number().int().optional().describe("Bus index (alternative to name)"),
+            send_to: z.string().optional().describe("Parent bus name (default: Master)"),
+            volume_db: z.number().optional().describe("Volume in dB"),
+            solo: z.boolean().optional().describe("Solo this bus"),
+            mute: z.boolean().optional().describe("Mute this bus"),
+            effect: z
+                .object({
+                type: z.string().describe("Effect class: Reverb, Delay, Compressor, Chorus, EQ, etc."),
+                index: z.number().int().optional().describe("Effect slot index"),
+                enabled: z.boolean().optional().describe("Enable/disable the effect"),
+                properties: z.record(z.string(), z.unknown()).optional().describe("Effect-specific properties"),
+            })
+                .optional()
+                .describe("Effect to add/remove"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: true },
+        operationParam: "action",
+        successHint: "Effect types must be full class names (e.g., AudioEffectReverb not Reverb).",
+    },
+    {
+        name: "audiobus_list",
+        method: "audiobus.list",
+        description: "List all audio buses with volume/send/solo/mute and per-bus effects. Read-only snapshot of the bus layout.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, audioTools, allowedTools);
+}

package/dist/tools/classdb.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+import { coercedBoolean } from "../shared/schemaCoercion.js";
+import { offsetLimitParams, paginationDoc } from "../shared/pagination.js";
+export const classdbTools = [
+    {
+        name: "classdb_get_info",
+        method: "classdb.get_info",
+        description: "Inspect any Godot class: properties, methods, signals, constants, inheritance. Supports engine + user class_name classes. " +
+            paginationDoc("<section>", { resumable: true }) +
+            "The envelope is per-section (properties, methods, signals, constants); offset and limit apply within each section (limit default 200, clamped above 200).",
+        inputSchema: {
+            class_name: z.string().describe("Engine class (e.g. RigidBody3D) or user-defined class_name."),
+            include_inherited: coercedBoolean()
+                .optional()
+                .describe("Include inherited members (default: false, own class only)."),
+            sections: z
+                .array(z.enum(["properties", "methods", "signals", "constants"]))
+                .optional()
+                .describe("Which sections to return (default: all). Limit to reduce token cost."),
+            ...offsetLimitParams,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    {
+        name: "classdb_search",
+        method: "classdb.search",
+        description: "Find Godot classes by inheritance and/or name pattern. Returns class list with parent + instantiability. " +
+            paginationDoc("classes", { resumable: true }) +
+            "limit default 200, clamped above 200.",
+        inputSchema: {
+            base_class: z.string().optional().describe("Filter to subclasses of this class."),
+            pattern: z.string().optional().describe("Case-insensitive substring match on class name."),
+            instantiable_only: coercedBoolean().optional().describe("Exclude abstract classes (default: true)."),
+            include_global: coercedBoolean().optional().describe("Include user class_name classes (default: true)."),
+            ...offsetLimitParams,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, classdbTools, allowedTools);
+}

package/dist/tools/collision.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+export const collisionTools = [
+    {
+        name: "collision_from_texture",
+        method: "node.collision_from_sprite",
+        description: "Auto-generate CollisionPolygon2D from a Sprite2D's texture alpha. Uses BitMap to trace opaque regions. For platformer terrain, character hitboxes, irregular shapes.",
+        inputSchema: {
+            sprite_path: z.string().describe("Path to a Sprite2D/TextureRect node with a texture"),
+            parent_path: z.string().optional().describe("Parent for the new CollisionPolygon2D (default: sprite's parent)"),
+            target_name: z.string().optional().describe("Name for the CollisionPolygon2D (default: {sprite}_collision)"),
+            simplification: z
+                .number()
+                .optional()
+                .describe("Polygon simplification epsilon 0.0-10.0 (default 2.0, higher=fewer points)"),
+        },
+        annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+        successHint: "Assign the generated polygon to a CollisionPolygon2D via node_set_property.",
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, collisionTools, allowedTools);
+}

package/dist/tools/debug.js

@@ -0,0 +1,46 @@
+/**
+ * Debugger tool definitions — breakpoint management + debug state
+ * via the toolkit's EditorDebuggerPlugin bridge. All 4 tools are
+ * group-only (lazy-loaded via discover_tools → debugger group).
+ */
+import { z } from "zod";
+import { coercedBoolean } from "../shared/schemaCoercion.js";
+export const debugTools = [
+    {
+        name: "debug_state",
+        method: "debug.state",
+        description: "Check debugger status: is a debug session active, is it paused at a breakpoint, can it be debugged. No params.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: "debug_list_breakpoints",
+        method: "debug.list_breakpoints",
+        description: "List all GDScript breakpoints currently set in the script editor. Returns file paths and line numbers. .gd only.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: "debug_set_breakpoint",
+        method: "debug.set_breakpoint",
+        description: "Set or clear a breakpoint at a specific file and line in the script editor. GDScript (.gd) files only.",
+        inputSchema: {
+            file_path: z.string().describe("res:// path to a .gd file (e.g. res://scripts/player.gd)"),
+            line: z.coerce.number().int().describe("1-based line number"),
+            // Optional with `.optional()` OUTERMOST: a coercion wrapper (preprocess =
+            // ZodPipe) does not inherit an inner `.optional()` under the SDK's
+            // io:"input" conversion, which would flip the param to `required` in
+            // tools/list. The plugin defaults enabled→true (debug_commands.gd), so no
+            // server-side .default is needed. A structural test guards against regression.
+            enabled: coercedBoolean().optional().describe("true to set, false to clear (default true)"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    },
+    {
+        name: "debug_continue",
+        method: "debug.continue",
+        description: "Resume execution when the debugger is paused at a breakpoint. Fails if not breaked.",
+        inputSchema: {},
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    },
+];

package/dist/tools/diff.js

@@ -0,0 +1,18 @@
+import { z } from "zod";
+import { registerTools } from "../registration/toolRegistry.js";
+// Line-based JSON diff between two scene-tree snapshots. Useful for
+// "what changed since I last looked?" workflows after a sequence of
+// mutations. The plugin does the heavy lifting; this module is a thin
+// pass-through.
+export const diffTools = [
+    {
+        name: "scene_diff",
+        method: "scene.diff",
+        description: "Compare a prior scene-tree snapshot against another snapshot (or current edited scene if 'after' omitted). Returns { changed, diff, added, removed }.",
+        inputSchema: { before: z.any(), after: z.any().optional() },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+];
+export function register(server, bridge, allowedTools) {
+    registerTools(server, bridge, diffTools, allowedTools);
+}