ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/animation/index.js

@@ -0,0 +1,241 @@
+// src/tools/animation/index.ts
+// MCP tool implementations for animation asset inspection (Phase 17).
+// 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 17 — ANIM-01 through ANIM-05):
+//   ue_list_animation_assets    — List all animation assets, optionally filtered by type
+//   ue_inspect_anim_blueprint   — Inspect AnimBP state machines, states, and transitions
+//   ue_inspect_montage          — Read montage sections, notifies, and slot assignments
+//   ue_inspect_blend_space      — Inspect blend space axes, samples, and grid config
+//   ue_read_retarget_mappings   — Read IK Retargeter source/target rig and chain mappings
+//
+// All tools require MCPBridge plugin (Phase 17 — ANIM-01 through ANIM-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_list_animation_assets handler — satisfies ANIM-01.
+ * Sends animation.list to the plugin; returns all animation assets, optionally filtered by type.
+ *
+ * @param args  Tool arguments including optional type_filter.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleListAnimationAssets(args, b = bridge) {
+    // Response data shape: AnimationListResult
+    const payload = {};
+    if (args.type_filter !== undefined) {
+        payload['type_filter'] = args.type_filter;
+    }
+    return sendOrDisconnect(b, {
+        type: 'animation.list',
+        payload,
+    });
+}
+/**
+ * ue_inspect_anim_blueprint handler — satisfies ANIM-02.
+ * Sends animation.inspectAnimBP to the plugin; returns state machines, states, transitions, and skeleton.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectAnimBlueprint(args, b = bridge) {
+    // Response data shape: AnimBlueprintInspectResult
+    return sendOrDisconnect(b, {
+        type: 'animation.inspectAnimBP',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_montage handler — satisfies ANIM-03.
+ * Sends animation.inspectMontage to the plugin; returns sections, notifies, and slot assignments.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectMontage(args, b = bridge) {
+    // Response data shape: MontageInspectResult
+    return sendOrDisconnect(b, {
+        type: 'animation.inspectMontage',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_blend_space handler — satisfies ANIM-04.
+ * Sends animation.inspectBlendSpace to the plugin; returns axes, samples, and grid configuration.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectBlendSpace(args, b = bridge) {
+    // Response data shape: BlendSpaceInspectResult
+    return sendOrDisconnect(b, {
+        type: 'animation.inspectBlendSpace',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_read_retarget_mappings handler — satisfies ANIM-05.
+ * Sends animation.retargetMappings to the plugin; returns source/target rigs and chain mappings.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleReadRetargetMappings(args, b = bridge) {
+    // Response data shape: RetargetMappingsResult
+    return sendOrDisconnect(b, {
+        type: 'animation.retargetMappings',
+        payload: { asset_path: args.asset_path },
+    });
+}
+// ---------------------------------------------------------------------------
+// registerAnimationTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE animation asset 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 17):
+ *   ue_list_animation_assets    — ANIM-01: List animation assets filtered by type
+ *   ue_inspect_anim_blueprint   — ANIM-02: Inspect AnimBP state machines and transitions
+ *   ue_inspect_montage          — ANIM-03: Read montage sections, notifies, slots
+ *   ue_inspect_blend_space      — ANIM-04: Inspect blend space axes and sample points
+ *   ue_read_retarget_mappings   — ANIM-05: Read IK Retargeter chain mappings
+ *
+ * @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 registerAnimationTools(server, _bridge) {
+    const b = _bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_animation_assets (ANIM-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_animation_assets', {
+        title: 'List Animation Assets',
+        description: '[requires_plugin] List all animation assets in the project, optionally filtered by type (AnimBlueprint, AnimMontage, BlendSpace, BlendSpace1D, AnimSequence).',
+        inputSchema: z.object({
+            type_filter: z
+                .string()
+                .optional()
+                .describe('Optional asset class filter: AnimBlueprint | AnimMontage | BlendSpace | BlendSpace1D | AnimSequence'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_animation_assets', async (args) => handleListAnimationAssets(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_anim_blueprint (ANIM-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_anim_blueprint', {
+        title: 'Inspect Animation Blueprint',
+        description: "[requires_plugin] Inspect an Animation Blueprint's state machines, states, transitions, and skeleton.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Animation Blueprint asset, e.g. /Game/Animations/ABP_Character'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_anim_blueprint', async (args) => handleInspectAnimBlueprint(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_montage (ANIM-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_montage', {
+        title: 'Inspect Montage',
+        description: '[requires_plugin] Read montage sections, notifies (with trigger times), and slot assignments.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Animation Montage asset, e.g. /Game/Animations/AM_Attack'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_montage', async (args) => handleInspectMontage(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_blend_space (ANIM-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_blend_space', {
+        title: 'Inspect Blend Space',
+        description: '[requires_plugin] Inspect blend space axes, sample points, and grid configuration.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the BlendSpace or BlendSpace1D asset, e.g. /Game/Animations/BS_Movement'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_blend_space', async (args) => handleInspectBlendSpace(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_read_retarget_mappings (ANIM-05)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_retarget_mappings', {
+        title: 'Read Retarget Mappings',
+        description: '[requires_plugin] Read IK Retargeter source/target skeleton rigs and chain mappings.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the IK Retargeter asset, e.g. /Game/Animations/RTG_CharacterRetarget'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_retarget_mappings', async (args) => handleReadRetargetMappings(args, b)));
+}

package/dist/tools/animation/types.js

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

package/dist/tools/audio/index.js

@@ -0,0 +1,204 @@
+// src/tools/audio/index.ts
+// MCP tool implementations for audio asset inspection (Phase 23).
+// 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 23 — AUD-01 through AUD-04):
+//   ue_list_sound_assets      — List all sound assets, optionally filtered by type
+//   ue_inspect_metasound      — Inspect MetaSound patch graph nodes, edges, inputs, outputs
+//   ue_inspect_sound_cue      — Read SoundCue node graph structure and attenuation settings
+//   ue_query_audio_insights   — Query Audio Insights monitoring data (active sounds, events)
+//
+// All tools require MCPBridge plugin (Phase 23 — AUD-01 through AUD-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(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_list_sound_assets handler — satisfies AUD-01.
+ * Sends audio.list to the plugin; returns all sound assets, optionally filtered by type.
+ *
+ * @param args  Tool arguments including optional type_filter.
+ * @param b     PluginBridgeClient instance (defaults to bridge created in registerAudioTools).
+ */
+export async function handleListSoundAssets(args, b) {
+    const bridge = b ?? new PluginBridgeClient();
+    // Response data shape: SoundAssetListResult
+    const payload = {};
+    if (args.type_filter !== undefined) {
+        payload['type_filter'] = args.type_filter;
+    }
+    return sendOrDisconnect(bridge, {
+        type: 'audio.list',
+        payload,
+    });
+}
+/**
+ * ue_inspect_metasound handler — satisfies AUD-02.
+ * Sends audio.metasound to the plugin; returns graph nodes, edges, inputs, and outputs.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to bridge created in registerAudioTools).
+ */
+export async function handleInspectMetasound(args, b) {
+    const bridge = b ?? new PluginBridgeClient();
+    // Response data shape: MetaSoundInspectResult
+    return sendOrDisconnect(bridge, {
+        type: 'audio.metasound',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_inspect_sound_cue handler — satisfies AUD-03.
+ * Sends audio.soundcue to the plugin; returns recursive node tree and attenuation settings.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to bridge created in registerAudioTools).
+ */
+export async function handleInspectSoundCue(args, b) {
+    const bridge = b ?? new PluginBridgeClient();
+    // Response data shape: SoundCueInspectResult
+    return sendOrDisconnect(bridge, {
+        type: 'audio.soundcue',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_query_audio_insights handler — satisfies AUD-04.
+ * Sends audio.insights to the plugin; returns monitoring data or informative unavailable message.
+ *
+ * @param args  No required parameters (empty object).
+ * @param b     PluginBridgeClient instance (defaults to bridge created in registerAudioTools).
+ */
+export async function handleQueryAudioInsights(args, b) {
+    const bridge = b ?? new PluginBridgeClient();
+    // Response data shape: AudioInsightsResult
+    return sendOrDisconnect(bridge, {
+        type: 'audio.insights',
+        payload: {},
+    });
+}
+// ---------------------------------------------------------------------------
+// registerAudioTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE audio asset inspection and monitoring 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 23):
+ *   ue_list_sound_assets      — AUD-01: List sound assets filtered by type
+ *   ue_inspect_metasound      — AUD-02: Inspect MetaSound patch graph nodes and connections
+ *   ue_inspect_sound_cue      — AUD-03: Read SoundCue node graph and attenuation settings
+ *   ue_query_audio_insights   — AUD-04: Query Audio Insights monitoring data
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (injected into handler calls).
+ */
+export function registerAudioTools(server, bridge) {
+    const b = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_sound_assets (AUD-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_sound_assets', {
+        title: 'List Sound Assets',
+        description: '[requires_plugin] List all sound assets in the project, optionally filtered by type (SoundWave, SoundCue, MetaSound). Returns asset paths, names, types, and audio properties.',
+        inputSchema: z.object({
+            type_filter: z
+                .enum(['SoundWave', 'SoundCue', 'MetaSound'])
+                .optional()
+                .describe('Filter by sound asset type. Omit to list all types.'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_sound_assets', async (args) => handleListSoundAssets(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_metasound (AUD-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_metasound', {
+        title: 'Inspect MetaSound Patch',
+        description: "[requires_plugin] Inspect a MetaSound patch's graph nodes, connections, input pins, and output pins.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE content path to the MetaSound asset, e.g. /Game/Audio/MS_Ambience'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_metasound', async (args) => handleInspectMetasound(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_sound_cue (AUD-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_sound_cue', {
+        title: 'Inspect Sound Cue',
+        description: "[requires_plugin] Read a SoundCue's node graph structure, configured parameters (volume, pitch), and attenuation settings.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE content path to the SoundCue asset, e.g. /Game/Audio/SC_Footstep'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_sound_cue', async (args) => handleInspectSoundCue(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_query_audio_insights (AUD-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_query_audio_insights', {
+        title: 'Query Audio Insights',
+        description: '[requires_plugin] Query Audio Insights monitoring data including active sound count, max channels, and recent audio events. Returns informative message if Audio Insights plugin is not enabled.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_query_audio_insights', async (args) => handleQueryAudioInsights(args, b)));
+}

package/dist/tools/audio/types.js

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