unreal-engine-mcp-server 0.5.0 → 0.5.2

package/src/graphql/loaders.ts

@@ -0,0 +1,244 @@
+/**
+ * DataLoader instances for GraphQL N+1 query optimization
+ * 
+ * DataLoaders batch and cache requests within a single GraphQL request,
+ * preventing the N+1 query problem when resolving nested fields.
+ */
+
+import DataLoader from 'dataloader';
+import type { AutomationBridge } from '../automation/index.js';
+import { Logger } from '../utils/logger.js';
+
+const log = new Logger('GraphQL:Loaders');
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface Actor {
+    name: string;
+    label?: string;
+    class?: string;
+    path?: string;
+    location?: { x: number; y: number; z: number };
+    rotation?: { pitch: number; yaw: number; roll: number };
+    scale?: { x: number; y: number; z: number };
+    tags?: string[];
+}
+
+export interface Asset {
+    name: string;
+    path: string;
+    class?: string;
+    packagePath?: string;
+    size?: number;
+}
+
+export interface Blueprint {
+    name: string;
+    path: string;
+    parentClass?: string;
+    variables?: Array<{ name: string; type: string; defaultValue?: unknown }>;
+    functions?: Array<{ name: string; parameters?: Array<{ name: string; type: string }> }>;
+    components?: Array<{ name: string; type: string }>;
+}
+
+// ============================================================================
+// Loader Factory
+// ============================================================================
+
+export interface GraphQLLoaders {
+    actorLoader: DataLoader<string, Actor | null>;
+    assetLoader: DataLoader<string, Asset | null>;
+    blueprintLoader: DataLoader<string, Blueprint | null>;
+    actorComponentsLoader: DataLoader<string, Array<{ name: string; type: string }> | null>;
+}
+
+/**
+ * Creates DataLoader instances for a GraphQL request context.
+ * 
+ * Each GraphQL request should have its own set of loaders to ensure
+ * proper request-scoped caching and batching.
+ */
+export function createLoaders(automationBridge: AutomationBridge): GraphQLLoaders {
+    return {
+        /**
+         * Batches actor fetches by name
+         */
+        actorLoader: new DataLoader<string, Actor | null>(
+            async (names: readonly string[]) => {
+                log.debug(`Batching actor fetch for ${names.length} actors`);
+
+                try {
+                    // Use batch fetch if available, otherwise fall back to individual fetches
+                    const result = await automationBridge.sendAutomationRequest<{
+                        success: boolean;
+                        actors?: Actor[];
+                    }>('control_actor', {
+                        action: 'batch_get',
+                        actorNames: [...names]
+                    });
+
+                    if (result.success && result.actors) {
+                        // Map results back to input order
+                        return names.map(name =>
+                            result.actors?.find(a => a.name === name || a.label === name) ?? null
+                        );
+                    }
+                } catch {
+                    log.debug('Batch fetch not supported, falling back to individual fetches');
+                }
+
+                // Fallback: fetch individually
+                const results = await Promise.all(
+                    names.map(async (name) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                actor?: Actor;
+                            }>('control_actor', {
+                                action: 'find_by_name',
+                                actorName: name
+                            });
+                            return result.success ? (result.actor ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 50
+            }
+        ),
+
+        /**
+         * Batches asset fetches by path
+         */
+        assetLoader: new DataLoader<string, Asset | null>(
+            async (paths: readonly string[]) => {
+                log.debug(`Batching asset fetch for ${paths.length} assets`);
+
+                try {
+                    const result = await automationBridge.sendAutomationRequest<{
+                        success: boolean;
+                        assets?: Asset[];
+                    }>('manage_asset', {
+                        action: 'batch_get',
+                        assetPaths: [...paths]
+                    });
+
+                    if (result.success && result.assets) {
+                        return paths.map(path =>
+                            result.assets?.find(a => a.path === path) ?? null
+                        );
+                    }
+                } catch {
+                    log.debug('Batch asset fetch not supported');
+                }
+
+                // Fallback: check existence individually
+                const results = await Promise.all(
+                    paths.map(async (path) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                exists?: boolean;
+                                asset?: Asset;
+                            }>('manage_asset', {
+                                action: 'exists',
+                                assetPath: path
+                            });
+
+                            if (result.success && result.exists) {
+                                return result.asset ?? { name: path.split('/').pop() || '', path };
+                            }
+                            return null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 100
+            }
+        ),
+
+        /**
+         * Batches blueprint fetches by path
+         */
+        blueprintLoader: new DataLoader<string, Blueprint | null>(
+            async (paths: readonly string[]) => {
+                log.debug(`Batching blueprint fetch for ${paths.length} blueprints`);
+
+                const results = await Promise.all(
+                    paths.map(async (path) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                blueprint?: Blueprint;
+                            }>('manage_blueprint', {
+                                action: 'get_blueprint',
+                                blueprintPath: path
+                            });
+                            return result.success ? (result.blueprint ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 20
+            }
+        ),
+
+        /**
+         * Batches actor component fetches
+         */
+        actorComponentsLoader: new DataLoader<string, Array<{ name: string; type: string }> | null>(
+            async (actorNames: readonly string[]) => {
+                log.debug(`Batching component fetch for ${actorNames.length} actors`);
+
+                const results = await Promise.all(
+                    actorNames.map(async (actorName) => {
+                        try {
+                            const result = await automationBridge.sendAutomationRequest<{
+                                success: boolean;
+                                components?: Array<{ name: string; type: string }>;
+                            }>('control_actor', {
+                                action: 'get_components',
+                                actorName
+                            });
+                            return result.success ? (result.components ?? null) : null;
+                        } catch {
+                            return null;
+                        }
+                    })
+                );
+                return results;
+            },
+            {
+                cache: true,
+                maxBatchSize: 30
+            }
+        )
+    };
+}
+
+/**
+ * Clears all loader caches (useful between mutations)
+ */
+export function clearLoaders(loaders: GraphQLLoaders): void {
+    loaders.actorLoader.clearAll();
+    loaders.assetLoader.clearAll();
+    loaders.blueprintLoader.clearAll();
+    loaders.actorComponentsLoader.clearAll();
+}

package/src/graphql/resolvers.ts

@@ -129,6 +129,35 @@ interface Blueprint {
   scsHierarchy?: Record<string, any>;
 }
 
+import { Logger } from '../utils/logger.js';
+
+const log = new Logger('GraphQL:Resolvers');
+
+/**
+ * Creates a GraphQL-friendly error with proper extensions
+ */
+class GraphQLResolverError extends Error {
+  extensions: { code: string; originalError?: string };
+
+  constructor(message: string, code: string = 'UNREAL_ENGINE_ERROR', originalError?: Error) {
+    super(message);
+    this.name = 'GraphQLResolverError';
+    this.extensions = {
+      code,
+      originalError: originalError?.message
+    };
+  }
+}
+
+/**
+ * Helper to create resolver errors with proper logging
+ */
+function createResolverError(operation: string, error: unknown): GraphQLResolverError {
+  const message = error instanceof Error ? error.message : String(error);
+  log.error(`${operation} failed:`, message);
+  return new GraphQLResolverError(`${operation} failed: ${message}`, 'UNREAL_ENGINE_ERROR', error instanceof Error ? error : undefined);
+}
+
 function logAutomationFailure(source: string, response: any) {
   try {
     if (!response || response.success !== false) {
@@ -138,7 +167,7 @@ function logAutomationFailure(source: string, response: any) {
     if (errorText.length === 0) {
       return;
     }
-    console.error(`[GraphQL] ${source} automation failure:`, errorText);
+    log.error(`${source} automation failure:`, errorText);
   } catch {
   }
 }
@@ -158,7 +187,7 @@ async function getActorProperties(
     });
     return result.success ? result.value || {} : {};
   } catch (error) {
-    console.error('Failed to get actor properties:', error);
+    log.error('Failed to get actor properties:', error);
     return {};
   }
 }
@@ -190,11 +219,11 @@ async function listAssets(
     }
 
     logAutomationFailure('list_assets', response);
-    console.error('Failed to list assets:', response);
+    log.warn('Failed to list assets - returning empty set');
     return { assets: [], totalCount: 0 };
   } catch (error) {
-    console.error('Failed to list assets:', error);
-    return { assets: [], totalCount: 0 };
+    log.error('Failed to list assets:', error);
+    throw createResolverError('listAssets', error);
   }
 }
 
@@ -229,33 +258,7 @@ async function listActors(
   }
 }
 
-/**
- * Helper to get blueprint details
- */
-async function getBlueprint(
-  automationBridge: AutomationBridge,
-  blueprintPath: string
-): Promise<Blueprint | null> {
-  try {
-    const response = await automationBridge.sendAutomationRequest(
-      'get_blueprint',
-      {
-        blueprintPath
-      },
-      { timeoutMs: 30000 }
-    );
 
-    if (response.success && response.result) {
-      return response.result as Blueprint;
-    }
-
-    logAutomationFailure('get_blueprint', response);
-    return null;
-  } catch (error) {
-    console.error('Failed to get blueprint:', error);
-    return null;
-  }
-}
 
 /**
  * GraphQL Resolvers Implementation
@@ -291,17 +294,10 @@ export const resolvers = {
 
     asset: async (_: any, { path }: { path: string }, context: GraphQLContext) => {
       try {
-        const response = await context.automationBridge.sendAutomationRequest(
-          'get_asset',
-          { assetPath: path },
-          { timeoutMs: 10000 }
-        );
-
-        if (response.success && response.result) {
-          return response.result;
+        if (!context.loaders) {
+          throw new Error('Loaders not initialized');
         }
-
-        return null;
+        return await context.loaders.assetLoader.load(path);
       } catch (error) {
         console.error('Failed to get asset:', error);
         return null;
@@ -336,11 +332,10 @@ export const resolvers = {
 
     actor: async (_: any, { name }: { name: string }, context: GraphQLContext) => {
       try {
-        const actors = await listActors(context.automationBridge, { tag: name });
-        if (actors.actors.length > 0) {
-          return actors.actors[0];
+        if (!context.loaders) {
+          throw new Error('Loaders not initialized');
         }
-        return null;
+        return await context.loaders.actorLoader.load(name);
       } catch (error) {
         console.error('Failed to get actor:', error);
         return null;
@@ -394,7 +389,10 @@ export const resolvers = {
     },
 
     blueprint: async (_: any, { path }: { path: string }, context: GraphQLContext) => {
-      return await getBlueprint(context.automationBridge, path);
+      if (!context.loaders) {
+        throw new Error('Loaders not initialized');
+      }
+      return await context.loaders.blueprintLoader.load(path);
     },
 
     levels: async (_: any, __: any, context: GraphQLContext) => {
@@ -524,9 +522,9 @@ export const resolvers = {
           { subAction: 'get_cells' },
           { timeoutMs: 10000 }
         );
-        
+
         if (response.success && response.result) {
-            return (response.result as any).cells || [];
+          return (response.result as any).cells || [];
         }
         return [];
       } catch (error) {
@@ -550,7 +548,7 @@ export const resolvers = {
         const edges = assets.map((asset, index) => ({
           node: {
             ...asset,
-            emitters: [], 
+            emitters: [],
             parameters: []
           },
           cursor: Buffer.from(`${asset.path}:${offset + index}`).toString('base64')

package/src/graphql/server.ts

@@ -5,6 +5,7 @@ import { createGraphQLSchema } from './schema.js';
 import type { GraphQLContext } from './types.js';
 import type { UnrealBridge } from '../unreal-bridge.js';
 import { AutomationBridge } from '../automation/index.js';
+import { createLoaders } from './loaders.js';
 
 export interface GraphQLServerConfig {
   enabled?: boolean;
@@ -65,7 +66,8 @@ export class GraphQLServer {
         },
         context: (): GraphQLContext => ({
           bridge: this.bridge,
-          automationBridge: this.automationBridge
+          automationBridge: this.automationBridge,
+          loaders: createLoaders(this.automationBridge)
         }),
         logging: {
           debug: (...args) => this.log.debug('[GraphQL]', ...args),

package/src/graphql/types.ts

@@ -1,7 +1,10 @@
 import type { UnrealBridge } from '../unreal-bridge.js';
 import { AutomationBridge } from '../automation/index.js';
+import type { GraphQLLoaders } from './loaders.js';
 
 export interface GraphQLContext {
     bridge: UnrealBridge;
     automationBridge: AutomationBridge;
+    /** DataLoaders for batching and caching - solves N+1 query problem */
+    loaders?: GraphQLLoaders;
 }

package/src/index.ts

@@ -13,6 +13,7 @@ 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 } = (() => {
@@ -106,6 +107,12 @@ export function createServer() {
   // 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(() => {
@@ -145,7 +152,7 @@ export function createServer() {
   const serverSetup = new ServerSetup(server, bridge, automationBridge, log, healthMonitor);
   serverSetup.setup(); // Register tools, resources, and prompts
 
-  return { server, bridge, automationBridge };
+  return { server, bridge, automationBridge, graphqlServer };
 }
 
 // Export configuration schema for session UI and runtime validation
@@ -170,7 +177,7 @@ export default function createServerDefault({ config }: { config?: any } = {}) {
 }
 
 export async function startStdioServer() {
-  const { server, automationBridge } = createServer();
+  const { server, automationBridge, graphqlServer } = createServer();
   const transport = new StdioServerTransport();
   let shuttingDown = false;
 
@@ -187,6 +194,12 @@ export async function startStdioServer() {
       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();

package/src/resources/assets.ts

@@ -1,6 +1,7 @@
 import { BaseTool } from '../tools/base-tool.js';
 import { IAssetResources } from '../types/tool-interfaces.js';
 import { coerceString } from '../utils/result-helpers.js';
+import { AutomationResponse } from '../types/automation-responses.js';
 
 export class AssetResources extends BaseTool implements IAssetResources {
   // Simple in-memory cache for asset listing
@@ -175,14 +176,14 @@ export class AssetResources extends BaseTool implements IAssetResources {
       // Use the native C++ plugin's list action instead of Python
       try {
         const normalizedDir = this.normalizeDir(dir);
-        const response = await this.sendAutomationRequest(
+        const response = await this.sendAutomationRequest<AutomationResponse>(
           'list',
           { directory: normalizedDir, limit, recursive: false },
           { timeoutMs: 30000 }
         );
 
         if (response.success !== false && response.result) {
-          const payload = response.result;
+          const payload = response.result as any;
 
           const foldersArr = Array.isArray(payload.folders_list)
             ? payload.folders_list.map((f: any) => ({
@@ -257,12 +258,12 @@ export class AssetResources extends BaseTool implements IAssetResources {
 
     try {
       const normalizedPath = this.normalizeDir(assetPath);
-      const response = await this.sendAutomationRequest(
+      const response = await this.sendAutomationRequest<AutomationResponse>(
         'asset_exists',
         { asset_path: normalizedPath }
       );
 
-      return response?.success !== false && response?.result?.exists === true;
+      return response?.success !== false && (response?.result as any)?.exists === true;
     } catch {
       return false;
     }

package/src/server/tool-registry.ts

@@ -210,7 +210,7 @@ export class ToolRegistry {
 
         this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const { name } = request.params;
-            let args: any = request.params.arguments || {};
+            let args: Record<string, unknown> = request.params.arguments || {};
             const startTime = Date.now();
 
             const connected = await this.ensureConnected();
@@ -258,13 +258,13 @@ export class ToolRegistry {
                         const props = inputSchema.properties || {};
                         const required: string[] = Array.isArray(inputSchema.required) ? inputSchema.required : [];
                         const missing = required.filter((k: string) => {
-                            const v = (args as any)[k];
+                            const v = (args as Record<string, unknown>)[k];
                             if (v === undefined || v === null) return true;
                             if (typeof v === 'string' && v.trim() === '') return true;
                             return false;
                         });
 
-                        const primitiveProps: any = {};
+                        const primitiveProps: Record<string, unknown> = {};
                         for (const k of missing) {
                             const p = props[k];
                             if (!p || typeof p !== 'object') continue;

package/src/server-setup.ts

@@ -1,10 +1,10 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+// import { ListPromptsRequestSchema, GetPromptRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { UnrealBridge } from './unreal-bridge.js';
 import { AutomationBridge } from './automation/index.js';
 import { Logger } from './utils/logger.js';
 import { HealthMonitor } from './services/health-monitor.js';
-import { prompts } from './prompts/index.js';
+// import { prompts } from './prompts/index.js';
 import { AssetResources } from './resources/assets.js';
 import { ActorResources } from './resources/actors.js';
 import { LevelResources } from './resources/levels.js';
@@ -73,7 +73,7 @@ export class ServerSetup {
     );
     toolRegistry.register();
 
-    this.registerPrompts();
+    // this.registerPrompts();
   }
 
   private validateEnvironment() {
@@ -110,39 +110,5 @@ export class ServerSetup {
     return ok;
   }
 
-  private registerPrompts() {
-    this.server.setRequestHandler(ListPromptsRequestSchema, async () => {
-      return {
-        prompts: prompts.map(p => ({
-          name: p.name,
-          description: p.description,
-          arguments: Object.entries(p.arguments || {}).map(([name, schema]) => {
-            const meta: Record<string, unknown> = {};
-            if (schema.type) meta.type = schema.type;
-            if (schema.enum) meta.enum = schema.enum;
-            if (schema.default !== undefined) meta.default = schema.default;
-            return {
-              name,
-              description: schema.description,
-              required: schema.required ?? false,
-              ...(Object.keys(meta).length ? { _meta: meta } : {})
-            };
-          })
-        }))
-      };
-    });
 
-    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-      const prompt = prompts.find(p => p.name === request.params.name);
-      if (!prompt) {
-        throw new Error(`Unknown prompt: ${request.params.name}`);
-      }
-      const args = (request.params.arguments || {}) as Record<string, unknown>;
-      const messages = prompt.build(args);
-      return {
-        description: prompt.description,
-        messages
-      };
-    });
-  }
 }