ultimate-unreal-engine-mcp 0.1.21 → 0.1.23

package/README.md

@@ -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)
@@ -543,6 +544,51 @@ 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.
+
+**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 spawned
+
+ue_get_component_bounds("BP_Door", component="DoorMesh")     ← automatic
+  → bounds: X=[806, 994] ✓ — 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
+
+ue_get_component_bounds("BP_Door", component="DoorMesh")     ← re-verify
+  → bounds: X=[806, 994] ✓ — back in place
+
+ue_look_at("BP_Door", angle="front")                          ← visual confirm
+  → [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

@@ -85,7 +85,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({
@@ -114,7 +114,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     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)'),
@@ -146,7 +146,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     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 +171,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 +195,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
@@ -242,7 +242,7 @@ export function registerEditorTools(server, bridge) {
     // --------------------------------------------------------------------------
     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'),
         }),

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.21",
+  "version": "0.1.23",
   "description": "MCP server giving AI assistants full access to Unreal Engine 5.7 projects",
   "type": "module",
   "engines": {

package/unreal-plugin/MCPBridge/Source/MCPBridgeEditor/Private/MCPViewportCommands.cpp

@@ -208,51 +208,24 @@ static FString TakeScreenshotToFile(int32 Width, int32 Height)
 		return FString();
 	}
 
-	// Enable realtime rendering so the viewport actually renders frames.
+	// Enable realtime rendering so the viewport continuously renders frames.
 	// Without this, the editor viewport only renders when "dirty" and
-	// ReadPixels captures a stale/blank framebuffer.
-	const bool bWasRealtime = ViewportClient->IsRealtime();
+	// FScreenshotRequest never gets picked up on subsequent calls.
 	ViewportClient->SetRealtime(true);
 
-	// Force a full viewport redraw. Invalidate marks it dirty,
-	// then Draw executes the render pipeline synchronously.
-	ViewportClient->Viewport->Invalidate();
-	ViewportClient->Viewport->Draw();
-	FlushRenderingCommands();
-
-	// Read pixels from the viewport framebuffer.
-	TArray<FColor> Pixels;
-	const bool bReadOk = ViewportClient->Viewport->ReadPixels(Pixels);
-
-	// Restore previous realtime state.
-	if (!bWasRealtime)
-	{
-		ViewportClient->SetRealtime(false);
-	}
-
-	if (!bReadOk)
-	{
-		return FString();
-	}
-
-	const int32 VPWidth  = ViewportClient->Viewport->GetSizeXY().X;
-	const int32 VPHeight = ViewportClient->Viewport->GetSizeXY().Y;
-
-	if (Pixels.Num() != VPWidth * VPHeight || VPWidth == 0 || VPHeight == 0)
-	{
-		return FString();
-	}
-
-	// Compress to PNG.
-	TArray64<uint8> PngData;
-	FImageUtils::PNGCompressImageArray(VPWidth, VPHeight, Pixels, PngData);
-
-	// Write to file.
 	const FString Timestamp = FDateTime::Now().ToString(TEXT("%Y%m%d_%H%M%S_%s"));
 	const FString FileName  = FString::Printf(TEXT("mcp_screenshot_%s.png"), *Timestamp);
 	const FString FilePath  = FPaths::Combine(GetMCPScreenshotDir(), FileName);
 
-	FFileHelper::SaveArrayToFile(PngData, *FilePath);
+	GScreenshotResolutionX = Width;
+	GScreenshotResolutionY = Height;
+
+	// Invalidate to ensure the viewport redraws with current camera state.
+	ViewportClient->Viewport->Invalidate();
+
+	// Request screenshot to a specific file path. With realtime enabled,
+	// the renderer will process this on the next frame.
+	FScreenshotRequest::RequestScreenshot(FilePath, false /* bShowUI */, false /* bAddFilenameSuffix */);
 
 	return FilePath;
 }
@@ -361,7 +334,7 @@ void RegisterViewportCommands(FMCPCommandRouter& Router)
 		Data->SetStringField(TEXT("file_path"), FilePath);
 		Data->SetNumberField(TEXT("width"),  static_cast<double>(Width));
 		Data->SetNumberField(TEXT("height"), static_cast<double>(Height));
-		Data->SetBoolField(TEXT("saved"), true);
+		Data->SetBoolField(TEXT("async"), true);
 
 		SendResponse(BuildViewportSuccessResponse(CorrId, Data) + TEXT("\n"));
 	});