ultimate-unreal-engine-mcp 0.1.22 → 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.
 
@@ -23,6 +23,7 @@ npx ultimate-unreal-engine-mcp setup
 - [Architecture](#architecture)
 - [Tool Catalog](#tool-catalog)
 - [Visual Review Loop](#visual-review-loop)
+- [Automatic Self-Verification](#automatic-self-verification)
 - [Headless vs Live](#headless-vs-live)
 - [Installation](#installation)
 - [C++ Plugin Setup](#c-plugin-setup)
@@ -51,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.
 
 ---
 
@@ -543,6 +544,45 @@ ue_cleanup_screenshots(confirm=true)
 
 ---
 
+## Automatic Self-Verification
+
+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.
+
+**How it works:**
+
+```
+ue_spawn_actor("BP_Door", location={x:1040, y:150, z:0})
+  → {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", ...)
+  → {success: true, _verification: {bounds: {min: {x:1040}, max: {x:1228}}}}
+  ← bounds shifted! rotation moved mesh out of gap ✗
+
+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")
+  → [screenshot inline] door visible, handle correct side ✓
+```
+
+**The Inspect-Reason-Fix cycle:**
+
+| Step | What happens | Tool |
+|------|-------------|------|
+| **Act** | Spawn, transform, or set property | `ue_spawn_actor`, `ue_transform_actor`, `ue_set_actor_property` |
+| **Measure** | Get exact numerical positions | `ue_get_component_bounds` |
+| **Reason** | Do bounds match expectations? | (AI reasoning) |
+| **Fix** | Adjust offsets to compensate | Same mutation tools |
+| **Verify** | Confirm fix worked, visually and numerically | `ue_get_component_bounds` + `ue_look_at` |
+
+The AI also has access to a `ue://best-practices/self-verification` MCP resource that documents verification patterns, common spatial pitfalls, and the full verification matrix.
+
+---
+
 ## Headless vs Live
 
 Some tools work without the UE Editor running. Others require the MCPBridge plugin connected to a live editor instance.

package/dist/index.js

@@ -77,6 +77,69 @@ import { registerNetworkingTools } from './tools/networking/index.js';
     registerMotionDesignTools(server); // Motion Design tools (MD-01..04)
     registerMovieRenderTools(server); // Movie Render Pipeline tools (MRP-01..04)
     registerNetworkingTools(server); // Networking & Replication tools (NET-01..04)
+    // ---------------------------------------------------------------------------
+    // Register best-practices resource: self-verification guide
+    // ---------------------------------------------------------------------------
+    server.registerResource('ue_best_practices', 'ue://best-practices/self-verification', {
+        title: 'UE MCP Best Practices: Self-Verification',
+        description: 'Guidelines for AI assistants using UE MCP tools. Covers mandatory self-verification after mutations, spatial reasoning patterns, and the inspect-reason-fix cycle.',
+        mimeType: 'text/markdown',
+    }, async (_uri) => ({
+        contents: [{
+                uri: 'ue://best-practices/self-verification',
+                mimeType: 'text/markdown',
+                text: `# UE MCP Best Practices: Self-Verification
+
+## Core Principle
+
+**Always verify your own work before reporting success to the user.**
+
+Every mutation (spawn, transform, property set, asset creation) must be followed by a verification step. Never ask the user to "check if that looks right" when you have tools to check it yourself.
+
+## Verification Matrix
+
+| After this action... | Verify with... |
+|---|---|
+| \`ue_spawn_actor\` | \`ue_get_component_bounds\` to confirm position, then \`ue_look_at\` to visually confirm |
+| \`ue_transform_actor\` | \`ue_get_component_bounds\` — rotations can shift meshes relative to pivots |
+| \`ue_set_actor_property\` (spatial) | \`ue_get_component_bounds\` for position/scale, \`ue_visual_review\` for visual properties |
+| \`ue_set_actor_property\` (material/mesh) | \`ue_look_at\` or \`ue_visual_review\` to confirm visual result |
+| \`ue_delete_actor\` | \`ue_list_actors\` to confirm removal |
+| \`ue_create_data_asset\` / \`ue_create_curve\` | \`ue_query_assets\` to confirm creation |
+| Any visual change | \`ue_visual_review\` or \`ue_look_at\` to see the result |
+
+## The Inspect-Reason-Fix Cycle
+
+When working with spatial placement (actors, components, doors, furniture):
+
+1. **Act** — spawn, transform, or set property
+2. **Measure** — \`ue_get_component_bounds\` to get exact numerical positions
+3. **Reason** — do the bounds match expectations? Are components where they should be?
+4. **Fix** — if not, adjust offsets/rotations to compensate
+5. **Verify** — re-measure to confirm the fix worked
+
+Repeat until all components are correctly positioned. Only THEN report success to the user.
+
+## Common Spatial Pitfalls
+
+- **Negative scale flips normals** — use 180-degree rotation instead of -1 scale to flip meshes
+- **Rotations shift mesh position** — rotating around a pivot moves the mesh; always check bounds after rotation
+- **Component offsets are relative** — a rotated parent changes where child offsets end up in world space
+- **Collision doesn't auto-follow mesh** — if you move/rotate a mesh component, the collision component may need separate adjustment
+
+## Visual Verification
+
+For any change that affects what the user will SEE in the viewport:
+1. Use \`ue_look_at\` to navigate the camera to the changed actor
+2. Inspect the screenshot — check for: missing meshes, wrong orientation, clipping, z-fighting, scale issues
+3. If something looks wrong, fix it BEFORE telling the user
+
+## Cleanup
+
+When a visual review session is complete, call \`ue_cleanup_screenshots(confirm=true)\` to free disk space.
+`,
+            }],
+    }));
     const transport = new StdioServerTransport();
     await server.connect(transport);
     log('Server ready — connected via stdio');

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
 // ---------------------------------------------------------------------------
 /**
@@ -85,7 +118,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     server.registerTool('ue_spawn_actor', {
         title: 'Spawn UE Actor',
-        description: '[requires_plugin] Spawn a new actor in the currently open UE Editor level at the specified location.',
+        description: '[requires_plugin] Spawn a new actor in the currently open UE Editor level at the specified location. After spawning, ALWAYS verify placement with ue_get_component_bounds or ue_look_at before reporting success to the user.',
         inputSchema: z.object({
             class_name: z.string().describe('The actor class to spawn (e.g., AStaticMeshActor)'),
             location: z.object({
@@ -104,17 +137,29 @@ 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
     // --------------------------------------------------------------------------
     server.registerTool('ue_set_actor_property', {
         title: 'Set Actor Property',
-        description: '[requires_plugin] Set a UPROPERTY value on an actor by label. Supports bool, int, float, string, name, text, actor (reference by label), and asset (reference by path).',
+        description: '[requires_plugin] Set a UPROPERTY value on an actor by label. Supports bool, int, float, string, name, text, actor (reference by label), and asset (reference by path). After setting spatial properties (transforms, offsets, scale), verify the result with ue_get_component_bounds before reporting success.',
         inputSchema: z.object({
             actor_label: z.string().describe('The editor label of the target actor'),
             property_name: z.string().describe('The UPROPERTY name to set (e.g., RoomID, RoomDoor, DoorCurve)'),
@@ -136,17 +181,19 @@ 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
     // --------------------------------------------------------------------------
     server.registerTool('ue_create_data_asset', {
         title: 'Create Data Asset',
-        description: '[requires_plugin] Create a UPrimaryDataAsset (or subclass) at the given path with reflection-set properties.',
+        description: '[requires_plugin] Create a UPrimaryDataAsset (or subclass) at the given path with reflection-set properties. After creation, verify the asset exists with ue_query_assets.',
         inputSchema: z.object({
             asset_path: z.string().describe('UE asset path, e.g. /Game/Data/DA_ValveHandle'),
             class_name: z.string().describe('Asset class name, e.g. ItemDefinition'),
@@ -171,7 +218,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     server.registerTool('ue_create_curve', {
         title: 'Create Float Curve',
-        description: '[requires_plugin] Create a UCurveFloat asset with keyframes at the given path.',
+        description: '[requires_plugin] Create a UCurveFloat asset with keyframes at the given path. After creation, verify the asset exists with ue_query_assets.',
         inputSchema: z.object({
             asset_path: z.string().describe('UE asset path, e.g. /Game/Curves/C_DoorSwing'),
             keys: z.array(z.object({
@@ -195,7 +242,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     server.registerTool('ue_transform_actor', {
         title: 'Transform UE Actor',
-        description: '[requires_plugin] Move, rotate, and/or scale an existing actor in the currently open UE Editor level.',
+        description: '[requires_plugin] Move, rotate, and/or scale an existing actor in the currently open UE Editor level. IMPORTANT: After transforming, always verify the result with ue_get_component_bounds (numerical check) or ue_look_at/ue_visual_review (visual check) before telling the user it worked. Rotations can shift meshes relative to pivots — always confirm final bounds.',
         inputSchema: z.object({
             actor_label: z.string().describe('The editor label of the actor to transform'),
             location: z
@@ -235,14 +282,16 @@ 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
     // --------------------------------------------------------------------------
     server.registerTool('ue_delete_actor', {
         title: 'Delete UE Actor',
-        description: '[requires_plugin] Delete an actor from the currently open UE Editor level. This operation is destructive.',
+        description: '[requires_plugin] Delete an actor from the currently open UE Editor level. This operation is destructive. After deleting, verify with ue_list_actors that the actor is gone.',
         inputSchema: z.object({
             actor_label: z.string().describe('The editor label of the actor to delete'),
         }),
@@ -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/dist/tools/viewport/index.js

@@ -428,7 +428,7 @@ export function registerViewportTools(server, bridge) {
     // --------------------------------------------------------------------------
     server.registerTool('ue_visual_review', {
         title: 'Visual Review Screenshot',
-        description: '[requires_plugin] Take a quick viewport screenshot for visual review. Returns the image inline with camera context. Use this for iterative review loops.',
+        description: '[requires_plugin] Take a quick viewport screenshot for visual review. Returns the image inline with camera context. Use this to VERIFY changes after any mutation (spawn, transform, property set). Always screenshot after making visual changes — do not ask the user to check manually.',
         inputSchema: z.object({
             width: z
                 .number()
@@ -662,7 +662,7 @@ export function registerViewportTools(server, bridge) {
     // --------------------------------------------------------------------------
     server.registerTool('ue_iterate_scene', {
         title: 'Full Scene Context Snapshot',
-        description: '[requires_plugin] Get full visual and semantic context in one call. Takes a screenshot AND returns structured data about nearby actors. Use this to orient yourself — see what you are looking at and what is nearby.',
+        description: '[requires_plugin] Get full visual and semantic context in one call. Takes a screenshot AND returns structured data about nearby actors. Use this to orient yourself and to verify complex multi-actor changes — see what you are looking at, what is nearby, and whether everything is in the right place.',
         inputSchema: z.object({
             width: z
                 .number()

package/package.json

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