@satelliteoflove/godot-mcp 3.21.0 → 3.21.1

package/addon/plugin.cfg

@@ -3,6 +3,6 @@
 name="Godot MCP"
 description="Model Context Protocol server for AI assistant integration"
 author="godot-mcp"
-version="3.21.0"
+version="3.21.1"
 script="plugin.gd"
 godot_version_min="4.5"

package/dist/__tests__/core/doc-examples.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=doc-examples.test.d.ts.map

package/dist/__tests__/core/doc-examples.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-examples.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/core/doc-examples.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/core/doc-examples.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { getActionVariants, buildVariantExample, rawJsonSchema, exampleForProp, } from '../../core/doc-examples.js';
+import { sceneTools, nodeTools, editorTools, projectTools, animationTools, tilemapTools, resourceTools, scene3dTools, docsTools, inputTools, profilerTools, runtimeStateTools, gameTimeTools, execTools, } from '../../tools/index.js';
+const ALL_TOOLS = [
+    ...sceneTools,
+    ...nodeTools,
+    ...editorTools,
+    ...projectTools,
+    ...animationTools,
+    ...tilemapTools,
+    ...resourceTools,
+    ...scene3dTools,
+    ...docsTools,
+    ...inputTools,
+    ...profilerTools,
+    ...runtimeStateTools,
+    ...gameTimeTools,
+    ...execTools,
+];
+// Tool + each of its action variants, as the doc generator sees them.
+const ACTION_CASES = ALL_TOOLS.flatMap((tool) => {
+    const variants = getActionVariants(rawJsonSchema(tool));
+    return variants ? variants.map((variant) => ({ tool, variant })) : [];
+});
+function variantOf(toolName, action) {
+    const tool = ALL_TOOLS.find((t) => t.name === toolName);
+    const variant = getActionVariants(rawJsonSchema(tool)).find((v) => v.action === action);
+    return { tool, variant };
+}
+describe('generated doc examples (#287)', () => {
+    it('discovers action variants across the tool surface', () => {
+        // Guards the whole premise: if union detection regresses, every per-action
+        // doc would silently fall back to the flat path again.
+        const toolsWithActions = new Set(ACTION_CASES.map((c) => c.tool.name));
+        expect(toolsWithActions.size).toBeGreaterThanOrEqual(14);
+        expect(ACTION_CASES.length).toBeGreaterThan(50);
+    });
+    // Defect 1: every generated example must satisfy the REAL Zod schema —
+    // including discriminator-only actions, schema-required fields, and refines.
+    it.each(ACTION_CASES.map((c) => [`${c.tool.name}:${c.variant.action}`, c]))('emits a schema-valid example for %s', (_label, { tool, variant }) => {
+        const example = buildVariantExample(variant, tool.schema);
+        const result = tool.schema.safeParse(example);
+        expect(result.success, JSON.stringify(example)).toBe(true);
+    });
+    // Defect 2: each action literal's .describe() must be available to render
+    // under the action heading (no more empty Actions sections).
+    it.each(ACTION_CASES.map((c) => [`${c.tool.name}:${c.variant.action}`, c]))('carries an action description for %s', (_label, { variant }) => {
+        const desc = String(variant.properties.action?.description ?? '').trim();
+        expect(desc.length).toBeGreaterThan(0);
+    });
+    it('includes schema-required fields beyond the discriminator (exec run -> source, remove -> name)', () => {
+        const run = variantOf('godot_exec', 'run');
+        expect(buildVariantExample(run.variant, run.tool.schema)).toMatchObject({
+            action: 'run',
+            source: expect.any(String),
+        });
+        const remove = variantOf('godot_exec', 'remove');
+        expect(buildVariantExample(remove.variant, remove.tool.schema)).toMatchObject({
+            action: 'remove',
+            name: expect.any(String),
+        });
+    });
+    it('satisfies a refine that JSON Schema cannot express (watch_start needs specs or signals)', () => {
+        const { tool, variant } = variantOf('godot_runtime_state', 'watch_start');
+        const example = buildVariantExample(variant, tool.schema);
+        // Required-only would be {action} and fail the refine; augmentation must add one.
+        const hasSpecs = Array.isArray(example.specs) && example.specs.length > 0;
+        const hasSignals = Array.isArray(example.signals) && example.signals.length > 0;
+        expect(hasSpecs || hasSignals).toBe(true);
+    });
+    it('does not over-specify actions that need only the discriminator (watch_collect)', () => {
+        const { tool, variant } = variantOf('godot_runtime_state', 'watch_collect');
+        const example = buildVariantExample(variant, tool.schema);
+        expect(example).toEqual({ action: 'watch_collect' });
+    });
+    describe('exampleForProp', () => {
+        it('builds a non-empty array from its items schema', () => {
+            const val = exampleForProp('paths', { type: 'array', items: { type: 'string' } });
+            expect(val).toEqual(['example']);
+        });
+        it('builds a union-typed array entry from the first branch (input sequence entries)', () => {
+            const { tool } = variantOf('godot_input', 'sequence');
+            const example = buildVariantExample(getActionVariants(rawJsonSchema(tool)).find((v) => v.action === 'sequence'), tool.schema);
+            const inputs = example.inputs;
+            expect(Array.isArray(inputs)).toBe(true);
+            expect(inputs.length).toBeGreaterThan(0);
+            expect(inputs[0]).not.toBeNull();
+        });
+        it('respects a numeric lower bound', () => {
+            expect(exampleForProp('hz', { type: 'integer', minimum: 1 })).toBe(1);
+        });
+        it('only populates required object fields', () => {
+            const val = exampleForProp('spec', {
+                type: 'object',
+                properties: { path: { type: 'string' }, fields: { type: 'array', items: { type: 'string' } } },
+                required: ['path'],
+            });
+            expect(val).toEqual({ path: '/root/Main/Player' });
+        });
+    });
+});
+//# sourceMappingURL=doc-examples.test.js.map

package/dist/__tests__/core/doc-examples.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-examples.test.js","sourceRoot":"","sources":["../../../src/__tests__/core/doc-examples.test.ts"],"names":[],"mappings":"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"}

package/dist/core/doc-examples.d.ts

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { AnyToolDefinition } from './types.js';
+export interface ActionVariant {
+    action: string;
+    properties: Record<string, Record<string, unknown>>;
+    required: string[];
+}
+export declare function rawJsonSchema(tool: AnyToolDefinition): Record<string, unknown>;
+export declare function getActionVariants(schema: Record<string, unknown>): ActionVariant[] | null;
+export declare function exampleForProp(name: string, prop: Record<string, unknown>): unknown;
+export declare function buildVariantExample(variant: ActionVariant, toolSchema: z.ZodType): Record<string, unknown>;
+//# sourceMappingURL=doc-examples.d.ts.map

package/dist/core/doc-examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-examples.d.ts","sourceRoot":"","sources":["../../src/core/doc-examples.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAOpD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAOD,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAG9E;AAID,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,aAAa,EAAE,GAAG,IAAI,CAezF;AAwBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAuCnF;AAOD,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,UAAU,EAAE,CAAC,CAAC,OAAO,GACpB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiBzB"}

package/dist/core/doc-examples.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+// The Anthropic-shaped input schema flattens discriminated unions into a single
+// object (see core/schema.ts), which discards per-action structure. For docs we
+// want that structure back, so read the raw (un-flattened) JSON Schema, where a
+// discriminatedUnion serializes to a top-level `oneOf` of per-action branches —
+// each carrying its own `required` list and the action literal's `.describe()`.
+export function rawJsonSchema(tool) {
+    const { $schema, ...rest } = z.toJSONSchema(tool.schema, { target: 'draft-07' });
+    return rest;
+}
+// Discriminated-union schemas serialize to oneOf (one object variant per
+// action). Pull each variant's action literal, properties, and required list.
+export function getActionVariants(schema) {
+    const branches = (schema.oneOf || schema.anyOf);
+    if (!Array.isArray(branches))
+        return null;
+    const variants = [];
+    for (const branch of branches) {
+        const properties = branch.properties || {};
+        const actionProp = properties.action;
+        const action = actionProp?.const ??
+            (Array.isArray(actionProp?.enum) ? actionProp.enum[0] : undefined);
+        if (action === undefined)
+            continue;
+        variants.push({ action, properties, required: branch.required || [] });
+    }
+    return variants.length > 0 ? variants : null;
+}
+// Representative values for well-known parameter names, so generated examples
+// read like real calls rather than `"example"` placeholders.
+const NAMED_EXAMPLES = {
+    node_path: '/root/Main/Player',
+    parent_path: '/root/Main',
+    new_parent_path: '/root/UI',
+    scene_path: 'res://scenes/enemy.tscn',
+    script_path: 'res://scripts/player.gd',
+    resource_path: 'res://resources/spriteframes.tres',
+    animation_name: 'idle',
+    node_name: 'NewNode',
+    node_type: 'Sprite2D',
+    name_pattern: '*Enemy*',
+    type: 'CharacterBody2D',
+    root_path: '/root/Main',
+    path: '/root/Main/Player',
+    signal: 'body_entered',
+};
+// Build a representative, schema-VALID value for one JSON-Schema property.
+// Recurses through arrays/objects/unions and produces NON-EMPTY arrays +
+// populated required object fields, so min-length / nested-required constraints hold.
+export function exampleForProp(name, prop) {
+    if (prop.const !== undefined)
+        return prop.const;
+    if (Array.isArray(prop.enum))
+        return prop.enum[0];
+    if (name in NAMED_EXAMPLES)
+        return NAMED_EXAMPLES[name];
+    // A prop that is itself a union (z.union / z.discriminatedUnion serialize to
+    // anyOf / oneOf — e.g. the input `sequence` entry shapes): build the first branch.
+    const branches = (prop.oneOf ?? prop.anyOf ?? prop.allOf);
+    if (Array.isArray(branches) && branches.length > 0) {
+        return exampleForProp(name, branches[0]);
+    }
+    switch (prop.type) {
+        case 'string':
+            return 'example';
+        case 'integer':
+        case 'number':
+            // Respect a lower bound so .min(n) constraints aren't violated.
+            return typeof prop.minimum === 'number' ? prop.minimum : 0;
+        case 'boolean':
+            return false;
+        case 'array': {
+            const items = prop.items;
+            // One representative element: keeps arrays non-empty so a length-based
+            // refine (e.g. watch_start's specs/signals) is satisfied.
+            return items ? [exampleForProp(name, items)] : [];
+        }
+        case 'object': {
+            const props = prop.properties || {};
+            const req = prop.required || [];
+            const obj = {};
+            for (const key of Object.keys(props)) {
+                if (req.includes(key))
+                    obj[key] = exampleForProp(key, props[key]);
+            }
+            return obj;
+        }
+        default:
+            return null;
+    }
+}
+// A copy-pasteable example for one action: the discriminator plus every
+// schema-required field. JSON Schema can't express cross-field refinements
+// (e.g. watch_start requires specs OR signals), so if the required-only example
+// fails the REAL Zod schema, add optional fields one at a time until it
+// validates — keeping the minimal field that unblocks it (#287).
+export function buildVariantExample(variant, toolSchema) {
+    const example = { action: variant.action };
+    for (const name of variant.required) {
+        if (name === 'action')
+            continue;
+        example[name] = exampleForProp(name, variant.properties[name]);
+    }
+    if (!toolSchema.safeParse(example).success) {
+        for (const [name, prop] of Object.entries(variant.properties)) {
+            if (name === 'action' || name in example)
+                continue;
+            example[name] = exampleForProp(name, prop);
+            if (toolSchema.safeParse(example).success)
+                break;
+            delete example[name]; // this field didn't unblock it — don't over-specify
+        }
+    }
+    return example;
+}
+//# sourceMappingURL=doc-examples.js.map

package/dist/core/doc-examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-examples.js","sourceRoot":"","sources":["../../src/core/doc-examples.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@satelliteoflove/godot-mcp",
-  "version": "3.21.0",
+  "version": "3.21.1",
   "description": "MCP server for Godot Engine integration",
   "type": "module",
   "main": "dist/index.js",