unreal-engine-mcp-server 0.4.7 → 0.5.0

package/src/services/health-monitor.ts

@@ -0,0 +1,132 @@
+import { UnrealBridge } from '../unreal-bridge.js';
+import { Logger } from '../utils/logger.js';
+
+export interface PerformanceMetrics {
+  totalRequests: number;
+  successfulRequests: number;
+  failedRequests: number;
+  averageResponseTime: number;
+  responseTimes: number[];
+  connectionStatus: 'connected' | 'disconnected' | 'error';
+  lastHealthCheck: Date;
+  uptime: number;
+  recentErrors: Array<{ time: string; scope: string; type: string; message: string; retriable: boolean }>;
+}
+
+export class HealthMonitor {
+  private logger: Logger;
+  public metrics: PerformanceMetrics;
+  private healthCheckTimer: NodeJS.Timeout | undefined;
+  private lastHealthSuccessAt = 0;
+  private readonly HEALTH_CHECK_INTERVAL_MS = 30000;
+
+  constructor(logger: Logger) {
+    this.logger = logger;
+    this.metrics = {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      averageResponseTime: 0,
+      responseTimes: [],
+      connectionStatus: 'disconnected',
+      lastHealthCheck: new Date(),
+      uptime: Date.now(),
+      recentErrors: []
+    };
+  }
+
+  trackPerformance(startTime: number, success: boolean) {
+    const responseTime = Date.now() - startTime;
+    this.metrics.totalRequests++;
+    if (success) {
+      this.metrics.successfulRequests++;
+    } else {
+      this.metrics.failedRequests++;
+    }
+
+    // Keep last 100 response times for average calculation
+    this.metrics.responseTimes.push(responseTime);
+    if (this.metrics.responseTimes.length > 100) {
+      this.metrics.responseTimes.shift();
+    }
+
+    // Calculate average
+    this.metrics.averageResponseTime = this.metrics.responseTimes.reduce((a, b) => a + b, 0) / this.metrics.responseTimes.length;
+  }
+
+  recordError(errorResponse: any) {
+      try {
+        this.metrics.recentErrors.push({
+          time: new Date().toISOString(),
+          scope: (errorResponse as any).scope || 'unknown',
+          type: (errorResponse as any)._debug?.errorType || 'UNKNOWN',
+          message: (errorResponse as any).error || (errorResponse as any).message || 'Unknown error',
+          retriable: Boolean((errorResponse as any).retriable)
+        });
+        if (this.metrics.recentErrors.length > 20) this.metrics.recentErrors.splice(0, this.metrics.recentErrors.length - 20);
+      } catch { }
+  }
+
+  async performHealthCheck(bridge: UnrealBridge): Promise<boolean> {
+    // If not connected, do not attempt any ping (stay quiet)
+    if (!bridge.isConnected) {
+      return false;
+    }
+    try {
+      // Use a safe, no-op stats command that always exists
+      await bridge.executeConsoleCommand('stat none');
+      this.metrics.connectionStatus = 'connected';
+      this.metrics.lastHealthCheck = new Date();
+      this.lastHealthSuccessAt = Date.now();
+      return true;
+    } catch (err1) {
+      this.metrics.connectionStatus = 'error';
+      this.metrics.lastHealthCheck = new Date();
+      // Avoid noisy warnings when engine may be shutting down; log at debug
+      this.logger.debug('Health check failed (console):', err1);
+      return false;
+    }
+  }
+
+  startHealthChecks(bridge: UnrealBridge) {
+    if (this.healthCheckTimer) return;
+    this.lastHealthSuccessAt = Date.now();
+    this.healthCheckTimer = setInterval(async () => {
+      // Only attempt health pings while connected; stay silent otherwise
+      if (!bridge.isConnected) {
+        // Optionally pause fully after 5 minutes of no success
+        const FIVE_MIN_MS = 5 * 60 * 1000;
+        if (!this.lastHealthSuccessAt || Date.now() - this.lastHealthSuccessAt > FIVE_MIN_MS) {
+          if (this.healthCheckTimer) {
+            clearInterval(this.healthCheckTimer);
+            this.healthCheckTimer = undefined;
+          }
+          this.logger.info('Health checks paused after 5 minutes without a successful response');
+        }
+        return;
+      }
+
+      await this.performHealthCheck(bridge);
+      // Stop sending echoes if we haven't had a successful response in > 5 minutes
+      const FIVE_MIN_MS = 5 * 60 * 1000;
+      if (!this.lastHealthSuccessAt || Date.now() - this.lastHealthSuccessAt > FIVE_MIN_MS) {
+        if (this.healthCheckTimer) {
+          clearInterval(this.healthCheckTimer);
+          this.healthCheckTimer = undefined;
+          this.logger.info('Health checks paused after 5 minutes without a successful response');
+        }
+      }
+    }, this.HEALTH_CHECK_INTERVAL_MS);
+  }
+
+  stopHealthChecks() {
+      if (this.healthCheckTimer) {
+          clearInterval(this.healthCheckTimer);
+          this.healthCheckTimer = undefined;
+      }
+  }
+
+  setLastHealthSuccessAt(time: number) {
+    this.lastHealthSuccessAt = time;
+  }
+}

package/src/services/metrics-server.ts

@@ -0,0 +1,142 @@
+import http from 'http';
+import { HealthMonitor } from './health-monitor.js';
+import { AutomationBridge } from '../automation/index.js';
+import { Logger } from '../utils/logger.js';
+import { wasmIntegration } from '../wasm/index.js';
+import { DEFAULT_AUTOMATION_HOST } from '../constants.js';
+
+interface MetricsServerOptions {
+  healthMonitor: HealthMonitor;
+  automationBridge: AutomationBridge;
+  logger: Logger;
+}
+
+function formatPrometheusMetrics(options: MetricsServerOptions): string {
+  const { healthMonitor, automationBridge } = options;
+  const m = healthMonitor.metrics;
+  const status = automationBridge.getStatus();
+  const wasmMetrics = wasmIntegration.getMetrics();
+  const wasmStatus = wasmIntegration.getStatus();
+
+  const lines: string[] = [];
+
+  // Basic request counters
+  lines.push('# HELP unreal_mcp_requests_total Total number of tool requests seen by the MCP server.');
+  lines.push('# TYPE unreal_mcp_requests_total counter');
+  lines.push(`unreal_mcp_requests_total ${m.totalRequests}`);
+
+  lines.push('# HELP unreal_mcp_requests_success_total Total number of successful tool requests.');
+  lines.push('# TYPE unreal_mcp_requests_success_total counter');
+  lines.push(`unreal_mcp_requests_success_total ${m.successfulRequests}`);
+
+  lines.push('# HELP unreal_mcp_requests_failed_total Total number of failed tool requests.');
+  lines.push('# TYPE unreal_mcp_requests_failed_total counter');
+  lines.push(`unreal_mcp_requests_failed_total ${m.failedRequests}`);
+
+  // Response time summary (simple gauges)
+  lines.push('# HELP unreal_mcp_average_response_time_ms Average response time of recent tool requests (ms).');
+  lines.push('# TYPE unreal_mcp_average_response_time_ms gauge');
+  lines.push(`unreal_mcp_average_response_time_ms ${Number.isFinite(m.averageResponseTime) ? m.averageResponseTime.toFixed(2) : '0'}`);
+
+  // Connection status gauges
+  lines.push('# HELP unreal_mcp_unreal_connected Whether the Unreal automation bridge is currently connected (1) or not (0).');
+  lines.push('# TYPE unreal_mcp_unreal_connected gauge');
+  lines.push(`unreal_mcp_unreal_connected ${status.connected ? 1 : 0}`);
+
+  lines.push('# HELP unreal_mcp_automation_pending_requests Number of pending automation bridge requests.');
+  lines.push('# TYPE unreal_mcp_automation_pending_requests gauge');
+  lines.push(`unreal_mcp_automation_pending_requests ${status.pendingRequests}`);
+
+  lines.push('# HELP unreal_mcp_automation_max_pending_requests Configured maximum number of pending automation bridge requests.');
+  lines.push('# TYPE unreal_mcp_automation_max_pending_requests gauge');
+  lines.push(`unreal_mcp_automation_max_pending_requests ${status.maxPendingRequests}`);
+
+  lines.push('# HELP unreal_mcp_automation_max_concurrent_connections Configured maximum concurrent automation bridge connections.');
+  lines.push('# TYPE unreal_mcp_automation_max_concurrent_connections gauge');
+  lines.push(`unreal_mcp_automation_max_concurrent_connections ${status.maxConcurrentConnections}`);
+
+  // WASM integration metrics
+  lines.push('# HELP unreal_mcp_wasm_enabled Whether the optional WebAssembly integration is enabled (1) or not (0).');
+  lines.push('# TYPE unreal_mcp_wasm_enabled gauge');
+  lines.push(`unreal_mcp_wasm_enabled ${wasmStatus.enabled ? 1 : 0}`);
+
+  lines.push('# HELP unreal_mcp_wasm_ready Whether the WebAssembly module has been initialized successfully (1) or not (0).');
+  lines.push('# TYPE unreal_mcp_wasm_ready gauge');
+  lines.push(`unreal_mcp_wasm_ready ${wasmStatus.ready ? 1 : 0}`);
+
+  lines.push('# HELP unreal_mcp_wasm_operations_total Total number of WASM-related operations recorded by the integration layer.');
+  lines.push('# TYPE unreal_mcp_wasm_operations_total counter');
+  lines.push(`unreal_mcp_wasm_operations_total ${wasmMetrics.totalOperations}`);
+
+  lines.push('# HELP unreal_mcp_wasm_operations_wasm_total Number of operations that used the WebAssembly implementation.');
+  lines.push('# TYPE unreal_mcp_wasm_operations_wasm_total counter');
+  lines.push(`unreal_mcp_wasm_operations_wasm_total ${wasmMetrics.wasmOperations}`);
+
+  lines.push('# HELP unreal_mcp_wasm_operations_ts_total Number of operations that used the TypeScript fallback implementation.');
+  lines.push('# TYPE unreal_mcp_wasm_operations_ts_total counter');
+  lines.push(`unreal_mcp_wasm_operations_ts_total ${wasmMetrics.tsOperations}`);
+
+  // Uptime in seconds
+  const uptimeSeconds = Math.floor((Date.now() - m.uptime) / 1000);
+  lines.push('# HELP unreal_mcp_uptime_seconds MCP server uptime in seconds (since HealthMonitor was created).');
+  lines.push('# TYPE unreal_mcp_uptime_seconds gauge');
+  lines.push(`unreal_mcp_uptime_seconds ${uptimeSeconds}`);
+
+  return lines.join('\n') + '\n';
+}
+
+export function startMetricsServer(options: MetricsServerOptions): void {
+  const { logger } = options;
+
+  const portEnv = process.env.MCP_METRICS_PORT || process.env.PROMETHEUS_PORT;
+  const port = portEnv ? Number(portEnv) : 0;
+
+  if (!port || !Number.isFinite(port) || port <= 0) {
+    logger.debug('Metrics server disabled (set MCP_METRICS_PORT to enable Prometheus /metrics endpoint).');
+    return;
+  }
+
+  try {
+    const server = http.createServer((req, res) => {
+      if (!req.url) {
+        res.statusCode = 400;
+        res.end('Bad Request');
+        return;
+      }
+
+      if (req.method !== 'GET') {
+        res.statusCode = 405;
+        res.setHeader('Allow', 'GET');
+        res.end('Method Not Allowed');
+        return;
+      }
+
+      if (!req.url.startsWith('/metrics')) {
+        res.statusCode = 404;
+        res.end('Not Found');
+        return;
+      }
+
+      try {
+        const body = formatPrometheusMetrics(options);
+        res.statusCode = 200;
+        res.setHeader('Content-Type', 'text/plain; version=0.0.4; charset=utf-8');
+        res.end(body);
+      } catch (err) {
+        logger.warn('Failed to render /metrics payload', err as any);
+        res.statusCode = 500;
+        res.end('Internal Server Error');
+      }
+    });
+
+    server.listen(port, () => {
+      logger.info(`Prometheus metrics server listening on http://${DEFAULT_AUTOMATION_HOST}:${port}/metrics`);
+    });
+
+    server.on('error', (err) => {
+      logger.warn('Metrics server error', err as any);
+    });
+  } catch (err) {
+    logger.warn('Failed to start metrics server', err as any);
+  }
+}