ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/validation/index.js

@@ -0,0 +1,183 @@
+// src/tools/validation/index.ts
+// MCP tool implementations for UE data validation and Blueprint compile-check (Phase 16).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge handlers.
+// Returns structured plugin_not_connected errors when the plugin is absent.
+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_validate_asset handler — satisfies VAL-01.
+ * Sends validate.asset to the plugin; returns structured pass/fail with error/warning counts.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleValidateAsset(args, b = bridge) {
+    // Response data shape: ValidationAssetResult
+    return sendOrDisconnect(b, {
+        type: 'validate.asset',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_validate_folder handler — satisfies VAL-02.
+ * Sends validate.folder to the plugin; returns per-folder summary with asset counts.
+ *
+ * @param args  Tool arguments including folder_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleValidateFolder(args, b = bridge) {
+    // Response data shape: ValidationFolderResult
+    return sendOrDisconnect(b, {
+        type: 'validate.folder',
+        payload: { folder_path: args.folder_path },
+    });
+}
+/**
+ * ue_validate_project handler — satisfies VAL-03.
+ * Sends validate.project to the plugin; returns categorized project-wide counts.
+ *
+ * @param _args  No input arguments (empty record).
+ * @param b      PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleValidateProject(_args, b = bridge) {
+    return sendOrDisconnect(b, { type: 'validate.project' });
+}
+/**
+ * ue_check_blueprint handler — satisfies VAL-04.
+ * Sends validate.blueprint to the plugin; returns compiled:bool with status and errorMessage.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleCheckBlueprint(args, b = bridge) {
+    // Response data shape: BlueprintCompileResult
+    return sendOrDisconnect(b, {
+        type: 'validate.blueprint',
+        payload: { asset_path: args.asset_path },
+    });
+}
+// ---------------------------------------------------------------------------
+// registerValidationTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE data validation and Blueprint compile-check 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 16):
+ *   ue_validate_asset    — VAL-01: Run data validation on a single asset
+ *   ue_validate_folder   — VAL-02: Run data validation on all assets in a folder
+ *   ue_validate_project  — VAL-03: Run data validation across all /Game/ assets
+ *   ue_check_blueprint   — VAL-04: Compile-check a Blueprint asset
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerValidationTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_validate_asset (VAL-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_validate_asset', {
+        title: 'Validate UE Asset',
+        description: '[requires_plugin] Run UE data validation rules on a single asset and return structured pass/fail results with error and warning counts.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe('UE long package path, e.g. /Game/Blueprints/BP_MyActor'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_validate_asset', async (args) => handleValidateAsset(args, _bridge)));
+    // --------------------------------------------------------------------------
+    // ue_validate_folder (VAL-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_validate_folder', {
+        title: 'Validate UE Assets in Folder',
+        description: '[requires_plugin] Run UE data validation on all assets under a folder path and return a summary report.',
+        inputSchema: z.object({
+            folder_path: z
+                .string()
+                .describe('UE package path prefix, e.g. /Game/Blueprints'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_validate_folder', async (args) => handleValidateFolder(args, _bridge)));
+    // --------------------------------------------------------------------------
+    // ue_validate_project (VAL-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_validate_project', {
+        title: 'Validate All Project Assets',
+        description: '[requires_plugin] Run UE data validation across all /Game/ assets and return categorized error, warning, and info counts.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_validate_project', async (_args) => handleValidateProject({}, _bridge)));
+    // --------------------------------------------------------------------------
+    // ue_check_blueprint (VAL-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_check_blueprint', {
+        title: 'Check Blueprint Compilation',
+        description: '[requires_plugin] Compile-check a Blueprint asset and return structured compiler messages indicating success or failure.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe('UE long package path to the Blueprint asset, e.g. /Game/Blueprints/BP_MyActor'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_check_blueprint', async (args) => handleCheckBlueprint(args, _bridge)));
+}

package/dist/tools/validation/types.js

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

package/dist/tools/viewport/index.js

@@ -0,0 +1,310 @@
+// src/tools/viewport/index.ts
+// MCP tool implementations for editor state, PIE control, and viewport operations (Phase 12).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge plugin.
+// Returns structured plugin_not_connected errors when the 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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerViewportTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Editor viewport, PIE control, and editor state 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 12):
+ *   ue_editor_state            — Query selected actors, open assets, viewport camera
+ *   ue_pie_start               — Start a PIE session
+ *   ue_pie_stop                — Stop the active PIE session
+ *   ue_pie_logs                — Read PIE output log lines
+ *   ue_pie_game_state          — Query runtime game state during PIE
+ *   ue_viewport_screenshot     — Capture viewport as screenshot
+ *   ue_viewport_camera         — Control viewport camera position/rotation/FOV
+ *   ue_viewport_render_mode    — Switch viewport render mode
+ *   ue_viewport_hires_screenshot — Take a high-resolution screenshot
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerViewportTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_editor_state
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_editor_state', {
+        title: 'Query UE Editor State',
+        description: '[requires_plugin] Query the current UE Editor state — selected actors, open assets, and viewport camera position.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_editor_state', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'editor.state' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_pie_start
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_pie_start', {
+        title: 'Start PIE Session',
+        description: '[requires_plugin] Start a Play In Editor (PIE) session.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_pie_start', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'pie.start' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_pie_stop
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_pie_stop', {
+        title: 'Stop PIE Session',
+        description: '[requires_plugin] Stop the active Play In Editor (PIE) session.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_pie_stop', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'pie.stop' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_pie_logs
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_pie_logs', {
+        title: 'Read PIE Logs',
+        description: '[requires_plugin] Read PIE output log lines captured since the PIE session started.',
+        inputSchema: z.object({
+            category_filter: z
+                .string()
+                .optional()
+                .describe('Filter log lines containing this string (case-insensitive, empty = all)'),
+            max_lines: z
+                .number()
+                .int()
+                .min(1)
+                .max(1000)
+                .optional()
+                .describe('Maximum log lines to return (default 100)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_pie_logs', async (args) => {
+        const payload = {};
+        if (args.category_filter)
+            payload['category_filter'] = args.category_filter;
+        if (args.max_lines !== undefined)
+            payload['max_lines'] = args.max_lines;
+        return sendOrDisconnect(_bridge, { type: 'pie.logs', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_pie_game_state
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_pie_game_state', {
+        title: 'Query PIE Game State',
+        description: '[requires_plugin] Query runtime game state during an active PIE session — actor positions and active GameMode.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_pie_game_state', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'pie.gameState' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_viewport_screenshot
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_viewport_screenshot', {
+        title: 'Take Viewport Screenshot',
+        description: '[requires_plugin] Capture the active UE viewport as a screenshot. Returns the screenshot directory path.',
+        inputSchema: z.object({
+            width: z
+                .number()
+                .int()
+                .min(64)
+                .max(7680)
+                .optional()
+                .describe('Screenshot width in pixels (default 1920)'),
+            height: z
+                .number()
+                .int()
+                .min(64)
+                .max(4320)
+                .optional()
+                .describe('Screenshot height in pixels (default 1080)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_viewport_screenshot', async (args) => {
+        const payload = {};
+        if (args.width !== undefined)
+            payload['width'] = args.width;
+        if (args.height !== undefined)
+            payload['height'] = args.height;
+        return sendOrDisconnect(_bridge, { type: 'viewport.screenshot', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_viewport_camera
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_viewport_camera', {
+        title: 'Control Viewport Camera',
+        description: '[requires_plugin] Set the viewport camera position, rotation, FOV, or orbit around a target point.',
+        inputSchema: z.object({
+            location: z
+                .object({
+                x: z.number(),
+                y: z.number(),
+                z: z.number(),
+            })
+                .optional()
+                .describe('Camera world position in Unreal units (cm)'),
+            rotation: z
+                .object({
+                pitch: z.number(),
+                yaw: z.number(),
+                roll: z.number(),
+            })
+                .optional()
+                .describe('Camera rotation in degrees'),
+            fov: z
+                .number()
+                .min(5)
+                .max(170)
+                .optional()
+                .describe('Horizontal field of view in degrees'),
+            look_at: z
+                .object({
+                x: z.number(),
+                y: z.number(),
+                z: z.number(),
+            })
+                .optional()
+                .describe('Point to orbit/look at — overrides rotation when location is also provided'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_viewport_camera', async (args) => {
+        const payload = {};
+        if (args.location !== undefined)
+            payload['location'] = args.location;
+        if (args.rotation !== undefined)
+            payload['rotation'] = args.rotation;
+        if (args.fov !== undefined)
+            payload['fov'] = args.fov;
+        if (args.look_at !== undefined)
+            payload['look_at'] = args.look_at;
+        return sendOrDisconnect(_bridge, { type: 'viewport.camera', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_viewport_render_mode
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_viewport_render_mode', {
+        title: 'Switch Viewport Render Mode',
+        description: '[requires_plugin] Switch the active viewport render mode.',
+        inputSchema: z.object({
+            mode: z
+                .enum(['lit', 'unlit', 'wireframe', 'collision', 'detail_lighting'])
+                .describe('Render mode: lit (default), unlit, wireframe, collision, detail_lighting'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_viewport_render_mode', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'viewport.renderMode',
+            payload: { mode: args.mode },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_viewport_hires_screenshot
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_viewport_hires_screenshot', {
+        title: 'High-Resolution Viewport Screenshot',
+        description: '[requires_plugin] Take a high-resolution screenshot with configurable multiplier. Returns the screenshot directory path.',
+        inputSchema: z.object({
+            resolution_multiplier: z
+                .number()
+                .int()
+                .min(1)
+                .max(8)
+                .optional()
+                .describe('Resolution multiplier (default 2 = 2x base resolution)'),
+            width: z
+                .number()
+                .int()
+                .min(64)
+                .max(7680)
+                .optional()
+                .describe('Base width in pixels (default 1920)'),
+            height: z
+                .number()
+                .int()
+                .min(64)
+                .max(4320)
+                .optional()
+                .describe('Base height in pixels (default 1080)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_viewport_hires_screenshot', async (args) => {
+        const payload = {};
+        if (args.resolution_multiplier !== undefined)
+            payload['resolution_multiplier'] = args.resolution_multiplier;
+        if (args.width !== undefined)
+            payload['width'] = args.width;
+        if (args.height !== undefined)
+            payload['height'] = args.height;
+        return sendOrDisconnect(_bridge, { type: 'viewport.hiresScreenshot', payload });
+    }));
+}