summer-engine 2.8.2 → 3.0.0

package/dist/mcp/tools/scene-tools.js

@@ -1,102 +1,12 @@
 import { z } from "zod";
-import { withEngine, extractOpError } from "./with-engine.js";
-// Engine ops that MUST be dispatched as their own single-op request. Mirrors
-// _summer_requires_single_async_dispatch (local_api_server.cpp, engine 0.5.60+):
-// the engine rejects any multi-op batch containing one of these WHOLESALE —
-// nothing in the batch executes, and the batch fails with per-op
-// failure_reason "unsupported_transport"/"skipped". Git ops are covered by the
-// prefix check below.
-const SINGLE_ONLY_OPS = new Set([
-    "SaveScene", "InstantiateScene", "ReplaceNode",
-    "SimulateInput", "ViewportSnapshot", "GameSnapshot",
-    "RunCommand", "RunVerification", "RunEditorScript",
-    "ImportFromUrl", "ImportFromUrlBatch", "ExtractZipFromUrl",
-]);
-function isSingleOnlyOp(kind) {
-    return SINGLE_ONLY_OPS.has(kind) || kind.startsWith("Git");
-}
-function sceneMutationOps(ops) {
-    const saveIndexes = ops
-        .map((op, index) => op.op === "SaveScene" ? index : -1)
-        .filter((index) => index >= 0);
-    if (saveIndexes.length > 1) {
-        throw new Error("A scene mutation batch may contain only one SaveScene");
-    }
-    if (saveIndexes.length === 1) {
-        if (saveIndexes[0] !== ops.length - 1) {
-            throw new Error("SaveScene must be the final operation in a scene mutation batch");
-        }
-        return ops;
-    }
-    return [...ops, { op: "SaveScene" }];
-}
-/** Split an op list into sequential engine requests: consecutive batchable ops
- *  stay grouped, each single-only op becomes its own request. Order preserved. */
-function chunkOpsForDispatch(ops) {
-    const chunks = [];
-    let current = [];
-    for (const op of ops) {
-        if (isSingleOnlyOp(String(op.op ?? ""))) {
-            if (current.length > 0) {
-                chunks.push(current);
-                current = [];
-            }
-            chunks.push([op]);
-        }
-        else {
-            current.push(op);
-        }
-    }
-    if (current.length > 0)
-        chunks.push(current);
-    return chunks;
-}
-/** Execute an op list as sequential engine requests honoring the single-op
- *  dispatch contract. Receipts from every request are preserved and merged, so
- *  an op that applied followed by one that failed is reported honestly instead
- *  of masked. */
-async function executeOpsChunked(send, ops) {
-    const chunks = chunkOpsForDispatch(ops);
-    if (chunks.length === 1)
-        return send(chunks[0]);
-    const receipts = [];
-    const combinedResults = [];
-    for (let i = 0; i < chunks.length; i++) {
-        const receipt = await send(chunks[i]);
-        receipts.push(receipt);
-        const envelope = (receipt ?? {});
-        if (Array.isArray(envelope.results)) {
-            combinedResults.push(...envelope.results);
-        }
-        if (extractOpError(receipt)) {
-            const failedKind = String(chunks[i][0]?.op ?? "batch");
-            const appliedOps = chunks.slice(0, i).flat().map((op) => String(op.op ?? ""));
-            const notSent = chunks.slice(i + 1).flat().map((op) => String(op.op ?? ""));
-            const baseError = (typeof envelope.error === "string" && envelope.error) || `Engine request failed (${failedKind}).`;
-            const honestError = appliedOps.length > 0
-                ? `${baseError} NOTE: ${appliedOps.length} earlier op(s) already applied (${appliedOps.join(", ")})` +
-                    (failedKind === "SaveScene"
-                        ? " — the scene is modified in the editor but NOT saved to disk. Fix the problem, then call summer_save_scene."
-                        : ".") +
-                    (notSent.length > 0 ? ` Not sent: ${notSent.join(", ")}.` : "")
-                : baseError;
-            return {
-                ...envelope,
-                error: honestError,
-                results: combinedResults,
-                receipts,
-            };
-        }
-    }
-    const last = (receipts[receipts.length - 1] ?? {});
-    return { ...last, results: combinedResults, requests: chunks.length, receipts };
-}
-/** Scene mutation entry point: appends the transaction-boundary SaveScene, then
- *  dispatches with the single-op contract (mutations batch together, SaveScene
- *  and other single-only ops travel alone). */
-function executeSceneMutation(client, scenePath, ops, options) {
-    return executeOpsChunked((chunk) => client.executeIdentityBoundOps(chunk, { ...(options ?? {}), scenePath }), sceneMutationOps(ops));
-}
+import { withEngine, ToolInputError } from "./with-engine.js";
+import { executeOpsChunked, executeSceneMutation } from "../../core/capabilities/engine-ops.js";
+import { annotateVariantTypes } from "../../core/capabilities/variant-types.js";
+import { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps, } from "../../core/capability-skew.js";
+// Re-exported for tests and for callers that reason about dispatch classes.
+// executeSceneMutation is the ONE copy in core/capabilities/engine-ops.ts,
+// re-exported here for the spatial tools (snap / align).
+export { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps, executeSceneMutation };
 function requireSuccessfulOps(result, context) {
     const receipt = (result ?? {});
     const results = Array.isArray(receipt.results)
@@ -144,16 +54,16 @@ Recommended workflow:
     }, async ({ path, rootName, rootType }) => withEngine(async (client) => {
         const safePath = path.trim().replace(/\\/g, "/");
         if (!safePath.startsWith("res://") || safePath.includes("..")) {
-            throw new Error("Scene path must be a traversal-free res:// project path.");
+            throw new ToolInputError("Scene path must be a traversal-free res:// project path.");
         }
         if (!safePath.endsWith(".tscn")) {
-            throw new Error("New scenes must use the text format: the path must end in .tscn.");
+            throw new ToolInputError("New scenes must use the text format: the path must end in .tscn.");
         }
         if (!VALID_ROOT_NAME.test(rootName)) {
-            throw new Error(`Invalid rootName "${rootName}": use letters, digits, underscores, hyphens, or spaces, starting with a letter or underscore.`);
+            throw new ToolInputError(`Invalid rootName "${rootName}": use letters, digits, underscores, hyphens, or spaces, starting with a letter or underscore.`);
         }
         if (!VALID_ROOT_TYPE.test(rootType)) {
-            throw new Error(`Invalid rootType "${rootType}": must be a plain class name like 'Node3D', 'Node2D', or 'Control'.`);
+            throw new ToolInputError(`Invalid rootType "${rootType}": must be a plain class name like 'Node3D', 'Node2D', or 'Control'.`);
         }
         // Same engine-routed guarded write path summer_write_file uses:
         // identity-bound, and mustNotExist makes the engine refuse (create-only)
@@ -282,16 +192,40 @@ Do not guess paths. Prefer:
 - Add a .glb/.gltf 3D model into the scene
 - Compose scenes from smaller scenes (e.g., add a "Player" scene into a "Level" scene)
 
-The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.`, {
+The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.
+
+PASS target_size FOR IMPORTED MODELS. Downloaded/generated .glb assets arrive at arbitrary scale (a "chair" can be 40 units tall). target_size uniformly scales the instanced subtree so its largest world-AABB dimension equals that many units — commit to real-world size: chair 1.0, door 2.0, car 4.5, person 1.7, tree 6-10. The result then reports dimensions + scale_applied; verify placement afterwards (summer_world_snapshot AABBs, summer_screenshot). Older engine builds ignore target_size — when the result lacks scale_applied, this tool appends a note and you must scale the node yourself (summer_set_prop scale) and re-check.`, {
         scenePath: z.string().describe("Target scene to receive the instance, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World'"),
         scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
         name: z.string().optional().describe("Override the instance name"),
-    }, async ({ scenePath, parent, scene, name }) => withEngine(async (client) => {
+        target_size: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Normalize the instance's physical size: uniformly scale it so its largest world-AABB dimension equals this many units (chair 1.0, car 4.5, person 1.7). Strongly recommended for imported .glb/.gltf models."),
+    }, async ({ scenePath, parent, scene, name, target_size }) => withEngine(async (client) => {
         const op = { op: "InstantiateScene", parent, scene };
         if (name)
             op.name = name;
-        return executeSceneMutation(client, scenePath, [op]);
+        if (target_size !== undefined)
+            op.target_size = target_size;
+        const result = await executeSceneMutation(client, scenePath, [op]);
+        // An older engine applies the op but silently drops target_size — its
+        // receipt then lacks scale_applied. Confess that instead of letting a
+        // 40-unit "chair" pass as normalized.
+        if (target_size !== undefined && result && typeof result === "object") {
+            const envelope = result;
+            const instanced = envelope.results?.find((entry) => entry.op === "InstantiateScene" && entry.ok === true);
+            if (instanced && !("scale_applied" in instanced)) {
+                return {
+                    ...envelope,
+                    target_size_note: `This Summer Engine build IGNORED target_size (no scale_applied in the receipt) — the instance is at the asset's raw scale, NOT normalized to ${target_size}. ` +
+                        "Scale it yourself (summer_set_prop scale, or ctx code in summer_run_script), verify with summer_world_snapshot/summer_screenshot, or update Summer Engine.",
+                };
+            }
+        }
+        return result;
     }));
     server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
 
@@ -335,19 +269,23 @@ The receiver node must have a script with the specified method.`, {
     }));
     server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
 
-Call this before modifying a node to understand its current state. Returns every property the Godot inspector would show.
+Call this before modifying a node to understand its current state. Returns every property the Godot inspector would show. Each prop carries the engine's raw Variant.Type integer as "type" plus its name as "type_name" (e.g. type 5 = TYPE_VECTOR2, 20 = TYPE_COLOR, 24 = TYPE_OBJECT); resource-valued props also carry resource_type / resource_path.
+
+Reads the currently OPEN scene — "path" is relative to its root (there is no scenePath argument; open the scene first if needed).
 
 Example: inspect a light to see its energy, color, shadow settings before changing them.`, {
         path: z.string().describe("Node path from scene tree, e.g. 'Player', 'World/Enemies/Boss', 'DirectionalLight3D'"),
-    }, async ({ path }) => withEngine(async (client) => client.inspectNode(path)));
+    }, async ({ path }) => 
+    // E2E 2026-09-03 F-14: the engine returns Variant.Type as a bare int.
+    withEngine(async (client) => annotateVariantTypes(await client.inspectNode(path))));
     server.tool("summer_inspect_resource", `Get all properties of a resource (material, mesh, shape, environment, etc).
 
 Use when you need the sub-properties of a resource attached to a node. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material — this tool tells you that material's albedo_color, metallic, roughness, etc.`, {
         path: z.string().describe("Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'"),
     }, async ({ path }) => withEngine(async (client) => client.inspectResource(path)));
-    server.tool("summer_batch", `Execute multiple operations in a single call, grouped into one undo step. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
+    server.tool("summer_batch", `Execute multiple operations in a single call. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
 
-The user can undo everything with a single Ctrl+Z. Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
+UNDO: when nothing in the list forces a split (see the single-op contract below), the whole batch is ONE undo step — the user undoes everything with a single Ctrl+Z. When single-only ops are present the list is split into sequential requests and EACH chunk is its own undo step (one Ctrl+Z per chunk; the receipt shows the chunks). Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
 
 Each op in the array uses the same format as the individual tools:
 - {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
@@ -363,11 +301,12 @@ Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action
 send it separately. scenePath selects every mutation target. The tool appends one
 final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
 must appear exactly once and be the final operation. The engine requires
-SaveScene, InstantiateScene, ReplaceNode, SimulateInput, and the Run*/Import*
+SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads
+(GetRuntimeSceneTree/GetRuntimeNode), and the Run*/Import*
 ops to travel as their own request, so this tool automatically splits your op
 list into sequential requests around them — each split chunk is its own undo
-step, and if a later chunk fails the receipt reports exactly which earlier ops
-already applied.`, {
+step (NOT one step for the whole batch), and if a later chunk fails the receipt
+reports exactly which earlier ops already applied.`, {
         scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
     }, async ({ scenePath, ops }) => withEngine(async (client) => {
@@ -376,21 +315,31 @@ already applied.`, {
             return kind === "WriteFile" || kind === "ReplaceText";
         });
         if (rawFileMutation) {
-            throw new Error(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
+            throw new ToolInputError(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
                 "Use summer_write_file or summer_replace_text so project identity, content guards, and same-file ordering are enforced.");
         }
         const sceneMutations = new Set([
             "AddNode", "RemoveNode", "MoveNode", "ReparentNode", "ReplaceNode",
             "SetProp", "SetResourceProperty", "ConnectSignal", "DisconnectSignal",
-            "InstantiateScene", "SaveScene", "Undo",
+            "InstantiateScene", "SaveScene", "SnapToSurface", "AlignDistribute3D", "Undo",
         ]);
-        const needsScenePath = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
+        // Read-only spatial queries target an exact scene (identity-bound) but
+        // never save — no SaveScene is appended for them.
+        const sceneQueries = new Set([
+            "TestPlacement3D", "NavigationProbe3D", "Starcast3D",
+        ]);
+        const containsMutation = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
+        const needsScenePath = containsMutation ||
+            ops.some((op) => sceneQueries.has(String(op.op ?? "")));
         if (needsScenePath && !scenePath) {
-            throw new Error("summer_batch requires scenePath when ops contains scene mutations");
+            throw new ToolInputError("summer_batch requires scenePath when ops targets a scene");
         }
         const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
-        return needsScenePath
-            ? executeSceneMutation(client, scenePath, ops, options)
-            : executeOpsChunked((chunk) => client.executeOps(chunk, options), ops);
+        if (containsMutation) {
+            return executeSceneMutation(client, scenePath, ops, options);
+        }
+        return executeOpsChunked((chunk) => needsScenePath
+            ? client.executeIdentityBoundOps(chunk, options)
+            : client.executeOps(chunk, options), ops, resolveSingleOnlyOps(client));
     }));
 }

package/dist/mcp/tools/script-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export { API_DOCS_NOT_INSTALLED, isApiDocsBundleInstalled, lookupApiDocs, resetApiDocsForTests, } from "../../core/capabilities/api-docs.js";
+export declare function registerScriptTools(server: McpServer): void;

package/dist/mcp/tools/script-tools.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { lookupApiDocs } from "../../core/capabilities/api-docs.js";
+import { RUN_EDITOR_SCRIPT_FALLBACK, RUN_SCRIPT_FALLBACK, buildRunEditorScriptOp, buildRunSceneScriptOp, } from "../../core/capabilities/scene-script.js";
+// Re-exported so existing tests keep importing the lookup from the tool module.
+export { API_DOCS_NOT_INSTALLED, isApiDocsBundleInstalled, lookupApiDocs, resetApiDocsForTests, } from "../../core/capabilities/api-docs.js";
+export function registerScriptTools(server) {
+    server.tool("summer_run_script", `Run a GDScript snippet INSIDE the live editor, against the currently OPEN scene. This is the scene-scripting workhorse: one script replaces long chains of add-node/set-prop calls, and it can compute (loops, randomness, math, procedural meshes) what individual CRUD ops cannot.
+
+SCRIPT CONTRACT — write ONLY the body below; do not add extends/@tool lines (missing ones are prepended and reported in 'normalizations'):
+
+  func run(ctx):
+      var root = ctx.get_scene_root()    # root node of the open scene
+      for i in range(10):
+          var m := MeshInstance3D.new()
+          m.mesh = BoxMesh.new()
+          m.position = Vector3(i * 2, 0, 0)
+          root.add_child(m)
+          ctx.set_owner_recursive(m)     # REQUIRED or the node is NOT saved
+      ctx.report("count", 10)            # structured value back to you
+
+- ctx.get_scene_root() — the open scene's root node. Full editor API access.
+- ctx.set_owner_recursive(node) — stamps node AND its descendants with the scene-root owner (equivalent to node.owner = root on each). Call it after add_child on every created subtree.
+- ctx.report(key, value) — return structured results (comes back in 'reports').
+- print(...) — captured and returned in 'output'.
+- OWNERSHIP: a created node whose owner is never set silently vanishes when the scene saves — descendants too. ctx.set_owner_recursive covers both.
+- Values here are real GDScript — Vector3(0,10,0), Color(1,0,0,1) — NOT the quoted variant strings used by summer_set_prop.
+
+Newer ctx builds also carry creation helpers that set the owner FOR you and return the node — prefer them: ctx.add_node(type, name, parent, props), ctx.find(name), ctx.get_or_create(type, name, parent), ctx.instance_scene(res_path, parent, name), ctx.add_mesh(shape, name, parent, props) / ctx.add_mesh_with_collision(...), ctx.mesh_from_arrays(...), ctx.make_material(props) / ctx.apply_material(node, material), ctx.grid(count_x, count_z, spacing, maker) / ctx.scatter(area, count, maker, seed), ctx.add_light_rig(target), ctx.ensure_environment(props), ctx.add_camera(position, look_at, make_current), ctx.summary(), ctx.save_scene(path). Unknown props keys are reported in 'prop_warnings', never silently dropped. On an older engine a missing helper is a plain GDScript error — fall back to the manual form above.
+
+WHEN TO USE: 3+ related ops, anything with computed placement (scatter, grids, rings), procedural geometry (SurfaceTool/ArrayMesh), bulk renames/retunes. For a single property tweak, summer_set_prop is cheaper. Use summer_api_docs to verify property/method names instead of guessing.
+
+THE LOOP: summer_world_snapshot (keep snapshot_id) -> summer_run_script -> summer_snapshot_diff + summer_screenshot -> inspect -> iterate. Never claim visual success without the screenshot.
+
+Returns {ok, ran, result, reports, output, errors, duration_ms, checkpoint} — newer engines add rolled_back (a runtime error rolled the whole undo action back; the scene is untouched) and budget_enforced (max_seconds was a HARD deadline; when the budget hits, the script errors with "Summer script budget exceeded" — split the work into smaller scripts, never resubmit the same oversized one). Read 'errors' even when ok — with undo:'none', a partially-failed script may have mutated the scene. If this engine build predates RunSceneScript, the result is a structured engine_lacks_op failure (nothing is sent): use summer_run_editor_script or update Summer Engine.`, {
+        source: z.string().describe("GDScript source containing `func run(ctx):`. No extends/@tool line — just the function (plus any helpers)."),
+        max_seconds: z
+            .number()
+            .optional()
+            .describe("Time budget in seconds (default 20, clamped 5-120). The script blocks the editor while it runs — keep it short."),
+        checkpoint: z
+            .boolean()
+            .optional()
+            .describe("Take a SummerGit checkpoint before running (default true). The result confesses (no_rewind_point) when no checkpoint could be taken."),
+        undo: z
+            .enum(["action", "none"])
+            .optional()
+            .describe("Transaction mode (newer engines). 'action' (engine default): the whole run is ONE named undo action, and a mid-script runtime error rolls it back before returning (result rolled_back:true) — no half-mutated scene. 'none': v1 behavior, checkpoint only. Older engines ignore this."),
+    }, async ({ source, max_seconds, checkpoint, undo }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "RunSceneScript", RUN_SCRIPT_FALLBACK);
+        if (missing)
+            return missing;
+        const { op, timeoutMs } = buildRunSceneScriptOp({ source, max_seconds, checkpoint, undo });
+        const result = await client.executeIdentityBoundOps([op], undefined, timeoutMs);
+        return withOldEngineHint(result, "RunSceneScript", "use summer_run_editor_script instead");
+    }));
+    server.tool("summer_run_editor_script", `Run a GDScript EditorScript in a FRESH HEADLESS editor spawned against the ON-DISK project. Cold path: a whole child editor boots, runs your script once, and exits — seconds to tens of seconds depending on the project and the script (about 2 s end to end on a small template project; large projects can spend 30 s+ just booting).
+
+USE FOR batch/project-wide jobs that should not block the live editor: re-saving many scenes, sweeping resources, mass import fixes, generating .tres assets, long bakes. It sees ONLY what is saved on disk — unsaved live edits in the open editor are INVISIBLE to it, and the live editor won't show its output until files reload. For work on the OPEN scene, use summer_run_script instead.
+
+SCRIPT CONTRACT — write a plain EditorScript body:
+
+  func _run():
+      var scene = load("res://main.tscn").instantiate()
+      # ... work ...
+      print("done")  # captured into output[]
+
+You may omit the '@tool' and 'extends EditorScript' lines — the engine prepends any that are missing and reports each fix in 'normalizations' (with 'line_offset' so error line numbers map back to your source). Including 'extends EditorScript' yourself is also fine.
+
+Returns {ok, ran, exit_code, output, errors, boot_errors, result, out_dir, checkpoint, normalizations} plus a failure_reason taxonomy on failure (script_parse_failed, timeout, spawn_failed, ...). A top-level no_rewind_point:true means no pre-run checkpoint exists — the run is NOT rewindable; tell the user before doing more destructive work. This headless child has NO renderer: screenshots/pixels are impossible here (see the headless-scripting skill).`, {
+        source: z.string().describe("EditorScript GDScript source with `func _run():`. '@tool' / 'extends EditorScript' are optional — missing lines are prepended and reported in normalizations."),
+        max_seconds: z
+            .number()
+            .optional()
+            .describe("Time budget in seconds for the child editor (default 120, clamped 15-600). Include boot time — large projects can take 30s+ just to start."),
+        checkpoint: z
+            .boolean()
+            .optional()
+            .describe("Take a SummerGit checkpoint before the child editor runs. The result confesses (no_rewind_point) when none could be taken."),
+    }, async ({ source, max_seconds, checkpoint }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "RunEditorScript", RUN_EDITOR_SCRIPT_FALLBACK);
+        if (missing)
+            return missing;
+        const { op, timeoutMs } = buildRunEditorScriptOp({ source, max_seconds, checkpoint });
+        return client.executeIdentityBoundOps([op], undefined, timeoutMs);
+    }));
+    server.tool("summer_api_docs", `Offline engine class-reference lookup — verify a property, method, signal, or constant BEFORE writing script code, instead of guessing names. No engine connection needed.
+
+Returns for a class: inherits, brief description, properties (name/type/default), method signatures, signals, constants. Pass 'member' to fetch one member (e.g. class_name:'BoxShape3D', member:'size' -> {name:'size', type:'Vector3', default:'Vector3(1, 1, 1)'}). Unknown names return closest-match suggestions.
+
+Entries list only members DECLARED on that class — walk 'inherits' for inherited ones (e.g. 'position' lives on Node3D, not MeshInstance3D). Data is compiled from the engine's class reference and stamped with the engine technical base it was generated from (technical_base in every successful result) — trust it over training memory for version-sensitive APIs; descriptions are trimmed to one line. When the bundled reference is missing from this install, the result says so (api_docs_not_installed) instead of guessing.`, {
+        class_name: z.string().describe("Engine class name, e.g. 'BoxShape3D', 'CharacterBody3D', 'SurfaceTool'. Case-insensitive."),
+        member: z
+            .string()
+            .optional()
+            .describe("Optional property/method/signal/constant name to fetch just that member, e.g. 'size' or 'move_and_slide'."),
+    }, async ({ class_name, member }) => {
+        try {
+            const result = lookupApiDocs(class_name, member);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                ...(result.ok === false ? { isError: true } : {}),
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Could not load the bundled api-docs asset (${message}). Reinstall/update the summer-engine package.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/mcp/tools/spatial-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSpatialTools(server: McpServer): void;