unreal-engine-mcp-server 0.3.1 → 0.4.3

package/src/tools/ui.ts

@@ -1,22 +1,10 @@
 // UI tools for Unreal Engine
 import { UnrealBridge } from '../unreal-bridge.js';
+import { bestEffortInterpretedText, interpretStandardResult } from '../utils/result-helpers.js';
 
 export class UITools {
   constructor(private bridge: UnrealBridge) {}
 
-  // Execute console command
-  private async _executeCommand(command: string) {
-    return this.bridge.httpCall('/remote/object/call', 'PUT', {
-      objectPath: '/Script/Engine.Default__KismetSystemLibrary',
-      functionName: 'ExecuteConsoleCommand',
-      parameters: {
-        Command: command,
-        SpecificPlayer: null
-      },
-      generateTransaction: false
-    });
-  }
-
   // Create widget blueprint
   async createWidget(params: {
     name: string;
@@ -57,10 +45,20 @@ except Exception as e:
 `.trim();
     try {
       const resp = await this.bridge.executePython(py);
-      const out = typeof resp === 'string' ? resp : JSON.stringify(resp);
-      const m = out.match(/RESULT:({.*})/);
-      if (m) { try { const parsed = JSON.parse(m[1]); return parsed.success ? { success: true, message: 'Widget blueprint created' } : { success: false, error: parsed.error }; } catch {} }
-      return { success: true, message: 'Widget blueprint creation attempted' };
+      const interpreted = interpretStandardResult(resp, {
+        successMessage: 'Widget blueprint created',
+        failureMessage: 'Failed to create WidgetBlueprint'
+      });
+
+      if (interpreted.success) {
+        return { success: true, message: interpreted.message };
+      }
+
+      return {
+        success: false,
+        error: interpreted.error ?? 'Failed to create widget blueprint',
+        details: bestEffortInterpretedText(interpreted)
+      };
     } catch (e) {
       return { success: false, error: `Failed to create widget blueprint: ${e}` };
     }
@@ -78,7 +76,7 @@ except Exception as e:
       alignment?: [number, number];
     };
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`AddWidgetComponent ${params.widgetName} ${params.componentType} ${params.componentName}`);
     
@@ -97,9 +95,7 @@ except Exception as e:
       }
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: `Component ${params.componentName} added to widget` };
   }
@@ -113,7 +109,7 @@ except Exception as e:
     color?: [number, number, number, number];
     fontFamily?: string;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`SetWidgetText ${params.widgetName}.${params.componentName} "${params.text}"`);
     
@@ -129,9 +125,7 @@ except Exception as e:
       commands.push(`SetWidgetFont ${params.widgetName}.${params.componentName} ${params.fontFamily}`);
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: 'Widget text updated' };
   }
@@ -144,7 +138,7 @@ except Exception as e:
     tint?: [number, number, number, number];
     sizeToContent?: boolean;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`SetWidgetImage ${params.widgetName}.${params.componentName} ${params.imagePath}`);
     
@@ -156,9 +150,7 @@ except Exception as e:
       commands.push(`SetWidgetSizeToContent ${params.widgetName}.${params.componentName} ${params.sizeToContent}`);
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: 'Widget image updated' };
   }
@@ -172,7 +164,7 @@ except Exception as e:
       size?: [number, number];
     }>;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`CreateHUDClass ${params.name}`);
     
@@ -183,9 +175,7 @@ except Exception as e:
       }
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: `HUD ${params.name} created` };
   }
@@ -197,11 +187,49 @@ except Exception as e:
     playerIndex?: number;
   }) {
     const playerIndex = params.playerIndex ?? 0;
+    const widgetName = params.widgetName?.trim();
+    if (!widgetName) {
+      return { success: false, error: 'widgetName is required' };
+    }
+
+    const verifyScript = `
+import unreal, json
+name = r"${widgetName}"
+candidates = []
+if name.startswith('/Game/'):
+    candidates.append(name)
+else:
+    candidates.append(f"/Game/UI/Widgets/{name}")
+    candidates.append(f"/Game/{name}")
+
+found_path = ''
+for path in candidates:
+    if unreal.EditorAssetLibrary.does_asset_exist(path):
+        found_path = path
+        break
+
+print('RESULT:' + json.dumps({'success': bool(found_path), 'path': found_path, 'candidates': candidates}))
+`.trim();
+
+    const verify = await this.bridge.executePythonWithResult(verifyScript);
+    if (!verify?.success) {
+      return { success: false, error: `Widget asset not found for ${widgetName}` };
+    }
+
     const command = params.visible 
-      ? `ShowWidget ${params.widgetName} ${playerIndex}`
-      : `HideWidget ${params.widgetName} ${playerIndex}`;
-    
-    return this.bridge.executeConsoleCommand(command);
+      ? `ShowWidget ${widgetName} ${playerIndex}`
+      : `HideWidget ${widgetName} ${playerIndex}`;
+
+    const raw = await this.bridge.executeConsoleCommand(command);
+    const summary = this.bridge.summarizeConsoleCommand(command, raw);
+
+    return {
+      success: true,
+      message: params.visible ? `Widget ${widgetName} show command issued` : `Widget ${widgetName} hide command issued`,
+      command: summary.command,
+      output: summary.output || undefined,
+      logLines: summary.logLines?.length ? summary.logLines : undefined
+    };
   }
 
   // Add widget to viewport
@@ -232,10 +260,20 @@ try:
             # Get the generated class from the widget blueprint
             widget_class = widget_bp.generated_class() if hasattr(widget_bp, 'generated_class') else widget_bp
             
-            # Get the world and player controller
-            world = unreal.EditorLevelLibrary.get_editor_world()
-            if not world:
-                print('RESULT:' + json.dumps({'success': False, 'error': 'No editor world available'}))
+      # Get the world and player controller via modern subsystems
+      world = None
+      try:
+        world = unreal.EditorUtilityLibrary.get_editor_world()
+      except Exception:
+        pass
+
+      if not world:
+        editor_subsystem = unreal.get_editor_subsystem(unreal.UnrealEditorSubsystem)
+        if editor_subsystem and hasattr(editor_subsystem, 'get_editor_world'):
+          world = editor_subsystem.get_editor_world()
+
+      if not world:
+        print('RESULT:' + json.dumps({'success': False, 'error': 'No editor world available. Start a PIE session or enable Editor Scripting Utilities.'}))
             else:
                 # Try to get player controller
                 try:
@@ -261,17 +299,20 @@ except Exception as e:
     
     try {
       const resp = await this.bridge.executePython(py);
-      const out = typeof resp === 'string' ? resp : JSON.stringify(resp);
-      const m = out.match(/RESULT:({.*})/);
-      if (m) {
-        try {
-          const parsed = JSON.parse(m[1]);
-          return parsed.success 
-            ? { success: true, message: `Widget added to viewport with z-order ${zOrder}` }
-            : { success: false, error: parsed.error };
-        } catch {}
+      const interpreted = interpretStandardResult(resp, {
+        successMessage: `Widget added to viewport with z-order ${zOrder}`,
+        failureMessage: 'Failed to add widget to viewport'
+      });
+
+      if (interpreted.success) {
+        return { success: true, message: interpreted.message };
       }
-      return { success: true, message: 'Widget add to viewport attempted' };
+
+      return {
+        success: false,
+        error: interpreted.error ?? 'Failed to add widget to viewport',
+        details: bestEffortInterpretedText(interpreted)
+      };
     } catch (e) {
       return { success: false, error: `Failed to add widget to viewport: ${e}` };
     }
@@ -297,7 +338,7 @@ except Exception as e:
       position?: [number, number];
     }>;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`CreateMenuWidget ${params.name} ${params.menuType}`);
     
@@ -308,9 +349,7 @@ except Exception as e:
       }
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: `Menu ${params.name} created` };
   }
@@ -329,7 +368,7 @@ except Exception as e:
       }>;
     }>;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`CreateWidgetAnimation ${params.widgetName} ${params.animationName} ${params.duration}`);
     
@@ -344,9 +383,7 @@ except Exception as e:
       }
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: `Animation ${params.animationName} created` };
   }
@@ -377,7 +414,7 @@ except Exception as e:
       margin?: [number, number, number, number];
     };
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     if (params.style.backgroundColor) {
       commands.push(`SetWidgetBackgroundColor ${params.widgetName}.${params.componentName} ${params.style.backgroundColor.join(' ')}`);
@@ -399,9 +436,7 @@ except Exception as e:
       commands.push(`SetWidgetMargin ${params.widgetName}.${params.componentName} ${params.style.margin.join(' ')}`);
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: 'Widget style updated' };
   }
@@ -423,7 +458,7 @@ except Exception as e:
     showCursor?: boolean;
     lockCursor?: boolean;
   }) {
-    const commands = [];
+  const commands: string[] = [];
     
     commands.push(`SetInputMode ${params.mode}`);
     
@@ -435,9 +470,7 @@ except Exception as e:
       commands.push(`SetMouseLockMode ${params.lockCursor}`);
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: `Input mode set to ${params.mode}` };
   }
@@ -475,9 +508,7 @@ except Exception as e:
       }
     }
     
-    for (const cmd of commands) {
-      await this.bridge.executeConsoleCommand(cmd);
-    }
+    await this.bridge.executeConsoleCommands(commands);
     
     return { success: true, message: 'Drag and drop configured' };
   }

package/src/tools/visual.ts

@@ -1,60 +1,281 @@
 import { UnrealBridge } from '../unreal-bridge.js';
 import { loadEnv } from '../types/env.js';
-import fs from 'fs';
+import { Logger } from '../utils/logger.js';
+import { coerceStringArray, interpretStandardResult } from '../utils/result-helpers.js';
+import { promises as fs } from 'fs';
 import path from 'path';
 
 export class VisualTools {
   private env = loadEnv();
+  private log = new Logger('VisualTools');
   constructor(private bridge: UnrealBridge) {}
 
   // Take a screenshot of viewport (high res or standard). Returns path and base64 (truncated)
   async takeScreenshot(params: { resolution?: string }) {
     const res = params.resolution && /^\d+x\d+$/i.test(params.resolution) ? params.resolution : '';
-    const cmd = res ? `HighResShot ${res}` : 'HighResShot';
+  const primaryCommand = res ? `HighResShot ${res}` : 'Shot';
+    const captureStartedAt = Date.now();
     try {
-      await this.bridge.executeConsoleCommand(cmd);
-      // Give the engine a moment to write the file
-await new Promise(r => setTimeout(r, 1200));
-      const p = await this.findLatestScreenshot();
-      if (!p) return { success: true, message: 'Screenshot triggered, but could not locate output file' };
+      const firstAttempt = await this.bridge.executeConsoleCommand(primaryCommand);
+      const firstSummary = this.bridge.summarizeConsoleCommand(primaryCommand, firstAttempt);
+
+      if (!res) {
+        const output = (firstSummary.output || '').toLowerCase();
+        const badInput = output.includes('bad input') || output.includes('unrecognized command');
+        const hasErrorLine = firstSummary.logLines?.some(line => /error:/i.test(line));
+        if (badInput || hasErrorLine) {
+          this.log.debug(`Screenshot primary command reported an error (${firstSummary.output || 'no output'})`);
+        }
+      }
+      // Give the engine a moment to write the file (UE can flush asynchronously)
+      await new Promise(r => setTimeout(r, 1200));
+      const p = await this.findLatestScreenshot(captureStartedAt);
+      if (!p) {
+        this.log.warn('Screenshot captured but output file was not found');
+        return { success: true, message: 'Screenshot triggered, but could not locate output file' };
+      }
       let b64: string | undefined;
+      let truncated = false;
+      let sizeBytes: number | undefined;
+      let mime: string | undefined;
       try {
-        const buf = fs.readFileSync(p);
-        // Limit to ~1MB to avoid huge responses
-        const max = 1024 * 1024;
-        b64 = buf.length > max ? buf.subarray(0, max).toString('base64') : buf.toString('base64');
+        const stat = await fs.stat(p);
+        sizeBytes = stat.size;
+        const max = 1024 * 1024; // 1 MiB cap for inline payloads
+        if (stat.size <= max) {
+          const buf = await fs.readFile(p);
+          b64 = buf.toString('base64');
+        } else {
+          truncated = true;
+        }
+        const ext = path.extname(p).toLowerCase();
+        if (ext === '.png') mime = 'image/png';
+        else if (ext === '.jpg' || ext === '.jpeg') mime = 'image/jpeg';
+        else if (ext === '.bmp') mime = 'image/bmp';
       } catch {}
-      return { success: true, imagePath: p, imageBase64: b64 };
+      return {
+        success: true,
+        imagePath: p.replace(/\\/g, '/'),
+        imageMimeType: mime,
+        imageSizeBytes: sizeBytes,
+        imageBase64: b64,
+        imageBase64Truncated: truncated
+      };
     } catch (err: any) {
       return { success: false, error: String(err?.message || err) };
     }
   }
 
-  private async findLatestScreenshot(): Promise<string | null> {
+  private async getEngineScreenshotDirectories(): Promise<string[]> {
+    const python = `
+import unreal
+import json
+import os
+
+result = {
+  "success": True,
+  "message": "",
+  "error": "",
+  "directories": [],
+  "warnings": [],
+  "details": []
+}
+
+def finalize():
+  data = dict(result)
+  if data.get("success"):
+    if not data.get("message"):
+      data["message"] = "Collected screenshot directories"
+    data.pop("error", None)
+  else:
+    if not data.get("error"):
+      data["error"] = data.get("message") or "Failed to collect screenshot directories"
+    if not data.get("message"):
+      data["message"] = data["error"]
+  if not data.get("warnings"):
+    data.pop("warnings", None)
+  if not data.get("details"):
+    data.pop("details", None)
+  if not data.get("directories"):
+    data.pop("directories", None)
+  return data
+
+def add_path(candidate, note=None):
+  if not candidate:
+    return
+  try:
+    abs_path = os.path.abspath(os.path.normpath(candidate))
+  except Exception as normalize_error:
+    result["warnings"].append(f"Failed to normalize path {candidate}: {normalize_error}")
+    return
+  if abs_path not in result["directories"]:
+    result["directories"].append(abs_path)
+    if note:
+      result["details"].append(f"{note}: {abs_path}")
+    else:
+      result["details"].append(f"Discovered screenshot directory: {abs_path}")
+
+try:
+  automation_dir = unreal.AutomationLibrary.get_screenshot_directory()
+  add_path(automation_dir, "Automation screenshot directory")
+except Exception as automation_error:
+  result["warnings"].append(f"Automation screenshot directory unavailable: {automation_error}")
+
+try:
+  project_saved = unreal.Paths.project_saved_dir()
+  add_path(project_saved, "Project Saved directory")
+  if project_saved:
+    add_path(os.path.join(project_saved, 'Screenshots'), "Project Saved screenshots")
+    add_path(os.path.join(project_saved, 'Screenshots', 'Windows'), "Project Saved Windows screenshots")
+    add_path(os.path.join(project_saved, 'Screenshots', 'WindowsEditor'), "Project Saved WindowsEditor screenshots")
+    try:
+      platform_name = unreal.SystemLibrary.get_platform_user_name()
+      if platform_name:
+        add_path(os.path.join(project_saved, 'Screenshots', platform_name), f"Project Saved screenshots for {platform_name}")
+        add_path(os.path.join(project_saved, 'Screenshots', f"{platform_name}Editor"), f"Project Saved editor screenshots for {platform_name}")
+    except Exception as platform_error:
+      result["warnings"].append(f"Failed to resolve platform-specific screenshot directories: {platform_error}")
+except Exception as saved_error:
+  result["warnings"].append(f"Project Saved directory unavailable: {saved_error}")
+
+try:
+  project_file = unreal.Paths.get_project_file_path()
+  if project_file:
+    project_dir = os.path.dirname(project_file)
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots'), "Project directory screenshots")
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots', 'Windows'), "Project directory Windows screenshots")
+    add_path(os.path.join(project_dir, 'Saved', 'Screenshots', 'WindowsEditor'), "Project directory WindowsEditor screenshots")
+except Exception as project_error:
+  result["warnings"].append(f"Project directory screenshots unavailable: {project_error}")
+
+if not result["directories"]:
+  result["warnings"].append("No screenshot directories discovered")
+
+print('RESULT:' + json.dumps(finalize()))
+`.trim()
+  .replace(/\r?\n/g, '\n');
+
+    try {
+      const response = await this.bridge.executePython(python);
+      const interpreted = interpretStandardResult(response, {
+        successMessage: 'Collected screenshot directories',
+        failureMessage: 'Failed to collect screenshot directories'
+      });
+
+      if (interpreted.details) {
+        for (const entry of interpreted.details) {
+          this.log.debug(entry);
+        }
+      }
+
+      if (interpreted.warnings) {
+        for (const warning of interpreted.warnings) {
+          this.log.debug(`Screenshot directory warning: ${warning}`);
+        }
+      }
+
+      const directories = coerceStringArray(interpreted.payload.directories);
+      if (directories?.length) {
+        return directories;
+      }
+
+      if (!interpreted.success && interpreted.error) {
+        this.log.warn(`Screenshot path probe failed: ${interpreted.error}`);
+      }
+
+      if (interpreted.rawText) {
+        try {
+          const fallback = JSON.parse(interpreted.rawText);
+          const fallbackDirs = coerceStringArray(fallback);
+          if (fallbackDirs?.length) {
+            return fallbackDirs;
+          }
+        } catch {}
+      }
+    } catch (err) {
+      this.log.debug('Screenshot path probe failed', err);
+    }
+    return [];
+  }
+
+  private async findLatestScreenshot(since?: number): Promise<string | null> {
     // Try env override, otherwise look in common UE Saved/Screenshots folder under project
     const candidates: string[] = [];
-    if (this.env.UE_SCREENSHOT_DIR) candidates.push(this.env.UE_SCREENSHOT_DIR);
+    const seen = new Set<string>();
+    const addCandidate = (candidate?: string | null) => {
+      if (!candidate) return;
+      const normalized = path.isAbsolute(candidate)
+        ? path.normalize(candidate)
+        : path.resolve(candidate);
+      if (!seen.has(normalized)) {
+        seen.add(normalized);
+        candidates.push(normalized);
+      }
+    };
+
+    if (this.env.UE_SCREENSHOT_DIR) addCandidate(this.env.UE_SCREENSHOT_DIR);
     if (this.env.UE_PROJECT_PATH) {
       const projectDir = path.dirname(this.env.UE_PROJECT_PATH);
-      candidates.push(path.join(projectDir, 'Saved', 'Screenshots'));
-candidates.push(path.join(projectDir, 'Saved', 'Screenshots', 'Windows'));
-      candidates.push(path.join(projectDir, 'Saved', 'Screenshots', 'WindowsEditor'));
+      addCandidate(path.join(projectDir, 'Saved', 'Screenshots'));
+      addCandidate(path.join(projectDir, 'Saved', 'Screenshots', 'Windows'));
+      addCandidate(path.join(projectDir, 'Saved', 'Screenshots', 'WindowsEditor'));
     }
-    // Fallback: common locations
-candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots'));
-    candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots', 'Windows'));
-    candidates.push(path.join(process.cwd(), 'Saved', 'Screenshots', 'WindowsEditor'));
-    let latest: { path: string; mtime: number } | null = null;
-    for (const c of candidates) {
+
+    const engineDirs = await this.getEngineScreenshotDirectories();
+    for (const dir of engineDirs) {
+      addCandidate(dir);
+    }
+
+    // Fallback: common locations relative to current working directory
+    addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots'));
+    addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots', 'Windows'));
+    addCandidate(path.join(process.cwd(), 'Saved', 'Screenshots', 'WindowsEditor'));
+
+    const searchDirs = new Set<string>();
+    const queue: string[] = [...candidates];
+    while (queue.length) {
+      const candidate = queue.pop();
+      if (!candidate || searchDirs.has(candidate)) continue;
+      searchDirs.add(candidate);
       try {
-        const entries = fs.readdirSync(c).map(f => path.join(c, f));
-        for (const fp of entries) {
-          if (!/\.png$/i.test(fp)) continue;
-          const st = fs.statSync(fp);
-          if (!latest || st.mtimeMs > latest.mtime) latest = { path: fp, mtime: st.mtimeMs };
+        const entries = await fs.readdir(candidate, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.isDirectory()) {
+            queue.push(path.join(candidate, entry.name));
+          }
         }
       } catch {}
     }
-    return latest?.path || null;
+
+    let latest: { path: string; mtime: number } | null = null;
+    let latestSince: { path: string; mtime: number } | null = null;
+    const cutoff = since ? since - 2000 : undefined; // allow slight clock drift
+
+    for (const dirPath of searchDirs) {
+      let entries: string[];
+      try {
+        entries = await fs.readdir(dirPath);
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        const fp = path.join(dirPath, entry);
+        if (!/\.(png|jpg|jpeg|bmp)$/i.test(fp)) continue;
+        try {
+          const st = await fs.stat(fp);
+          const info = { path: fp, mtime: st.mtimeMs };
+          if (!latest || info.mtime > latest.mtime) {
+            latest = info;
+          }
+          if (cutoff !== undefined && st.mtimeMs >= cutoff) {
+            if (!latestSince || info.mtime > latestSince.mtime) {
+              latestSince = info;
+            }
+          }
+        } catch {}
+      }
+    }
+    const chosen = latestSince || latest;
+    return chosen?.path || null;
   }
 }

package/src/types/tool-types.ts

@@ -332,12 +332,3 @@ export type GetToolResponse<T extends ToolName> = ToolResponseMap[T];
 // Helper type for getting parameters by tool name
 export type GetToolParams<T extends keyof ConsolidatedToolParams> = ConsolidatedToolParams[T];
 
-// Export a type guard to check if a response is successful
-export function isSuccessResponse(response: BaseToolResponse): response is BaseToolResponse & { success: true } {
-  return response.success === true;
-}
-
-// Export a type guard to check if a response has an error
-export function isErrorResponse(response: BaseToolResponse): response is BaseToolResponse & { error: string } {
-  return response.success === false && typeof response.error === 'string';
-}