ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/docs/index.js

@@ -0,0 +1,251 @@
+// src/tools/docs/index.ts
+// Registers UE documentation tools backed by DocIndex and the bundled UE 5.7 API data.
+// All handlers are wrapped with withKnownIssues() per INF-06.
+import { z } from 'zod';
+import { withKnownIssues } from '../known-issues/middleware.js';
+import { DocIndex } from '../../docs/doc-index.js';
+import { UE57_API_RECORDS } from '../../docs/data/ue57-api.js';
+// ---------------------------------------------------------------------------
+// Module-level singleton — loaded once at import time.
+// Avoids rebuilding the MiniSearch index on every tool call.
+// ---------------------------------------------------------------------------
+const docIndex = new DocIndex();
+docIndex.load(UE57_API_RECORDS);
+// ---------------------------------------------------------------------------
+// Pure handler functions (exported for testing without MCP server)
+// ---------------------------------------------------------------------------
+/**
+ * ue_search_api handler logic — exported for direct testing.
+ * @param args     Tool input args ({ query: string })
+ * @param index    DocIndex to query (defaults to the module singleton)
+ */
+export async function handleSearchApi(args, index = docIndex) {
+    const results = index.search(args.query, 20);
+    if (results.length === 0) {
+        return {
+            content: [
+                { type: 'text', text: `No results found for query: "${args.query}"` },
+            ],
+        };
+    }
+    const lines = [
+        `Search results for "${args.query}" (${results.length} result${results.length === 1 ? '' : 's'}):`,
+    ];
+    results.forEach((result, idx) => {
+        const r = result.record;
+        const scoreStr = result.score.toFixed(2);
+        lines.push('');
+        lines.push(`${idx + 1}. [${r.type}] ${r.fullName} (score: ${scoreStr})`);
+        if (r.module) {
+            if (r.type === 'class' || r.type === 'enum') {
+                lines.push(`   Module: ${r.module} | Include: ${r.includePath}`);
+            }
+            else {
+                if (r.signature) {
+                    lines.push(`   Signature: ${r.signature}`);
+                }
+                lines.push(`   Include: ${r.includePath}`);
+            }
+        }
+        if (r.description) {
+            lines.push(`   ${r.description}`);
+        }
+    });
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+/**
+ * ue_lookup_class handler logic — exported for direct testing.
+ * @param args     Tool input args ({ class_name: string })
+ * @param index    DocIndex to query (defaults to the module singleton)
+ */
+export async function handleLookupClass(args, index = docIndex) {
+    const records = index.lookupClass(args.class_name);
+    if (records.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Class not found: "${args.class_name}". Check spelling and case (e.g., UStaticMeshComponent).`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const classRecord = records.find((r) => r.type === 'class') ?? records[0];
+    const members = records.filter((r) => r.type !== 'class');
+    const lines = [
+        `Class: ${classRecord.className}`,
+        `Module: ${classRecord.module}`,
+        `Include: #include "${classRecord.includePath}"`,
+        `Description: ${classRecord.description}`,
+    ];
+    if (classRecord.deprecated) {
+        lines.push('');
+        lines.push(`[DEPRECATED] ${classRecord.deprecatedMessage}`);
+        if (classRecord.replacementAPI) {
+            lines.push(`Replacement: ${classRecord.replacementAPI}`);
+        }
+    }
+    lines.push('');
+    lines.push(`Members (${members.length}):`);
+    if (members.length === 0) {
+        lines.push('  (no indexed members)');
+    }
+    else {
+        for (const m of members) {
+            if (m.type === 'function') {
+                lines.push(`  [function] ${m.name} — ${m.signature}`);
+            }
+            else if (m.type === 'property') {
+                lines.push(`  [property] ${m.name}`);
+            }
+            else {
+                lines.push(`  [${m.type}] ${m.name}`);
+            }
+        }
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+/**
+ * ue_get_include_path handler logic — exported for direct testing.
+ * @param args     Tool input args ({ class_name: string })
+ * @param index    DocIndex to query (defaults to the module singleton)
+ */
+export async function handleGetIncludePath(args, index = docIndex) {
+    const includePath = index.getIncludePath(args.class_name);
+    if (includePath === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No include path found for "${args.class_name}". Class not in UE 5.7 index.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `#include "${includePath}"` }],
+    };
+}
+/**
+ * ue_check_deprecation handler logic — exported for direct testing.
+ * @param args     Tool input args ({ symbol_name: string })
+ * @param index    DocIndex to query (defaults to the module singleton)
+ */
+export async function handleCheckDeprecation(args, index = docIndex) {
+    const result = index.checkDeprecation(args.symbol_name);
+    if (result === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Symbol not found: "${args.symbol_name}". Cannot check deprecation status.`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (!result.deprecated) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `"${args.symbol_name}" is NOT deprecated in UE 5.7. Safe to use.`,
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `"${args.symbol_name}" IS DEPRECATED in UE 5.7.\nReason: ${result.message}\nRecommended replacement: ${result.replacement}`,
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register UE documentation tools on the MCP server.
+ *
+ * Tools registered:
+ *   ue_search_api        — Full-text search across the UE API reference
+ *   ue_lookup_class      — Look up a specific UE class in the API docs
+ *   ue_get_include_path  — Get the correct #include path for a UE class
+ *   ue_check_deprecation — Check if a UE symbol is deprecated in UE 5.7
+ *
+ * @param server  The McpServer instance to register tools on.
+ */
+export function registerDocsTools(server) {
+    // --------------------------------------------------------------------------
+    // ue_search_api
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_search_api', {
+        title: 'Search UE API',
+        description: 'Search the Unreal Engine 5.7 API reference documentation for classes, functions, and concepts.',
+        inputSchema: z.object({
+            query: z.string().describe('Search query (e.g., "UStaticMeshComponent collision")'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_search_api', async (args) => {
+        return handleSearchApi(args);
+    }));
+    // --------------------------------------------------------------------------
+    // ue_lookup_class
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_lookup_class', {
+        title: 'Lookup UE Class',
+        description: 'Look up a specific Unreal Engine class in the API docs, returning its description, hierarchy, and key methods.',
+        inputSchema: z.object({
+            class_name: z.string().describe('The UE class name (e.g., UStaticMeshComponent)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_lookup_class', async (args) => {
+        return handleLookupClass(args);
+    }));
+    // --------------------------------------------------------------------------
+    // ue_get_include_path
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_get_include_path', {
+        title: 'Get UE Include Path',
+        description: 'Get the correct #include path for a Unreal Engine class (e.g., #include "Components/StaticMeshComponent.h").',
+        inputSchema: z.object({
+            class_name: z.string().describe('The UE class name to find the include path for'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_get_include_path', async (args) => {
+        return handleGetIncludePath(args);
+    }));
+    // --------------------------------------------------------------------------
+    // ue_check_deprecation
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_check_deprecation', {
+        title: 'Check UE Symbol Deprecation',
+        description: 'Check whether a UE 5.7 symbol (class, function, or macro) is deprecated and what the recommended replacement is.',
+        inputSchema: z.object({
+            symbol_name: z.string().describe('The UE symbol name to check for deprecation'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_check_deprecation', async (args) => {
+        return handleCheckDeprecation(args);
+    }));
+}

package/dist/tools/editor/index.js

@@ -0,0 +1,242 @@
+// src/tools/editor/index.ts
+// Real tool implementations for UE Editor actor/asset operations (Phase 9).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge plugin.
+// Returns structured plugin_not_connected errors (not crashes) when plugin is absent.
+import { z } from 'zod';
+import { withKnownIssues } from '../known-issues/middleware.js';
+import { PluginBridgeClient, PluginNotConnectedError } from '../../plugin-bridge/client.js';
+// ---------------------------------------------------------------------------
+// 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(bridge, cmd) {
+    try {
+        const response = await bridge.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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerEditorTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Editor actor/asset 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 9 — real implementations):
+ *   ue_list_actors        — List actors in the current level
+ *   ue_spawn_actor        — Spawn a new actor in the level
+ *   ue_transform_actor    — Move, rotate, and/or scale an existing actor
+ *   ue_delete_actor       — Delete an actor from the level
+ *   ue_query_assets       — Query the UE asset registry
+ *   ue_trace_references   — Trace asset reference graph
+ *   ue_read_level_layout  — Read the open level structure
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerEditorTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_actors
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_actors', {
+        title: 'List UE Actors',
+        description: '[requires_plugin] List all actors in the currently open UE Editor level.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_actors', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'actor.list' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_spawn_actor
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_spawn_actor', {
+        title: 'Spawn UE Actor',
+        description: '[requires_plugin] Spawn a new actor in the currently open UE Editor level at the specified location.',
+        inputSchema: z.object({
+            class_name: z.string().describe('The actor class to spawn (e.g., AStaticMeshActor)'),
+            location: z.object({
+                x: z.number().describe('X coordinate in Unreal units (cm)'),
+                y: z.number().describe('Y coordinate in Unreal units (cm)'),
+                z: z.number().describe('Z coordinate in Unreal units (cm)'),
+            }).describe('World-space location to spawn the actor at'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_spawn_actor', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'actor.spawn',
+            payload: { class_name: args.class_name, location: args.location },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_transform_actor  (Phase 9 — adds scale field; renamed from Phase 1 stub)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_transform_actor', {
+        title: 'Transform UE Actor',
+        description: '[requires_plugin] Move, rotate, and/or scale an existing actor in the currently open UE Editor level.',
+        inputSchema: z.object({
+            actor_label: z.string().describe('The editor label of the actor to transform'),
+            location: z
+                .object({
+                x: z.number().describe('X coordinate in Unreal units (cm)'),
+                y: z.number().describe('Y coordinate in Unreal units (cm)'),
+                z: z.number().describe('Z coordinate in Unreal units (cm)'),
+            })
+                .optional()
+                .describe('New world-space location (optional — omit to keep current location)'),
+            rotation: z
+                .object({
+                pitch: z.number().describe('Pitch angle in degrees'),
+                yaw: z.number().describe('Yaw angle in degrees'),
+                roll: z.number().describe('Roll angle in degrees'),
+            })
+                .optional()
+                .describe('New rotation in degrees (optional — omit to keep current rotation)'),
+            scale: z
+                .object({
+                x: z.number().describe('X scale factor'),
+                y: z.number().describe('Y scale factor'),
+                z: z.number().describe('Z scale factor'),
+            })
+                .optional()
+                .describe('New 3D scale (optional, default 1.0 per axis)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_transform_actor', async (args) => {
+        const payload = { actor_label: args.actor_label };
+        if (args.location)
+            payload['location'] = args.location;
+        if (args.rotation)
+            payload['rotation'] = args.rotation;
+        if (args.scale)
+            payload['scale'] = args.scale;
+        return sendOrDisconnect(_bridge, { type: 'actor.transform', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_delete_actor
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_delete_actor', {
+        title: 'Delete UE Actor',
+        description: '[requires_plugin] Delete an actor from the currently open UE Editor level. This operation is destructive.',
+        inputSchema: z.object({
+            actor_label: z.string().describe('The editor label of the actor to delete'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+    }, withKnownIssues('ue_delete_actor', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'actor.delete',
+            payload: { actor_label: args.actor_label },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_query_assets
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_query_assets', {
+        title: 'Query UE Assets',
+        description: '[requires_plugin] Query the UE asset registry for assets matching optional filters (type, path prefix, tag).',
+        inputSchema: z.object({
+            asset_type: z
+                .string()
+                .optional()
+                .describe('Asset class name to filter by (e.g., StaticMesh, Blueprint)'),
+            path_prefix: z
+                .string()
+                .optional()
+                .describe('Asset path prefix to filter by (e.g., /Game/Meshes/)'),
+            tag: z
+                .string()
+                .optional()
+                .describe('Asset tag key to filter by'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_query_assets', async (args) => {
+        // Map TS-friendly names to the C++ handler's expected field names.
+        // C++ expects 'asset_class' (not 'asset_type') and 'tag_key' (not 'tag').
+        const payload = {};
+        if (args.asset_type)
+            payload['asset_class'] = args.asset_type;
+        if (args.path_prefix)
+            payload['path_prefix'] = args.path_prefix;
+        if (args.tag)
+            payload['tag_key'] = args.tag;
+        return sendOrDisconnect(_bridge, { type: 'asset.query', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_trace_references  (new tool — EDT-06)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_trace_references', {
+        title: 'Trace UE Asset References',
+        description: '[requires_plugin] Trace the reference graph for a given asset — what it depends on and what depends on it.',
+        inputSchema: z.object({
+            package_path: z.string().describe('Asset package path (e.g. /Game/Meshes/SM_Rock)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_trace_references', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'asset.references',
+            payload: { package_path: args.package_path },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_read_level_layout  (new tool — EDT-07)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_level_layout', {
+        title: 'Read UE Level Layout',
+        description: '[requires_plugin] Read the open level structure — placed actors, streaming sublevels, and world partition status.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_level_layout', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'level.layout' });
+    }));
+}