ultimate-unreal-engine-mcp 0.1.23 → 0.1.24

package/README.md

@@ -1,12 +1,12 @@
 # Ultimate Unreal Engine MCP
 
-**132 tools. 26 domains. Full read/write access to Unreal Engine 5.7 — including live editor APIs, Blueprint graphs, and viewport screenshots.**
+**133 tools. 26 domains. Full read/write access to Unreal Engine 5.7 — including live editor APIs, Blueprint graphs, and viewport screenshots.**
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Node 22+](https://img.shields.io/badge/Node.js-22%2B-brightgreen.svg)](https://nodejs.org/)
 [![UE 5.7](https://img.shields.io/badge/Unreal%20Engine-5.7-orange.svg)](https://www.unrealengine.com/)
 [![Tests](https://img.shields.io/badge/tests-1021%20passing-success.svg)](#development)
-[![Tools](https://img.shields.io/badge/tools-132-informational.svg)](#tool-catalog)
+[![Tools](https://img.shields.io/badge/tools-133-informational.svg)](#tool-catalog)
 
 MCP (Model Context Protocol) is a standard that lets AI assistants call tools on external systems — this server exposes Unreal Engine as those tools.
 
@@ -52,7 +52,7 @@ npx ultimate-unreal-engine-mcp setup --project "C:/MyGame"
 
 This command writes the correct config for your client. The C++ plugin is optional — file-system tools (C++ parsing, code gen, configs, builds, docs) work without it. Install the plugin for live editor tools (Blueprints, actors, viewport, screenshots).
 
-> **Zero optional dependencies.** The C++ plugin compiles on any UE 5.7 install — binary or source. All 129 tools use runtime reflection for optional UE modules (MetaSound, LiveLink, GAS, etc.), so the plugin loads regardless of which plugins your project has enabled. Handlers gracefully report when their target module isn't available.
+> **Zero optional dependencies.** The C++ plugin compiles on any UE 5.7 install — binary or source. All 133 tools use runtime reflection for optional UE modules (MetaSound, LiveLink, GAS, etc.), so the plugin loads regardless of which plugins your project has enabled. Handlers gracefully report when their target module isn't available.
 
 ---
 
@@ -546,7 +546,7 @@ ue_cleanup_screenshots(confirm=true)
 
 ## Automatic Self-Verification
 
-Every mutating tool description includes **mandatory verification guidance** — the AI is instructed to verify its own work before reporting success. This isn't a suggestion; it's baked into the tool interface.
+Verification isn't a suggestion. It's **server-side enforced**. Every mutating tool automatically queries `actor.componentBounds` after the mutation completes and appends the verification data to the response. The AI sees bounds, positions, and component state in the same tool call result, whether it asked for it or not. If something is wrong, the data is right there and impossible to miss.
 
 **Why this matters:** In spatial work (placing doors, aligning meshes, wiring components), a single transform can have cascading effects — rotating a mesh around a pivot shifts its world position, negative scale flips face normals making geometry invisible, collision volumes don't automatically follow mesh offsets. Without verification, the AI reports "done" while the door is floating 2 meters from the wall.
 
@@ -554,24 +554,18 @@ Every mutating tool description includes **mandatory verification guidance** —
 
 ```
 ue_spawn_actor("BP_Door", location={x:1040, y:150, z:0})
-  → Actor spawned
-
-ue_get_component_bounds("BP_Door", component="DoorMesh")     ← automatic
-  → bounds: X=[806, 994] ✓ — in the doorway
+  → {actor_label: "BP_Door", _verification: {bounds: {min: {x:806}, max: {x:994}}}}
+  ← bounds auto-appended by server — in the doorway ✓
 
 ue_set_actor_property("BP_Door", "DoorMesh.RelativeRotation", ...)
-  → Property set
-
-ue_get_component_bounds("BP_Door", component="DoorMesh")     ← automatic
-  → bounds: X=[1040, 1228] ✗ — rotation shifted mesh out of gap
-
-ue_set_actor_property("BP_Door", "DoorMesh.RelativeLocation", ...)   ← self-correction
-  → Offset compensated
+  → {success: true, _verification: {bounds: {min: {x:1040}, max: {x:1228}}}}
+  ← bounds shifted! rotation moved mesh out of gap ✗
 
-ue_get_component_bounds("BP_Door", component="DoorMesh")     ← re-verify
-  → bounds: X=[806, 994] ✓ — back in place
+ue_set_actor_property("BP_Door", "DoorMesh.RelativeLocation", ...)
+  → {success: true, _verification: {bounds: {min: {x:806}, max: {x:994}}}}
+  ← back in place after offset compensation ✓
 
-ue_look_at("BP_Door", angle="front")                          ← visual confirm
+ue_look_at("BP_Door", angle="front")
   → [screenshot inline] door visible, handle correct side ✓
 ```
 

package/dist/tools/editor/index.js

@@ -43,6 +43,39 @@ async function sendOrDisconnect(bridge, cmd) {
     }
 }
 // ---------------------------------------------------------------------------
+// autoVerifyBounds helper
+// ---------------------------------------------------------------------------
+/**
+ * Queries actor.componentBounds after a mutation and appends verification
+ * data to the original result. If the verification call fails, the original
+ * result is returned unmodified (verification is best-effort).
+ */
+async function autoVerifyBounds(bridge, actorLabel, originalResult) {
+    // Don't verify if the original command failed
+    if (originalResult.isError)
+        return originalResult;
+    try {
+        const verifyResponse = await bridge.sendCommand({
+            type: 'actor.componentBounds',
+            payload: { actor_label: actorLabel },
+            correlationId: '',
+        });
+        const verifyData = verifyResponse.success
+            ? { _verification: { actor_label: actorLabel, bounds: verifyResponse.data } }
+            : { _verification: { actor_label: actorLabel, error: verifyResponse.error } };
+        return {
+            content: [
+                ...originalResult.content,
+                { type: 'text', text: JSON.stringify(verifyData) },
+            ],
+        };
+    }
+    catch {
+        // Verification is best-effort; don't break the original result
+        return originalResult;
+    }
+}
+// ---------------------------------------------------------------------------
 // registerEditorTools
 // ---------------------------------------------------------------------------
 /**
@@ -104,10 +137,22 @@ export function registerEditorTools(server, bridge) {
         if (args.label) {
             payload['label'] = args.label;
         }
-        return sendOrDisconnect(_bridge, {
+        const result = await sendOrDisconnect(_bridge, {
             type: 'actor.spawn',
             payload,
         });
+        // Auto-verify: query bounds of the spawned actor
+        const label = args.label ?? (result.content?.[0] && 'text' in result.content[0]
+            ? (() => { try {
+                return JSON.parse(result.content[0].text)?.actor_label;
+            }
+            catch {
+                return undefined;
+            } })()
+            : undefined);
+        if (label)
+            return autoVerifyBounds(_bridge, label, result);
+        return result;
     }));
     // --------------------------------------------------------------------------
     // ue_set_actor_property
@@ -136,10 +181,12 @@ export function registerEditorTools(server, bridge) {
         if (args.component_name) {
             payload['component_name'] = args.component_name;
         }
-        return sendOrDisconnect(_bridge, {
+        const result = await sendOrDisconnect(_bridge, {
             type: 'actor.setProperty',
             payload,
         });
+        // Auto-verify: query bounds after property change
+        return autoVerifyBounds(_bridge, args.actor_label, result);
     }));
     // --------------------------------------------------------------------------
     // ue_create_data_asset
@@ -235,7 +282,9 @@ export function registerEditorTools(server, bridge) {
             payload['rotation'] = args.rotation;
         if (args.scale)
             payload['scale'] = args.scale;
-        return sendOrDisconnect(_bridge, { type: 'actor.transform', payload });
+        const result = await sendOrDisconnect(_bridge, { type: 'actor.transform', payload });
+        // Auto-verify: query bounds after transform
+        return autoVerifyBounds(_bridge, args.actor_label, result);
     }));
     // --------------------------------------------------------------------------
     // ue_delete_actor
@@ -251,10 +300,30 @@ export function registerEditorTools(server, bridge) {
             destructiveHint: true,
         },
     }, withKnownIssues('ue_delete_actor', async (args) => {
-        return sendOrDisconnect(_bridge, {
+        const result = await sendOrDisconnect(_bridge, {
             type: 'actor.delete',
             payload: { actor_label: args.actor_label },
         });
+        // Auto-verify: confirm actor no longer exists
+        if (!result.isError) {
+            try {
+                const verifyResponse = await _bridge.sendCommand({
+                    type: 'actor.list',
+                    correlationId: '',
+                });
+                if (verifyResponse.success) {
+                    const actors = verifyResponse.data;
+                    return {
+                        content: [
+                            ...result.content,
+                            { type: 'text', text: JSON.stringify({ _verification: { deleted: args.actor_label, remaining_actors: actors } }) },
+                        ],
+                    };
+                }
+            }
+            catch { /* verification is best-effort */ }
+        }
+        return result;
     }));
     // --------------------------------------------------------------------------
     // ue_query_assets
@@ -325,4 +394,25 @@ export function registerEditorTools(server, bridge) {
     }, withKnownIssues('ue_read_level_layout', async (_args) => {
         return sendOrDisconnect(_bridge, { type: 'level.layout' });
     }));
+    // --------------------------------------------------------------------------
+    // ue_get_component_bounds
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_get_component_bounds', {
+        title: 'Get Actor Component Bounds',
+        description: '[requires_plugin] Get the world-space bounding box and transform of an actor and its components. Use this to verify spatial placement after spawning, transforming, or setting properties. Returns min/max bounds, center, and extent for each component.',
+        inputSchema: z.object({
+            actor_label: z.string().describe('The editor label of the actor to inspect'),
+            component_name: z.string().optional().describe('Optional: inspect a specific component only (e.g., DoorMesh, DoorCollision)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_get_component_bounds', async (args) => {
+        const payload = { actor_label: args.actor_label };
+        if (args.component_name) {
+            payload['component_name'] = args.component_name;
+        }
+        return sendOrDisconnect(_bridge, { type: 'actor.componentBounds', payload });
+    }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultimate-unreal-engine-mcp",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "description": "MCP server giving AI assistants full access to Unreal Engine 5.7 projects",
   "type": "module",
   "engines": {