ultimate-unreal-engine-mcp 0.1.0

package/dist/setup.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+// setup.ts — One-command installer for Ultimate Unreal Engine MCP.
+// Automatically configures Claude Desktop, Claude Code, or Cursor to use this server.
+//
+// Usage:
+//   npx ultimate-unreal-engine-mcp setup
+//   npx ultimate-unreal-engine-mcp setup --project "C:/MyGame"
+//   npx ultimate-unreal-engine-mcp setup --client claude-code
+//   npx ultimate-unreal-engine-mcp setup --port 55557
+import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { platform, env } from 'node:process';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function log(msg) {
+    console.error(msg);
+}
+function getConfigPath(client) {
+    const home = env['USERPROFILE'] || env['HOME'] || '';
+    switch (client) {
+        case 'claude-desktop':
+            if (platform === 'win32') {
+                return join(env['APPDATA'] || join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+            }
+            return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        case 'claude-code':
+            return join(home, '.claude', 'settings.json');
+        case 'cursor':
+            if (platform === 'win32') {
+                return join(env['APPDATA'] || join(home, 'AppData', 'Roaming'), 'Cursor', 'User', 'globalStorage', 'cursor.mcp', 'config.json');
+            }
+            return join(home, '.config', 'cursor', 'mcp.json');
+        default:
+            return '';
+    }
+}
+function parseArgs(argv) {
+    let project = '';
+    let client = 'claude-desktop';
+    let port = 55557;
+    let pluginOnly = false;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--project' && argv[i + 1]) {
+            project = argv[++i];
+        }
+        else if (argv[i] === '--client' && argv[i + 1]) {
+            client = argv[++i];
+        }
+        else if (argv[i] === '--port' && argv[i + 1]) {
+            port = parseInt(argv[++i], 10);
+        }
+        else if (argv[i] === '--plugin-only') {
+            pluginOnly = true;
+        }
+    }
+    return { project, client, port, pluginOnly };
+}
+// ---------------------------------------------------------------------------
+// Plugin installer
+// ---------------------------------------------------------------------------
+function installPlugin(projectRoot) {
+    const pluginSrc = join(dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1')), '..', 'unreal-plugin', 'MCPBridge');
+    const pluginDest = join(projectRoot, 'Plugins', 'MCPBridge');
+    if (!existsSync(pluginSrc)) {
+        log(`  Plugin source not found at ${pluginSrc}`);
+        log('  You may need to copy unreal-plugin/MCPBridge/ manually.');
+        return false;
+    }
+    if (existsSync(pluginDest)) {
+        log(`  Plugin already exists at ${pluginDest} — skipping copy.`);
+        return true;
+    }
+    try {
+        mkdirSync(dirname(pluginDest), { recursive: true });
+        cpSync(pluginSrc, pluginDest, { recursive: true });
+        log(`  Copied MCPBridge plugin to ${pluginDest}`);
+        return true;
+    }
+    catch (err) {
+        log(`  Failed to copy plugin: ${err}`);
+        log(`  Copy manually: cp -r "${pluginSrc}" "${pluginDest}"`);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Config writer
+// ---------------------------------------------------------------------------
+function configureClient(client, port, projectRoot) {
+    const configPath = getConfigPath(client);
+    if (!configPath) {
+        log(`  Unknown client: ${client}`);
+        log('  Supported: claude-desktop, claude-code, cursor');
+        return;
+    }
+    // For claude-code, we use the mcpServers format in settings.json
+    // For claude-desktop and cursor, we use the standard MCP config format
+    let config = {};
+    if (existsSync(configPath)) {
+        try {
+            config = JSON.parse(readFileSync(configPath, 'utf-8'));
+        }
+        catch {
+            log(`  Warning: Could not parse existing ${configPath}, creating fresh config.`);
+        }
+    }
+    const serverEntry = {
+        command: 'npx',
+        args: ['-y', 'ultimate-unreal-engine-mcp'],
+    };
+    // Only add env if project root is specified
+    const envBlock = {};
+    if (projectRoot) {
+        envBlock['UE_PROJECT_ROOT'] = projectRoot;
+    }
+    if (port !== 55557) {
+        envBlock['UE_PLUGIN_PORT'] = String(port);
+    }
+    if (Object.keys(envBlock).length > 0) {
+        serverEntry['env'] = envBlock;
+    }
+    if (client === 'claude-code') {
+        // Claude Code uses settings.json with mcpServers at top level
+        if (!config['mcpServers'] || typeof config['mcpServers'] !== 'object') {
+            config['mcpServers'] = {};
+        }
+        config['mcpServers']['unreal-engine'] = serverEntry;
+    }
+    else {
+        // Claude Desktop and Cursor use the standard format
+        if (!config['mcpServers'] || typeof config['mcpServers'] !== 'object') {
+            config['mcpServers'] = {};
+        }
+        config['mcpServers']['unreal-engine'] = serverEntry;
+    }
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    log(`  Configured ${client} at ${configPath}`);
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+    const args = parseArgs(process.argv.slice(2));
+    // Check if this is a "setup" invocation or just running the server
+    const command = process.argv[2];
+    if (command !== 'setup') {
+        // Not setup — just import and run the server
+        // This is handled by the bin entry pointing to dist/index.js
+        console.error('Usage: npx ultimate-unreal-engine-mcp setup [--project <path>] [--client <name>] [--port <num>]');
+        console.error('');
+        console.error('Options:');
+        console.error('  --project <path>     Path to your UE project (optional, can set later via UE_PROJECT_ROOT)');
+        console.error('  --client <name>      claude-desktop (default), claude-code, or cursor');
+        console.error('  --port <num>         Plugin TCP port (default: 55557)');
+        console.error('  --plugin-only        Only install the UE plugin, skip MCP config');
+        console.error('');
+        console.error('Examples:');
+        console.error('  npx ultimate-unreal-engine-mcp setup');
+        console.error('  npx ultimate-unreal-engine-mcp setup --project "C:/MyGame" --client claude-code');
+        process.exit(1);
+    }
+    log('');
+    log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    log(' Ultimate Unreal Engine MCP — Setup');
+    log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    log('');
+    // Step 1: Configure MCP client
+    if (!args.pluginOnly) {
+        log('Step 1: Configuring MCP client...');
+        configureClient(args.client, args.port, args.project);
+        log('');
+    }
+    // Step 2: Install UE plugin (if project path provided)
+    if (args.project) {
+        const projectRoot = resolve(args.project);
+        if (!existsSync(projectRoot)) {
+            log(`Step 2: Project path not found: ${projectRoot}`);
+            log('  Skipping plugin install. You can copy it manually later.');
+        }
+        else {
+            log('Step 2: Installing UE plugin...');
+            installPlugin(projectRoot);
+            log('');
+            log('  After installing, regenerate project files and compile.');
+            log('  The plugin starts a TCP server on port ' + args.port + ' when the editor launches.');
+        }
+    }
+    else {
+        log('Step 2: No --project path specified.');
+        log('  To install the UE plugin later, copy unreal-plugin/MCPBridge/');
+        log('  into your UE project\'s Plugins/ folder.');
+    }
+    log('');
+    log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    log(' Setup complete!');
+    log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    log('');
+    log('Next steps:');
+    log('  1. Restart ' + args.client);
+    log('  2. Ask Claude: "List all Blueprint assets in my project"');
+    log('');
+    if (!args.project) {
+        log('Optional: Set your UE project path:');
+        log('  npx ultimate-unreal-engine-mcp setup --project "C:/path/to/MyGame"');
+        log('');
+    }
+}
+main();

package/dist/tools/ai-systems/index.js

@@ -0,0 +1,247 @@
+// src/tools/ai-systems/index.ts
+// MCP tool implementations for AI system asset inspection (Phase 22).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge handlers.
+// Returns structured plugin_not_connected errors when the plugin is absent.
+//
+// Tools registered (Phase 22 — AI-01 through AI-05):
+//   ue_inspect_behavior_tree  — Inspect BT node hierarchy, decorators, and services
+//   ue_inspect_state_tree     — Read State Tree states, transitions, and tasks
+//   ue_inspect_blackboard     — List Blackboard keys with types and instance-sync status
+//   ue_inspect_eqs            — Inspect EQS query templates: generators, tests, scoring
+//   ue_query_navmesh          — Query NavMesh build status, bounds, and point reachability
+//
+// All tools require MCPBridge plugin (Phase 22 — AI-01 through AI-05).
+import { z } from 'zod';
+import { withKnownIssues } from '../known-issues/middleware.js';
+import { PluginBridgeClient, PluginNotConnectedError } from '../../plugin-bridge/client.js';
+// Module-level bridge instance — injected in tests via exported handler signatures.
+const bridge = new PluginBridgeClient();
+// ---------------------------------------------------------------------------
+// sendOrDisconnect helper
+// ---------------------------------------------------------------------------
+/**
+ * Sends a command to the bridge and returns a ToolResult.
+ *
+ * - On success (response.success true): returns data as JSON text.
+ * - On command-level failure (response.success false): returns isError:true with error JSON.
+ * - On PluginNotConnectedError: returns isError:true with plugin_not_connected JSON.
+ * - On other errors: rethrows (withKnownIssues catches and formats).
+ *
+ * NOTE: sendCommand() overwrites correlationId with crypto.randomUUID() internally;
+ * passing an empty string is safe and correct (per STATE.md decision).
+ */
+async function sendOrDisconnect(b, cmd) {
+    try {
+        const response = await b.sendCommand({ ...cmd, correlationId: '' });
+        if (!response.success) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: response.error }) }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response.data ?? {}) }],
+        };
+    }
+    catch (err) {
+        if (err instanceof PluginNotConnectedError) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(err.bridgeError) }],
+            };
+        }
+        throw err; // withKnownIssues catches unexpected errors
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported handler functions (for direct unit testing via bridge injection)
+// ---------------------------------------------------------------------------
+/**
+ * ue_inspect_behavior_tree handler — satisfies AI-01.
+ * Sends ai.behaviorTree to the plugin; returns node hierarchy, decorators, and services.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectBehaviorTree(args, b = bridge) {
+    // Response data shape: BehaviorTreeInspectResult
+    return sendOrDisconnect(b, {
+        type: 'ai.behaviorTree',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_state_tree handler — satisfies AI-02.
+ * Sends ai.stateTree to the plugin; returns states, transitions, and tasks.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectStateTree(args, b = bridge) {
+    // Response data shape: StateTreeInspectResult
+    return sendOrDisconnect(b, {
+        type: 'ai.stateTree',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_blackboard handler — satisfies AI-03.
+ * Sends ai.blackboard to the plugin; returns Blackboard keys with types and instance-sync status.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectBlackboard(args, b = bridge) {
+    // Response data shape: BlackboardInspectResult
+    return sendOrDisconnect(b, {
+        type: 'ai.blackboard',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_eqs handler — satisfies AI-04.
+ * Sends ai.eqs to the plugin; returns EQS generator classes, tests, and scoring configuration.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectEqs(args, b = bridge) {
+    // Response data shape: EQSInspectResult
+    return sendOrDisconnect(b, {
+        type: 'ai.eqs',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_query_navmesh handler — satisfies AI-05.
+ * Sends ai.navmesh to the plugin; returns NavMesh build status, bounds, and optional
+ * point-to-point reachability when both start_point and end_point are provided.
+ *
+ * @param args  Tool arguments including optional start_point and end_point.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleQueryNavmesh(args, b = bridge) {
+    // Response data shape: NavMeshQueryResult
+    const payload = {};
+    if (args.start_point !== undefined && args.end_point !== undefined) {
+        payload['start_point'] = args.start_point;
+        payload['end_point'] = args.end_point;
+    }
+    return sendOrDisconnect(b, {
+        type: 'ai.navmesh',
+        payload,
+    });
+}
+// ---------------------------------------------------------------------------
+// registerAISystemsTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE AI system inspection tools on the MCP server.
+ *
+ * All tools in this domain require the MCPBridge editor plugin.
+ * When the plugin is not connected, each handler returns:
+ *   { isError: true, content: [{ type: 'text', text: <plugin_not_connected JSON> }] }
+ *
+ * Tools registered (Phase 22):
+ *   ue_inspect_behavior_tree  — AI-01: Inspect BT node hierarchy with decorators and services
+ *   ue_inspect_state_tree     — AI-02: Read State Tree states, transitions, and tasks
+ *   ue_inspect_blackboard     — AI-03: List Blackboard keys with types and instance-sync status
+ *   ue_inspect_eqs            — AI-04: Inspect EQS query generators, tests, and scoring
+ *   ue_query_navmesh          — AI-05: Query NavMesh status, bounds, and reachability
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param _bridge Optional PluginBridgeClient for testing (not used directly — handlers
+ *                accept bridge injection via their exported function signatures).
+ */
+export function registerAISystemsTools(server, _bridge) {
+    const b = _bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_inspect_behavior_tree (AI-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_behavior_tree', {
+        title: 'Inspect Behavior Tree',
+        description: '[requires_plugin] Inspect a Behavior Tree asset\'s node hierarchy, decorators, and services.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Behavior Tree asset, e.g. /Game/AI/BT_EnemyLogic'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_behavior_tree', async (args) => handleInspectBehaviorTree(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_state_tree (AI-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_state_tree', {
+        title: 'Inspect State Tree',
+        description: '[requires_plugin] Read a State Tree\'s states, transitions, and tasks.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the State Tree asset, e.g. /Game/AI/ST_NPCBehavior'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_state_tree', async (args) => handleInspectStateTree(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_blackboard (AI-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_blackboard', {
+        title: 'Inspect Blackboard',
+        description: '[requires_plugin] List all Blackboard keys with their types, default values, and instance-sync status.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Blackboard Data asset, e.g. /Game/AI/BB_EnemyData'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_blackboard', async (args) => handleInspectBlackboard(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_eqs (AI-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_eqs', {
+        title: 'Inspect EQS Query',
+        description: '[requires_plugin] Inspect an Environment Query System template\'s generators, tests, and scoring configuration.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the EQS query asset, e.g. /Game/AI/EQS_FindCover'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_eqs', async (args) => handleInspectEqs(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_query_navmesh (AI-05)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_query_navmesh', {
+        title: 'Query NavMesh',
+        description: '[requires_plugin] Query NavMesh build status, bounds, and optionally test reachability between two points.',
+        inputSchema: z.object({
+            start_point: z
+                .object({ x: z.number(), y: z.number(), z: z.number() })
+                .optional()
+                .describe('Optional start point for reachability test'),
+            end_point: z
+                .object({ x: z.number(), y: z.number(), z: z.number() })
+                .optional()
+                .describe('Optional end point for reachability test'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_query_navmesh', async (args) => handleQueryNavmesh(args, b)));
+}

package/dist/tools/ai-systems/types.js

@@ -0,0 +1,4 @@
+// src/tools/ai-systems/types.ts
+// TypeScript result interfaces for the five AI system MCP tools (Phase 22).
+// These interfaces mirror the JSON shapes returned by the C++ handlers in Plan 22-01.
+export {};