ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/chaos/index.js

@@ -0,0 +1,230 @@
+// src/tools/chaos/index.ts
+// MCP tool implementations for Chaos physics management (Phase 26).
+// 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 26 — CHAOS-01 through CHAOS-04):
+//   ue_inspect_geometry_collection  — Inspect geometry collection fracture hierarchy and bone data
+//   ue_reset_destruction            — Reset geometry collection actor to initial unfractured state
+//   ue_read_cloth_params            — Read Chaos cloth simulation parameters from actor or asset
+//   ue_manage_physics_cache         — Start, stop, or query Chaos physics cache recording
+//
+// All tools require MCPBridge plugin (Phase 26 — CHAOS-01 through CHAOS-04).
+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 _defaultBridge = new PluginBridgeClient();
+// ---------------------------------------------------------------------------
+// sendOrDisconnect helper
+// ---------------------------------------------------------------------------
+/**
+ * Sends a command to the bridge and returns a ToolResult.
+ *
+ * - On success (response.success true): returns data as JSON text.
+ * - On command-level failure (response.success false): returns isError:true with error JSON.
+ * - On PluginNotConnectedError: returns isError:true with plugin_not_connected JSON.
+ * - On other errors: rethrows (withKnownIssues catches and formats).
+ *
+ * NOTE: sendCommand() overwrites correlationId with crypto.randomUUID() internally;
+ * passing an empty string is safe and correct (per STATE.md decision).
+ */
+async function sendOrDisconnect(b, cmd) {
+    try {
+        const response = await b.sendCommand({ ...cmd, correlationId: '' });
+        if (!response.success) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: response.error }) }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify(response.data ?? {}) }],
+        };
+    }
+    catch (err) {
+        if (err instanceof PluginNotConnectedError) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify(err.bridgeError) }],
+            };
+        }
+        throw err; // withKnownIssues catches unexpected errors
+    }
+}
+// ---------------------------------------------------------------------------
+// Exported handler functions (for direct unit testing via bridge injection)
+// ---------------------------------------------------------------------------
+/**
+ * ue_inspect_geometry_collection handler — satisfies CHAOS-01.
+ * Sends chaos.geometryCollection to the plugin; returns fracture hierarchy,
+ * bone count, level breakdown, and damage thresholds.
+ *
+ * @param args  Tool arguments — provide asset_path and/or actor_label.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectGeometryCollection(args, b = _defaultBridge) {
+    // Response data shape: GeometryCollectionInspectResult
+    const payload = {};
+    if (args.asset_path !== undefined)
+        payload['asset_path'] = args.asset_path;
+    if (args.actor_label !== undefined)
+        payload['actor_label'] = args.actor_label;
+    return sendOrDisconnect(b, {
+        type: 'chaos.geometryCollection',
+        payload,
+    });
+}
+/**
+ * ue_reset_destruction handler — satisfies CHAOS-02.
+ * Sends chaos.resetDestruction to the plugin; resets a geometry collection
+ * actor to its initial unfractured state.
+ *
+ * @param args  Tool arguments including actor_label.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleResetDestruction(args, b = _defaultBridge) {
+    // Response data shape: DestructionResetResult
+    return sendOrDisconnect(b, {
+        type: 'chaos.resetDestruction',
+        payload: { actor_label: args.actor_label },
+    });
+}
+/**
+ * ue_read_cloth_params handler — satisfies CHAOS-03.
+ * Sends chaos.cloth to the plugin; returns cloth simulation parameters
+ * (stiffness, damping, friction, gravity scale, wind coefficients).
+ *
+ * @param args  Tool arguments — provide actor_label and/or asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleReadClothParams(args, b = _defaultBridge) {
+    // Response data shape: ClothParamsResult
+    const payload = {};
+    if (args.actor_label !== undefined)
+        payload['actor_label'] = args.actor_label;
+    if (args.asset_path !== undefined)
+        payload['asset_path'] = args.asset_path;
+    return sendOrDisconnect(b, {
+        type: 'chaos.cloth',
+        payload,
+    });
+}
+/**
+ * ue_manage_physics_cache handler — satisfies CHAOS-04.
+ * Sends chaos.physicsCache to the plugin; starts, stops, or queries
+ * Chaos physics cache recording state.
+ *
+ * @param args  Tool arguments including action and optional actor_label.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleManagePhysicsCache(args, b = _defaultBridge) {
+    // Response data shape: PhysicsCacheResult
+    const payload = { action: args.action };
+    if (args.actor_label !== undefined)
+        payload['actor_label'] = args.actor_label;
+    return sendOrDisconnect(b, {
+        type: 'chaos.physicsCache',
+        payload,
+    });
+}
+// ---------------------------------------------------------------------------
+// registerChaosTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Chaos physics management 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 26):
+ *   ue_inspect_geometry_collection  — CHAOS-01: Inspect fracture hierarchy and clusters
+ *   ue_reset_destruction            — CHAOS-02: Reset geometry collection to unfractured state
+ *   ue_read_cloth_params            — CHAOS-03: Read cloth simulation parameters
+ *   ue_manage_physics_cache         — CHAOS-04: Start/stop/query physics cache recording
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerChaosTools(server, bridge) {
+    const b = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_inspect_geometry_collection (CHAOS-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_geometry_collection', {
+        title: 'Inspect Geometry Collection',
+        description: "[requires_plugin] Inspect a Chaos geometry collection's fracture hierarchy, bone count, level breakdown, and damage thresholds. Provide either asset_path or actor_label.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .optional()
+                .describe("UE asset path to the geometry collection, e.g. '/Game/Destruction/GC_Wall'"),
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Editor actor label of a placed geometry collection actor'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_geometry_collection', async (args) => handleInspectGeometryCollection(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_reset_destruction (CHAOS-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_reset_destruction', {
+        title: 'Reset Destruction State',
+        description: '[requires_plugin] Reset a geometry collection actor to its initial unfractured state. Reverses any in-editor destruction simulation.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .describe('Editor actor label of the geometry collection actor to reset'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_reset_destruction', async (args) => handleResetDestruction(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_read_cloth_params (CHAOS-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_cloth_params', {
+        title: 'Read Cloth Simulation Parameters',
+        description: '[requires_plugin] Read Chaos cloth simulation parameters (stiffness, damping, friction, gravity, wind) from a skeletal mesh actor or cloth asset. Requires the ChaosCloth plugin to be enabled.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Editor actor label of an actor with cloth simulation'),
+            asset_path: z
+                .string()
+                .optional()
+                .describe("UE asset path to a cloth asset, e.g. '/Game/Characters/Cloth_Cape'"),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_cloth_params', async (args) => handleReadClothParams(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_manage_physics_cache (CHAOS-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_manage_physics_cache', {
+        title: 'Manage Physics Cache',
+        description: "[requires_plugin] Start, stop, or query Chaos physics cache recording. Use action 'start' to begin recording, 'stop' to end recording, 'query' to check status and frame count.",
+        inputSchema: z.object({
+            action: z
+                .enum(['start', 'stop', 'query'])
+                .describe("Cache operation: 'start' to begin recording, 'stop' to end, 'query' to inspect"),
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Optional actor label for actor-specific cache operations'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_manage_physics_cache', async (args) => handleManagePhysicsCache(args, b)));
+}

package/dist/tools/chaos/types.js

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

package/dist/tools/collision-physics/index.js

@@ -0,0 +1,211 @@
+// src/tools/collision-physics/index.ts
+// MCP tool implementations for collision and physics configuration (Phase 20).
+// 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 20 — PHY-01 through PHY-04):
+//   ue_read_collision              — Read collision preset, enabled state, object type, and per-channel responses
+//   ue_set_collision               — Set collision preset and/or individual channel response overrides
+//   ue_manage_physical_material    — Read or modify physical material properties (friction, restitution, density)
+//   ue_inspect_physics_asset       — Inspect physics asset per-bone body setup (capsules, spheres, boxes)
+//
+// All tools require MCPBridge plugin (Phase 20 — PHY-01 through PHY-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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerCollisionPhysicsTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE collision and physics configuration 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 20):
+ *   ue_read_collision              — Read collision preset and channel responses on a component (PHY-01)
+ *   ue_set_collision               — Set collision preset and channel responses (PHY-02)
+ *   ue_manage_physical_material    — Read/set physical material properties (PHY-03)
+ *   ue_inspect_physics_asset       — Inspect physics asset body setup per bone (PHY-04)
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerCollisionPhysicsTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_read_collision (PHY-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_collision', {
+        title: 'Read Collision Settings',
+        description: '[requires_plugin] Read collision preset, enabled state, object type, and per-channel response map from a primitive component on an actor.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .describe('Editor actor label'),
+            component_name: z
+                .string()
+                .optional()
+                .describe('Component name; defaults to first UPrimitiveComponent if omitted'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_collision', async (args) => {
+        const payload = { actor_label: args.actor_label };
+        if (args.component_name !== undefined)
+            payload['component_name'] = args.component_name;
+        return sendOrDisconnect(_bridge, { type: 'collision.read', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_set_collision (PHY-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_set_collision', {
+        title: 'Set Collision Settings',
+        description: "[requires_plugin] Set collision preset and/or individual channel response overrides on a primitive component. Returns updated collision state.",
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .describe('Editor actor label'),
+            component_name: z
+                .string()
+                .optional()
+                .describe('Component name; defaults to first UPrimitiveComponent if omitted'),
+            preset: z
+                .string()
+                .optional()
+                .describe("Collision preset profile name, e.g. 'BlockAll', 'OverlapAll', 'NoCollision'"),
+            responses: z
+                .array(z.object({
+                channel: z.number(),
+                response: z.enum(['Ignore', 'Overlap', 'Block']),
+            }))
+                .optional()
+                .describe('Per-channel response overrides; channel is ECollisionChannel int value'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_set_collision', async (args) => {
+        const payload = { actor_label: args.actor_label };
+        if (args.component_name !== undefined)
+            payload['component_name'] = args.component_name;
+        if (args.preset !== undefined)
+            payload['preset'] = args.preset;
+        if (args.responses !== undefined)
+            payload['responses'] = args.responses;
+        return sendOrDisconnect(_bridge, { type: 'collision.set', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_manage_physical_material (PHY-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_manage_physical_material', {
+        title: 'Read/Set Physical Material Properties',
+        description: "[requires_plugin] Read or modify physical material properties (friction, restitution, density, surface type). Use action 'read' to inspect, 'write' to modify.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe("UE asset path to the UPhysicalMaterial, e.g. '/Game/PhysMats/PM_Rock'"),
+            action: z
+                .enum(['read', 'write'])
+                .describe("Operation to perform: 'read' to inspect, 'write' to modify"),
+            friction: z
+                .number()
+                .optional(),
+            static_friction: z
+                .number()
+                .optional(),
+            restitution: z
+                .number()
+                .optional(),
+            density: z
+                .number()
+                .optional(),
+            surface_type: z
+                .number()
+                .optional()
+                .describe('EPhysicalSurface enum value'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_manage_physical_material', async (args) => {
+        const payload = {
+            asset_path: args.asset_path,
+            action: args.action,
+        };
+        if (args.friction !== undefined)
+            payload['friction'] = args.friction;
+        if (args.static_friction !== undefined)
+            payload['static_friction'] = args.static_friction;
+        if (args.restitution !== undefined)
+            payload['restitution'] = args.restitution;
+        if (args.density !== undefined)
+            payload['density'] = args.density;
+        if (args.surface_type !== undefined)
+            payload['surface_type'] = args.surface_type;
+        return sendOrDisconnect(_bridge, { type: 'physics.material', payload });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_inspect_physics_asset (PHY-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_physics_asset', {
+        title: 'Inspect Physics Asset Bodies',
+        description: "[requires_plugin] Inspect a physics asset's per-bone body setup including primitive shapes (capsules, spheres, boxes), dimensions, and mass configuration.",
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe("UE asset path to the UPhysicsAsset, e.g. '/Game/Characters/SK_Mannequin_PhysicsAsset'"),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_physics_asset', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'physics.asset',
+            payload: { asset_path: args.asset_path },
+        });
+    }));
+}