ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/pcg/index.js

@@ -0,0 +1,164 @@
+// src/tools/pcg/index.ts
+// MCP tool implementations for PCG Framework operations (Phase 24).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge plugin.
+// Returns structured plugin_not_connected errors when the plugin is absent.
+//
+// Tools registered (Phase 24 — PCG-01 through PCG-04):
+//   ue_list_pcg_graphs    — List all PCG graph assets in the project
+//   ue_inspect_pcg_graph  — Inspect nodes, connections, and parameters of a PCG graph
+//   ue_execute_pcg_graph  — Execute a PCG graph on an actor with optional parameter overrides
+//   ue_query_pcg_results  — Query PCG execution results for an actor
+//
+// All tools require MCPBridge plugin (Phase 24 — PCG-01 through PCG-04).
+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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerPCGTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE PCG Framework 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 24):
+ *   ue_list_pcg_graphs    — List all PCG graph assets in the project
+ *   ue_inspect_pcg_graph  — Inspect nodes, connections, and parameters of a PCG graph
+ *   ue_execute_pcg_graph  — Execute a PCG graph on an actor with optional parameter overrides
+ *   ue_query_pcg_results  — Query PCG execution results for an actor
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerPCGTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_pcg_graphs
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_pcg_graphs', {
+        title: 'List PCG Graphs',
+        description: '[requires_plugin] List all PCG graph assets in the project with node count and component assignment.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_pcg_graphs', async (_args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'pcg.list',
+            payload: {},
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_inspect_pcg_graph
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_pcg_graph', {
+        title: 'Inspect PCG Graph',
+        description: '[requires_plugin] Inspect a PCG graph\'s nodes, connections, parameters, and enabled state.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('Content browser path to the PCG graph asset, e.g. /Game/PCG/MyGraph'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_pcg_graph', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'pcg.inspect',
+            payload: { asset_path: args.asset_path },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_execute_pcg_graph
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_execute_pcg_graph', {
+        title: 'Execute PCG Graph',
+        description: '[requires_plugin] Execute a PCG graph on an actor\'s PCG component with optional parameter overrides.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .min(1)
+                .describe('Display label of the actor with a PCG component'),
+            parameter_overrides: z
+                .record(z.union([z.number(), z.string()]))
+                .optional()
+                .describe('Key-value map of parameter overrides to apply before execution'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_execute_pcg_graph', async (args) => {
+        const payload = {
+            actor_label: args.actor_label,
+        };
+        if (args.parameter_overrides !== undefined) {
+            payload['parameter_overrides'] = args.parameter_overrides;
+        }
+        return sendOrDisconnect(_bridge, { type: 'pcg.execute', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_query_pcg_results
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_query_pcg_results', {
+        title: 'Query PCG Results',
+        description: '[requires_plugin] Query PCG execution results for an actor — point counts, data entries, and warnings.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .min(1)
+                .describe('Display label of the actor with a PCG component'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_query_pcg_results', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'pcg.results',
+            payload: { actor_label: args.actor_label },
+        });
+    }));
+}

package/dist/tools/selection/index.js

@@ -0,0 +1,180 @@
+// src/tools/selection/index.ts
+// MCP tool implementations for Actor Selection and Duplication (Phase 19).
+// 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 19 — SEL-01 through SEL-04):
+//   ue_select_actors     — Select or deselect actors by name, label, or class
+//   ue_get_selection     — Get current editor selection or change selection mode
+//   ue_duplicate_actors  — Duplicate selected actors with optional position offset
+//   ue_convert_actor     — Convert an actor to a different class
+//
+// All tools require MCPBridge plugin (Phase 19 — SEL-01 through SEL-04).
+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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerSelectionTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE actor selection and duplication 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 19):
+ *   ue_select_actors    — SEL-01: Select or deselect actors by name, label, or class
+ *   ue_get_selection    — SEL-02: Get current editor selection or change selection mode
+ *   ue_duplicate_actors — SEL-03: Duplicate selected actors with optional offset
+ *   ue_convert_actor    — SEL-04: Convert an actor to a different class
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerSelectionTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_select_actors (SEL-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_select_actors', {
+        title: 'Select Actors',
+        description: "[requires_plugin] Select or deselect actors in the editor by name, label, or class. Supports wildcard patterns (e.g. 'Light*').",
+        inputSchema: z.object({
+            actors: z
+                .array(z.string())
+                .optional()
+                .describe('Actor labels or names to match. Supports wildcards like Light*'),
+            class_filter: z
+                .string()
+                .optional()
+                .describe('Select all actors of this class, e.g. StaticMeshActor'),
+            action: z
+                .enum(['select', 'deselect'])
+                .default('select')
+                .describe('Whether to select or deselect matched actors'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_select_actors', async (args) => {
+        const payload = {};
+        if (args.actors !== undefined)
+            payload['actors'] = args.actors;
+        if (args.class_filter !== undefined)
+            payload['class_filter'] = args.class_filter;
+        if (args.action !== undefined)
+            payload['action'] = args.action;
+        return sendOrDisconnect(_bridge, { type: 'selection.select', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_get_selection (SEL-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_get_selection', {
+        title: 'Get/Set Actor Selection',
+        description: "[requires_plugin] Get the current editor actor selection. Optionally change selection mode: 'all' selects everything, 'none' clears selection, 'invert' toggles each actor.",
+        inputSchema: z.object({
+            mode: z
+                .enum(['current', 'all', 'none', 'invert'])
+                .default('current')
+                .describe('Selection mode: current (read only), all, none, or invert'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_get_selection', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'selection.get',
+            payload: { mode: args.mode },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_duplicate_actors (SEL-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_duplicate_actors', {
+        title: 'Duplicate Selected Actors',
+        description: '[requires_plugin] Duplicate all currently selected actors in the editor with an optional position offset. Defaults to offset (100, 0, 0) if not specified.',
+        inputSchema: z.object({
+            offset: z
+                .object({
+                x: z.number().default(100),
+                y: z.number().default(0),
+                z: z.number().default(0),
+            })
+                .optional()
+                .describe('Position offset for duplicated actors in UE units'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_duplicate_actors', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'selection.duplicate',
+            payload: { offset: args.offset ?? { x: 100, y: 0, z: 0 } },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_convert_actor (SEL-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_convert_actor', {
+        title: 'Convert Actor Class',
+        description: "[requires_plugin] Convert an actor to a different class (e.g. StaticMeshActor to a Blueprint class). The actor is replaced with a new instance of the target class at the same transform.",
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .describe('Label of the actor to convert'),
+            target_class: z
+                .string()
+                .describe("Target class name (e.g. 'StaticMeshActor') or full path (e.g. '/Game/BP_MyActor.BP_MyActor_C')"),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
+    }, withKnownIssues('ue_convert_actor', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'selection.convert',
+            payload: { actor_label: args.actor_label, target_class: args.target_class },
+        });
+    }));
+}

package/dist/tools/sequencer/index.js

@@ -0,0 +1,218 @@
+// src/tools/sequencer/index.ts
+// MCP tool implementations for Sequencer & Cinematics operations (Phase 13).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge plugin.
+// Returns structured plugin_not_connected errors when the plugin is absent.
+//
+// Tools registered (Phase 13 — SEQ-01 through SEQ-05):
+//   ue_create_sequence        — Create a new Level Sequence asset
+//   ue_list_sequence_tracks   — List all tracks in a Level Sequence
+//   ue_add_sequence_track     — Add a transform or float track to an actor
+//   ue_add_keyframe           — Add a keyframe at a given frame on a track
+//   ue_sequence_playback      — Control Level Sequence playback (play/pause/stop/scrub)
+//
+// All tools require MCPBridge plugin (Phase 13 — SEQ-01 through SEQ-05).
+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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerSequencerTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Sequencer & Cinematics 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 13):
+ *   ue_create_sequence        — Create a new Level Sequence asset
+ *   ue_list_sequence_tracks   — List all tracks in a Level Sequence
+ *   ue_add_sequence_track     — Add a property or transform track for an actor
+ *   ue_add_keyframe           — Add a keyframe at a specified frame on a track
+ *   ue_sequence_playback      — Control Level Sequence playback
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerSequencerTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_create_sequence
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_create_sequence', {
+        title: 'Create Level Sequence',
+        description: '[requires_plugin] Create a new Level Sequence asset at the specified content path and open it in the Sequencer editor.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('Content browser path for the new sequence, e.g. /Game/Cinematics/MySequence'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_create_sequence', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'sequencer.create',
+            payload: { asset_path: args.asset_path },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_list_sequence_tracks
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_sequence_tracks', {
+        title: 'List Sequence Tracks',
+        description: '[requires_plugin] List all tracks in a Level Sequence with bound objects, track type, section count, and key count.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('Content browser path to the Level Sequence asset'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_sequence_tracks', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'sequencer.tracks',
+            payload: { asset_path: args.asset_path },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_add_sequence_track
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_add_sequence_track', {
+        title: 'Add Sequence Track',
+        description: '[requires_plugin] Add a property or transform track to a Level Sequence for a given actor.',
+        inputSchema: z.object({
+            asset_path: z.string().min(1),
+            actor_label: z
+                .string()
+                .min(1)
+                .describe('Display label of the actor to bind the track to'),
+            track_type: z
+                .enum(['transform', 'float'])
+                .describe('Track type: transform (3D transform track) or float (generic float property track)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_add_sequence_track', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'sequencer.addTrack',
+            payload: {
+                asset_path: args.asset_path,
+                actor_label: args.actor_label,
+                track_type: args.track_type,
+            },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_add_keyframe
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_add_keyframe', {
+        title: 'Add Keyframe',
+        description: '[requires_plugin] Add a keyframe at a specified frame number on an existing track in a Level Sequence.',
+        inputSchema: z.object({
+            asset_path: z.string().min(1),
+            track_type: z
+                .enum(['transform', 'float'])
+                .describe('Type of track to add keyframe to'),
+            frame: z
+                .number()
+                .int()
+                .min(0)
+                .describe('Frame number (integer, 0-based at sequence display rate)'),
+            value: z
+                .number()
+                .optional()
+                .describe('Keyframe value for float tracks (ignored for transform tracks, defaults 0.0)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_add_keyframe', async (args) => {
+        const payload = {
+            asset_path: args.asset_path,
+            track_type: args.track_type,
+            frame: args.frame,
+        };
+        if (args.value !== undefined) {
+            payload['value'] = args.value;
+        }
+        return sendOrDisconnect(_bridge, { type: 'sequencer.addKey', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_sequence_playback
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_sequence_playback', {
+        title: 'Sequence Playback Control',
+        description: '[requires_plugin] Control Level Sequence playback — play, pause, stop, or scrub to a specific frame.',
+        inputSchema: z.object({
+            asset_path: z.string().min(1),
+            action: z
+                .enum(['play', 'pause', 'stop', 'scrub'])
+                .describe('Playback action: play, pause, stop, or scrub to a frame'),
+            frame: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Target frame number for scrub action'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_sequence_playback', async (args) => {
+        const payload = {
+            asset_path: args.asset_path,
+            action: args.action,
+        };
+        if (args.frame !== undefined) {
+            payload['frame'] = args.frame;
+        }
+        return sendOrDisconnect(_bridge, { type: 'sequencer.playback', payload });
+    }));
+}