unreal-engine-mcp-server 0.3.1 → 0.4.0

package/src/tools/debug.ts

@@ -22,13 +22,11 @@ export class DebugVisualizationTools {
   private async pyDraw(scriptBody: string) {
     const script = `
 import unreal
-# Use modern UnrealEditorSubsystem instead of deprecated EditorLevelLibrary
+# Strict modern API: require UnrealEditorSubsystem (UE 5.1+)
 ues = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
-if ues:
-    world = ues.get_editor_world()
-else:
-    # Fallback to deprecated API if subsystem not available
-    world = unreal.EditorLevelLibrary.get_editor_world()
+if not ues:
+    raise Exception('UnrealEditorSubsystem not available')
+world = ues.get_editor_world()
 ${scriptBody}
 `.trim()
       .replace(/\r?\n/g, '\n');

package/src/tools/rc.ts

@@ -176,7 +176,7 @@ except Exception as e:
 
   // Expose an actor by label/name into a preset
   async exposeActor(params: { presetPath: string; actorName: string }) {
-    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nactor_name = r"${params.actorName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    if not preset:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset not found'}))\n    else:\n        actor_sub = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n        target = None\n        for a in actor_sub.get_all_level_actors():\n            if not a: continue\n            try:\n                if a.get_actor_label() == actor_name or a.get_name() == actor_name:\n                    target = a; break\n            except Exception: pass\n        if not target:\n            print('RESULT:' + json.dumps({'success': False, 'error': 'Actor not found'}))\n        else:\n            try:\n                unreal.RemoteControlFunctionLibrary.expose_actor(preset, target, None)\n                unreal.EditorAssetLibrary.save_asset(preset_path)\n                print('RESULT:' + json.dumps({'success': True}))\n            except Exception as e:\n                print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
+    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nactor_name = r"${params.actorName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    if not preset:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset not found'}))\n    else:\n        actor_sub = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)\n        target = None\n        for a in actor_sub.get_all_level_actors():\n            if not a: continue\n            try:\n                if a.get_actor_label() == actor_name or a.get_name() == actor_name:\n                    target = a; break\n            except Exception: pass\n        if not target:\n            print('RESULT:' + json.dumps({'success': False, 'error': 'Actor not found'}))\n        else:\n            try:\n                # Expose with a default-initialized optional args struct (cannot pass None)\n                args = unreal.RemoteControlOptionalExposeArgs()\n                unreal.RemoteControlFunctionLibrary.expose_actor(preset, target, args)\n                unreal.EditorAssetLibrary.save_asset(preset_path)\n                print('RESULT:' + json.dumps({'success': True}))\n            except Exception as e:\n                print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
     const resp = await this.executeWithRetry(
       () => this.bridge.executePython(python),
       'exposeActor'
@@ -194,7 +194,7 @@ except Exception as e:
 
   // Expose a property on an object into a preset
   async exposeProperty(params: { presetPath: string; objectPath: string; propertyName: string }) {
-    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nobj_path = r"${params.objectPath}"\nprop_name = r"${params.propertyName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    obj = unreal.load_object(None, obj_path)\n    if not preset or not obj:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset or object not found'}))\n    else:\n        try:\n            unreal.RemoteControlFunctionLibrary.expose_property(preset, obj, prop_name, None)\n            unreal.EditorAssetLibrary.save_asset(preset_path)\n            print('RESULT:' + json.dumps({'success': True}))\n        except Exception as e:\n            print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
+    const python = `\nimport unreal, json\npreset_path = r"${params.presetPath}"\nobj_path = r"${params.objectPath}"\nprop_name = r"${params.propertyName}"\ntry:\n    preset = unreal.EditorAssetLibrary.load_asset(preset_path)\n    obj = unreal.load_object(None, obj_path)\n    if not preset or not obj:\n        print('RESULT:' + json.dumps({'success': False, 'error': 'Preset or object not found'}))\n    else:\n        try:\n            # Expose with default optional args struct (cannot pass None)\n            args = unreal.RemoteControlOptionalExposeArgs()\n            unreal.RemoteControlFunctionLibrary.expose_property(preset, obj, prop_name, args)\n            unreal.EditorAssetLibrary.save_asset(preset_path)\n            print('RESULT:' + json.dumps({'success': True}))\n        except Exception as e:\n            print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\nexcept Exception as e:\n    print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))\n`.trim();
     const resp = await this.executeWithRetry(
       () => this.bridge.executePython(python),
       'exposeProperty'

package/src/tools/sequence.ts

@@ -334,12 +334,31 @@ except Exception as e:
    * Play the current level sequence
    */
   async play(params?: { startTime?: number; loopMode?: 'once' | 'loop' | 'pingpong' }) {
+    const loop = params?.loopMode || '';
     const py = `
 import unreal, json
+
+# Helper to resolve SequencerLoopMode from a friendly string
+def _resolve_loop_mode(mode_str):
+    try:
+        m = str(mode_str).lower()
+        slm = unreal.SequencerLoopMode
+        if m in ('once','noloop','no_loop'):
+            return getattr(slm, 'SLM_NoLoop', getattr(slm, 'NoLoop'))
+        if m in ('loop',):
+            return getattr(slm, 'SLM_Loop', getattr(slm, 'Loop'))
+        if m in ('pingpong','ping_pong'):
+            return getattr(slm, 'SLM_PingPong', getattr(slm, 'PingPong'))
+    except Exception:
+        pass
+    return None
+
 try:
     unreal.LevelSequenceEditorBlueprintLibrary.play()
-    ${params?.loopMode ? `unreal.LevelSequenceEditorBlueprintLibrary.set_loop_mode('${params.loopMode}')` : ''}
-    print('RESULT:' + json.dumps({'success': True, 'playing': True}))
+    loop_mode = _resolve_loop_mode('${loop}')
+    if loop_mode is not None:
+        unreal.LevelSequenceEditorBlueprintLibrary.set_loop_mode(loop_mode)
+    print('RESULT:' + json.dumps({'success': True, 'playing': True, 'loopMode': '${loop || 'default'}'}))
 except Exception as e:
     print('RESULT:' + json.dumps({'success': False, 'error': str(e)}))
 `.trim();

package/src/utils/response-validator.ts

@@ -95,40 +95,68 @@ export class ResponseValidator {
   }
 
   /**
-   * Wrap a tool response with validation
+   * Wrap a tool response with validation and MCP-compliant content shape.
+   *
+   * MCP tools/call responses must contain a `content` array. Many internal
+   * handlers return structured JSON objects (e.g., { success, message, ... }).
+   * This wrapper serializes such objects into a single text block while keeping
+   * existing `content` responses intact.
    */
   wrapResponse(toolName: string, response: any): any {
     // Ensure response is safe to serialize first
     try {
-      // The response should already be cleaned, but double-check
       if (response && typeof response === 'object') {
-        // Make sure we can serialize it
         JSON.stringify(response);
       }
     } catch (_error) {
       log.error(`Response for ${toolName} contains circular references, cleaning...`);
       response = cleanObject(response);
     }
-    
-    const validation = this.validateResponse(toolName, response);
-    
-    // Add validation metadata
+
+    // If handler already returned MCP content, keep it as-is (still validate)
+    const alreadyMcpShaped = response && typeof response === 'object' && Array.isArray(response.content);
+
+    // Choose the payload to validate: if already MCP-shaped, validate the
+    // structured content extracted from text; otherwise validate the object directly.
+    const validationTarget = alreadyMcpShaped ? response : response;
+    const validation = this.validateResponse(toolName, validationTarget);
+
     if (!validation.valid) {
       log.warn(`Tool ${toolName} response validation failed:`, validation.errors);
-      
-      // Add warning to response but don't fail
-      if (response && typeof response === 'object') {
-        response._validation = {
-          valid: false,
-          errors: validation.errors
-        };
+    }
+
+    // If it's already MCP-shaped, return as-is (optionally append validation meta)
+    if (alreadyMcpShaped) {
+      if (!validation.valid) {
+        try {
+          (response as any)._validation = { valid: false, errors: validation.errors };
+        } catch {}
       }
+      return response;
     }
 
-    // Don't add structuredContent to the response - it's for internal validation only
-    // Adding it can cause circular references
-    
-    return response;
+    // Otherwise, wrap structured result into MCP content
+    let text: string;
+    try {
+      // Pretty-print small objects for readability
+      text = typeof response === 'string'
+        ? response
+        : JSON.stringify(response ?? { success: true }, null, 2);
+    } catch (_e) {
+      text = String(response);
+    }
+
+    const wrapped = {
+      content: [
+        { type: 'text', text }
+      ]
+    } as any;
+
+    if (!validation.valid) {
+      wrapped._validation = { valid: false, errors: validation.errors };
+    }
+
+    return wrapped;
   }
 
   /**