unreal-engine-mcp-server 0.4.5 → 0.4.7

package/dist/tools/logs.js

@@ -0,0 +1,262 @@
+import { loadEnv } from '../types/env.js';
+import { Logger } from '../utils/logger.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+export class LogTools {
+    bridge;
+    env = loadEnv();
+    log = new Logger('LogTools');
+    cachedLogPath;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async readOutputLog(params) {
+        const target = await this.resolveLogPath(params.logPath);
+        if (!target) {
+            return { success: false, error: 'Log file not found' };
+        }
+        const maxLines = typeof params.lines === 'number' && params.lines > 0 ? Math.min(params.lines, 2000) : 200;
+        let text = '';
+        try {
+            text = await this.tailFile(target, maxLines);
+        }
+        catch (err) {
+            return { success: false, error: String(err?.message || err) };
+        }
+        const rawLines = text.split(/\r?\n/).filter(l => l.length > 0);
+        const parsed = rawLines.map(l => this.parseLine(l));
+        const mappedLevel = params.filterLevel || 'All';
+        const includeCats = Array.isArray(params.filterCategory) && params.filterCategory.length ? new Set(params.filterCategory) : undefined;
+        const includePrefixes = Array.isArray(params.includePrefixes) && params.includePrefixes.length ? params.includePrefixes : undefined;
+        const excludeCats = Array.isArray(params.excludeCategories) && params.excludeCategories.length ? new Set(params.excludeCategories) : undefined;
+        const filtered = parsed.filter(e => {
+            if (!e)
+                return false;
+            if (mappedLevel && mappedLevel !== 'All') {
+                const lv = (e.level || 'Log');
+                if (lv === 'Display') {
+                    if (mappedLevel !== 'Log')
+                        return false;
+                }
+                else if (lv !== mappedLevel) {
+                    return false;
+                }
+            }
+            if (includeCats && e.category && !includeCats.has(e.category))
+                return false;
+            if (includePrefixes && includePrefixes.length && e.category) {
+                if (!includePrefixes.some(p => (e.category ?? '').startsWith(p)))
+                    return false;
+            }
+            if (excludeCats && e.category && excludeCats.has(e.category))
+                return false;
+            return true;
+        });
+        const includeInternal = Boolean((includeCats && includeCats.has('LogPython')) ||
+            (includePrefixes && includePrefixes.some(p => 'LogPython'.startsWith(p))));
+        const sanitized = includeInternal ? filtered : filtered.filter(entry => !this.isInternalLogEntry(entry));
+        return { success: true, logPath: target.replace(/\\/g, '/'), entries: sanitized, filteredCount: sanitized.length };
+    }
+    async resolveLogPath(override) {
+        if (override && typeof override === 'string' && override.trim()) {
+            try {
+                const st = await fs.stat(override);
+                if (st.isFile()) {
+                    return this.cacheLogPath(path.resolve(override));
+                }
+            }
+            catch { }
+        }
+        if (this.cachedLogPath && (await this.fileExists(this.cachedLogPath))) {
+            return this.cachedLogPath;
+        }
+        const envLog = await this.resolveFromProjectEnv();
+        if (envLog) {
+            return envLog;
+        }
+        if (this.bridge.isConnected) {
+            try {
+                const script = `
+import unreal, json, os
+paths = []
+try:
+    d = unreal.Paths.project_log_dir()
+    if d:
+        paths.append(os.path.abspath(d))
+except Exception:
+    pass
+try:
+    sd = unreal.Paths.project_saved_dir()
+    if sd:
+        p = os.path.join(sd, 'Logs')
+        paths.append(os.path.abspath(p))
+except Exception:
+    pass
+try:
+    pf = unreal.Paths.get_project_file_path()
+    if pf:
+        pd = os.path.dirname(pf)
+        p = os.path.join(pd, 'Saved', 'Logs')
+        paths.append(os.path.abspath(p))
+except Exception:
+    pass
+all_logs = []
+for base in paths:
+    try:
+        if os.path.isdir(base):
+            for name in os.listdir(base):
+                if name.lower().endswith('.log'):
+                    fp = os.path.join(base, name)
+                    try:
+                        m = os.path.getmtime(fp)
+                        all_logs.append({'p': fp, 'm': m})
+                    except Exception:
+                        pass
+    except Exception:
+        pass
+all_logs.sort(key=lambda x: x['m'], reverse=True)
+print('RESULT:' + json.dumps({'dirs': paths, 'logs': all_logs}))
+`.trim();
+                const res = await this.bridge.executePythonWithResult(script);
+                const logs = Array.isArray(res?.logs) ? res.logs : [];
+                for (const entry of logs) {
+                    const p = typeof entry?.p === 'string' ? entry.p : undefined;
+                    if (p && p.trim())
+                        return this.cacheLogPath(p);
+                }
+            }
+            catch { }
+        }
+        const fallback = await this.findLatestLogInDir(path.join(process.cwd(), 'Saved', 'Logs'));
+        if (fallback) {
+            return fallback;
+        }
+        return undefined;
+    }
+    async resolveFromProjectEnv() {
+        const projectPath = this.env.UE_PROJECT_PATH;
+        if (projectPath && typeof projectPath === 'string' && projectPath.trim()) {
+            const projectDir = path.dirname(projectPath);
+            const logsDir = path.join(projectDir, 'Saved', 'Logs');
+            const envLog = await this.findLatestLogInDir(logsDir);
+            if (envLog) {
+                return envLog;
+            }
+        }
+        return undefined;
+    }
+    async findLatestLogInDir(dir) {
+        if (!dir)
+            return undefined;
+        try {
+            const entries = await fs.readdir(dir);
+            const candidates = [];
+            for (const name of entries) {
+                if (!name.toLowerCase().endsWith('.log'))
+                    continue;
+                const fp = path.join(dir, name);
+                try {
+                    const st = await fs.stat(fp);
+                    candidates.push({ p: fp, m: st.mtimeMs });
+                }
+                catch { }
+            }
+            if (candidates.length) {
+                candidates.sort((a, b) => b.m - a.m);
+                return this.cacheLogPath(candidates[0].p);
+            }
+        }
+        catch { }
+        return undefined;
+    }
+    async fileExists(filePath) {
+        try {
+            const st = await fs.stat(filePath);
+            return st.isFile();
+        }
+        catch {
+            return false;
+        }
+    }
+    cacheLogPath(p) {
+        this.cachedLogPath = p;
+        return p;
+    }
+    async tailFile(filePath, maxLines) {
+        const handle = await fs.open(filePath, 'r');
+        try {
+            const stat = await handle.stat();
+            const chunkSize = 128 * 1024;
+            let position = stat.size;
+            let remaining = '';
+            const lines = [];
+            while (position > 0 && lines.length < maxLines) {
+                const readSize = Math.min(chunkSize, position);
+                position -= readSize;
+                const buf = Buffer.alloc(readSize);
+                await handle.read(buf, 0, readSize, position);
+                remaining = buf.toString('utf8') + remaining;
+                const parts = remaining.split(/\r?\n/);
+                remaining = parts.shift() || '';
+                while (parts.length) {
+                    const line = parts.pop();
+                    if (line === undefined)
+                        break;
+                    if (line.length === 0)
+                        continue;
+                    lines.unshift(line);
+                    if (lines.length >= maxLines)
+                        break;
+                }
+            }
+            if (lines.length < maxLines && remaining) {
+                lines.unshift(remaining);
+            }
+            return lines.slice(0, maxLines).join('\n');
+        }
+        finally {
+            try {
+                await handle.close();
+            }
+            catch { }
+        }
+    }
+    parseLine(line) {
+        const m1 = line.match(/^\[?(\d{4}\.\d{2}\.\d{2}-\d{2}\.\d{2}\.\d{2}:\d+)\]?\s*\[(.*?)\]\s*(.*)$/);
+        if (m1) {
+            const rest = m1[3];
+            const m2 = rest.match(/^(\w+):\s*(Error|Warning|Display|Log|Verbose|VeryVerbose):\s*(.*)$/);
+            if (m2) {
+                return { timestamp: m1[1], category: m2[1], level: m2[2] === 'Display' ? 'Log' : m2[2], message: m2[3] };
+            }
+            const m3 = rest.match(/^(\w+):\s*(.*)$/);
+            if (m3) {
+                return { timestamp: m1[1], category: m3[1], level: 'Log', message: m3[2] };
+            }
+            return { timestamp: m1[1], message: rest };
+        }
+        const m = line.match(/^(\w+):\s*(Error|Warning|Display|Log|Verbose|VeryVerbose):\s*(.*)$/);
+        if (m) {
+            return { category: m[1], level: m[2] === 'Display' ? 'Log' : m[2], message: m[3] };
+        }
+        const mAlt = line.match(/^(\w+):\s*(.*)$/);
+        if (mAlt) {
+            return { category: mAlt[1], level: 'Log', message: mAlt[2] };
+        }
+        return { message: line };
+    }
+    isInternalLogEntry(entry) {
+        if (!entry)
+            return false;
+        const category = entry.category?.toLowerCase() || '';
+        const message = entry.message?.trim() || '';
+        if (category === 'logpython' && message.startsWith('RESULT:')) {
+            return true;
+        }
+        if (!entry.category && message.startsWith('[') && message.includes('LogPython: RESULT:')) {
+            return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=logs.js.map

package/dist/types/tool-types.d.ts

@@ -75,6 +75,17 @@ export interface SystemControlResponse extends BaseToolResponse {
     soundPlaying?: boolean;
     widgetPath?: string;
     widgetVisible?: boolean;
+    imagePath?: string;
+    imageBase64?: string;
+    pid?: number;
+    logPath?: string;
+    entries?: Array<{
+        timestamp?: string;
+        category?: string;
+        level?: string;
+        message: string;
+    }>;
+    filteredCount?: number;
 }
 export interface ConsoleCommandResponse extends BaseToolResponse {
     command?: string;
@@ -131,7 +142,7 @@ export type AnimationAction = 'create_animation_bp' | 'play_montage' | 'setup_ra
 export type EffectAction = 'particle' | 'niagara' | 'debug_shape';
 export type BlueprintAction = 'create' | 'add_component';
 export type EnvironmentAction = 'create_landscape' | 'sculpt' | 'add_foliage' | 'paint_foliage';
-export type SystemAction = 'profile' | 'show_fps' | 'set_quality' | 'play_sound' | 'create_widget' | 'show_widget';
+export type SystemAction = 'profile' | 'show_fps' | 'set_quality' | 'play_sound' | 'create_widget' | 'show_widget' | 'screenshot' | 'engine_start' | 'engine_quit' | 'read_log';
 export type VerificationAction = 'foliage_type_exists' | 'foliage_instances_near' | 'landscape_exists' | 'quality_level';
 export interface ConsolidatedToolParams {
     manage_asset: {
@@ -229,6 +240,15 @@ export interface ConsolidatedToolParams {
         widgetName?: string;
         widgetType?: string;
         visible?: boolean;
+        resolution?: string;
+        projectPath?: string;
+        editorExe?: string;
+        filter_category?: string | string[];
+        filter_level?: 'Error' | 'Warning' | 'Log' | 'Verbose' | 'VeryVerbose' | 'All';
+        lines?: number;
+        log_path?: string;
+        include_prefixes?: string[];
+        exclude_categories?: string[];
     };
     console_command: {
         command: string;

package/dist/utils/response-validator.js

@@ -2,6 +2,66 @@ import Ajv from 'ajv';
 import { Logger } from './logger.js';
 import { cleanObject } from './safe-json.js';
 const log = new Logger('ResponseValidator');
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function normalizeText(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function buildSummaryText(toolName, payload) {
+    if (typeof payload === 'string') {
+        const normalized = payload.trim();
+        return normalized || `${toolName} responded`;
+    }
+    if (typeof payload === 'number' || typeof payload === 'bigint' || typeof payload === 'boolean') {
+        return `${toolName} responded: ${payload}`;
+    }
+    if (!isRecord(payload)) {
+        return `${toolName} responded`;
+    }
+    const parts = [];
+    const message = typeof payload.message === 'string' ? normalizeText(payload.message) : '';
+    const error = typeof payload.error === 'string' ? normalizeText(payload.error) : '';
+    const success = typeof payload.success === 'boolean' ? (payload.success ? 'success' : 'failed') : '';
+    const path = typeof payload.path === 'string' ? payload.path : '';
+    const name = typeof payload.name === 'string' ? payload.name : '';
+    const warningCount = Array.isArray(payload.warnings) ? payload.warnings.length : 0;
+    if (message)
+        parts.push(message);
+    if (error && (!message || !message.includes(error)))
+        parts.push(`error: ${error}`);
+    if (success)
+        parts.push(success);
+    if (path)
+        parts.push(`path: ${path}`);
+    if (name)
+        parts.push(`name: ${name}`);
+    if (warningCount > 0)
+        parts.push(`warnings: ${warningCount}`);
+    const summary = isRecord(payload.summary) ? payload.summary : undefined;
+    if (summary) {
+        const summaryParts = [];
+        for (const [key, value] of Object.entries(summary)) {
+            if (typeof value === 'number' || typeof value === 'string') {
+                summaryParts.push(`${key}: ${value}`);
+            }
+            if (summaryParts.length >= 3)
+                break;
+        }
+        if (summaryParts.length) {
+            parts.push(`summary(${summaryParts.join(', ')})`);
+        }
+    }
+    if (parts.length === 0) {
+        const keys = Object.keys(payload).slice(0, 3);
+        if (keys.length) {
+            return `${toolName} responded (${keys.join(', ')})`;
+        }
+    }
+    return parts.length > 0
+        ? parts.join(' | ')
+        : `${toolName} responded`;
+}
 /**
  * Response Validator for MCP Tool Outputs
  * Validates tool responses against their defined output schemas
@@ -127,15 +187,10 @@ export class ResponseValidator {
             return response;
         }
         // Otherwise, wrap structured result into MCP content
-        let text;
-        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 summarySource = structuredPayload !== undefined ? structuredPayload : response;
+        let text = buildSummaryText(toolName, summarySource);
+        if (!text || !text.trim()) {
+            text = buildSummaryText(toolName, response);
         }
         const wrapped = {
             content: [

package/docs/unreal-tool-test-cases.md

@@ -196,6 +196,8 @@ Additional advanced blueprint scenarios remain documented in the legacy matrix f
 | 2 | Play sound with missing asset fails | `{"action":"play_sound","soundPath":"/Game/MCP/Audio/Missing"}` | Error message reports that the sound asset could not be found. |
 | 3 | Play sound at location missing asset fails | `{"action":"play_sound","soundPath":"/Game/MCP/Audio/Missing","location":{"x":0,"y":0,"z":0}}` | Error message reports that the sound asset could not be found for the world location playback. |
 | 4 | Play sound with empty path fails validation | `{"action":"play_sound","soundPath":"","volume":1.0}` | Error message explains that the sound asset path could not be resolved. |
+| 5 | Read Output Log tail with defaults | `{"action":"read_log","lines":50,"filter_level":"All"}` | Success response returns recent log entries and the logPath used. |
+| 6 | Read Output Log filtered by custom categories | `{"action":"read_log","filter_category":"LogMyCategory,LogOtherLog","filter_level":"Error","lines":100}` | Success response returns only matching categories at Error level. |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unreal-engine-mcp-server",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "mcpName": "io.github.ChiR24/unreal-engine-mcp",
   "description": "A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via Remote Control API. Built with TypeScript and designed for game development automation.",
   "type": "module",

package/server.json

@@ -2,13 +2,13 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
   "name": "io.github.ChiR24/unreal-engine-mcp",
   "description": "MCP server for Unreal Engine 5 with 13 tools for game development automation.",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "unreal-engine-mcp-server",
-      "version": "0.4.5",
+      "version": "0.4.7",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -28,6 +28,7 @@ import { SequenceTools } from './tools/sequence.js';
 import { IntrospectionTools } from './tools/introspection.js';
 import { VisualTools } from './tools/visual.js';
 import { EngineTools } from './tools/engine.js';
+import { LogTools } from './tools/logs.js';
 import { consolidatedToolDefinitions } from './tools/consolidated-tool-definitions.js';
 import { handleConsolidatedToolCall } from './tools/consolidated-tool-handlers.js';
 import { prompts } from './prompts/index.js';
@@ -88,7 +89,7 @@ const CONFIG = {
   RETRY_DELAY_MS: 2000,
   // Server info
   SERVER_NAME: 'unreal-engine-mcp',
-  SERVER_VERSION: '0.4.5',
+  SERVER_VERSION: '0.4.7',
   // Monitoring
   HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -237,6 +238,7 @@ export function createServer() {
   const introspectionTools = new IntrospectionTools(bridge);
   const visualTools = new VisualTools(bridge);
   const engineTools = new EngineTools(bridge);
+  const logTools = new LogTools(bridge);
 
   const server = new Server(
     {
@@ -474,11 +476,22 @@ export function createServer() {
     let args: any = request.params.arguments || {};
     const startTime = Date.now();
 
-    // Ensure connection only when needed, with 3 attempts
-    const connected = await ensureConnectedOnDemand();
-    if (!connected) {
-      trackPerformance(startTime, false);
-      return createNotConnectedResponse(name);
+    let requiresEngine = true;
+    try {
+      const n = String(name);
+      if (n === 'system_control') {
+        const action = String((args || {}).action || '').trim();
+        if (action === 'read_log') {
+          requiresEngine = false;
+        }
+      }
+    } catch {}
+    if (requiresEngine) {
+      const connected = await ensureConnectedOnDemand();
+      if (!connected) {
+        trackPerformance(startTime, false);
+        return createNotConnectedResponse(name);
+      }
     }
     
 // Create tools object for handler
@@ -505,6 +518,7 @@ export function createServer() {
       introspectionTools,
       visualTools,
       engineTools,
+      logTools,
       // Elicitation (client-optional)
       elicit: elicitation.elicit,
       supportsElicitation: elicitation.supports,

package/src/tools/consolidated-tool-definitions.ts

@@ -537,7 +537,7 @@ Supported actions: profile, show_fps, set_quality, play_sound, create_widget, sh
       properties: {
         action: { 
           type: 'string', 
-          enum: ['profile', 'show_fps', 'set_quality', 'play_sound', 'create_widget', 'show_widget', 'screenshot', 'engine_start', 'engine_quit'],
+          enum: ['profile', 'show_fps', 'set_quality', 'play_sound', 'create_widget', 'show_widget', 'screenshot', 'engine_start', 'engine_quit', 'read_log'],
           description: 'System action'
         },
         // Performance
@@ -577,6 +577,14 @@ Supported actions: profile, show_fps, set_quality, play_sound, create_widget, sh
         // Engine lifecycle
         projectPath: { type: 'string', description: 'Absolute path to .uproject file (e.g., "C:/Projects/MyGame/MyGame.uproject"). Required for engine_start unless UE_PROJECT_PATH environment variable is set.' },
         editorExe: { type: 'string', description: 'Absolute path to Unreal Editor executable (e.g., "C:/UnrealEngine/Engine/Binaries/Win64/UnrealEditor.exe"). Required for engine_start unless UE_EDITOR_EXE environment variable is set.' }
+        ,
+        // Log reading
+        filter_category: { description: 'Category filter as string or array; comma-separated or array values' },
+        filter_level: { type: 'string', enum: ['Error','Warning','Log','Verbose','VeryVerbose','All'], description: 'Log level filter' },
+        lines: { type: 'number', description: 'Number of lines to read from tail' },
+        log_path: { type: 'string', description: 'Absolute path to a specific .log file to read' },
+        include_prefixes: { type: 'array', items: { type: 'string' }, description: 'Only include categories starting with any of these prefixes' },
+        exclude_categories: { type: 'array', items: { type: 'string' }, description: 'Categories to exclude' }
       },
       required: ['action']
     },
@@ -594,7 +602,14 @@ Supported actions: profile, show_fps, set_quality, play_sound, create_widget, sh
         imageBase64: { type: 'string', description: 'Screenshot image base64 (truncated)' },
         pid: { type: 'number', description: 'Process ID for launched editor' },
         message: { type: 'string', description: 'Status message' },
-        error: { type: 'string', description: 'Error message if failed' }
+        error: { type: 'string', description: 'Error message if failed' },
+        logPath: { type: 'string', description: 'Log file path used for read_log' },
+        entries: { 
+          type: 'array',
+          items: { type: 'object', properties: { timestamp: { type: 'string' }, category: { type: 'string' }, level: { type: 'string' }, message: { type: 'string' } } },
+          description: 'Parsed Output Log entries'
+        },
+        filteredCount: { type: 'number', description: 'Count of entries after filtering' }
       }
     }
   },

package/src/tools/consolidated-tool-handlers.ts

@@ -823,8 +823,25 @@ print('RESULT:' + json.dumps({'success': exists, 'exists': exists, 'path': path}
         }
 
       // 9. SYSTEM CONTROL
-case 'system_control':
+      case 'system_control':
         switch (requireAction(args)) {
+          case 'read_log': {
+            const filterCategoryRaw = args.filter_category;
+            const filterCategory = Array.isArray(filterCategoryRaw)
+              ? filterCategoryRaw
+              : typeof filterCategoryRaw === 'string' && filterCategoryRaw.trim() !== ''
+                ? filterCategoryRaw.split(',').map((s: string) => s.trim()).filter(Boolean)
+                : undefined;
+            const res = await tools.logTools.readOutputLog({
+              filterCategory,
+              filterLevel: args.filter_level,
+              lines: typeof args.lines === 'number' ? args.lines : undefined,
+              logPath: typeof args.log_path === 'string' ? args.log_path : undefined,
+              includePrefixes: Array.isArray(args.include_prefixes) ? args.include_prefixes : undefined,
+              excludeCategories: Array.isArray(args.exclude_categories) ? args.exclude_categories : undefined
+            });
+            return cleanObject(res);
+          }
           case 'profile': {
             const res = await tools.performanceTools.startProfiling({ type: args.profileType, duration: args.duration });
             return cleanObject(res);