@npgamedev/godot-mcp-server 0.0.1 → 1.0.1

package/dist/groups/groupMatch.js

@@ -0,0 +1,182 @@
+/**
+ * Group keyword matching — the query → scored → dominant-filtered → capped
+ * scoring pipeline behind discover_tools' fuzzy search. Scores a keyword against
+ * every built-in group (via the GROUPS catalogue) and every extension group (via
+ * the extensionGroups accessor), applies the recall-biased dominant-match
+ * filter, and caps the fuzzy result set (3 per keyword, 5 total). Also coerces
+ * the raw request param to a string[]. Pure leaf — no SDK, no registration, no
+ * module state.
+ */
+import { GROUPS, allDefs } from "./groupCatalogue.js";
+import { extensionGroupEntries } from "./extensionGroups.js";
+import { isAllowedInReadOnly } from "../security/profiles.js";
+// ── Keyword matching ────────────────────────────────────────────────
+// Substring matching requires query.length >= 3 to avoid noisy 1-2 char
+// matches. Short domain terms ("2d", "3d", "ui", "ai") must be added as
+// explicit exact-match keywords in the group definition.
+function matchKeywords(query, keywords) {
+    let score = 0;
+    for (const kw of keywords) {
+        if (query === kw)
+            score += 3;
+        else if (query.includes(kw))
+            score += 2;
+        else if (kw.includes(query) && query.length >= 3)
+            score += 1;
+    }
+    return score;
+}
+// Score a query against a list of tool names — the loop shared by both
+// findMatchesSingle halves (built-in groups pass group.tools directly; extension
+// groups map cmd.toolName into an array). Each name is normalized "_"→space, then
+// contributes +1 to `delta` when its normalized form substring-contains the query
+// (same query.length >= 3 floor as matchKeywords) and flips `exact` on a raw- or
+// normalized-name equality. The caller adds `delta` to its running score and ORs
+// `exact` into its running flag.
+function scoreToolNameTokens(q, toolNames) {
+    let delta = 0;
+    let exact = false;
+    for (const toolName of toolNames) {
+        const norm = toolName.replace(/_/g, " ");
+        if (norm.includes(q) && q.length >= 3)
+            delta += 1;
+        if (toolName === q || norm === q)
+            exact = true;
+    }
+    return { delta, exact };
+}
+// Recall-biased dominant-match filter. A multi-word query
+// substring-matches several unrelated groups' single keywords (+2 each) while
+// the intended group scores far higher; admitting those incidental matches
+// bloats the tool context. Drop candidates below this fraction of the top score
+// — but NEVER hide a valid group (over-activation is the safe failure direction;
+// it is clearer for the LLM to receive extra groups and reset them than to have
+// a valid group withheld). Safeguards: keep top-1 always, inclusive boundary,
+// and exempt exact keyword/tool-name matches.
+const DOMINANT_MATCH_RATIO = 0.5;
+/**
+ * Score a single keyword against all groups, apply the dominant-match filter,
+ * and return surviving {name, score} sorted desc. Exported so the prune +
+ * recall-preservation guardrail is directly testable.
+ */
+export function findMatchesSingle(keyword, readOnly) {
+    const q = keyword.toLowerCase();
+    const matches = [];
+    for (const group of GROUPS) {
+        if (readOnly) {
+            const hasReadOnlyTool = group.tools.some((t) => {
+                const d = allDefs.get(t);
+                return d ? isAllowedInReadOnly(d.annotations) : false;
+            });
+            if (!hasReadOnlyTool)
+                continue;
+        }
+        let score = matchKeywords(q, group.keywords);
+        let exact = group.keywords.includes(q);
+        const toolNameScore = scoreToolNameTokens(q, group.tools);
+        score += toolNameScore.delta;
+        exact = exact || toolNameScore.exact;
+        if (score > 0)
+            matches.push({ name: group.name, score, exact });
+    }
+    for (const [name, ext] of extensionGroupEntries()) {
+        if (readOnly) {
+            const hasReadOnly = ext.commands.some((c) => isAllowedInReadOnly(c.annotations));
+            if (!hasReadOnly)
+                continue;
+        }
+        let score = 0;
+        let exact = ext.keywords.includes(q);
+        if (ext.keywords.length > 0) {
+            score += matchKeywords(q, ext.keywords);
+        }
+        const descTokens = (ext.description || name).toLowerCase().split(/\s+/);
+        for (const tok of descTokens) {
+            if (q === tok)
+                score += 2;
+            else if (tok.includes(q) && q.length >= 3)
+                score += 1;
+        }
+        const toolNameScore = scoreToolNameTokens(q, ext.commands.map((c) => c.toolName));
+        score += toolNameScore.delta;
+        exact = exact || toolNameScore.exact;
+        if (score > 0)
+            matches.push({ name, score, exact });
+    }
+    matches.sort((a, b) => b.score - a.score);
+    // Apply the dominant-match filter. matches[0] is the top score (sorted desc).
+    // Keep: the top match (i === 0), any exact match (exempt), and anything within
+    // DOMINANT_MATCH_RATIO of the top (inclusive >=). Single-keyword queries cluster
+    // within 2× so they survive intact; only the multi-word-phrase noise is pruned.
+    let kept = matches;
+    if (matches.length > 1) {
+        const cutoff = matches[0].score * DOMINANT_MATCH_RATIO;
+        kept = matches.filter((m, i) => i === 0 || m.exact || m.score >= cutoff);
+    }
+    return kept.map((m) => ({ name: m.name, score: m.score }));
+}
+const FUZZY_PER_ELEMENT_CAP = 3;
+const FUZZY_TOTAL_CAP = 5;
+/**
+ * Cap fuzzy results: 3 per keyword, 5 total.
+ * Round-robin top-1 per keyword first (each keyword gets representation),
+ * then fill remaining slots by score.
+ */
+export function capFuzzyResults(perKeyword) {
+    // Per-element cap: keep top-3 per keyword.
+    const cappedPerKeyword = new Map();
+    for (const [keyword, matches] of perKeyword) {
+        cappedPerKeyword.set(keyword, matches.slice(0, FUZZY_PER_ELEMENT_CAP));
+    }
+    // Collect all unique candidates (for counting truncation).
+    const allUnique = new Set();
+    for (const matches of perKeyword.values()) {
+        for (const m of matches)
+            allUnique.add(m.name);
+    }
+    // Round 1: top-1 per keyword (round-robin ensures each keyword gets representation).
+    const selected = new Set();
+    const selectedList = [];
+    for (const [, matches] of cappedPerKeyword) {
+        if (selectedList.length >= FUZZY_TOTAL_CAP)
+            break;
+        const best = matches.find((m) => !selected.has(m.name));
+        if (best) {
+            selected.add(best.name);
+            selectedList.push(best.name);
+        }
+    }
+    // Round 2: fill remaining from all capped matches by aggregate score.
+    const remaining = new Map();
+    for (const matches of cappedPerKeyword.values()) {
+        for (const m of matches) {
+            if (selected.has(m.name))
+                continue;
+            remaining.set(m.name, (remaining.get(m.name) ?? 0) + m.score);
+        }
+    }
+    const sorted = [...remaining.entries()].sort((a, b) => b[1] - a[1]);
+    for (const [name] of sorted) {
+        if (selectedList.length >= FUZZY_TOTAL_CAP)
+            break;
+        selected.add(name);
+        selectedList.push(name);
+    }
+    return { selected: selectedList, additionalCount: allUnique.size - selected.size };
+}
+/** Coerce request param to string[]. Handles stringified JSON arrays. */
+export function coerceRequest(raw) {
+    if (Array.isArray(raw))
+        return raw;
+    if (typeof raw === "string" && raw.startsWith("[")) {
+        try {
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed))
+                return parsed.map(String);
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return [raw];
+}

package/dist/groups/groupResult.js

@@ -0,0 +1,16 @@
+/** A freshly-activated group: tool names map to bare { name } metas. */
+export function activatedResult(name, toolNames, description) {
+    return { name, status: "activated", tools: toolNames.map((t) => ({ name: t })), description };
+}
+/** An already-loaded group (idempotent activate / status query). */
+export function alreadyLoadedResult(name, tools, description) {
+    return { name, status: "already_loaded", tools, description };
+}
+/** An available (not-yet-loaded) group carrying a description. */
+export function availableResult(name, tools, description) {
+    return { name, status: "available", tools, description };
+}
+/** The shared read-only-empty result (identical string in both built-in + ext paths). */
+export function readOnlyEmptyResult(name) {
+    return availableResult(name, [], `Group '${name}' has no tools available in read-only mode.`);
+}

package/dist/groups/groupState.js

@@ -0,0 +1,15 @@
+// ── Group-loaded session state ───────────────────────────────────────
+//
+// Leaf module (no imports) holding which on-demand tool groups have been
+// activated this session. A separate leaf so tool-def modules (e.g.
+// tools/playtest.ts) can read load state via isGroupLoaded() WITHOUT importing
+// the heavy groups.ts — which would form an import cycle once groups.ts derives
+// its tool lookup from catalogue.ts
+// (catalogue → tools/playtest → groups → catalogue). groups.ts mutates
+// `loadedGroups` directly (shared Set); it is never reassigned.
+/** Names of built-in groups activated this session (via discover_tools). */
+export const loadedGroups = new Set();
+/** Whether a built-in group has been activated this session. */
+export function isGroupLoaded(name) {
+    return loadedGroups.has(name);
+}

package/dist/groups/groupToolHandlers.js

@@ -0,0 +1,103 @@
+import { callAndWrap, injectSuccessHint } from "../registration/toolDispatch.js";
+import { toolErrorFromPayload, toolErrorFromException } from "../shared/errorContract.js";
+import { buildScreenshotResult } from "../registration/screenshotResponse.js";
+import { RUNTIME_TOOLS, LSP_TOOLS } from "./groupCatalogue.js";
+import { createLspHandler } from "../tools/lsp.js";
+// ── Special-case handlers ────────────────────────────────────────────
+// Tools with non-standard response processing. Each returns a handler
+// function matching the registerTool callback signature.
+/** signal_emit routes by channel (editor or runtime). */
+function handleSignalEmit(bridge, def) {
+    return async (input) => {
+        const parsed = input;
+        // The schema maps the hidden "game" alias to "runtime" upstream, so only
+        // "runtime" reaches here as the runtime trigger; anything else is editor.
+        const channel = parsed.channel ?? "editor";
+        const params = { node_path: parsed.node_path, signal_name: parsed.signal_name, args: parsed.args ?? [] };
+        return callAndWrap(bridge, def.method, params, { runtime: channel === "runtime" });
+    };
+}
+/**
+ * editor_screenshot returns an image block plus metadata for an inline/both
+ * capture, or a lean text-only path envelope for a disk-mode capture (PNG
+ * persisted toolkit-side, only its file path returned — no image bytes).
+ */
+function handleEditorScreenshot(bridge, def) {
+    return async (input) => {
+        try {
+            const result = await bridge.call(def.method, input ?? {});
+            const err = toolErrorFromPayload(result);
+            if (err)
+                return err;
+            const obj = result;
+            // Disk-mode capture: a saved path with no image bytes is a success, not the
+            // empty-content failure below.
+            if (obj?.path && !obj.image_base64) {
+                return buildScreenshotResult(undefined, obj.mime_type, {
+                    width: obj.width,
+                    height: obj.height,
+                    bytes: obj.bytes,
+                    path: obj.path,
+                    remediation: obj.remediation,
+                    hint: obj.hint,
+                    image_detail: obj.image_detail,
+                    returned: obj.returned,
+                });
+            }
+            if (!obj?.image_base64) {
+                return toolErrorFromPayload({
+                    success: false,
+                    code: "EMPTY_CONTENT",
+                    error: "screenshot returned no image bytes — node may lack visual content. Use editor_screenshot for full viewport.",
+                });
+            }
+            return buildScreenshotResult(obj.image_base64, obj.mime_type, {
+                width: obj.width,
+                height: obj.height,
+                bytes: obj.bytes,
+                path: obj.path,
+                remediation: obj.remediation,
+                hint: obj.hint,
+                image_detail: obj.image_detail,
+                returned: obj.returned,
+            });
+        }
+        catch (err) {
+            return toolErrorFromException(err);
+        }
+    };
+}
+// ── Handler dispatch ─────────────────────────────────────────────────
+/**
+ * Create the handler for a given tool, respecting runtime routing
+ * and special-case tools.
+ */
+export function createGroupToolHandler(bridge, def) {
+    switch (def.name) {
+        case "signal_emit":
+            return handleSignalEmit(bridge, def);
+        case "editor_screenshot":
+            return handleEditorScreenshot(bridge, def);
+        default: {
+            if (LSP_TOOLS.has(def.name)) {
+                const projectPath = process.env.GODOT_MCP_PROJECT_PATH ?? process.cwd();
+                const handler = createLspHandler(def.name, projectPath);
+                // LSP handlers own their TCP transport and never flow through callAndWrap,
+                // so their declared successHint must be injected here, matching the
+                // custom-handler wrapping registerTools does. injectSuccessHint no-ops on
+                // an error result or a payload that already carries a hint.
+                if (!def.successHint)
+                    return handler;
+                const hintText = def.successHint;
+                return async (input) => {
+                    const result = await handler(input);
+                    if (!result.isError)
+                        injectSuccessHint(result, hintText);
+                    return result;
+                };
+            }
+            const useRuntime = RUNTIME_TOOLS.has(def.name);
+            return (input) => callAndWrap(bridge, def.method, input, { runtime: useRuntime });
+        }
+    }
+}

package/dist/groups/groupTypes.js

@@ -0,0 +1,10 @@
+/**
+ * Group type leaf — the {@link GroupName} string-literal union (every built-in
+ * group's canonical name) and the {@link GroupDef} shape
+ * (name/description/tools/keywords) that each `GROUPS` entry conforms to. Pure
+ * types with zero runtime imports, so any module can depend on the group
+ * vocabulary without pulling in the catalogue data.
+ *
+ * @module
+ */
+export {};

package/dist/groups/groups.js

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import { registerToolWrapped, batchToolRegistration } from "../registration/toolRegistry.js";
+import { coercedBoolean } from "../shared/schemaCoercion.js";
+import { enrichGroupResults } from "../registration/toolMeta.js";
+import { updateToolRef, hasToolRef } from "../registration/toolRefs.js";
+// Static group catalogue (the GROUPS literal + its derived lookup/index sets)
+// and group-loaded state — both leaf modules that do NOT import groups.ts, so
+// tool-def modules never cycle back here via registration/catalogue.ts.
+// groupCatalogue.ts owns allDefs (derived from that catalogue's ALL_TOOL_DEFS).
+import { GROUPS, allDefs, GROUP_NAMES } from "./groupCatalogue.js";
+import { loadedGroups } from "./groupState.js";
+// Dynamic extension-group registry. The extensionGroups / loadedExtensionGroups
+// maps live there (private); this orchestrator touches ext state only through
+// these accessors (clearExtensionGroups on reset, reportExtGroupStatus for the
+// catalog path's ext query). Activation + deactivation live in
+// groupActivation.ts.
+import { clearExtensionGroups, extensionGroupEntries, getExtensionGroup, loadedExtensionGroupCount, reportExtGroupStatus, } from "./extensionGroups.js";
+// Keyword-scoring pipeline. findMatchesSingle scores a query against built-in +
+// extension groups; capFuzzyResults caps the fuzzy set; coerceRequest normalizes
+// the raw request param.
+import { findMatchesSingle, capFuzzyResults, coerceRequest } from "./groupMatch.js";
+// Group-activation lifecycle. registerGroupTools, the command/query split
+// (activateGroupByName / reportGroupStatusByName dispatchers over activateGroup /
+// reportGroupStatus), deactivateGroups, and buildDiscoverToolsDesc all live
+// there; the discover_tools handler below composes them. reportGroupStatus is
+// used directly by the catalog path; reportGroupStatusByName carries the
+// built-in-vs-ext query dispatch at the exact/fuzzy call sites.
+import { activateGroupByName, reportGroupStatus, reportGroupStatusByName, buildDiscoverToolsDesc, deactivateGroups, } from "./groupActivation.js";
+export { GROUPS, GROUP_TOOL_NAMES, RUNTIME_TOOLS, LSP_TOOLS } from "./groupCatalogue.js";
+export { addExtensionGroup, removeExtensionCommand, removeExtensionGroup, removeUngroupedExtensionTool, hasExtensionGroups, } from "./extensionGroups.js";
+// ── Keyword matching (re-exported from groupMatch.ts) ───────────────
+// The keyword-scoring pipeline lives in the pure leaf groupMatch.ts. Re-export
+// findMatchesSingle — it is consumed externally (groups.test.ts,
+// extensions.test.ts, §39 smoke) — so importers of groups.js get one stable
+// entry point. (capFuzzyResults / coerceRequest are export-but-internal:
+// imported above for the discover_tools handler; no barrel entry needed.)
+export { findMatchesSingle } from "./groupMatch.js";
+// loadedGroups (session group-load state) + isGroupLoaded() live in the leaf
+// module groupState.ts (imported above) — lets tool-def modules read load
+// state without importing groups.ts. resetLoadedGroups() below still clears it.
+/** Clear loaded-group tracking (used by config reload). */
+export function resetLoadedGroups() {
+    loadedGroups.clear();
+    clearExtensionGroups();
+}
+/**
+ * Register the discover_tools meta-tool and its handler.
+ * Call this during base registration. Idempotent — if the tool
+ * already exists, updates its description in-place (one notification);
+ * otherwise registers fresh (also one notification).
+ */
+export function registerGroupSystem(server, bridge, readOnly) {
+    if (hasToolRef("discover_tools")) {
+        updateToolRef("discover_tools", { description: buildDiscoverToolsDesc(bridge, readOnly) });
+        return;
+    }
+    registerToolWrapped(server, bridge, "discover_tools", {
+        description: buildDiscoverToolsDesc(bridge, readOnly),
+        inputSchema: {
+            request: z
+                .union([z.string(), z.array(z.string())])
+                .optional()
+                .describe("Names or keywords to find tool groups. Built-in: " + GROUP_NAMES.join(", ") + " (plus extension groups)."),
+            activate: z
+                .boolean()
+                .optional()
+                .describe("Auto-activate matching groups. Default true. Set false to browse without loading."),
+            include_schemas: coercedBoolean()
+                .optional()
+                .describe("Include full parameter schemas and annotations in the response. " +
+                "Default false. Only needed when you activated a group but the " +
+                "new tools are missing from your tool list."),
+            reset: z
+                .union([z.boolean(), z.array(z.string())])
+                .optional()
+                .describe("Deactivate groups. true = reset ALL on-demand groups. " +
+                'Array of group names = selectively deactivate only those groups (e.g. reset: ["tilemap", "audio"]). ' +
+                "false or omitted = keep current groups active."),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (input) => {
+        const parsed = input;
+        const activate = parsed.activate !== false;
+        const includeSchemas = parsed.include_schemas === true;
+        const requestIsEmpty = Array.isArray(parsed.request) && parsed.request.length === 0;
+        const groupResults = [];
+        const deactivated = [];
+        let fuzzyHint;
+        batchToolRegistration(server, () => {
+            // Phase 1: reset/deactivation (false is a no-op, same as omitting).
+            if (parsed.reset !== undefined && parsed.reset !== false) {
+                const names = parsed.reset === true ? true : parsed.reset;
+                deactivated.push(...deactivateGroups(names, readOnly));
+            }
+            // Phase 2: process request — exact names activate directly,
+            // unrecognized elements trigger fuzzy keyword search.
+            // Empty array is treated as "no request" (catalog trigger), not "zero elements".
+            if (parsed.request !== undefined && !requestIsEmpty) {
+                const elements = coerceRequest(parsed.request);
+                const allNames = new Set([
+                    ...GROUP_NAMES,
+                    ...[...extensionGroupEntries()].map(([name]) => name),
+                ]);
+                const exactElements = [];
+                const fuzzyElements = [];
+                for (const el of elements) {
+                    if (allNames.has(el))
+                        exactElements.push(el);
+                    else
+                        fuzzyElements.push(el);
+                }
+                // Exact matches (uncapped — agent asked for these by name).
+                for (const name of exactElements) {
+                    const result = activate
+                        ? activateGroupByName(server, bridge, name, readOnly)
+                        : reportGroupStatusByName(bridge, name, readOnly);
+                    result.match = "exact_name";
+                    groupResults.push(result);
+                }
+                // Fuzzy matches (capped: 3 per element, 5 total).
+                if (fuzzyElements.length > 0) {
+                    const perKeyword = new Map();
+                    for (const keyword of fuzzyElements) {
+                        perKeyword.set(keyword, findMatchesSingle(keyword, readOnly));
+                    }
+                    const { selected, additionalCount } = capFuzzyResults(perKeyword);
+                    for (const name of selected) {
+                        if (groupResults.some((r) => r.name === name))
+                            continue;
+                        const result = activate
+                            ? activateGroupByName(server, bridge, name, readOnly)
+                            : reportGroupStatusByName(bridge, name, readOnly);
+                        result.match = "loose_keyword";
+                        groupResults.push(result);
+                    }
+                    if (additionalCount > 0) {
+                        fuzzyHint = `${additionalCount} additional group(s) matched but were not activated — refine your request or pass exact group names.`;
+                    }
+                }
+            }
+            // Update discover_tools description inside the batch so the
+            // tools/list_changed notification fires atomically with all
+            // registrations.
+            updateToolRef("discover_tools", { description: buildDiscoverToolsDesc(bridge, readOnly) });
+        });
+        // No params (or empty array without reset) → full catalog (no activation).
+        // Empty array + reset → reset only; hint nudges a follow-up call for the catalog.
+        const catalogRequested = parsed.request === undefined || requestIsEmpty;
+        const resetActive = parsed.reset !== undefined && parsed.reset !== false;
+        if (catalogRequested && !resetActive) {
+            for (const group of GROUPS) {
+                groupResults.push(reportGroupStatus(bridge, group.name, readOnly));
+            }
+            for (const [name] of extensionGroupEntries()) {
+                groupResults.push(reportExtGroupStatus(name));
+            }
+        }
+        if (requestIsEmpty && resetActive && !fuzzyHint) {
+            fuzzyHint = "All groups have been reset. Call discover_tools() with no parameters to browse the full catalog.";
+        }
+        // Post-collection enrichment: replace bare {name} tool objects with
+        // full metadata for activated/already_loaded groups.
+        const extCmdLookup = new Map();
+        for (const [, ext] of extensionGroupEntries()) {
+            for (const cmd of ext.commands)
+                extCmdLookup.set(cmd.toolName, cmd);
+        }
+        enrichGroupResults(groupResults, includeSchemas, allDefs, extCmdLookup);
+        // Build response.
+        const response = { success: true, groups: groupResults };
+        if (fuzzyHint)
+            response.hint = fuzzyHint;
+        if (deactivated.length > 0) {
+            response.deactivated = deactivated;
+            if (parsed.reset === true)
+                response.reset_all = true;
+            const deactivatedTools = [];
+            for (const gName of deactivated) {
+                const group = GROUPS.find((g) => g.name === gName);
+                if (group)
+                    deactivatedTools.push(...group.tools);
+                const ext = getExtensionGroup(gName);
+                if (ext)
+                    deactivatedTools.push(...ext.commands.map((c) => c.toolName));
+            }
+            if (deactivatedTools.length > 0)
+                response.deactivated_tools = deactivatedTools;
+            if (!response.hint) {
+                response.hint =
+                    "Deactivated tools are no longer callable. " +
+                        "Call discover_tools(request=[...]) to re-activate before using them.";
+            }
+        }
+        // Cumulative >5 warning — checks total loaded groups across all calls.
+        const totalLoaded = loadedGroups.size + loadedExtensionGroupCount();
+        if (totalLoaded > 5) {
+            response.warning =
+                `${totalLoaded} groups currently loaded. ` +
+                    "This adds many tools to your context and may degrade response quality. " +
+                    "Prefer activating only the groups needed for your current task. " +
+                    "Use reset to deactivate groups you no longer need.";
+        }
+        return { content: [{ type: "text", text: JSON.stringify(response) }] };
+    });
+}