ultimate-unreal-engine-mcp 0.1.23 → 0.1.25

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,113 @@ 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 });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_rebuild
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_rebuild', {
+        title: 'Save, Rebuild & Relaunch Editor',
+        description: '[requires_plugin] Saves all dirty packages, closes the editor, runs Build.bat, and relaunches the editor. Returns build output and relaunch status.',
+        inputSchema: z.object({
+            project_path: z.string().describe('Absolute path to the .uproject file'),
+            ue_path: z.string().optional().describe('UE engine install path (default: C:/Program Files/Epic Games/UE_5.7)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+    }, withKnownIssues('ue_rebuild', async (args) => {
+        const { execFileSync, spawn } = await import('child_process');
+        const net = await import('net');
+        const uePath = args.ue_path ?? 'C:/Program Files/Epic Games/UE_5.7';
+        const projectPath = args.project_path;
+        const steps = [];
+        // Step 1: Save all
+        try {
+            const saveResult = await _bridge.sendCommand({ type: 'editor.saveAll', correlationId: '' });
+            steps.push({ step: 'save', success: saveResult.success });
+        }
+        catch (err) {
+            steps.push({ step: 'save', error: err.message });
+        }
+        // Step 2: Quit editor
+        try {
+            await _bridge.sendCommand({ type: 'editor.quit', correlationId: '' });
+            steps.push({ step: 'quit', sent: true });
+        }
+        catch {
+            steps.push({ step: 'quit', sent: true, note: 'connection dropped (expected)' });
+        }
+        // Step 3: Wait for editor to fully close (poll TCP port)
+        const waitForClose = () => new Promise((resolve) => {
+            let attempts = 0;
+            const check = () => {
+                const sock = net.createConnection({ port: 55557, host: '127.0.0.1' });
+                sock.on('connect', () => { sock.destroy(); attempts++; if (attempts < 60) setTimeout(check, 500); else resolve(false); });
+                sock.on('error', () => { resolve(true); });
+            };
+            setTimeout(check, 1000);
+        });
+        const closed = await waitForClose();
+        steps.push({ step: 'wait_close', closed });
+        // Step 4: Build (using execFileSync to avoid shell injection)
+        try {
+            const buildBat = `${uePath}/Engine/Build/BatchFiles/Build.bat`;
+            const buildArgs = ['ScaryRogueEditor', 'Win64', 'Development', `-Project=${projectPath}`, '-WaitMutex'];
+            const buildOutput = execFileSync(buildBat, buildArgs, { encoding: 'utf8', timeout: 300000, shell: true });
+            const succeeded = buildOutput.includes('Succeeded');
+            const lastLines = buildOutput.trim().split('\n').slice(-5).join('\n');
+            steps.push({ step: 'build', succeeded, output: lastLines });
+            if (!succeeded) {
+                return { content: [{ type: 'text', text: JSON.stringify({ steps }) }] };
+            }
+        }
+        catch (err) {
+            steps.push({ step: 'build', error: err.message?.slice(0, 500) });
+            return { content: [{ type: 'text', text: JSON.stringify({ steps }) }] };
+        }
+        // Step 5: Relaunch editor
+        try {
+            const editorExe = `${uePath}/Engine/Binaries/Win64/UnrealEditor.exe`;
+            const child = spawn(editorExe, [projectPath], { detached: true, stdio: 'ignore' });
+            child.unref();
+            steps.push({ step: 'relaunch', pid: child.pid });
+        }
+        catch (err) {
+            steps.push({ step: 'relaunch', error: err.message });
+        }
+        // Step 6: Wait for editor to reconnect (TCP port available)
+        const waitForReconnect = () => new Promise((resolve) => {
+            let attempts = 0;
+            const check = () => {
+                const sock = net.createConnection({ port: 55557, host: '127.0.0.1' });
+                sock.on('connect', () => { sock.destroy(); resolve(true); });
+                sock.on('error', () => { attempts++; if (attempts < 120) setTimeout(check, 1000); else resolve(false); });
+            };
+            setTimeout(check, 5000);
+        });
+        const reconnected = await waitForReconnect();
+        steps.push({ step: 'wait_reconnect', reconnected });
+        return { content: [{ type: 'text', text: JSON.stringify({ steps }) }] };
+    }));
 }

package/package.json

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

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

@@ -10,6 +10,9 @@
 
 #include "Editor.h"
 #include "Selection.h"
+#include "FileHelpers.h"
+#include "HAL/PlatformMisc.h"
+#include "Containers/Ticker.h"
 #include "EditorViewportClient.h"
 #include "LevelEditorViewport.h"
 #include "EngineUtils.h"
@@ -170,4 +173,46 @@ void RegisterEditorStateCommands(FMCPCommandRouter& Router)
 
 		SendResponse(BuildEditorStateSuccessResponse(CorrId, Data) + TEXT("\n"));
 	});
+
+	// -----------------------------------------------------------------------
+	// editor.saveAll
+	// Saves all dirty packages (levels, assets). Returns count of saved packages.
+	// -----------------------------------------------------------------------
+	Router.RegisterHandler(TEXT("editor.saveAll"), [](TSharedPtr<FJsonObject> Cmd, FMCPResponseSender SendResponse)
+	{
+		const FString CorrId = Cmd->GetStringField(TEXT("correlationId"));
+
+		const bool bSaved = FEditorFileUtils::SaveDirtyPackages(
+			false,  // bPromptUserToSave
+			true,   // bSaveMapPackages
+			true,   // bSaveContentPackages
+			false); // bFastSave
+
+		TSharedPtr<FJsonObject> Data = MakeShared<FJsonObject>();
+		Data->SetBoolField(TEXT("saved"), bSaved);
+
+		SendResponse(BuildEditorStateSuccessResponse(CorrId, Data) + TEXT("\n"));
+	});
+
+	// -----------------------------------------------------------------------
+	// editor.quit
+	// Gracefully closes the editor. Response is sent before shutdown begins.
+	// -----------------------------------------------------------------------
+	Router.RegisterHandler(TEXT("editor.quit"), [](TSharedPtr<FJsonObject> Cmd, FMCPResponseSender SendResponse)
+	{
+		const FString CorrId = Cmd->GetStringField(TEXT("correlationId"));
+
+		TSharedPtr<FJsonObject> Data = MakeShared<FJsonObject>();
+		Data->SetBoolField(TEXT("quitting"), true);
+
+		SendResponse(BuildEditorStateSuccessResponse(CorrId, Data) + TEXT("\n"));
+
+		// Defer the actual quit to next tick so the response gets sent first.
+		FTSTicker::GetCoreTicker().AddTicker(
+			FTickerDelegate::CreateLambda([](float) -> bool
+		{
+			FPlatformMisc::RequestExit(false); // false = clean shutdown
+			return false;
+		}), 0.1f);
+	});
 }

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

@@ -186,6 +186,120 @@ static UObject* CreateFbxFactory(bool bImportMaterials, bool bCombineMeshes, flo
 
 void RegisterImportExportCommands(FMCPCommandRouter& Router)
 {
+	// -----------------------------------------------------------------------
+	// import.texture
+	// Imports a texture file (PNG, JPG, TGA, etc.) to a UE content path.
+	// Uses UTextureFactory via reflection. Runs synchronously (no Interchange).
+	// Payload: { source_file, dest_path }
+	// -----------------------------------------------------------------------
+	Router.RegisterHandler(TEXT("import.texture"), [](TSharedPtr<FJsonObject> Cmd, FMCPResponseSender SendResponse)
+	{
+		const FString CorrId = Cmd->GetStringField(TEXT("correlationId"));
+
+		TSharedPtr<FJsonObject> Payload;
+		const TSharedPtr<FJsonValue>* PayloadVal = Cmd->Values.Find(TEXT("payload"));
+		if (PayloadVal && (*PayloadVal)->Type == EJson::Object)
+		{
+			Payload = (*PayloadVal)->AsObject();
+		}
+
+		FString SourceFile, DestPath;
+		if (!Payload.IsValid()
+			|| !Payload->TryGetStringField(TEXT("source_file"), SourceFile) || SourceFile.IsEmpty()
+			|| !Payload->TryGetStringField(TEXT("dest_path"), DestPath) || DestPath.IsEmpty())
+		{
+			SendResponse(BuildImpErrorResponse(CorrId, TEXT("missing_required_fields")) + TEXT("\n"));
+			return;
+		}
+
+		if (SourceFile.Contains(TEXT("..")) || !FPaths::FileExists(SourceFile))
+		{
+			SendResponse(BuildImpErrorResponse(CorrId, TEXT("source_file_not_found")) + TEXT("\n"));
+			return;
+		}
+
+		if (!IsValidAssetPath(DestPath))
+		{
+			SendResponse(BuildImpErrorResponse(CorrId, TEXT("invalid_dest_path")) + TEXT("\n"));
+			return;
+		}
+
+		// Split dest into path + name.
+		FString PackagePath = DestPath;
+		FString AssetName;
+		if (DestPath.EndsWith(TEXT("/")))
+		{
+			AssetName = FPaths::GetBaseFilename(SourceFile);
+			PackagePath = DestPath.LeftChop(1);
+		}
+		else
+		{
+			AssetName = FPackageName::GetLongPackageAssetName(DestPath);
+			PackagePath = FPackageName::GetLongPackagePath(DestPath);
+			if (AssetName.IsEmpty())
+			{
+				AssetName = FPaths::GetBaseFilename(SourceFile);
+				PackagePath = DestPath;
+			}
+		}
+
+		// Find UTextureFactory via reflection (avoids including engine-specific headers).
+		UClass* TextureFactoryClass = FindObject<UClass>(nullptr, TEXT("/Script/UnrealEd.TextureFactory"));
+		if (!TextureFactoryClass)
+		{
+			SendResponse(BuildImpErrorResponse(CorrId, TEXT("texture_factory_not_found")) + TEXT("\n"));
+			return;
+		}
+
+		UObject* TextureFactory = NewObject<UObject>(GetTransientPackage(), TextureFactoryClass);
+		if (!TextureFactory)
+		{
+			SendResponse(BuildImpErrorResponse(CorrId, TEXT("factory_creation_failed")) + TEXT("\n"));
+			return;
+		}
+
+		// Create import task.
+		IAssetTools& AT = FModuleManager::LoadModuleChecked<FAssetToolsModule>(TEXT("AssetTools")).Get();
+
+		UAssetImportTask* Task = NewObject<UAssetImportTask>();
+		Task->Filename = SourceFile;
+		Task->DestinationPath = PackagePath;
+		Task->DestinationName = AssetName;
+		Task->bAutomated = true;
+		Task->bReplaceExisting = true;
+		Task->bSave = true;
+
+		// Set the factory.
+		FObjectProperty* FactoryProp = CastField<FObjectProperty>(
+			Task->GetClass()->FindPropertyByName(TEXT("Factory")));
+		if (FactoryProp)
+		{
+			FactoryProp->SetObjectPropertyValue_InContainer(Task, TextureFactory);
+		}
+
+		// Run import via ticker (same pattern as FBX — avoids task graph recursion).
+		FTSTicker::GetCoreTicker().AddTicker(
+			FTickerDelegate::CreateLambda([CorrId, SendResponse, Task, &AT](float) -> bool
+		{
+			TArray<UAssetImportTask*> Tasks;
+			Tasks.Add(Task);
+			AT.ImportAssetTasks(Tasks);
+
+			TArray<TSharedPtr<FJsonValue>> AssetsArray;
+			for (const FString& ImportedPath : Task->ImportedObjectPaths)
+			{
+				AssetsArray.Add(MakeShared<FJsonValueString>(ImportedPath));
+			}
+
+			TSharedPtr<FJsonObject> Data = MakeShared<FJsonObject>();
+			Data->SetArrayField(TEXT("assets"), AssetsArray);
+			Data->SetNumberField(TEXT("count"), static_cast<double>(AssetsArray.Num()));
+
+			SendResponse(BuildImpSuccessResponse(CorrId, Data) + TEXT("\n"));
+			return false;
+		}), 0.0f);
+	});
+
 	// -----------------------------------------------------------------------
 	// import.fbx (IMP-01)
 	// Imports an FBX file to a UE content path.

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

@@ -208,9 +208,7 @@ static FString TakeScreenshotToFile(int32 Width, int32 Height)
 		return FString();
 	}
 
-	// Enable realtime rendering so the viewport continuously renders frames.
-	// Without this, the editor viewport only renders when "dirty" and
-	// FScreenshotRequest never gets picked up on subsequent calls.
+	// Enable realtime rendering so the viewport renders frames continuously.
 	ViewportClient->SetRealtime(true);
 
 	const FString Timestamp = FDateTime::Now().ToString(TEXT("%Y%m%d_%H%M%S_%s"));
@@ -220,13 +218,22 @@ static FString TakeScreenshotToFile(int32 Width, int32 Height)
 	GScreenshotResolutionX = Width;
 	GScreenshotResolutionY = Height;
 
-	// Invalidate to ensure the viewport redraws with current camera state.
+	// Force a complete render cycle BEFORE requesting the screenshot.
+	// This ensures the viewport has rendered the current camera state.
+	// Without this, subsequent screenshots within the same session fail
+	// because FScreenshotRequest only fires once per rendered frame.
 	ViewportClient->Viewport->Invalidate();
+	GEditor->RedrawAllViewports();
+	FlushRenderingCommands();
 
-	// Request screenshot to a specific file path. With realtime enabled,
-	// the renderer will process this on the next frame.
+	// Now request the screenshot — the next frame render will capture it.
 	FScreenshotRequest::RequestScreenshot(FilePath, false /* bShowUI */, false /* bAddFilenameSuffix */);
 
+	// Force another render to actually capture the screenshot.
+	ViewportClient->Viewport->Invalidate();
+	GEditor->RedrawAllViewports();
+	FlushRenderingCommands();
+
 	return FilePath;
 }