ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/worldpartition/index.js

@@ -0,0 +1,226 @@
+// src/tools/worldpartition/index.ts
+// MCP tool implementations for World Partition management (Phase 18).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge handlers.
+// Returns structured plugin_not_connected errors when the plugin is absent.
+//
+// Tools registered (Phase 18 — WP-01 through WP-04):
+//   ue_read_world_partition        — Read WP grid size, loading range, streaming config, runtime hash
+//   ue_manage_data_layers          — List, create, toggle, or assign actors to data layers
+//   ue_inspect_streaming_sources   — Inspect streaming source components and their configurations
+//   ue_trigger_hlod_generation     — Trigger HLOD generation or inspect HLOD layer config
+//
+// All tools require MCPBridge plugin (Phase 18 — WP-01 through WP-04).
+import { z } from 'zod';
+import { withKnownIssues } from '../known-issues/middleware.js';
+import { PluginBridgeClient, PluginNotConnectedError } from '../../plugin-bridge/client.js';
+// Module-level bridge instance — injected in tests via exported handler signatures.
+const bridge = new PluginBridgeClient();
+// ---------------------------------------------------------------------------
+// sendOrDisconnect helper
+// ---------------------------------------------------------------------------
+/**
+ * Sends a command to the bridge and returns a ToolResult.
+ *
+ * - On success (response.success true): returns data as JSON text.
+ * - On command-level failure (response.success false): returns isError:true with error JSON.
+ * - On PluginNotConnectedError: returns isError:true with plugin_not_connected JSON.
+ * - On other errors: rethrows (withKnownIssues catches and formats).
+ *
+ * NOTE: sendCommand() overwrites correlationId with crypto.randomUUID() internally;
+ * passing an empty string is safe and correct (per STATE.md decision).
+ */
+async function sendOrDisconnect(b, cmd) {
+    try {
+        const response = await b.sendCommand({ ...cmd, correlationId: '' });
+        if (!response.success) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: response.error }) }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response.data ?? {}) }],
+        };
+    }
+    catch (err) {
+        if (err instanceof PluginNotConnectedError) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(err.bridgeError) }],
+            };
+        }
+        throw err; // withKnownIssues catches unexpected errors
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported handler functions (for direct unit testing via bridge injection)
+// ---------------------------------------------------------------------------
+/**
+ * ue_read_world_partition handler — satisfies WP-01.
+ * Sends worldpartition.settings to the plugin; returns WP configuration.
+ *
+ * @param args  Tool arguments (none required for this tool).
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleReadWorldPartition(args, b = bridge) {
+    // Response data shape: WorldPartitionSettingsResult
+    void args; // No parameters required
+    return sendOrDisconnect(b, {
+        type: 'worldpartition.settings',
+        payload: {},
+    });
+}
+/**
+ * ue_manage_data_layers handler — satisfies WP-02.
+ * Sends worldpartition.dataLayers to the plugin; lists, creates, toggles, or assigns actors to data layers.
+ *
+ * @param args  Tool arguments including action and optional layer/actor parameters.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleManageDataLayers(args, b = bridge) {
+    // Response data shape: DataLayersResult (variant depends on action)
+    const payload = { action: args.action };
+    if (args.layer_name !== undefined)
+        payload['layer_name'] = args.layer_name;
+    if (args.layer_type !== undefined)
+        payload['layer_type'] = args.layer_type;
+    if (args.initial_state !== undefined)
+        payload['initial_state'] = args.initial_state;
+    if (args.actor_label !== undefined)
+        payload['actor_label'] = args.actor_label;
+    return sendOrDisconnect(b, {
+        type: 'worldpartition.dataLayers',
+        payload,
+    });
+}
+/**
+ * ue_inspect_streaming_sources handler — satisfies WP-03.
+ * Sends worldpartition.streamingSources to the plugin; returns streaming source components.
+ *
+ * @param args  Tool arguments including optional actor_label filter.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectStreamingSources(args, b = bridge) {
+    // Response data shape: StreamingSourcesResult
+    const payload = {};
+    if (args.actor_label !== undefined)
+        payload['actor_label'] = args.actor_label;
+    return sendOrDisconnect(b, {
+        type: 'worldpartition.streamingSources',
+        payload,
+    });
+}
+/**
+ * ue_trigger_hlod_generation handler — satisfies WP-04.
+ * Sends worldpartition.hlod to the plugin; inspects HLOD config or triggers HLOD build.
+ *
+ * @param args  Tool arguments including action ("inspect" | "generate").
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleTriggerHlodGeneration(args, b = bridge) {
+    // Response data shape: HlodResult (variant depends on action)
+    return sendOrDisconnect(b, {
+        type: 'worldpartition.hlod',
+        payload: { action: args.action },
+    });
+}
+// ---------------------------------------------------------------------------
+// registerWorldPartitionTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE World Partition management tools on the MCP server.
+ *
+ * All tools in this domain require the MCPBridge editor plugin.
+ * When the plugin is not connected, each handler returns:
+ *   { isError: true, content: [{ type: 'text', text: <plugin_not_connected JSON> }] }
+ *
+ * Tools registered (Phase 18):
+ *   ue_read_world_partition        — WP-01: Read WP configuration (grid size, loading range, streaming)
+ *   ue_manage_data_layers          — WP-02: List, create, toggle data layers; assign actors to layers
+ *   ue_inspect_streaming_sources   — WP-03: Inspect streaming source components and target states
+ *   ue_trigger_hlod_generation     — WP-04: Inspect HLOD layer config or trigger HLOD build
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param _bridge Optional PluginBridgeClient for testing (not used directly — handlers
+ *                accept bridge injection via their exported function signatures).
+ */
+export function registerWorldPartitionTools(server, _bridge) {
+    const b = _bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_read_world_partition (WP-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_world_partition', {
+        title: 'Read World Partition Settings',
+        description: '[requires_plugin] Read World Partition configuration including grid size, loading range, streaming state, and runtime hash.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_world_partition', async (args) => handleReadWorldPartition(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_manage_data_layers (WP-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_manage_data_layers', {
+        title: 'Manage Data Layers',
+        description: '[requires_plugin] List, create, enable/disable data layers, or assign actors to data layers in a World Partition world.',
+        inputSchema: z.object({
+            action: z
+                .enum(['list', 'create', 'toggle', 'assign_actor'])
+                .describe('Action to perform on data layers'),
+            layer_name: z
+                .string()
+                .optional()
+                .describe('Data layer name (required for create, toggle, assign_actor)'),
+            layer_type: z
+                .enum(['Runtime', 'Editor'])
+                .optional()
+                .describe('Layer type (required for create)'),
+            initial_state: z
+                .enum(['Unloaded', 'Loaded', 'Activated'])
+                .optional()
+                .describe('Initial runtime state (for toggle action)'),
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Actor label to assign to layer (for assign_actor action)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_manage_data_layers', async (args) => handleManageDataLayers(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_streaming_sources (WP-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_streaming_sources', {
+        title: 'Inspect Streaming Sources',
+        description: '[requires_plugin] Inspect World Partition streaming source components, their shapes, priorities, and target states.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Optional actor label to filter streaming sources'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_streaming_sources', async (args) => handleInspectStreamingSources(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_trigger_hlod_generation (WP-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_trigger_hlod_generation', {
+        title: 'HLOD Generation',
+        description: '[requires_plugin] Trigger HLOD generation or inspect HLOD layer configuration for World Partition.',
+        inputSchema: z.object({
+            action: z
+                .enum(['inspect', 'generate'])
+                .describe('inspect: read HLOD layer config; generate: trigger HLOD build'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_trigger_hlod_generation', async (args) => handleTriggerHlodGeneration(args, b)));
+}

package/dist/tools/worldpartition/types.js

@@ -0,0 +1,4 @@
+// src/tools/worldpartition/types.ts
+// TypeScript result interfaces for the four World Partition MCP tools (Phase 18).
+// These interfaces mirror the JSON shapes returned by the C++ handlers in Plan 01.
+export {};

package/dist/utils/execFileNoThrow.js

@@ -0,0 +1,40 @@
+// src/utils/execFileNoThrow.ts
+// Safe subprocess wrapper using array-form execFile — no shell string interpolation.
+// Never throws: non-zero exit codes are returned as { status: N }, not thrown.
+// Use this for ALL subprocess invocations in the codebase.
+//
+// Security: array-form execFile passes args as an array directly to the OS —
+// shell metacharacters (`;`, `|`, `&`, etc.) are inert. Mitigates T-06-04.
+import { execFile } from 'node:child_process';
+/**
+ * Invoke a subprocess using array-form execFile and return its output.
+ * Never throws — non-zero exit codes are captured in the returned status field.
+ *
+ * @param cmd     Executable name or absolute path. Never a shell string.
+ * @param args    Arguments array. Shell metacharacters are inert.
+ * @param options Optional execution context (cwd, env, timeout).
+ */
+export async function execFileNoThrow(cmd, args, options) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, {
+            cwd: options?.cwd,
+            env: options?.env,
+            timeout: options?.timeoutMs,
+            // 50 MB buffer — UBT can produce large compilation logs
+            maxBuffer: 50 * 1024 * 1024,
+        }, (err, stdout, stderr) => {
+            if (!err) {
+                resolve({ stdout, stderr, status: 0 });
+            }
+            else {
+                // err.code is the numeric exit status on non-zero exit; null if killed by signal.
+                // err.stdout / err.stderr may contain captured output on some Node versions —
+                // prefer them when set, fall back to the direct callback params.
+                const status = typeof err.code === 'number' ? err.code : null;
+                const outStr = err.stdout ?? stdout;
+                const errStr = err.stderr ?? stderr;
+                resolve({ stdout: outStr, stderr: errStr, status });
+            }
+        });
+    });
+}

package/dist/utils/logger.js

@@ -0,0 +1,27 @@
+// Structured logger for the UE MCP server.
+// All output goes to console.error (stderr) — NEVER console.log or console.info.
+// Reason: console.log writes to stdout, which is the MCP JSON-RPC channel.
+// Any stdout output corrupts the protocol stream and disconnects the client.
+// See: PITFALLS.md Pitfall 8, CONTEXT.md locked decision.
+/**
+ * Logs an informational message to stderr with the [UE MCP] prefix.
+ * Use for normal operational messages (startup, connection status, etc.).
+ */
+export function log(message, ...args) {
+    console.error(`[UE MCP] ${message}`, ...args);
+}
+/**
+ * Logs a warning message to stderr with the [UE MCP WARN] prefix.
+ * Use for non-fatal issues that operators should be aware of.
+ */
+export function warn(message, ...args) {
+    console.error(`[UE MCP WARN] ${message}`, ...args);
+}
+/**
+ * Logs an error message to stderr with the [UE MCP ERROR] prefix.
+ * Use for caught exceptions and error conditions. The err argument is
+ * logged inline — pass an Error object or any useful context.
+ */
+export function error(message, err) {
+    console.error(`[UE MCP ERROR] ${message}`, err ?? '');
+}

package/dist/utils/path-guard.js

@@ -0,0 +1,26 @@
+// Path traversal guard — validates user-supplied file paths against project root.
+// Implements ASVS V4 access control: resolves path and asserts within project root.
+// Mitigates T-01-04 (path traversal via AI-crafted file path args).
+//
+// Windows compatible: path.resolve() and path.sep handle backslashes correctly.
+// Do NOT use string concatenation with '/' — use path.resolve() + path.sep.
+import * as path from 'path';
+/**
+ * Resolves userPath and asserts it is within (or equal to) projectRoot.
+ *
+ * @param userPath    The path supplied by the MCP tool caller (may be relative or absolute).
+ * @param projectRoot The project root to validate against (should be absolute).
+ * @returns           The resolved absolute path on success.
+ * @throws Error      If the resolved path escapes the project root.
+ */
+export function validatePath(userPath, projectRoot) {
+    const resolved = path.resolve(userPath);
+    const normalizedRoot = path.resolve(projectRoot);
+    // Accept paths that are exactly the root or start with root + separator
+    // Using path.sep ensures correct behavior on Windows (backslash) and POSIX (slash)
+    if (resolved !== normalizedRoot &&
+        !resolved.startsWith(normalizedRoot + path.sep)) {
+        throw new Error(`Path traversal rejected: "${userPath}" resolves outside project root "${projectRoot}"`);
+    }
+    return resolved;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "ultimate-unreal-engine-mcp",
+  "version": "0.1.0",
+  "description": "MCP server giving AI assistants full access to Unreal Engine 5.7 projects",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "dist/index.js",
+  "bin": {
+    "ultimate-unreal-engine-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "unreal-plugin"
+  ],
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "minisearch": "^7.2.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
+    "eslint": "^10.4.1",
+    "tsx": "^4.22.3",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  }
+}

package/unreal-plugin/MCPBridge/MCPBridge.uplugin

@@ -0,0 +1,29 @@
+{
+  "FileVersion": 3,
+  "Version": 1,
+  "VersionName": "1.0",
+  "FriendlyName": "MCPBridge",
+  "Description": "TCP bridge between the UE 5.7 Editor and the Model Context Protocol (MCP) server. Allows AI assistants to access live editor APIs via JSON-newline commands.",
+  "Category": "Editor",
+  "CreatedBy": "",
+  "CreatedByURL": "",
+  "DocsURL": "",
+  "MarketplaceURL": "",
+  "SupportURL": "",
+  "CanContainContent": false,
+  "IsBetaVersion": false,
+  "IsExperimentalVersion": false,
+  "Installed": false,
+  "Modules": [
+    {
+      "Name": "MCPBridgeRuntime",
+      "Type": "Runtime",
+      "LoadingPhase": "Default"
+    },
+    {
+      "Name": "MCPBridgeEditor",
+      "Type": "Editor",
+      "LoadingPhase": "PostEngineInit"
+    }
+  ]
+}

package/unreal-plugin/MCPBridge/Source/MCPBridgeEditor/MCPBridgeEditor.Build.cs

@@ -0,0 +1,68 @@
+// MCPBridgeEditor.Build.cs
+// Editor module: UEditorSubsystem lifecycle, editor API handlers (Phases 8-29).
+// Depends on MCPBridgeRuntime for the TCP server.
+// This module is guarded by WITH_EDITOR -- never ships to cooked builds.
+
+using UnrealBuildTool;
+
+public class MCPBridgeEditor : ModuleRules
+{
+    public MCPBridgeEditor(ReadOnlyTargetRules Target) : base(Target)
+    {
+        PCHUsage = ModuleRules.PCHUsageMode.UseExplicitOrSharedPCHs;
+
+        PublicDependencyModuleNames.AddRange(new string[]
+        {
+            "Core",
+            "MCPBridgeRuntime",
+        });
+
+        PrivateDependencyModuleNames.AddRange(new string[]
+        {
+            "CoreUObject",
+            "Engine",
+            "UnrealEd",
+            "EditorSubsystem",
+            "Json",
+            "Kismet",
+            "BlueprintGraph",
+            "AssetRegistry",
+            "EnhancedInput",
+            "LevelEditor",
+            "SlateCore",
+            "DataValidation",
+            "LevelSequence",
+            "MovieScene",
+            "MovieSceneTracks",
+            "LevelSequenceEditor",
+            "MaterialEditor",
+            "AssetTools",
+            "AnimGraph",
+            "AnimGraphRuntime",
+            "IKRig",
+            "WorldPartitionEditor",
+            "PhysicsCore",
+            "MetasoundEngine",
+            "MetasoundFrontend",
+            "InterchangeEngine",
+            "InterchangePipelines",
+            "AIModule",
+            "StateTreeModule",
+            "NavigationSystem",
+            "GameplayAbilities",        // Phase 25 - GAS
+            "GameplayTags",             // Phase 25 - GAS
+            "GameplayTasks",            // Phase 25 - GAS
+            "GeometryCollectionEngine", // Phase 26 - Chaos destruction (UGeometryCollectionComponent)
+            "ChaosCloth",               // Phase 26 - Chaos cloth simulation parameters
+            "LiveLinkInterface",        // Phase 27 - ILiveLinkClient, FLiveLinkSubjectKey, FLiveLinkSubjectFrameData
+            "LiveLink",                 // Phase 27 - ULiveLinkSubjectSettings for per-subject enabled state control
+            "AvalancheRundown",         // Phase 28 - Motion Design Scene State machines (experimental)
+            "AvalancheTransition",      // Phase 28 - Motion Design Transition Logic trees (experimental)
+            "RemoteControl",            // Phase 28 - Remote Control preset read/write
+            "MovieRenderPipelineCore",  // Phase 29 - UMoviePipelineQueue, UMoviePipelineExecutorJob, config/settings types
+            "MovieRenderPipelineEditor", // Phase 29 - UMoviePipelineQueueSubsystem
+            "OnlineSubsystem",          // Phase 30 - IOnlineSubsystem, IOnlineSession, FOnlineSessionSettings
+            "OnlineSubsystemUtils",     // Phase 30 - Online subsystem helper utilities
+        });
+    }
+}