ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/known-issues/middleware.js

@@ -0,0 +1,55 @@
+// src/tools/known-issues/middleware.ts
+// Wraps tool handlers with a pre-execution KNOWN_ISSUES check.
+// Matching issues are prepended as warnings to the tool response content array.
+// Handler exceptions are caught and returned as isError responses — never propagated.
+import { readKnownIssues } from './store.js';
+// ---------------------------------------------------------------------------
+// withKnownIssues
+// ---------------------------------------------------------------------------
+/**
+ * Wraps a tool handler with a KNOWN_ISSUES pre-execution check.
+ *
+ * Before invoking the real handler:
+ *   1. Reads KNOWN_ISSUES.md (cached by mtime — cheap on cache hit).
+ *   2. Filters issues where affectedTools includes toolName or '*' (wildcard).
+ *   3. If matching issues exist, prepends a single warning content item
+ *      (all warnings joined by '\n') before the handler's content items.
+ *
+ * Exceptions thrown by the handler are caught and returned as:
+ *   { isError: true, content: [{ type: 'text', text: 'Error: <message>' }] }
+ *
+ * @param toolName  The MCP tool name (e.g., 'ue_read_cpp_class').
+ * @param handler   The real tool handler to wrap.
+ * @returns         A new handler with the same signature.
+ */
+export function withKnownIssues(toolName, handler) {
+    return async (args) => {
+        const issues = await readKnownIssues();
+        const relevant = issues.filter((i) => i.affectedTools.includes(toolName) || i.affectedTools.includes('*'));
+        let result;
+        try {
+            result = await handler(args);
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+            };
+        }
+        if (relevant.length === 0) {
+            return result;
+        }
+        const warnings = relevant
+            .map((i) => `[KNOWN ISSUE ${i.id}] ${i.description} — Resolution: ${i.resolution}`)
+            .join('\n');
+        return {
+            content: [{ type: 'text', text: warnings }, ...result.content],
+            isError: result.isError,
+        };
+    };
+}

package/dist/tools/known-issues/store.js

@@ -0,0 +1,125 @@
+// src/tools/known-issues/store.ts
+// Reads, caches, and writes KNOWN_ISSUES.md at the project root.
+// Cache is keyed by file mtime — re-reads only when the file changes.
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { PROJECT_ROOT } from '../../config.js';
+const KNOWN_ISSUES_PATH = path.join(PROJECT_ROOT, 'KNOWN_ISSUES.md');
+const cache = { issues: [], mtime: 0 };
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract the text after a bold field label on a line.
+ * e.g., "**Description:** foo" → "foo"
+ */
+function extractField(lines, label) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith(label)) {
+            return trimmed.slice(label.length).trim();
+        }
+    }
+    return '';
+}
+/**
+ * Parse a single issue block (text after "## ISSUE-" prefix).
+ * The first line of the block is the issue number suffix (e.g., "001\n...").
+ */
+function parseIssueBlock(block) {
+    const newlineIdx = block.indexOf('\n');
+    const idSuffix = newlineIdx === -1 ? block.trim() : block.slice(0, newlineIdx).trim();
+    if (!idSuffix)
+        return null;
+    const id = 'ISSUE-' + idSuffix;
+    const body = newlineIdx === -1 ? '' : block.slice(newlineIdx + 1);
+    const lines = body.split('\n');
+    const description = extractField(lines, '**Description:**');
+    const affectedToolsRaw = extractField(lines, '**Affected tools:**');
+    const rootCause = extractField(lines, '**Root cause:**');
+    const resolution = extractField(lines, '**Resolution:**');
+    const dateAdded = extractField(lines, '**Date added:**');
+    const statusRaw = extractField(lines, '**Status:**').toLowerCase();
+    const status = statusRaw === 'resolved' ? 'resolved' : 'active';
+    const affectedTools = affectedToolsRaw.trim() === ''
+        ? []
+        : affectedToolsRaw.split(',').map((s) => s.trim()).filter(Boolean);
+    return { id, description, affectedTools, rootCause, resolution, dateAdded, status };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Read and parse all ## ISSUE-NNN sections from KNOWN_ISSUES.md.
+ * Results are cached by mtime; a second call without file changes returns the
+ * same array reference without performing a second fs.readFile.
+ *
+ * Returns [] if the file does not exist or contains no ## ISSUE- sections.
+ */
+export async function readKnownIssues() {
+    let stat;
+    try {
+        stat = await fs.stat(KNOWN_ISSUES_PATH);
+    }
+    catch (err) {
+        if (err !== null &&
+            typeof err === 'object' &&
+            'code' in err &&
+            err.code === 'ENOENT') {
+            return [];
+        }
+        throw err;
+    }
+    const currentMtime = stat.mtimeMs;
+    if (currentMtime === cache.mtime) {
+        return cache.issues;
+    }
+    const content = await fs.readFile(KNOWN_ISSUES_PATH, 'utf8');
+    // Split on '\n## ISSUE-' — the first segment is the header (discarded).
+    const segments = content.split('\n## ISSUE-');
+    const issueBlocks = segments.slice(1); // discard header segment
+    const issues = [];
+    for (const block of issueBlocks) {
+        const issue = parseIssueBlock(block);
+        if (issue !== null) {
+            issues.push(issue);
+        }
+    }
+    cache.issues = issues;
+    cache.mtime = currentMtime;
+    return issues;
+}
+/**
+ * Append a new ## ISSUE-NNN section to KNOWN_ISSUES.md.
+ * The issue number is auto-incremented from the highest existing issue number.
+ * Invalidates the mtime cache so the next readKnownIssues() call re-reads the file.
+ *
+ * Returns the full KnownIssue with the computed id.
+ */
+export async function appendKnownIssue(issue) {
+    const existing = await readKnownIssues();
+    // Compute next ID
+    let maxN = 0;
+    for (const existing_issue of existing) {
+        const n = parseInt(existing_issue.id.replace('ISSUE-', ''), 10);
+        if (!isNaN(n) && n > maxN) {
+            maxN = n;
+        }
+    }
+    const nextN = maxN + 1;
+    const id = 'ISSUE-' + String(nextN).padStart(3, '0');
+    // Build the markdown block matching KNOWN_ISSUES.md format
+    const affectedToolsStr = issue.affectedTools.join(', ');
+    const block = `\n## ${id}\n` +
+        `**Description:** ${issue.description}\n` +
+        `**Affected tools:** ${affectedToolsStr}\n` +
+        `**Root cause:** ${issue.rootCause}\n` +
+        `**Resolution:** ${issue.resolution}\n` +
+        `**Date added:** ${issue.dateAdded}\n` +
+        `**Status:** ${issue.status}\n` +
+        `\n---`;
+    await fs.appendFile(KNOWN_ISSUES_PATH, block, 'utf8');
+    // Invalidate cache so next read picks up the newly appended content
+    cache.mtime = 0;
+    return { ...issue, id };
+}

package/dist/tools/livelink/index.js

@@ -0,0 +1,203 @@
+// src/tools/livelink/index.ts
+// MCP tool implementations for Live Link source/subject management (Phase 27).
+// 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 27 — LL-01 through LL-04):
+//   ue_list_livelink_sources    — List all active Live Link sources with connection status
+//   ue_list_livelink_subjects   — List all Live Link subjects with roles and enabled state
+//   ue_control_livelink_subject — Pause or resume an individual Live Link subject
+//   ue_preview_livelink_data    — Inspect current frame data for a Live Link subject
+//
+// All tools require MCPBridge plugin (Phase 27 — LL-01 through LL-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 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_livelink_sources handler — satisfies LL-01.
+ * Sends livelink.sources to the plugin; returns all active Live Link sources
+ * with connection status, source type, and machine name.
+ *
+ * @param args  Tool arguments (no parameters required).
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleListLiveLinkSources(args, b = bridge) {
+    // Response data shape: LiveLinkSourcesResult
+    void args; // no parameters
+    return sendOrDisconnect(b, {
+        type: 'livelink.sources',
+        payload: {},
+    });
+}
+/**
+ * ue_list_livelink_subjects handler — satisfies LL-02.
+ * Sends livelink.subjects to the plugin; returns all Live Link subjects
+ * with their roles (Animation, Transform, Camera, Light) and enabled state.
+ *
+ * @param args  Tool arguments (no parameters required).
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleListLiveLinkSubjects(args, b = bridge) {
+    // Response data shape: LiveLinkSubjectsResult
+    void args; // no parameters
+    return sendOrDisconnect(b, {
+        type: 'livelink.subjects',
+        payload: {},
+    });
+}
+/**
+ * ue_control_livelink_subject handler — satisfies LL-03.
+ * Sends livelink.control to the plugin; pauses or resumes an individual
+ * Live Link subject by toggling its enabled state.
+ *
+ * @param args  Tool arguments: subject_name and enabled flag.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleControlLiveLinkSubject(args, b = bridge) {
+    // Response data shape: LiveLinkControlResult
+    return sendOrDisconnect(b, {
+        type: 'livelink.control',
+        payload: { subject_name: args.subject_name, enabled: args.enabled },
+    });
+}
+/**
+ * ue_preview_livelink_data handler — satisfies LL-04.
+ * Sends livelink.preview to the plugin; returns the current frame data for
+ * a Live Link subject (transform, camera, or animation bone data).
+ *
+ * @param args  Tool arguments: subject_name.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handlePreviewLiveLinkData(args, b = bridge) {
+    // Response data shape: LiveLinkPreviewResult
+    return sendOrDisconnect(b, {
+        type: 'livelink.preview',
+        payload: { subject_name: args.subject_name },
+    });
+}
+// ---------------------------------------------------------------------------
+// registerLiveLinkTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Live Link source/subject 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 27):
+ *   ue_list_livelink_sources    — LL-01: List Live Link sources with status
+ *   ue_list_livelink_subjects   — LL-02: List subjects with roles and enabled state
+ *   ue_control_livelink_subject — LL-03: Pause or resume a Live Link subject
+ *   ue_preview_livelink_data    — LL-04: Inspect current frame data for a subject
+ *
+ * @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 registerLiveLinkTools(server, _bridge) {
+    const b = _bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_livelink_sources (LL-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_livelink_sources', {
+        title: 'List Live Link Sources',
+        description: '[requires_plugin] List all active Live Link sources with connection status, source type, and machine name. Returns informative message if Live Link plugin is not enabled.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_livelink_sources', async (args) => handleListLiveLinkSources(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_list_livelink_subjects (LL-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_livelink_subjects', {
+        title: 'List Live Link Subjects',
+        description: '[requires_plugin] List all Live Link subjects with their roles (Animation, Transform, Camera, Light) and enabled/disabled state.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_livelink_subjects', async (args) => handleListLiveLinkSubjects(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_control_livelink_subject (LL-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_control_livelink_subject', {
+        title: 'Control Live Link Subject',
+        description: '[requires_plugin] Pause or resume an individual Live Link subject by toggling its enabled state.',
+        inputSchema: z.object({
+            subject_name: z
+                .string()
+                .min(1)
+                .describe("Name of the Live Link subject to control, e.g. 'MyMocapActor'"),
+            enabled: z
+                .boolean()
+                .describe('true to resume/enable the subject, false to pause/disable it'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_control_livelink_subject', async (args) => handleControlLiveLinkSubject(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_preview_livelink_data (LL-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_preview_livelink_data', {
+        title: 'Preview Live Link Data',
+        description: '[requires_plugin] Inspect the current frame data for a Live Link subject. Returns role-specific data: transform (location/rotation/scale), camera (FOV/aperture/focus), or animation (bone transforms, capped at 10 bones).',
+        inputSchema: z.object({
+            subject_name: z
+                .string()
+                .min(1)
+                .describe("Name of the Live Link subject to preview, e.g. 'MyCamera'"),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_preview_livelink_data', async (args) => handlePreviewLiveLinkData(args, b)));
+}

package/dist/tools/livelink/types.js

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

package/dist/tools/material/index.js

@@ -0,0 +1,190 @@
+// src/tools/material/index.ts
+// MCP tool implementations for material parameter inspection and material instance creation (Phase 15).
+// 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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerMaterialTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE material parameter inspection and material instance 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 15):
+ *   ue_material_params           — Read all parameters from a material or material instance
+ *   ue_create_material_instance  — Create a new Material Instance Constant asset from a parent material
+ *   ue_set_material_param        — Set a scalar, vector, or texture parameter on a material instance
+ *   ue_actor_materials           — List all material asset paths used by an actor or static mesh
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerMaterialTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_material_params
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_material_params', {
+        title: 'Read Material Parameters',
+        description: '[requires_plugin] Read all scalar, vector, and texture parameters from a material asset or material instance. Returns parameter name, type, current value, and default value.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe('UE asset path to the material or material instance, e.g. "/Game/Materials/M_Rock"'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_material_params', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'material.params',
+            payload: { asset_path: args.asset_path },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_create_material_instance
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_create_material_instance', {
+        title: 'Create Material Instance',
+        description: '[requires_plugin] Create a new Material Instance Constant asset from a parent material. The instance is saved to disk as a persistent UE asset.',
+        inputSchema: z.object({
+            parent_path: z
+                .string()
+                .describe('UE asset path of the parent material, e.g. "/Game/Materials/M_Rock"'),
+            instance_path: z
+                .string()
+                .describe('Package path (directory) for the new instance, e.g. "/Game/Materials". Must start with /Game/.'),
+            instance_name: z
+                .string()
+                .describe('Asset name for the new instance, e.g. "MI_Rock_Red"'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_create_material_instance', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'material.createInstance',
+            payload: {
+                parent_path: args.parent_path,
+                instance_path: args.instance_path,
+                instance_name: args.instance_name,
+            },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_set_material_param
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_set_material_param', {
+        title: 'Set Material Instance Parameter',
+        description: '[requires_plugin] Set a scalar, vector, or texture parameter override on a Material Instance Constant. The value type must match param_type.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe('UE asset path to the Material Instance Constant'),
+            param_name: z
+                .string()
+                .describe('Parameter name as defined in the parent material'),
+            param_type: z
+                .enum(['scalar', 'vector', 'texture'])
+                .describe('Parameter type: scalar (float), vector (RGBA), or texture (asset path string)'),
+            value: z
+                .union([
+                z.number(),
+                z.object({
+                    r: z.number(),
+                    g: z.number(),
+                    b: z.number(),
+                    a: z.number().optional(),
+                }),
+                z.string(),
+            ])
+                .describe('Parameter value: number for scalar, {r,g,b,a} object for vector, asset path string for texture'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_set_material_param', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'material.setParam',
+            payload: {
+                asset_path: args.asset_path,
+                param_name: args.param_name,
+                param_type: args.param_type,
+                value: args.value,
+            },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_actor_materials
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_actor_materials', {
+        title: 'List Actor or Mesh Materials',
+        description: '[requires_plugin] List all material asset paths used by an actor in the open level or by a Static Mesh asset. Provide either actor_label or asset_path.',
+        inputSchema: z.object({
+            actor_label: z
+                .string()
+                .optional()
+                .describe('Label of the actor in the open level (e.g. "StaticMeshActor_0"). Provide this OR asset_path.'),
+            asset_path: z
+                .string()
+                .optional()
+                .describe('UE asset path to a Static Mesh asset (e.g. "/Game/Meshes/SM_Rock"). Provide this OR actor_label.'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_actor_materials', async (args) => {
+        const payload = {};
+        if (args.actor_label)
+            payload['actor_label'] = args.actor_label;
+        if (args.asset_path)
+            payload['asset_path'] = args.asset_path;
+        return sendOrDisconnect(_bridge, { type: 'material.actorMaterials', payload });
+    }));
+}