@npgamedev/godot-mcp-server 0.0.1 → 1.0.0

package/dist/mcp/resources.js

@@ -0,0 +1,113 @@
+/**
+ * Register the read-only Godot resources (`godot://scene/{path}`,
+ * `godot://script/{path}`, `godot://project/info`) on the server. Each fetches
+ * live state over the bridge and degrades to an error payload if the call fails.
+ */
+export function registerResources(server, bridge) {
+    // ── godot://scene/{path} ─────────────────────────────────────────────
+    // Returns the scene tree snapshot for the given scene file path.
+    // The path should be a res:// path (e.g. "res://Main.tscn").
+    server.resource("scene", "godot://scene/{path}", { mimeType: "application/json" }, async (uri) => {
+        const path = decodeScenePath(uri.href);
+        try {
+            const result = await bridge.call("scene.get_tree", {
+                depth: 4,
+                include_properties: false,
+            });
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify({
+                            error: err.message,
+                            path,
+                        }),
+                    },
+                ],
+            };
+        }
+    });
+    // ── godot://script/{path} ───────────────────────────────────────────
+    // Returns the script source for a given res:// path.
+    server.resource("script", "godot://script/{path}", { mimeType: "text/x-gdscript" }, async (uri) => {
+        const path = decodeScriptPath(uri.href);
+        try {
+            const result = (await bridge.call("script.read", {
+                file_path: path,
+            }));
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "text/x-gdscript",
+                        text: typeof result?.content === "string" ? result.content : JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "text/plain",
+                        text: `Error reading script: ${err.message}`,
+                    },
+                ],
+            };
+        }
+    });
+    // ── godot://project/info ─────────────────────────────────────────────
+    // Returns project metadata (name, Godot version, etc.).
+    server.resource("project-info", "godot://project/info", { mimeType: "application/json" }, async (uri) => {
+        try {
+            const result = await bridge.call("project.get_settings", {
+                keys: ["application/config/name", "application/config/version"],
+            });
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: "application/json",
+                        text: JSON.stringify({ error: err.message }),
+                    },
+                ],
+            };
+        }
+    });
+}
+// ── URI helpers ───────────────────────────────────────────────────────
+/** Extract the res:// path from a godot://scene/ URI. */
+function decodeScenePath(href) {
+    // godot://scene/res://Main.tscn → res://Main.tscn
+    const match = href.match(/^godot:\/\/scene\/(.+)$/);
+    return match ? decodeURIComponent(match[1]) : href;
+}
+/** Extract the res:// path from a godot://script/ URI. */
+function decodeScriptPath(href) {
+    const match = href.match(/^godot:\/\/script\/(.+)$/);
+    return match ? decodeURIComponent(match[1]) : href;
+}

package/dist/mcp/roots.js

@@ -0,0 +1,30 @@
+/** Resolved project path — set once at startup via init(). */
+let projectRoot;
+/** Set the resolved project root (startup wiring). @internal */
+export function init(path) {
+    projectRoot = path;
+}
+/**
+ * Register a `godot://roots` resource that returns the project root(s).
+ * This lets MCP clients discover what Godot project this server is
+ * connected to without relying on the client's own root list.
+ */
+export function registerRoots(server) {
+    server.resource("roots", "godot://roots", { mimeType: "application/json" }, async (uri) => {
+        const roots = [];
+        if (projectRoot) {
+            // Normalize to file:// URI for cross-platform compatibility.
+            const fileUri = projectRoot.startsWith("file://") ? projectRoot : `file://${projectRoot.replace(/\\/g, "/")}`;
+            roots.push({ uri: fileUri, name: "Godot Project" });
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: "application/json",
+                    text: JSON.stringify({ roots }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/dist/registration/catalogue.js

@@ -0,0 +1,123 @@
+// ── Canonical tool catalogue ─────────────────────────────────────────
+//
+// THE single source of truth for "every tool definition the server ships".
+// ALL_TOOL_DEFS is the complete, deduplicated list of every per-module
+// ToolDef array under src/tools/. Counting (the --tools-count CLI flag),
+// the structural smoke catalogue (test/sections/01_catalogue.ts), the
+// unfiltered structural checks (test/structural.ts), and the groups.ts
+// name→def lookup all derive from this list — so a tool can never be
+// counted in one place and missed in another.
+//
+// GUARDRAIL — enumeration only. This list is for counting and static
+// validation. It is NOT the registration path: the eager set is still
+// `allowed − GROUP_TOOL_NAMES` fed to per-module registerTools() in
+// index.ts. Do not route runtime registration through ALL_TOOL_DEFS — it
+// would eagerly advertise every tool and defeat the on-demand split.
+//
+// Maintenance: when a new src/tools/ module is added, import its ToolDef
+// array here. The completeness guard in 01_catalogue.ts (GROUP/RUNTIME/LSP
+// tool names ⊆ ALL_TOOL_NAMES) plus the no-duplicate-names assertion catch
+// the common mistakes (forgotten array, double-counted convenience export).
+import { animationTools } from "../tools/animation.js";
+import { assetTools } from "../tools/asset.js";
+import { audioTools } from "../tools/audio.js";
+import { classdbTools } from "../tools/classdb.js";
+import { collisionTools } from "../tools/collision.js";
+import { debugTools } from "../tools/debug.js";
+import { diffTools } from "../tools/diff.js";
+import { editorTools } from "../tools/editor.js";
+import { fileTools } from "../tools/file.js";
+import { folderTools } from "../tools/folder.js";
+import { inputMapTools } from "../tools/inputMap.js";
+import { layerNameTools } from "../tools/layerNames.js";
+import { lspAnalysisTools, lspNavigationTools } from "../tools/lsp.js";
+import { navigationTools } from "../tools/navigation.js";
+import { nodeTools } from "../tools/node.js";
+import { nodeManagementTools } from "../tools/nodeManagement.js";
+import { particleTools } from "../tools/particles.js";
+import { pathTools } from "../tools/path.js";
+import { playtestTools } from "../tools/playtest.js";
+import { proceduralTools } from "../tools/procedural.js";
+import { resourceTools } from "../tools/resource.js";
+import { runtimeTools } from "../tools/runtime.js";
+import { saveTools } from "../tools/save.js";
+import { sceneTools } from "../tools/scene.js";
+import { sceneInheritanceTools } from "../tools/sceneInheritance.js";
+import { sceneQueryTools } from "../tools/sceneQuery.js";
+import { scriptTools } from "../tools/script.js";
+import { signalTools } from "../tools/signals.js";
+import { soundTools } from "../tools/sound.js";
+import { spatialTools } from "../tools/spatial.js";
+import { spriteframesTools } from "../tools/spriteframes.js";
+import { themeTools } from "../tools/theme.js";
+import { textureTools } from "../tools/texture.js";
+import { threeDTools } from "../tools/threeD.js";
+import { tilemapTools } from "../tools/tilemap.js";
+// NOTE: split tileset exports — NOT the unsplit `tilesetTools` convenience
+// spread, which would double-count. Same reasoning applies to lsp above
+// (lspAnalysisTools + lspNavigationTools, not the combined `lspTools`).
+import { tilesetStructuralTools, tilesetEditTools } from "../tools/tileset.js";
+/**
+ * Every tool definition the server ships, across all src/tools/ modules.
+ * Both eager and on-demand (group) tools live here — the eager/on-demand
+ * split is a visibility partition over this set (see serverMode.ts
+ * MODULE_ALLOWED and groups.ts GROUP_TOOL_NAMES), not two pools.
+ */
+export const ALL_TOOL_DEFS = [
+    ...animationTools,
+    ...assetTools,
+    ...audioTools,
+    ...classdbTools,
+    ...collisionTools,
+    ...debugTools,
+    ...diffTools,
+    ...editorTools,
+    ...fileTools,
+    ...folderTools,
+    ...inputMapTools,
+    ...layerNameTools,
+    ...lspAnalysisTools,
+    ...lspNavigationTools,
+    ...navigationTools,
+    ...nodeTools,
+    ...nodeManagementTools,
+    ...particleTools,
+    ...pathTools,
+    ...playtestTools,
+    ...proceduralTools,
+    ...resourceTools,
+    ...runtimeTools,
+    ...saveTools,
+    ...sceneTools,
+    ...sceneInheritanceTools,
+    ...sceneQueryTools,
+    ...scriptTools,
+    ...signalTools,
+    ...soundTools,
+    ...spatialTools,
+    ...spriteframesTools,
+    ...themeTools,
+    ...threeDTools,
+    ...textureTools,
+    ...tilemapTools,
+    ...tilesetStructuralTools,
+    ...tilesetEditTools,
+];
+/** Names of every tool in ALL_TOOL_DEFS. */
+export const ALL_TOOL_NAMES = new Set(ALL_TOOL_DEFS.map((t) => t.name));
+/**
+ * Always-registered tools that live OUTSIDE the per-module ToolDef arrays
+ * (registered directly in index.ts / groups.ts, so absent from
+ * ALL_TOOL_DEFS). Keep in sync with index.ts registerGroups() +
+ * registerExtensionsRefresh(). Excludes per-project extension tools, which
+ * are dynamic.
+ */
+export const META_TOOL_NAMES = ["discover_tools", "extensions_refresh"];
+/**
+ * Whether `name` is one of the server's own built-in tool names — any tool in the
+ * static catalogue (eager or on-demand) or an always-on meta tool. The authority
+ * for "this name belongs to the server, not to an extension."
+ */
+export function isBuiltinToolName(name) {
+    return ALL_TOOL_NAMES.has(name) || META_TOOL_NAMES.includes(name);
+}

package/dist/registration/extensionCollision.js

@@ -0,0 +1,38 @@
+/**
+ * Extension name-collision guard.
+ *
+ * Refuses an extension tool whose name would shadow a built-in tool or a tool
+ * that is already registered. The server is the only component that holds BOTH
+ * its full built-in catalogue and a discovered extension's chosen name at
+ * registration time — the toolkit publishes the extensions but never sees the
+ * server's built-in list — so a built-in↔extension name clash can only be caught
+ * here.
+ *
+ * Installed extensions run in-process with full trust, so refusing a clash is
+ * defence-in-depth against ACCIDENTAL name reuse (a well-meaning author reuses a
+ * name the server already ships), not a privilege boundary: the clash is skipped
+ * with a loud warning, never a crash, and the incumbent always wins — a built-in
+ * is never overwritten, and between two extensions the first to register keeps the
+ * name.
+ */
+import { isBuiltinToolName } from "./catalogue.js";
+import { hasToolRef } from "./toolRefs.js";
+/**
+ * Whether registering an extension tool under `toolName` would collide with a
+ * built-in tool or an already-registered tool; the caller MUST skip the tool when
+ * this returns true (the incumbent keeps the name). A collision is logged to
+ * stderr so the skip is diagnosable; a free name returns false silently.
+ *
+ * @remarks
+ * The explicit pre-check makes the MCP SDK's duplicate-name handling moot for
+ * correctness: the SDK's `registerTool` throws `Tool <name> is already registered`
+ * on a repeated name, so refusing the collision here skips the one tool cleanly
+ * instead of letting that throw abort the surrounding registration batch.
+ */
+export function extensionNameCollides(toolName) {
+    if (isBuiltinToolName(toolName) || hasToolRef(toolName)) {
+        process.stderr.write(`[godot-mcp] extension tool '${toolName}' collides with a built-in (or already-registered) tool — skipped\n`);
+        return true;
+    }
+    return false;
+}

package/dist/registration/operations.js

@@ -0,0 +1,67 @@
+/**
+ * Operation-coverage counting — the single derivation of how many distinct
+ * *operations* (action-discriminator values) the built-in tool surface exposes.
+ *
+ * An action-consolidated tool packs several operations behind one enum
+ * discriminator (`node_manage.action` → rename/reparent/reorder/duplicate), so a
+ * raw tool count understates the real breadth. This module is the SSOT the
+ * `--tools-count` CLI, the `01_catalogue` drift gate, and the tool-reference
+ * generator all count through, so the number can never differ between them.
+ *
+ * Human-facing only: operation counts feed reports and docs, never a tool
+ * description or `discover_tools` output.
+ *
+ * @module
+ */
+import { z } from "zod";
+/**
+ * The distinct operations a tool exposes through its discriminator: the values
+ * of its `operationParam` enum, else its explicit `operations` list, else an
+ * empty array for a tool that performs one implicit operation with no
+ * discriminator.
+ *
+ * @param def one catalogue tool definition
+ * @returns the operation value names, or an empty array for a single-operation
+ *   tool — callers that need a count floor it at 1 (see {@link operationCountOf})
+ * @remarks Reads the enum values via `z.toJSONSchema` (the codebase idiom, robust
+ *   across Zod point releases) rather than the Zod-instance enum API. A missing or
+ *   non-enum `operationParam` yields no values; the drift gate is what asserts the
+ *   param names a real enum.
+ */
+export function operationsOf(def) {
+    if (def.operationParam) {
+        const values = enumValuesOf(def.inputSchema, def.operationParam);
+        if (values.length > 0)
+            return values;
+    }
+    if (def.operations && def.operations.length > 0)
+        return def.operations;
+    return [];
+}
+/** A tool's operation count — its discriminator values, or 1 for a single-operation tool. */
+export function operationCountOf(def) {
+    return Math.max(1, operationsOf(def).length);
+}
+/**
+ * Total built-in operations across every catalogued tool — the sum of each
+ * tool's {@link operationCountOf}.
+ *
+ * @param defs the canonical catalogue (`ALL_TOOL_DEFS`)
+ * @returns the operation grand total (the figure `--tools-count` prints and the
+ *   drift gate snapshots)
+ */
+export function countBuiltinOperations(defs) {
+    let total = 0;
+    for (const def of defs)
+        total += operationCountOf(def);
+    return total;
+}
+/**
+ * The enum values of a top-level inputSchema param, or an empty array when the
+ * param is absent or not a plain enum (e.g. a string, or an enum nested in a
+ * union — those tools declare `operations` instead).
+ */
+function enumValuesOf(inputSchema, param) {
+    const json = z.toJSONSchema(z.object(inputSchema));
+    return json.properties?.[param]?.enum ?? [];
+}

package/dist/registration/screenshotResponse.js

@@ -0,0 +1,71 @@
+/**
+ * Shared response builder for screenshot tools — the one place the image-first
+ * multi-content shape lives, shared by the editor and runtime screenshot tools.
+ */
+/**
+ * Build a screenshot tool's response from the toolkit payload.
+ *
+ * When `imageBase64` is present the response is image-first: the captured image
+ * block, then a JSON metadata text block — the agent sees the picture, then the
+ * dimensions. When it is absent (a `disk`-mode capture that persisted the PNG
+ * and returned only its path), the response is a single lean text block naming
+ * the on-disk `path` — no empty image block.
+ *
+ * @param imageBase64 base64 image bytes from the toolkit (`image_base64`), or
+ *                    `undefined` for a disk-only capture that persisted the PNG.
+ * @param mimeType    image MIME type; the image block falls back to "image/png"
+ *                    when absent, and the disk text block omits it when absent.
+ * @param meta        metadata serialized into the text block. `path` is the
+ *                    saved file path (disk/both) or a node echo (inline node
+ *                    focus); `hint` is any toolkit guidance to relay; `remediation`
+ *                    names a visible side effect the toolkit took (main-screen
+ *                    switch, foregrounding); `image_detail` is the detail level the
+ *                    toolkit applied to the inline image (`full`/`mid`/`low`);
+ *                    `returned` is the returned image's `"WxH"` — for disk-only the
+ *                    full-res dims of the saved file. Both are relayed verbatim from
+ *                    the toolkit payload — this builder never recomputes dimensions.
+ *                    Undefined keys are dropped by `JSON.stringify`, so each appears
+ *                    only when present.
+ */
+export function buildScreenshotResult(imageBase64, mimeType, meta) {
+    if (imageBase64 === undefined) {
+        // Disk-only capture: the toolkit saved the PNG and returned just its path.
+        // Lean text envelope (path first — the actionable field), no image block.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        path: meta.path,
+                        width: meta.width,
+                        height: meta.height,
+                        bytes: meta.bytes,
+                        mime_type: mimeType,
+                        remediation: meta.remediation,
+                        hint: meta.hint,
+                        image_detail: meta.image_detail,
+                        returned: meta.returned,
+                    }),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            { type: "image", data: imageBase64, mimeType: mimeType ?? "image/png" },
+            {
+                type: "text",
+                text: JSON.stringify({
+                    width: meta.width,
+                    height: meta.height,
+                    bytes: meta.bytes,
+                    path: meta.path,
+                    remediation: meta.remediation,
+                    hint: meta.hint,
+                    image_detail: meta.image_detail,
+                    returned: meta.returned,
+                }),
+            },
+        ],
+    };
+}

package/dist/registration/toolDispatch.js

@@ -0,0 +1,76 @@
+/**
+ * Tool dispatch — execute ONE tool call: route it to the bridge, normalize
+ * the result into the canonical MCP error contract, and inject the
+ * happy-path success hint. The per-call primitive that registration wires
+ * every default tool's handler through; it knows nothing of registration
+ * (no version gate, path guard, or hook pipeline — those wrap the handler
+ * one layer above, in the registration core's wrappedHandler). A mid-tier module:
+ * below registration, above the error/serialization leaves.
+ */
+import { stableStringify } from "../shared/stableJson.js";
+import { BridgeError } from "../shared/errors.js";
+import { toolError, toolErrorFromPayload, toolErrorFromException, runtimeErrorWithCrashContext, } from "../shared/errorContract.js";
+/**
+ * Whether a success hint should be applied: the payload is a non-null
+ * object with no existing hint. The server never overwrites a
+ * toolkit-provided hint. Shared by both injection sites — the raw-object
+ * path in callAndWrap and the parsed-text-block path in injectSuccessHint —
+ * which keep their distinct serialization
+ * steps; only this boolean decision is unified.
+ */
+function shouldApplySuccessHint(payload) {
+    return !!payload && typeof payload === "object" && !payload.hint;
+}
+// ── Shared call wrapper ─────────────────────────────────────────────
+/**
+ * Shared handler body for tools that do a single bridge call and
+ * JSON-stringify the result. Centralises error-contract compliance:
+ *   1. Try/catch around the bridge call — BridgeError becomes toolError.
+ *   2. Result payload inspection — {success: false} becomes toolError.
+ *   3. Happy path — JSON-stringified into a text content block.
+ *
+ * Screenshots and other multi-content handlers stay custom but use
+ * toolError directly for their error branches.
+ */
+export async function callAndWrap(bridge, method, input, opts = {}) {
+    try {
+        const result = opts.runtime
+            ? await bridge.callRuntime(method, input, opts.timeoutMs, opts.signal)
+            : await bridge.call(method, input, opts.timeoutMs, opts.signal);
+        const err = toolErrorFromPayload(result);
+        if (err)
+            return err;
+        // Inject success hint if provided and toolkit didn't already set one
+        if (opts.successHint && shouldApplySuccessHint(result))
+            result.hint = opts.successHint;
+        return { content: [{ type: "text", text: stableStringify(result) }] };
+    }
+    catch (err) {
+        if (opts.runtime)
+            return runtimeErrorWithCrashContext(bridge, err);
+        if (opts.extensionTimeoutHint && err instanceof BridgeError && err.code === "TIMEOUT") {
+            return toolError("TIMEOUT", err.message, opts.extensionTimeoutHint);
+        }
+        return toolErrorFromException(err);
+    }
+}
+// ── Success-hint injection (custom-handler path) ────────────────────
+/** Inject a success hint into the first JSON text block of a ToolTextResult.
+ *  Skips if the payload already has a toolkit-provided hint. */
+export function injectSuccessHint(result, hint) {
+    for (const block of result.content) {
+        if (block.type === "text") {
+            try {
+                const payload = JSON.parse(block.text);
+                if (shouldApplySuccessHint(payload)) {
+                    payload.hint = hint;
+                    block.text = JSON.stringify(payload);
+                    return;
+                }
+            }
+            catch {
+                /* non-JSON text content — skip */
+            }
+        }
+    }
+}

package/dist/registration/toolMeta.js

@@ -0,0 +1,104 @@
+/**
+ * Tool metadata enrichment for discover_tools responses.
+ *
+ * Converts ToolDef (Zod schemas) and ExtensionCmd (raw JSON Schema) into
+ * lightweight, LLM-readable metadata objects. Used by the discover_tools
+ * handler to enrich activation responses so agents can call tools without
+ * a separate schema lookup round-trip.
+ */
+import { z } from "zod";
+// ── JSON Schema → param map (reverse of jsonSchemaToZodShape) ──────
+/**
+ * Flatten a JSON Schema properties/required structure to a simplified
+ * parameter map. Mirrors jsonSchemaToZodShape() in reverse to build the
+ * human-readable param info for discover_tools enrichment. Handles the same
+ * types as jsonSchemaToZodShape.
+ */
+export function jsonSchemaToParamMap(schema) {
+    const properties = schema.properties;
+    if (!properties)
+        return {};
+    const required = new Set(schema.required ?? []);
+    const params = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let type;
+        switch (prop.type) {
+            case "string":
+                type = Array.isArray(prop.enum) && prop.enum.length > 0 ? "enum" : "string";
+                break;
+            case "number":
+            case "integer":
+                type = "number";
+                break;
+            case "boolean":
+                type = "boolean";
+                break;
+            case "array":
+                type = "array";
+                break;
+            default:
+                type = "string";
+                break;
+        }
+        const description = typeof prop.description === "string" ? prop.description : undefined;
+        params[key] = { type, required: required.has(key), ...(description && { description }) };
+    }
+    return params;
+}
+// ── Enrichment helpers ───────────────────────────────────────────────
+/**
+ * Build a ToolMeta from a built-in ToolDef.
+ * Converts the Zod inputSchema to JSON Schema via z.toJSONSchema(),
+ * then flattens to a simplified param map.
+ */
+function enrichBuiltinTool(def, includeSchemas) {
+    const meta = { name: def.name, description: def.description };
+    if (includeSchemas) {
+        const jsonSchema = z.toJSONSchema(z.object(def.inputSchema));
+        meta.parameters = jsonSchemaToParamMap(jsonSchema);
+        if (def.annotations)
+            meta.annotations = def.annotations;
+    }
+    return meta;
+}
+/**
+ * Build a ToolMeta from an ExtensionCmd.
+ * Extension schemas are already raw JSON Schema — flatten directly.
+ */
+function enrichExtensionTool(cmd, includeSchemas) {
+    const meta = { name: cmd.toolName, description: cmd.description };
+    if (includeSchemas) {
+        meta.parameters = jsonSchemaToParamMap(cmd.inputSchema);
+        if (cmd.annotations)
+            meta.annotations = cmd.annotations;
+    }
+    return meta;
+}
+// ── Post-collection enrichment ───────────────────────────────────────
+/**
+ * Enrich group results after collection. For activated/already_loaded
+ * groups, replace bare tool names with full metadata. For available
+ * groups, tools stay as {name} only.
+ *
+ * @param results - Raw group results from the discover_tools handler (activateGroupByName / reportGroupStatusByName)
+ * @param includeSchemas - Whether to include parameters + annotations
+ * @param allDefs - Master lookup of all built-in ToolDefs by name
+ * @param extGroupCommands - Lookup of extension commands by tool name
+ */
+export function enrichGroupResults(results, includeSchemas, allDefs, extGroupCommands) {
+    for (const result of results) {
+        if (result.status !== "activated" && result.status !== "already_loaded")
+            continue;
+        result.tools = result.tools.map((tool) => {
+            const def = allDefs.get(tool.name);
+            if (def)
+                return enrichBuiltinTool(def, includeSchemas);
+            const extCmd = extGroupCommands.get(tool.name);
+            if (extCmd)
+                return enrichExtensionTool(extCmd, includeSchemas);
+            // Fallback: tool name only (shouldn't happen for loaded groups).
+            return tool;
+        });
+    }
+    return results;
+}

package/dist/registration/toolRefs.js

@@ -0,0 +1,48 @@
+/**
+ * Shared tool-ref registry. Tracks RegisteredTool refs returned by
+ * server.registerTool() so that tools can be surgically removed by
+ * name (stub->real swap in discover_tools) or bulk-removed
+ * (config reload).
+ */
+const toolRefs = new Map();
+export function setToolRef(name, ref) {
+    toolRefs.set(name, ref);
+}
+/** Update a registered tool's properties in-place (one notification). */
+export function updateToolRef(name, updates) {
+    const ref = toolRefs.get(name);
+    if (!ref?.update)
+        return false;
+    ref.update(updates);
+    return true;
+}
+export function removeToolByName(name) {
+    const ref = toolRefs.get(name);
+    if (!ref)
+        return false;
+    try {
+        ref.remove();
+    }
+    catch {
+        /* already removed */
+    }
+    toolRefs.delete(name);
+    return true;
+}
+export function removeAllToolRefs() {
+    for (const [, ref] of toolRefs) {
+        try {
+            ref.remove();
+        }
+        catch {
+            /* already removed */
+        }
+    }
+    toolRefs.clear();
+}
+export function hasToolRef(name) {
+    return toolRefs.has(name);
+}
+export function toolRefCount() {
+    return toolRefs.size;
+}