unreal-engine-mcp-server 0.4.0 → 0.4.3

package/src/tools/materials.ts

@@ -1,133 +1,149 @@
 import { UnrealBridge } from '../unreal-bridge.js';
+import { coerceBoolean, interpretStandardResult } from '../utils/result-helpers.js';
+import { escapePythonString } from '../utils/python.js';
 
 export class MaterialTools {
   constructor(private bridge: UnrealBridge) {}
 
   async createMaterial(name: string, path: string) {
     try {
-      // Validate name
       if (!name || name.trim() === '') {
         return { success: false, error: 'Material name cannot be empty' };
       }
-      
-      // Check name length (Unreal has 260 char path limit)
+
       if (name.length > 100) {
         return { success: false, error: `Material name too long (${name.length} chars). Maximum is 100 characters.` };
       }
-      
-      // Validate name doesn't contain invalid characters
-      // Unreal Engine doesn't allow: spaces, dots, slashes, backslashes, pipes, angle brackets, 
-      // curly braces, square brackets, parentheses, @, #, etc.
+
       const invalidChars = /[\s./<>|{}[\]()@#\\]/;
       if (invalidChars.test(name)) {
         const foundChars = name.match(invalidChars);
         return { success: false, error: `Material name contains invalid characters: '${foundChars?.[0]}'. Avoid spaces, dots, slashes, backslashes, brackets, and special symbols.` };
       }
-      
-      // Validate path type
+
       if (typeof path !== 'string') {
         return { success: false, error: `Invalid path type: expected string, got ${typeof path}` };
       }
-      
-      // Clean up path - remove trailing slashes
-      const cleanPath = path.replace(/\/$/, '');
-      
-      // Validate path starts with /Game or /Engine
+
+      const trimmedPath = path.trim();
+      const effectivePath = trimmedPath.length === 0 ? '/Game' : trimmedPath;
+      const cleanPath = effectivePath.replace(/\/$/, '');
+
       if (!cleanPath.startsWith('/Game') && !cleanPath.startsWith('/Engine')) {
         return { success: false, error: `Invalid path: must start with /Game or /Engine, got ${cleanPath}` };
       }
-      
-      // Use Python API to create material
-      const materialPath = `${cleanPath}/${name}`;
-      // Use the correct Unreal Engine 5 Python API
+
+      const normalizedPath = cleanPath.toLowerCase();
+      const restrictedPrefixes = ['/engine/restricted', '/engine/generated', '/engine/transient'];
+      if (restrictedPrefixes.some(prefix => normalizedPath.startsWith(prefix))) {
+        const errorMessage = `Destination path is read-only and cannot be used for material creation: ${cleanPath}`;
+        return { success: false, error: errorMessage, message: errorMessage };
+      }
+
+    const materialPath = `${cleanPath}/${name}`;
+    const payload = { name, cleanPath, materialPath };
+    const escapedName = escapePythonString(name);
       const pythonCode = `
-import unreal
-import json
+import unreal, json
+
+payload = json.loads(r'''${JSON.stringify(payload)}''')
+result = {
+    'success': False,
+    'message': '',
+    'error': '',
+    'warnings': [],
+    'details': [],
+    'name': payload.get('name') or "${escapedName}",
+    'path': payload.get('materialPath')
+}
+
+material_path = result['path']
+clean_path = payload.get('cleanPath') or '/Game'
 
 try:
-    # Check if material already exists
-    material_path = '${materialPath}'
     if unreal.EditorAssetLibrary.does_asset_exist(material_path):
-        print(json.dumps({"success": True, "exists": True, "path": material_path}))
+        result['success'] = True
+        result['exists'] = True
+        result['message'] = f"Material already exists at {material_path}"
     else:
-        # Get the AssetTools
         asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
-        
-        # Create a MaterialFactoryNew
         factory = unreal.MaterialFactoryNew()
-        
-        # Clean up the path - remove trailing slashes
-        clean_path = '${cleanPath}'.rstrip('/')
-        
-        # Create the material asset at the specified path
-        # The path should be: /Game/FolderName and asset name separately
         asset = asset_tools.create_asset(
-            asset_name='${name}',
+            asset_name=payload.get('name'),
             package_path=clean_path,
             asset_class=unreal.Material,
             factory=factory
         )
-        
         if asset:
-            # Save the package
             unreal.EditorAssetLibrary.save_asset(material_path)
-            print(json.dumps({"success": True, "created": True, "path": material_path}))
+            result['success'] = True
+            result['created'] = True
+            result['message'] = f"Material created at {material_path}"
         else:
-            print(json.dumps({"success": False, "error": "Failed to create material"}))
-except Exception as e:
-    print(json.dumps({"success": False, "error": str(e)}))
+            result['error'] = 'Failed to create material'
+            result['message'] = result['error']
+except Exception as exc:
+    result['error'] = str(exc)
+    if not result['message']:
+        result['message'] = result['error']
+
+print('RESULT:' + json.dumps(result))
 `.trim();
-      
+
       const pyResult = await this.bridge.executePython(pythonCode);
-      
-      // Parse the Python response
-      let responseStr = '';
-      if (pyResult?.LogOutput && Array.isArray(pyResult.LogOutput)) {
-        responseStr = pyResult.LogOutput.map((log: any) => log.Output || '').join('');
-      } else if (typeof pyResult === 'string') {
-        responseStr = pyResult;
-      } else {
-        responseStr = JSON.stringify(pyResult);
+      const interpreted = interpretStandardResult(pyResult, {
+        successMessage: `Material ${name} processed`,
+        failureMessage: 'Failed to create material'
+      });
+
+      if (interpreted.success) {
+        const exists = coerceBoolean(interpreted.payload.exists, false) === true;
+        const created = coerceBoolean(interpreted.payload.created, false) === true;
+        if (exists) {
+          return { success: true, path: materialPath, message: `Material ${name} already exists at ${materialPath}` };
+        }
+        if (created) {
+          return { success: true, path: materialPath, message: `Material ${name} created at ${materialPath}` };
+        }
+        return { success: true, path: materialPath, message: interpreted.message };
       }
-      
-      // Try to extract JSON response
-      try {
-        // Look for JSON in the output
-        const jsonMatch = responseStr.match(/\{.*\}/s);
-        if (jsonMatch) {
-          const result = JSON.parse(jsonMatch[0]);
-          if (result.success) {
-            if (result.exists) {
-              return { success: true, path: materialPath, message: `Material ${name} already exists at ${path}` };
-            } else if (result.created) {
-              return { success: true, path: materialPath, message: `Material ${name} created at ${path}` };
-            }
-          } else {
-            return { success: false, error: result.error || 'Failed to create material' };
-          }
+
+      if (interpreted.error) {
+        const exists = await this.assetExists(materialPath);
+        if (exists) {
+          return {
+            success: true,
+            path: materialPath,
+            message: `Material ${name} created at ${materialPath}`,
+            warnings: interpreted.warnings,
+            details: interpreted.details
+          };
         }
-      } catch {
-        // JSON parsing failed, fall back to verification
+        return {
+          success: false,
+          error: interpreted.error,
+          warnings: interpreted.warnings,
+          details: interpreted.details
+        };
       }
 
-      // Fallback: Verify creation using EditorAssetLibrary
-      let verify: any = {};
-      try {
-        verify = await this.bridge.call({
-          objectPath: '/Script/EditorScriptingUtilities.Default__EditorAssetLibrary',
-          functionName: 'DoesAssetExist',
-          parameters: {
-            AssetPath: materialPath
-          }
-        });
-      } catch {}
-
-      const exists = verify?.ReturnValue === true || verify?.Result === true;
+      const exists = await this.assetExists(materialPath);
       if (exists) {
-        return { success: true, path: materialPath, message: `Material ${name} created at ${path}` };
-      } else {
-        return { success: false, error: 'Material creation may have failed. Check Output Log for details.', debug: responseStr };
+        return {
+          success: true,
+          path: materialPath,
+          message: `Material ${name} created at ${materialPath}`,
+          warnings: interpreted.warnings,
+          details: interpreted.details
+        };
       }
+
+      return {
+        success: false,
+        error: interpreted.message,
+        warnings: interpreted.warnings,
+        details: interpreted.details
+      };
     } catch (err) {
       return { success: false, error: `Failed to create material: ${err}` };
     }
@@ -145,4 +161,19 @@ except Exception as e:
       return { success: false, error: `Failed to apply material: ${err}` };
     }
   }
+
+  private async assetExists(assetPath: string): Promise<boolean> {
+    try {
+      const response = await this.bridge.call({
+        objectPath: '/Script/EditorScriptingUtilities.Default__EditorAssetLibrary',
+        functionName: 'DoesAssetExist',
+        parameters: {
+          AssetPath: assetPath
+        }
+      });
+      return coerceBoolean(response?.ReturnValue ?? response?.Result ?? response, false) === true;
+    } catch {
+      return false;
+    }
+  }
 }

package/src/tools/niagara.ts

@@ -1,5 +1,6 @@
 import { UnrealBridge } from '../unreal-bridge.js';
 import { sanitizeAssetName, validateAssetParams } from '../utils/validation.js';
+import { interpretStandardResult, coerceString } from '../utils/result-helpers.js';
 
 export class NiagaraTools {
   constructor(private bridge: UnrealBridge) {}
@@ -21,54 +22,50 @@ export class NiagaraTools {
   }) {
     try {
     const path = params.savePath || '/Game/Effects/Niagara';
-    // const fullPath = `${path}/${params.name}`; // Currently unused
-      const python = `
+    const python = `
 import unreal
+import json
+
 path = r"${path}"
 name = r"${params.name}"
 full_path = f"{path}/{name}"
-# If already exists, just report success
+
 if unreal.EditorAssetLibrary.does_asset_exist(full_path):
-    print("RESULT:{'success': True, 'path': '" + full_path + "', 'existing': True}")
+    print('RESULT:' + json.dumps({'success': True, 'path': full_path, 'existing': True}))
 else:
     asset_tools = unreal.AssetToolsHelpers.get_asset_tools()
     factory = None
     try:
         factory = unreal.NiagaraSystemFactoryNew()
-    except Exception as e:
+    except Exception:
         factory = None
+
     if factory is None:
-        print("RESULT:{'success': False, 'error': 'NiagaraSystemFactoryNew unavailable'}")
+        print('RESULT:' + json.dumps({'success': False, 'error': 'NiagaraSystemFactoryNew unavailable'}))
     else:
         asset = asset_tools.create_asset(asset_name=name, package_path=path, asset_class=unreal.NiagaraSystem, factory=factory)
         if asset:
             unreal.EditorAssetLibrary.save_asset(full_path)
-            print("RESULT:{'success': True, 'path': '" + full_path + "'}")
+            print('RESULT:' + json.dumps({'success': True, 'path': full_path}))
         else:
-            print("RESULT:{'success': False, 'error': 'AssetTools create_asset failed'}")
+            print('RESULT:' + json.dumps({'success': False, 'error': 'AssetTools create_asset failed'}))
 `.trim();
       const resp = await this.bridge.executePython(python);
-      let output = '';
-      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) {
-        output = resp.LogOutput.map((l: any) => l.Output || '').join('');
-      } else if (typeof resp === 'string') {
-        output = resp;
-      } else {
-        output = JSON.stringify(resp);
-      }
-      const m = output.match(/RESULT:({.*})/);
-      if (m) {
-        try {
-          const parsed = JSON.parse(m[1].replace(/'/g, '"'));
-          if (parsed.success) {
-            return { success: true, path: parsed.path, message: `Niagara system ${params.name} created` };
-          }
-          return { success: false, error: parsed.error || 'Unknown error creating Niagara system' };
-        } catch {
-          // fallthrough
-        }
+      const interpreted = interpretStandardResult(resp, {
+        successMessage: `Niagara system ${params.name} created`,
+        failureMessage: `Failed to create Niagara system ${params.name}`
+      });
+
+      if (!interpreted.success) {
+        return { success: false, error: interpreted.error ?? interpreted.message };
       }
-      return { success: false, error: 'No RESULT from Python when creating Niagara system' };
+
+      const pathFromPayload = coerceString(interpreted.payload.path) ?? `${path}/${params.name}`;
+      return {
+        success: true,
+        path: pathFromPayload,
+        message: interpreted.message
+      };
     } catch (err) {
       return { success: false, error: `Failed to create Niagara system: ${err}` };
     }
@@ -122,9 +119,7 @@ else:
           commands.push(`SetEmitterMesh ${params.systemName} ${params.emitterName} ${props.mesh}`);
         }
       }
-      for (const cmd of commands) {
-        await this.bridge.executeConsoleCommand(cmd);
-      }
+      await this.bridge.executeConsoleCommands(commands);
       return { success: true, message: `Emitter ${params.emitterName} added to ${params.systemName}` };
     } catch (err) {
       return { success: false, error: `Failed to add emitter: ${err}` };
@@ -192,21 +187,24 @@ else:
       // Verify existence via Python to avoid RC EditorAssetLibrary issues
       const verifyPy = `
 import unreal
+import json
+
 p = r"${fullPath}"
-print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLibrary.does_asset_exist(p) else 'False'))
+exists = bool(unreal.EditorAssetLibrary.does_asset_exist(p))
+print('RESULT:' + json.dumps({'success': True, 'exists': exists}))
 `.trim();
       const verifyResp = await this.bridge.executePython(verifyPy);
-      let vout = '';
-      if (verifyResp?.LogOutput && Array.isArray(verifyResp.LogOutput)) vout = verifyResp.LogOutput.map((l: any) => l.Output || '').join('');
-      else if (typeof verifyResp === 'string') vout = verifyResp; else vout = JSON.stringify(verifyResp);
-      const m = vout.match(/RESULT:({.*})/);
-      if (m) {
-        try {
-          const parsed = JSON.parse(m[1].replace(/'/g, '"'));
-          if (!parsed.exists) {
-            return { success: false, error: `Asset not found after creation: ${fullPath}` };
-          }
-        } catch {}
+      const verifyResult = interpretStandardResult(verifyResp, {
+        successMessage: 'Niagara asset verification complete',
+        failureMessage: `Failed to verify Niagara asset at ${fullPath}`
+      });
+
+      if (!verifyResult.success) {
+        return { success: false, error: verifyResult.error ?? verifyResult.message };
+      }
+
+      if (verifyResult.payload.exists === false) {
+        return { success: false, error: `Asset not found after creation: ${fullPath}` };
       }
 
       return { success: true, message: `${params.effectType} effect ${safeName} created`, path: fullPath };
@@ -237,7 +235,7 @@ print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLi
         if (s.gridResolution) { const r = s.gridResolution; commands.push(`SetGPUGridResolution ${params.name} ${r[0]} ${r[1]} ${r[2]}`); }
         if (s.iterations !== undefined) commands.push(`SetGPUIterations ${params.name} ${s.iterations}`);
       }
-      for (const cmd of commands) await this.bridge.executeConsoleCommand(cmd);
+  await this.bridge.executeConsoleCommands(commands);
       return { success: true, message: `GPU simulation ${params.name} created`, path: `${path}/${params.name}` };
     } catch (err) {
       return { success: false, error: `Failed to create GPU simulation: ${err}` };
@@ -259,54 +257,62 @@ print("RESULT:{'success': True, 'exists': %s}" % ('True' if unreal.EditorAssetLi
       const loc = Array.isArray(params.location) ? { x: params.location[0], y: params.location[1], z: params.location[2] } : params.location;
       const rot = params.rotation || [0, 0, 0];
       const scl = Array.isArray(params.scale) ? params.scale : (typeof params.scale === 'number' ? [params.scale, params.scale, params.scale] : [1, 1, 1]);
-      const py = `
+    const py = `
 import unreal
+import json
+
 loc = unreal.Vector(${loc.x || 0}, ${loc.y || 0}, ${loc.z || 0})
 rot = unreal.Rotator(${rot[0]}, ${rot[1]}, ${rot[2]})
 scale = unreal.Vector(${scl[0]}, ${scl[1]}, ${scl[2]})
 sys_path = r"${params.systemPath}"
+
 if unreal.EditorAssetLibrary.does_asset_exist(sys_path):
-    sys = unreal.EditorAssetLibrary.load_asset(sys_path)
-    actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
-    actor = actor_subsystem.spawn_actor_from_class(unreal.NiagaraActor, loc, rot)
-    if actor:
-        comp = actor.get_niagara_component()
-        try:
-            comp.set_asset(sys)
-        except Exception:
-            try:
-                comp.set_editor_property('asset', sys)
-            except Exception:
-                pass
-        comp.set_world_scale3d(scale)
-        comp.activate(True)
-        actor.set_actor_label(f"Niagara_{unreal.SystemLibrary.get_game_time_in_seconds(actor.get_world()):.0f}")
-        print("RESULT:{'success': True, 'actor': '" + actor.get_actor_label() + "'}")
-    else:
-        print("RESULT:{'success': False, 'error': 'Failed to spawn NiagaraActor'}")
+  sys = unreal.EditorAssetLibrary.load_asset(sys_path)
+  actor_subsystem = unreal.get_editor_subsystem(unreal.EditorActorSubsystem)
+  actor = actor_subsystem.spawn_actor_from_class(unreal.NiagaraActor, loc, rot)
+  if actor:
+    comp = actor.get_niagara_component()
+    try:
+      comp.set_asset(sys)
+    except Exception:
+      try:
+        comp.set_editor_property('asset', sys)
+      except Exception:
+        pass
+    comp.set_world_scale3d(scale)
+    comp.activate(True)
+    actor.set_actor_label(f"Niagara_{unreal.SystemLibrary.get_game_time_in_seconds(actor.get_world()):.0f}")
+    print('RESULT:' + json.dumps({'success': True, 'actor': actor.get_actor_label()}))
+  else:
+    print('RESULT:' + json.dumps({'success': False, 'error': 'Failed to spawn NiagaraActor'}))
 else:
-    print("RESULT:{'success': False, 'error': 'System asset not found'}")
+  print('RESULT:' + json.dumps({'success': False, 'error': 'System asset not found'}))
 `.trim();
-      const resp = await this.bridge.executePython(py);
-      let output = '';
-      if (resp?.LogOutput && Array.isArray(resp.LogOutput)) output = resp.LogOutput.map((l: any) => l.Output || '').join('');
-      else if (typeof resp === 'string') output = resp; else output = JSON.stringify(resp);
-      const m = output.match(/RESULT:({.*})/);
-      if (m) {
-        try { const parsed = JSON.parse(m[1].replace(/'/g, '"')); return parsed.success ? { success: true, message: 'Niagara effect spawned' } : { success: false, error: parsed.error || 'Spawn failed' }; } catch {}
-      }
-      return { success: true, message: 'Niagara effect spawn attempted' };
+    const resp = await this.bridge.executePython(py);
+    const interpreted = interpretStandardResult(resp, {
+      successMessage: 'Niagara effect spawned',
+      failureMessage: 'Failed to spawn Niagara effect'
+    });
+
+    const actorLabel = coerceString(interpreted.payload.actor);
+
+    if (!interpreted.success) {
+      return { success: false, error: interpreted.error ?? interpreted.message };
+    }
+
+    const outcome: { success: true; message: string; actor?: string } = {
+      success: true,
+      message: interpreted.message
+    };
+
+    if (actorLabel) {
+      outcome.actor = actorLabel;
+    }
+
+    return outcome;
     } catch (err) {
       return { success: false, error: `Failed to spawn effect: ${err}` };
     }
   }
 
-  private async _executeCommand(command: string) {
-    return this.bridge.httpCall('/remote/object/call', 'PUT', {
-      objectPath: '/Script/Engine.Default__KismetSystemLibrary',
-      functionName: 'ExecuteConsoleCommand',
-      parameters: { WorldContextObject: null, Command: command, SpecificPlayer: null },
-      generateTransaction: false
-    });
-  }
 }