ultimate-unreal-engine-mcp 0.1.0

package/dist/tools/gas/index.js

@@ -0,0 +1,222 @@
+// src/tools/gas/index.ts
+// MCP tool implementations for Gameplay Ability System asset inspection (Phase 25).
+// 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 25 — GAS-01 through GAS-04):
+//   ue_list_abilities             — List Gameplay Ability classes with tags, costs, and cooldowns
+//   ue_inspect_gameplay_effect    — Inspect Gameplay Effect modifiers, duration, and stacking
+//   ue_read_attribute_set         — Read Attribute Set definitions with base values and clamping
+//   ue_query_gameplay_tags        — Query Gameplay Tag hierarchy and find tagged assets
+//
+// All tools require MCPBridge plugin (Phase 25 — GAS-01 through GAS-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_abilities handler — satisfies GAS-01.
+ * Sends gas.abilities to the plugin; returns all Gameplay Ability classes with
+ * tags, cost/cooldown effect references, and instancing policy.
+ *
+ * @param args  Tool arguments including optional class_filter.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleListAbilities(args, b = bridge) {
+    // Response data shape: AbilityListResult
+    const payload = {};
+    if (args.class_filter !== undefined) {
+        payload['class_filter'] = args.class_filter;
+    }
+    return sendOrDisconnect(b, {
+        type: 'gas.abilities',
+        payload,
+    });
+}
+/**
+ * ue_inspect_gameplay_effect handler — satisfies GAS-02.
+ * Sends gas.effects to the plugin; returns modifiers, duration policy,
+ * stacking configuration, period interval, and Gameplay Cue tags.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleInspectGameplayEffect(args, b = bridge) {
+    // Response data shape: GameplayEffectInspectResult
+    return sendOrDisconnect(b, {
+        type: 'gas.effects',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_read_attribute_set handler — satisfies GAS-03.
+ * Sends gas.attributes to the plugin; returns all Attribute Set properties
+ * with base values, replication status, and clamping information.
+ *
+ * @param args  Tool arguments including asset_path.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleReadAttributeSet(args, b = bridge) {
+    // Response data shape: AttributeSetReadResult
+    return sendOrDisconnect(b, {
+        type: 'gas.attributes',
+        payload: { asset_path: args.asset_path },
+    });
+}
+/**
+ * ue_query_gameplay_tags handler — satisfies GAS-04.
+ * Sends gas.tags to the plugin; returns matching tag paths from the hierarchy
+ * and optionally finds all assets that reference a specific tag.
+ *
+ * @param args  Tool arguments including optional tag_filter and find_assets_with_tag.
+ * @param b     PluginBridgeClient instance (defaults to module-level singleton).
+ */
+export async function handleQueryGameplayTags(args, b = bridge) {
+    // Response data shape: GameplayTagQueryResult
+    const payload = {
+        tag_filter: args.tag_filter ?? '',
+    };
+    if (args.find_assets_with_tag !== undefined) {
+        payload['find_assets_with_tag'] = args.find_assets_with_tag;
+    }
+    return sendOrDisconnect(b, {
+        type: 'gas.tags',
+        payload,
+    });
+}
+// ---------------------------------------------------------------------------
+// registerGASTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Gameplay Ability System 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 25):
+ *   ue_list_abilities             — GAS-01: List ability classes with tags, costs, and instancing
+ *   ue_inspect_gameplay_effect    — GAS-02: Inspect effect modifiers, duration, stacking
+ *   ue_read_attribute_set         — GAS-03: Read Attribute Set definitions with base values
+ *   ue_query_gameplay_tags        — GAS-04: Query tag hierarchy and find tagged assets
+ *
+ * @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 registerGASTools(server, _bridge) {
+    const b = _bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_abilities (GAS-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_abilities', {
+        title: 'List Gameplay Abilities',
+        description: '[requires_plugin] List all Gameplay Ability classes in the project with their tags, cost/cooldown effect references, and instancing policy.',
+        inputSchema: z.object({
+            class_filter: z
+                .string()
+                .optional()
+                .describe('Optional substring to filter ability class names (e.g. "Melee" matches GA_MeleeAttack)'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_abilities', async (args) => handleListAbilities(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_inspect_gameplay_effect (GAS-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_inspect_gameplay_effect', {
+        title: 'Inspect Gameplay Effect',
+        description: '[requires_plugin] Inspect a Gameplay Effect asset\'s modifiers, duration policy, stacking configuration, and period interval.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Gameplay Effect asset, e.g. /Game/GAS/GE_DealDamage'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_inspect_gameplay_effect', async (args) => handleInspectGameplayEffect(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_read_attribute_set (GAS-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_read_attribute_set', {
+        title: 'Read Attribute Set',
+        description: '[requires_plugin] Read an Attribute Set class\'s attributes with base values, replication status, and clamping information.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('UE long package path to the Attribute Set asset, e.g. /Game/GAS/AS_Character'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_read_attribute_set', async (args) => handleReadAttributeSet(args, b)));
+    // --------------------------------------------------------------------------
+    // ue_query_gameplay_tags (GAS-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_query_gameplay_tags', {
+        title: 'Query Gameplay Tags',
+        description: '[requires_plugin] Query the Gameplay Tag hierarchy by filter and optionally find all assets that reference a specific tag.',
+        inputSchema: z.object({
+            tag_filter: z
+                .string()
+                .optional()
+                .describe('Optional tag prefix or substring to filter results (e.g. "Ability.Melee" returns all melee ability tags)'),
+            find_assets_with_tag: z
+                .string()
+                .optional()
+                .describe('Optional exact tag path to perform a reverse lookup — returns all assets referencing this tag'),
+        }),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_query_gameplay_tags', async (args) => handleQueryGameplayTags(args, b)));
+}

package/dist/tools/gas/types.js

@@ -0,0 +1,5 @@
+// src/tools/gas/types.ts
+// TypeScript result interfaces for the four Gameplay Ability System MCP tools (Phase 25).
+// These interfaces mirror the JSON shapes returned by the C++ handlers in Plan 25-01.
+// Requirements covered: GAS-01, GAS-02, GAS-03, GAS-04.
+export {};

package/dist/tools/import-export/index.js

@@ -0,0 +1,218 @@
+// src/tools/import-export/index.ts
+// MCP tool implementations for asset import/export operations (Phase 21).
+// 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 21 — IMP-01 through IMP-04):
+//   ue_import_fbx       — Import an FBX file into the project at a specified content path
+//   ue_import_usd       — Import a USD file using the Interchange pipeline
+//   ue_export_mesh      — Export a StaticMesh or SkeletalMesh asset to FBX format
+//   ue_batch_import     — Batch import multiple files from a directory with configurable settings
+//
+// Command mappings:
+//   ue_import_fbx    -> import.fbx
+//   ue_import_usd    -> import.usd
+//   ue_export_mesh   -> export.mesh
+//   ue_batch_import  -> import.batch
+//
+// All tools require MCPBridge plugin (Phase 21 — IMP-01 through IMP-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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerImportExportTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE asset import/export 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 21):
+ *   ue_import_fbx    — IMP-01: Import an FBX file into the project
+ *   ue_import_usd    — IMP-02: Import a USD file via Interchange pipeline
+ *   ue_export_mesh   — IMP-03: Export a static/skeletal mesh to FBX
+ *   ue_batch_import  — IMP-04: Batch import multiple files with settings
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (injected bridge replaces module singleton).
+ */
+export function registerImportExportTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_import_fbx (IMP-01)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_import_fbx', {
+        title: 'Import FBX File',
+        description: '[requires_plugin] Import an FBX file into the project at a specified content path. Returns the list of created asset paths.',
+        inputSchema: z.object({
+            source_file: z
+                .string()
+                .min(1)
+                .describe('Absolute OS path to the .fbx file to import'),
+            dest_path: z
+                .string()
+                .min(1)
+                .describe('Content browser destination path, e.g. /Game/Meshes'),
+            import_materials: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Import materials from FBX'),
+            combine_meshes: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Combine all meshes into a single asset'),
+            scale_factor: z
+                .number()
+                .optional()
+                .default(1.0)
+                .describe('Import scale factor'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_import_fbx', async (args) => sendOrDisconnect(_bridge, {
+        type: 'import.fbx',
+        payload: { ...args },
+    })));
+    // --------------------------------------------------------------------------
+    // ue_import_usd (IMP-02)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_import_usd', {
+        title: 'Import USD File',
+        description: '[requires_plugin] Import a USD file into the project using the Interchange pipeline. Supports .usd, .usda, and .usdc formats.',
+        inputSchema: z.object({
+            source_file: z
+                .string()
+                .min(1)
+                .describe('Absolute OS path to the USD file'),
+            dest_path: z
+                .string()
+                .min(1)
+                .describe('Content browser destination path'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_import_usd', async (args) => sendOrDisconnect(_bridge, {
+        type: 'import.usd',
+        payload: { ...args },
+    })));
+    // --------------------------------------------------------------------------
+    // ue_export_mesh (IMP-03)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_export_mesh', {
+        title: 'Export Mesh to FBX',
+        description: '[requires_plugin] Export a StaticMesh or SkeletalMesh asset to FBX format at the specified output path.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .min(1)
+                .describe('Content browser path to the mesh asset, e.g. /Game/Meshes/MyMesh'),
+            output_file: z
+                .string()
+                .min(1)
+                .describe('Absolute OS path for the output .fbx file'),
+            export_collision: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('Include collision geometry in export'),
+            level_of_detail: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .default(0)
+                .describe('LOD level to export (0 = base)'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_export_mesh', async (args) => sendOrDisconnect(_bridge, {
+        type: 'export.mesh',
+        payload: { ...args },
+    })));
+    // --------------------------------------------------------------------------
+    // ue_batch_import (IMP-04)
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_batch_import', {
+        title: 'Batch Import Files',
+        description: '[requires_plugin] Import multiple files from a directory into the project with configurable settings. Supports filtering by file extension.',
+        inputSchema: z.object({
+            directory: z
+                .string()
+                .min(1)
+                .describe('Absolute OS path to the directory containing files to import'),
+            extensions: z
+                .array(z.string())
+                .optional()
+                .default(['fbx'])
+                .describe("File extensions to import, e.g. ['fbx', 'obj', 'usd']"),
+            dest_path: z
+                .string()
+                .min(1)
+                .describe('Content browser destination path'),
+            import_materials: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Import materials from source files'),
+            scale_factor: z
+                .number()
+                .optional()
+                .default(1.0)
+                .describe('Import scale factor for all files'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_batch_import', async (args) => sendOrDisconnect(_bridge, {
+        type: 'import.batch',
+        payload: { ...args },
+    })));
+}

package/dist/tools/input/index.js

@@ -0,0 +1,146 @@
+// src/tools/input/index.ts
+// MCP tool implementations for Enhanced Input Management (Phase 14).
+// All tools route commands through PluginBridgeClient to the C++ MCPBridge plugin.
+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
+    }
+}
+// ---------------------------------------------------------------------------
+// registerInputTools
+// ---------------------------------------------------------------------------
+/**
+ * Register UE Enhanced Input 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 14):
+ *   ue_list_input_actions     — List all UInputAction assets with value types
+ *   ue_create_input_action    — Create a new UInputAction asset
+ *   ue_list_input_contexts    — List all UInputMappingContext assets with bindings
+ *   ue_add_input_binding      — Add or update a key binding in a UInputMappingContext
+ *
+ * @param server  The McpServer instance to register tools on.
+ * @param bridge  Optional PluginBridgeClient for testing (defaults to a new instance).
+ */
+export function registerInputTools(server, bridge) {
+    const _bridge = bridge ?? new PluginBridgeClient();
+    // --------------------------------------------------------------------------
+    // ue_list_input_actions
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_input_actions', {
+        title: 'List Input Actions',
+        description: '[requires_plugin] List all UInputAction assets in the project with their value types (bool, float, Axis2D, Axis3D).',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_input_actions', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'input.listActions' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_create_input_action
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_create_input_action', {
+        title: 'Create Input Action',
+        description: '[requires_plugin] Create a new UInputAction asset at the given content path with the specified value type.',
+        inputSchema: z.object({
+            asset_path: z.string().describe('Content-browser package path, e.g. /Game/Input/IA_Jump'),
+            value_type: z
+                .enum(['bool', 'float', 'Axis2D', 'Axis3D'])
+                .describe('Input action value type'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_create_input_action', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'input.createAction',
+            payload: { asset_path: args.asset_path, value_type: args.value_type },
+        });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_list_input_contexts
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_input_contexts', {
+        title: 'List Input Mapping Contexts',
+        description: '[requires_plugin] List all UInputMappingContext assets in the project with their action-to-key bindings.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_input_contexts', async (_args) => {
+        return sendOrDisconnect(_bridge, { type: 'input.listContexts' });
+    }));
+    // --------------------------------------------------------------------------
+    // ue_add_input_binding
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_add_input_binding', {
+        title: 'Add Input Binding',
+        description: '[requires_plugin] Add or update a key binding in a UInputMappingContext. Maps an Input Action to a keyboard/gamepad key.',
+        inputSchema: z.object({
+            asset_path: z
+                .string()
+                .describe('Package path of the UInputMappingContext, e.g. /Game/Input/IMC_Default'),
+            action_path: z
+                .string()
+                .describe('Package path of the UInputAction to bind, e.g. /Game/Input/IA_Jump'),
+            key: z
+                .string()
+                .describe('Key name as a UE FKey string, e.g. SpaceBar, Gamepad_FaceButton_Bottom'),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_add_input_binding', async (args) => {
+        return sendOrDisconnect(_bridge, {
+            type: 'input.addBinding',
+            payload: {
+                asset_path: args.asset_path,
+                action_path: args.action_path,
+                key: args.key,
+            },
+        });
+    }));
+}

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

@@ -0,0 +1,88 @@
+// src/tools/known-issues/index.ts
+// Registers the ue_list_known_issues and ue_add_known_issue MCP tools.
+// Both tools are wrapped with withKnownIssues middleware per INF-06.
+import { z } from 'zod';
+import { withKnownIssues } from './middleware.js';
+import { readKnownIssues, appendKnownIssue } from './store.js';
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+/**
+ * Register KNOWN_ISSUES management tools on the MCP server.
+ *
+ * Tools registered:
+ *   ue_list_known_issues  — returns all entries from KNOWN_ISSUES.md (read-only)
+ *   ue_add_known_issue    — appends a new entry to KNOWN_ISSUES.md
+ *
+ * @param server  The McpServer instance to register tools on.
+ */
+export function registerKnownIssuesTools(server) {
+    // --------------------------------------------------------------------------
+    // ue_list_known_issues
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_list_known_issues', {
+        title: 'List Known Issues',
+        description: 'Returns all entries from KNOWN_ISSUES.md. Run this before any operation to check for known issues that may affect the result.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_list_known_issues', async () => {
+        const issues = await readKnownIssues();
+        if (issues.length === 0) {
+            return {
+                content: [{ type: 'text', text: 'No known issues recorded.' }],
+            };
+        }
+        const lines = issues.map((i) => `## ${i.id}\n` +
+            `**Description:** ${i.description}\n` +
+            `**Affected tools:** ${i.affectedTools.join(', ')}\n` +
+            `**Root cause:** ${i.rootCause}\n` +
+            `**Resolution:** ${i.resolution}\n` +
+            `**Date added:** ${i.dateAdded}\n` +
+            `**Status:** ${i.status}`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n\n---\n\n') }],
+        };
+    }));
+    // --------------------------------------------------------------------------
+    // ue_add_known_issue
+    // --------------------------------------------------------------------------
+    server.registerTool('ue_add_known_issue', {
+        title: 'Add Known Issue',
+        description: 'Appends a new entry to KNOWN_ISSUES.md after user approves a fix.',
+        inputSchema: z.object({
+            description: z.string(),
+            affectedTools: z
+                .string()
+                .describe('Comma-separated tool names, or * for all tools'),
+            rootCause: z.string(),
+            resolution: z.string(),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+        },
+    }, withKnownIssues('ue_add_known_issue', async ({ description, affectedTools, rootCause, resolution }) => {
+        const issue = await appendKnownIssue({
+            description,
+            affectedTools: affectedTools
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean),
+            rootCause,
+            resolution,
+            dateAdded: new Date().toISOString().split('T')[0] ?? '',
+            status: 'active',
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Known issue recorded as ${issue.id}. It will be surfaced as a warning before any affected tool runs.`,
+                },
+            ],
+        };
+    }));
+}