unreal-engine-mcp-server 0.5.4 → 0.5.6

package/src/handlers/resource-handlers.ts

@@ -1,186 +0,0 @@
-import { ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { UnrealBridge } from '../unreal-bridge.js';
-import { AutomationBridge } from '../automation/index.js';
-import { AssetResources } from '../resources/assets.js';
-import { ActorResources } from '../resources/actors.js';
-import { LevelResources } from '../resources/levels.js';
-import { HealthMonitor } from '../services/health-monitor.js';
-
-export class ResourceHandler {
-  constructor(
-    private server: Server,
-    private bridge: UnrealBridge,
-    private automationBridge: AutomationBridge,
-    private assetResources: AssetResources,
-    private actorResources: ActorResources,
-    private levelResources: LevelResources,
-    private healthMonitor: HealthMonitor,
-    private ensureConnected: () => Promise<boolean>
-  ) { }
-
-  registerHandlers() {
-    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const uri = request.params.uri;
-
-      if (uri === 'ue://assets') {
-        const ok = await this.ensureConnected();
-        if (!ok) {
-          return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
-        }
-        const list = await this.assetResources.list('/Game', true);
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(list, null, 2)
-          }]
-        };
-      }
-
-      if (uri === 'ue://actors') {
-        const ok = await this.ensureConnected();
-        if (!ok) {
-          return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
-        }
-        const list = await this.actorResources.listActors();
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(list, null, 2)
-          }]
-        };
-      }
-
-      if (uri === 'ue://level') {
-        const ok = await this.ensureConnected();
-        if (!ok) {
-          return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
-        }
-        const level = await this.levelResources.getCurrentLevel();
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(level, null, 2)
-          }]
-        };
-      }
-
-      if (uri === 'ue://health') {
-        const uptimeMs = Date.now() - this.healthMonitor.metrics.uptime;
-        const automationStatus = this.automationBridge.getStatus();
-
-        let versionInfo: any = {};
-        let featureFlags: any = {};
-        if (this.bridge.isConnected) {
-          try { versionInfo = await this.bridge.getEngineVersion(); } catch { }
-          try { featureFlags = await this.bridge.getFeatureFlags(); } catch { }
-        }
-
-        const responseTimes = this.healthMonitor.metrics.responseTimes.slice(-25);
-        const automationSummary = {
-          connected: automationStatus.connected,
-          activePort: automationStatus.activePort,
-          pendingRequests: automationStatus.pendingRequests,
-          listeningPorts: automationStatus.listeningPorts,
-          lastHandshakeAt: automationStatus.lastHandshakeAt,
-          lastRequestSentAt: automationStatus.lastRequestSentAt,
-          maxPendingRequests: automationStatus.maxPendingRequests,
-          maxConcurrentConnections: automationStatus.maxConcurrentConnections
-        };
-
-        const health = {
-          status: this.healthMonitor.metrics.connectionStatus,
-          uptimeSeconds: Math.floor(uptimeMs / 1000),
-          performance: {
-            totalRequests: this.healthMonitor.metrics.totalRequests,
-            successfulRequests: this.healthMonitor.metrics.successfulRequests,
-            failedRequests: this.healthMonitor.metrics.failedRequests,
-            successRate: this.healthMonitor.metrics.totalRequests > 0 ? Number(((this.healthMonitor.metrics.successfulRequests / this.healthMonitor.metrics.totalRequests) * 100).toFixed(2)) : null,
-            averageResponseTimeMs: Math.round(this.healthMonitor.metrics.averageResponseTime),
-            recentResponseTimesMs: responseTimes
-          },
-          lastHealthCheckIso: this.healthMonitor.metrics.lastHealthCheck.toISOString(),
-          unrealConnection: {
-            status: this.bridge.isConnected ? 'connected' : 'disconnected',
-            transport: 'automation_bridge',
-            engineVersion: versionInfo,
-            features: {
-              pythonEnabled: false,
-              subsystems: featureFlags.subsystems || {},
-              automationBridgeConnected: automationStatus.connected
-            }
-          },
-          recentErrors: this.healthMonitor.metrics.recentErrors.slice(-10),
-          automationBridge: automationSummary,
-          raw: {
-            metrics: this.healthMonitor.metrics,
-            automationStatus
-          }
-        };
-
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(health, null, 2)
-          }]
-        };
-      }
-
-      if (uri === 'ue://automation-bridge') {
-        const status = this.automationBridge.getStatus();
-        const content = {
-          summary: {
-            enabled: status.enabled,
-            connected: status.connected,
-            host: status.host,
-            port: status.port,
-            capabilityTokenRequired: status.capabilityTokenRequired,
-            pendingRequests: status.pendingRequests
-          },
-          connections: status.connections,
-          timestamps: {
-            connectedAt: status.connectedAt,
-            lastHandshakeAt: status.lastHandshakeAt,
-            lastMessageAt: status.lastMessageAt,
-            lastRequestSentAt: status.lastRequestSentAt
-          },
-          lastDisconnect: status.lastDisconnect,
-          lastHandshakeFailure: status.lastHandshakeFailure,
-          lastError: status.lastError,
-          lastHandshakeMetadata: status.lastHandshakeMetadata,
-          pendingRequestDetails: status.pendingRequestDetails,
-          listening: status.webSocketListening
-        };
-
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(content, null, 2)
-          }]
-        };
-      }
-
-      if (uri === 'ue://version') {
-        const ok = await this.ensureConnected();
-        if (!ok) {
-          return { contents: [{ uri, mimeType: 'text/plain', text: 'Unreal Engine not connected (after 3 attempts).' }] };
-        }
-        const info = await this.bridge.getEngineVersion();
-        return {
-          contents: [{
-            uri,
-            mimeType: 'application/json',
-            text: JSON.stringify(info, null, 2)
-          }]
-        };
-      }
-
-      throw new Error(`Unknown resource: ${uri}`);
-    });
-  }
-}

package/src/index.ts

@@ -1,243 +0,0 @@
-
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { Logger } from './utils/logger.js';
-import { UnrealBridge } from './unreal-bridge.js';
-import { AutomationBridge } from './automation/index.js';
-import { createRequire } from 'node:module';
-import { responseValidator } from './utils/response-validator.js';
-import { z } from 'zod';
-import { initializeWASM } from './wasm/index.js';
-import { consolidatedToolDefinitions } from './tools/consolidated-tool-definitions.js';
-import { HealthMonitor } from './services/health-monitor.js';
-import { ServerSetup } from './server-setup.js';
-import { startMetricsServer } from './services/metrics-server.js';
-import { config } from './config.js';
-import { GraphQLServer } from './graphql/server.js';
-
-const require = createRequire(import.meta.url);
-const packageInfo: { name?: string; version?: string } = (() => {
-  try {
-    return require('../package.json');
-  } catch (error) {
-    const log = new Logger('UE-MCP');
-    log.debug('Unable to read package.json for server metadata', error);
-    return {};
-  }
-})();
-const DEFAULT_SERVER_NAME = typeof packageInfo.name === 'string' && packageInfo.name.trim().length > 0
-  ? packageInfo.name
-  : 'unreal-engine-mcp';
-const DEFAULT_SERVER_VERSION = typeof packageInfo.version === 'string' && packageInfo.version.trim().length > 0
-  ? packageInfo.version
-  : '0.5.4';
-
-function routeStdoutLogsToStderr(): void {
-  if (!config.MCP_ROUTE_STDOUT_LOGS) {
-    return;
-  }
-
-  const writeToStderr = (...args: unknown[]): void => {
-    const line = args
-      .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
-      .join(' ');
-    process.stderr.write(`${line}\n`);
-  };
-
-  console.log = (...args: unknown[]): void => { writeToStderr(...args); };
-  console.info = (...args: unknown[]): void => { writeToStderr(...args); };
-  if (typeof console.debug === 'function') {
-    console.debug = (...args: unknown[]): void => { writeToStderr(...args); };
-  }
-}
-
-const log = new Logger('UE-MCP');
-
-// Ensure stdout remains JSON-only for MCP by routing logs to stderr unless opted out.
-routeStdoutLogsToStderr();
-
-// Configuration
-const CONFIG = {
-  MAX_RETRY_ATTEMPTS: 3,
-  RETRY_DELAY_MS: 2000,
-  SERVER_NAME: DEFAULT_SERVER_NAME,
-  SERVER_VERSION: DEFAULT_SERVER_VERSION,
-  AUTOMATION_HEARTBEAT_MS: 15000,
-  HEALTH_CHECK_INTERVAL_MS: 30000
-};
-
-export function createServer() {
-  const bridge = new UnrealBridge();
-  const healthMonitor = new HealthMonitor(log);
-
-  const automationBridge = new AutomationBridge({
-    serverName: CONFIG.SERVER_NAME,
-    serverVersion: CONFIG.SERVER_VERSION,
-    heartbeatIntervalMs: CONFIG.AUTOMATION_HEARTBEAT_MS,
-    clientMode: config.MCP_AUTOMATION_CLIENT_MODE
-  });
-  bridge.setAutomationBridge(automationBridge);
-
-
-  automationBridge.on('connected', ({ metadata, port, protocol }) => {
-    log.info(
-      `Automation bridge connected (port=${port}, protocol=${protocol ?? 'none'})`,
-      metadata
-    );
-  });
-
-  automationBridge.on('disconnected', ({ code, reason, port, protocol }) => {
-    log.info(
-      `Automation bridge disconnected (code=${code}, reason=${reason || 'n/a'}, port=${port}, protocol=${protocol ?? 'none'})`
-    );
-  });
-
-  automationBridge.on('handshakeFailed', ({ reason, port }) => {
-    log.warn(`Automation bridge handshake failed (port=${port}): ${reason}`);
-  });
-
-  automationBridge.on('message', (message) => {
-    log.debug('Automation bridge inbound message', message);
-  });
-
-  automationBridge.on('error', (error) => {
-    log.error('Automation bridge error', error);
-  });
-
-  // Optionally expose Prometheus-style metrics via /metrics
-  startMetricsServer({ healthMonitor, automationBridge, logger: log });
-
-  // Initialize GraphQL server (controlled by GRAPHQL_ENABLED env var)
-  const graphqlServer = new GraphQLServer(bridge, automationBridge);
-  graphqlServer.start().catch((error) => {
-    log.warn('GraphQL server failed to start:', error);
-  });
-
-  // Initialize WebAssembly module for high-performance operations (5-8x faster)
-  log.debug('Initializing WebAssembly integration...');
-  initializeWASM().then(() => {
-    log.info('✅ WebAssembly integration initialized (JSON parsing and math operations)');
-  }).catch((error) => {
-    log.warn('⚠️ WebAssembly initialization failed, using TypeScript fallbacks:', error);
-  });
-
-  // Initialize response validation with schemas
-  log.debug('Initializing response validation...');
-  const toolDefs = consolidatedToolDefinitions;
-  toolDefs.forEach((tool: any) => {
-    if (tool.outputSchema) {
-      responseValidator.registerSchema(tool.name, tool.outputSchema);
-    }
-  });
-  log.debug(`Registered ${responseValidator.getStats().totalSchemas} output schemas for validation`);
-
-  log.debug('Server starting without connecting to Unreal Engine');
-  healthMonitor.metrics.connectionStatus = 'disconnected';
-
-  const server = new Server(
-    {
-      name: CONFIG.SERVER_NAME,
-      version: CONFIG.SERVER_VERSION
-    },
-    {
-      capabilities: {
-        tools: {},
-        resources: {},
-        prompts: {}
-      }
-    }
-  );
-
-  // Setup server using helper class
-  const serverSetup = new ServerSetup(server, bridge, automationBridge, log, healthMonitor);
-  serverSetup.setup(); // Register tools, resources, and prompts
-
-  return { server, bridge, automationBridge, graphqlServer };
-}
-
-// Export configuration schema for session UI and runtime validation
-export const configSchema = z.object({
-  logLevel: z.enum(['debug', 'info', 'warn', 'error']).optional().default('info').describe('Runtime log level'),
-  projectPath: z.string().optional().default('C:/Users/YourName/Documents/Unreal Projects/YourProject').describe('Absolute path to your Unreal .uproject file')
-});
-
-// Default export for runtime configuration support.
-export default function createServerDefault({ config }: { config?: any } = {}) {
-  try {
-    if (config) {
-      if (typeof config.logLevel === 'string') process.env.LOG_LEVEL = config.logLevel;
-      if (typeof config.projectPath === 'string' && config.projectPath.trim()) process.env.UE_PROJECT_PATH = config.projectPath;
-    }
-  } catch (e) {
-    console.debug('[createServerDefault] Failed to apply config to environment:', (e as any)?.message || e);
-  }
-
-  const { server } = createServer();
-  return server;
-}
-
-export async function startStdioServer() {
-  const { server, automationBridge, graphqlServer } = createServer();
-  const transport = new StdioServerTransport();
-  let shuttingDown = false;
-
-  const handleShutdown = async (signal?: NodeJS.Signals) => {
-    if (shuttingDown) {
-      return;
-    }
-    shuttingDown = true;
-    const reason = signal ? ` due to ${signal}` : '';
-    log.info(`Shutting down MCP server${reason}`);
-    try {
-      automationBridge.stop();
-    } catch (error) {
-      log.warn('Failed to stop automation bridge cleanly', error);
-    }
-
-    try {
-      await graphqlServer.stop();
-    } catch (error) {
-      log.warn('Failed to stop GraphQL server cleanly', error);
-    }
-
-    try {
-      if (typeof (server as any).close === 'function') {
-        await (server as any).close();
-      }
-    } catch (error) {
-      log.warn('Failed to close MCP server transport cleanly', error);
-    }
-
-    if (signal) {
-      process.exit(0);
-    }
-  };
-
-  ['SIGINT', 'SIGTERM'].forEach((signal) => {
-    process.once(signal as NodeJS.Signals, () => {
-      void handleShutdown(signal as NodeJS.Signals);
-    });
-  });
-
-  process.once('beforeExit', () => {
-    automationBridge.stop();
-  });
-
-  process.once('exit', () => {
-    automationBridge.stop();
-  });
-
-  const originalWrite = process.stdout.write;
-  process.stdout.write = function (...args: any[]) {
-    const message = args[0];
-    if (typeof message === 'string' && message.includes('jsonrpc')) {
-      log.debug(`Sending to client: ${message.substring(0, 200)}...`);
-    }
-    return originalWrite.apply(process.stdout, args as any);
-  } as any;
-
-  await server.connect(transport);
-  log.info('Unreal Engine MCP Server started on stdio');
-}
-
-// Direct execution is handled via src/cli.ts to keep this module side-effect free.

package/src/resources/actors.ts

@@ -1,127 +0,0 @@
-import { UnrealBridge } from '../unreal-bridge.js';
-import { coerceNumber, coerceString } from '../utils/result-helpers.js';
-
-interface CacheEntry {
-  data: any;
-  timestamp: number;
-}
-
-export class ActorResources {
-  private cache = new Map<string, CacheEntry>();
-  private readonly CACHE_TTL_MS = 5000; // 5 seconds cache for actors (they change more frequently)
-  private automationBridgeAvailable = false;
-
-  constructor(private bridge: UnrealBridge, private automationBridge?: any) {
-    this.automationBridgeAvailable = Boolean(automationBridge && typeof automationBridge.sendAutomationRequest === 'function');
-  }
-  
-  private getFromCache(key: string): any | null {
-    const entry = this.cache.get(key);
-    if (entry && (Date.now() - entry.timestamp) < this.CACHE_TTL_MS) {
-      return entry.data;
-    }
-    this.cache.delete(key);
-    return null;
-  }
-  
-  private setCache(key: string, data: any): void {
-    this.cache.set(key, { data, timestamp: Date.now() });
-  }
-
-  async listActors() {
-    // Check cache first
-    const cached = this.getFromCache('listActors');
-    if (cached !== null) {
-      return cached;
-    }
-    
-    try {
-      if (!this.automationBridgeAvailable) {
-        return { success: false, error: 'Automation bridge is not available. Please ensure Unreal Engine is running with the MCP Automation Bridge plugin.' };
-      }
-
-      const resp: any = await this.automationBridge.sendAutomationRequest('control_actor', { action: 'list' });
-      if (resp && resp.success !== false && Array.isArray((resp.result || resp).actors)) {
-        const actors = (resp.result || resp).actors as any[];
-        const count = coerceNumber((resp.result || resp).count) ?? actors.length;
-        const payload = { success: true as const, count, actors };
-        this.setCache('listActors', payload);
-        return payload;
-      }
-
-      return { success: false, error: 'Failed to retrieve actor list from automation bridge' };
-    } catch (err) {
-      return { success: false, error: `Failed to list actors: ${err}` };
-    }
-  }
-
-  async getActorByName(actorName: string) {
-    try {
-      if (!this.automationBridgeAvailable) {
-        return { success: false, error: 'Automation bridge is not available' };
-      }
-
-      const resp: any = await this.automationBridge.sendAutomationRequest('control_actor', {
-        action: 'find_by_name',
-        name: actorName
-      });
-
-      if (resp && resp.success !== false && resp.result) {
-        return {
-          success: true as const,
-          name: coerceString(resp.result.name) ?? actorName,
-          path: coerceString(resp.result.path),
-          class: coerceString(resp.result.class)
-        };
-      }
-
-      return {
-        success: false as const,
-        error: `Actor not found: ${actorName}`
-      };
-    } catch (err) {
-      return { success: false, error: `Failed to get actor: ${err}` };
-    }
-  }
-
-  async getActorTransform(actorPath: string) {
-    try {
-      return await this.bridge.getObjectProperty({
-        objectPath: actorPath,
-        propertyName: 'ActorTransform'
-      });
-    } catch (err) {
-      return { error: `Failed to get transform: ${err}` };
-    }
-  }
-
-  async listActorComponents(actorPath: string) {
-    try {
-      if (!this.automationBridgeAvailable) {
-        return { success: false, error: 'Automation bridge is not available' };
-      }
-
-      const resp: any = await this.automationBridge.sendAutomationRequest('control_actor', {
-        action: 'list_components',
-        actor_path: actorPath
-      });
-
-      if (resp && resp.success !== false && Array.isArray(resp.result?.components)) {
-        return {
-          success: true as const,
-          components: resp.result.components
-        };
-      }
-
-      return {
-        success: false as const,
-        error: `Failed to resolve components for ${actorPath}`
-      };
-    } catch (err) {
-      return {
-        success: false as const,
-        error: `Component lookup failed: ${err}`
-      };
-    }
-  }
-}