ultimate-unreal-engine-mcp 0.1.0

package/dist/generators/file-modifier.js

@@ -0,0 +1,276 @@
+// src/generators/file-modifier.ts
+// Pure in-memory string transformations for modifying existing UE C++ header files.
+//
+// GEN-05: addProperty — inserts UPROPERTY declaration after last existing UPROPERTY
+// GEN-06: addFunction — inserts UFUNCTION declaration after last existing UFUNCTION
+// GEN-07: addInclude  — inserts #include before .generated.h line (idempotent)
+// GEN-08: all modifications validated via validateUhtRules before returning
+//
+// T-05-06 mitigation: all output passes through validateUhtRules (specifier/name integrity).
+// T-05-08 mitigation: TDD suite covers insertion edge cases.
+//
+// Constraints:
+//   - Pure functions — no fs, no async, no side effects
+//   - Never throws — always returns ModifyResult
+//   - console.error only (never console.log)
+import { parseCppFile } from '../parsers/cpp-parser.js';
+import { validateUhtRules } from './uht-validator.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Inserts `toInsert` lines after the given 0-based line index.
+ */
+function insertLinesAt(lines, afterLineIndex, toInsert) {
+    return [
+        ...lines.slice(0, afterLineIndex + 1),
+        ...toInsert,
+        ...lines.slice(afterLineIndex + 1),
+    ];
+}
+/**
+ * Validates modified content with UHT rules and returns ModifyResult.
+ */
+function validateAndReturn(content) {
+    const validation = validateUhtRules(content);
+    if (!validation.valid) {
+        return { success: false, error: validation.errors.join('; ') };
+    }
+    return { success: true, content };
+}
+/**
+ * Find the 0-based line index of GENERATED_BODY() starting from startLine (0-based).
+ * Returns -1 if not found within the search range.
+ */
+function findGeneratedBodyLine(lines, startLine) {
+    for (let i = startLine; i < lines.length; i++) {
+        const ln = lines[i] ?? '';
+        if (ln.includes('GENERATED_BODY()')) {
+            return i;
+        }
+        // Stop searching if we hit a class-ending brace at depth 0
+        // (simple heuristic: if line is just '}' or '};' after the opening brace)
+        if (i > startLine + 2 && (ln.trim() === '}' || ln.trim() === '};')) {
+            break;
+        }
+    }
+    return -1;
+}
+// ---------------------------------------------------------------------------
+// Public functions
+// ---------------------------------------------------------------------------
+/**
+ * Adds a UPROPERTY declaration to an existing class in the C++ header content.
+ *
+ * Algorithm:
+ * 1. Parse content — error if parse fails.
+ * 2. Find class by name — error if not found.
+ * 3. If class has existing properties: insert after the last property's declaration line.
+ *    If not: insert after GENERATED_BODY() line.
+ * 4. Validate with validateUhtRules before returning.
+ *
+ * GEN-05, GEN-08
+ */
+export function addProperty(content, className, decl) {
+    try {
+        const parseResult = parseCppFile(content);
+        if (!parseResult.success) {
+            return { success: false, error: `Parse error: ${parseResult.error}` };
+        }
+        const cls = parseResult.data.classes.find((c) => c.name === className);
+        if (!cls) {
+            return { success: false, error: `Class '${className}' not found in file` };
+        }
+        const lines = content.split('\n');
+        // Build the insertion block (tab-indented, UE style)
+        const specStr = decl.specifiers.join(', ');
+        const defaultSuffix = decl.defaultValue ? ` = ${decl.defaultValue}` : '';
+        const insertBlock = [
+            `\tUPROPERTY(${specStr})`,
+            `\t${decl.type} ${decl.name}${defaultSuffix};`,
+            `\t`,
+        ];
+        let insertAfterIndex;
+        if (cls.properties.length > 0) {
+            // Insert after the declaration line of the last property.
+            // prop.line is 1-based line of the UPROPERTY macro.
+            // Declaration is on the next line: prop.line + 1 (1-based) = prop.line (0-based).
+            const lastProp = cls.properties[cls.properties.length - 1];
+            // 0-based index of declaration line = lastProp.line (since macro is at lastProp.line - 1 in 0-based,
+            // declaration is at lastProp.line in 0-based)
+            insertAfterIndex = lastProp.line; // 0-based index of the property declaration line
+        }
+        else {
+            // No properties — find GENERATED_BODY() and insert after it
+            // cls.line is 1-based class declaration line, convert to 0-based
+            const classLineIdx = cls.line - 1;
+            const genBodyIdx = findGeneratedBodyLine(lines, classLineIdx);
+            if (genBodyIdx < 0) {
+                return { success: false, error: `GENERATED_BODY() not found in class '${className}'` };
+            }
+            insertAfterIndex = genBodyIdx;
+        }
+        const newLines = insertLinesAt(lines, insertAfterIndex, insertBlock);
+        const newContent = newLines.join('\n');
+        return validateAndReturn(newContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[file-modifier] addProperty error: ${msg}`);
+        return { success: false, error: `Internal error: ${msg}` };
+    }
+}
+/**
+ * Adds a UFUNCTION declaration to an existing class in the C++ header content.
+ *
+ * Algorithm:
+ * 1. Parse content — error if parse fails.
+ * 2. Find class by name — error if not found.
+ * 3. If class has existing functions: insert after the last function's declaration line.
+ *    If not: insert after GENERATED_BODY() line.
+ * 4. Validate with validateUhtRules before returning.
+ *
+ * GEN-06, GEN-08
+ */
+export function addFunction(content, className, decl) {
+    try {
+        const parseResult = parseCppFile(content);
+        if (!parseResult.success) {
+            return { success: false, error: `Parse error: ${parseResult.error}` };
+        }
+        const cls = parseResult.data.classes.find((c) => c.name === className);
+        if (!cls) {
+            return { success: false, error: `Class '${className}' not found in file` };
+        }
+        const lines = content.split('\n');
+        // Build the insertion block (tab-indented, UE style)
+        const specStr = decl.specifiers.join(', ');
+        const paramStr = decl.params ?? '';
+        const constSuffix = decl.isConst ? ' const' : '';
+        const insertBlock = [
+            `\tUFUNCTION(${specStr})`,
+            `\t${decl.returnType} ${decl.name}(${paramStr})${constSuffix};`,
+            `\t`,
+        ];
+        let insertAfterIndex;
+        if (cls.functions.length > 0) {
+            // Insert after the declaration line of the last function.
+            // fn.line is 1-based line of the UFUNCTION macro.
+            // Declaration is on the next line: fn.line + 1 (1-based) = fn.line (0-based).
+            const lastFn = cls.functions[cls.functions.length - 1];
+            insertAfterIndex = lastFn.line; // 0-based index of the function declaration line
+        }
+        else {
+            // No functions — find GENERATED_BODY() and insert after it
+            const classLineIdx = cls.line - 1;
+            const genBodyIdx = findGeneratedBodyLine(lines, classLineIdx);
+            if (genBodyIdx < 0) {
+                return { success: false, error: `GENERATED_BODY() not found in class '${className}'` };
+            }
+            insertAfterIndex = genBodyIdx;
+        }
+        const newLines = insertLinesAt(lines, insertAfterIndex, insertBlock);
+        const newContent = newLines.join('\n');
+        return validateAndReturn(newContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[file-modifier] addFunction error: ${msg}`);
+        return { success: false, error: `Internal error: ${msg}` };
+    }
+}
+/**
+ * Adds an #include directive to a C++ header file.
+ *
+ * Algorithm:
+ * 1. Parse content — error if parse fails.
+ * 2. Check for duplicate — if include already present, return unchanged content (idempotent).
+ * 3. Find .generated.h line — if present, insert before it.
+ *    Otherwise insert after last #include, or after #pragma once if no includes.
+ * 4. Validate with validateUhtRules before returning.
+ *
+ * GEN-07, GEN-08
+ */
+export function addInclude(content, includePath) {
+    try {
+        const parseResult = parseCppFile(content);
+        if (!parseResult.success) {
+            return { success: false, error: `Parse error: ${parseResult.error}` };
+        }
+        const { includes } = parseResult.data;
+        // Normalize the includePath for duplicate checking.
+        // Strip surrounding quotes or angle brackets.
+        const normalizedPath = includePath.replace(/^["<]/, '').replace(/[">]$/, '');
+        // Check if already present (idempotent)
+        const alreadyPresent = includes.some((inc) => {
+            // Parser strips angle brackets for angle-bracket includes, adds '<>' prefix
+            // For quoted includes, the parser stores just the path without quotes
+            const normalizedInc = inc.startsWith('<') ? inc.slice(1, -1) : inc;
+            return normalizedInc === normalizedPath;
+        });
+        if (alreadyPresent) {
+            return { success: true, content };
+        }
+        // Determine the formatted include directive
+        const isAngleBracket = includePath.startsWith('<') && includePath.endsWith('>');
+        let directive;
+        if (isAngleBracket) {
+            directive = `#include ${includePath}`;
+        }
+        else {
+            // If path already has quotes, use as-is; otherwise add quotes
+            if (includePath.startsWith('"') && includePath.endsWith('"')) {
+                directive = `#include ${includePath}`;
+            }
+            else {
+                directive = `#include "${includePath}"`;
+            }
+        }
+        const lines = content.split('\n');
+        // Find the .generated.h line index (0-based)
+        let generatedHLineIdx = -1;
+        let lastIncludeLineIdx = -1;
+        let pragmaOnceLineIdx = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const ln = lines[i] ?? '';
+            const trimmed = ln.trim();
+            if (trimmed.startsWith('#pragma once')) {
+                pragmaOnceLineIdx = i;
+            }
+            if (trimmed.startsWith('#include')) {
+                lastIncludeLineIdx = i;
+                if (trimmed.includes('.generated.h')) {
+                    generatedHLineIdx = i;
+                }
+            }
+        }
+        let newLines;
+        if (generatedHLineIdx >= 0) {
+            // Insert before the .generated.h line
+            newLines = [
+                ...lines.slice(0, generatedHLineIdx),
+                directive,
+                ...lines.slice(generatedHLineIdx),
+            ];
+        }
+        else if (lastIncludeLineIdx >= 0) {
+            // Insert after the last #include line
+            newLines = insertLinesAt(lines, lastIncludeLineIdx, [directive]);
+        }
+        else if (pragmaOnceLineIdx >= 0) {
+            // Insert after #pragma once
+            newLines = insertLinesAt(lines, pragmaOnceLineIdx, [directive]);
+        }
+        else {
+            // Insert at the beginning
+            newLines = [directive, ...lines];
+        }
+        const newContent = newLines.join('\n');
+        return validateAndReturn(newContent);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[file-modifier] addInclude error: ${msg}`);
+        return { success: false, error: `Internal error: ${msg}` };
+    }
+}

package/dist/generators/uht-validator.js

@@ -0,0 +1,177 @@
+// src/generators/uht-validator.ts
+// Pure UHT pre-validation for generated or modified C++ header content.
+// GEN-08: validates content against UHT rules before any disk write.
+//
+// Rules enforced:
+//   1. GENERATED_BODY() present in every UCLASS body
+//   2. ClassName.generated.h must be the last #include
+//   3. No duplicate UPROPERTY names within a class
+//   4. No duplicate UFUNCTION names within a class
+//   5. UPROPERTY specifiers must be from the known allowlist (bare word specifiers only)
+//
+// Never throws — always returns UhtValidationResult.
+// Pure function — no fs, no async, no side effects.
+//
+// T-05-01 mitigation: parseCppFile already caps balanced-paren search at 500 lines.
+// The line-scan in this module is O(n) with no backtracking — safe for large input.
+import { parseCppFile } from '../parsers/cpp-parser.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Known valid bare-word UPROPERTY specifiers.
+ * Compound specifiers (containing '=' or '(') are always allowed and not checked here.
+ */
+const VALID_UPROPERTY_SPECIFIERS = new Set([
+    'EditAnywhere',
+    'EditDefaultsOnly',
+    'EditInstanceOnly',
+    'VisibleAnywhere',
+    'VisibleDefaultsOnly',
+    'VisibleInstanceOnly',
+    'BlueprintReadWrite',
+    'BlueprintReadOnly',
+    'BlueprintGetter',
+    'BlueprintSetter',
+    'Category',
+    'DisplayName',
+    'AdvancedDisplay',
+    'SaveGame',
+    'Transient',
+    'Replicated',
+    'ReplicatedUsing',
+    'NotReplicated',
+    'Config',
+    'GlobalConfig',
+    'Localized',
+    'Export',
+    'NoClear',
+    'EditFixedSize',
+    'meta',
+    'AllowPrivateAccess',
+]);
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+/**
+ * Validates generated or modified C++ header content against UHT rules.
+ *
+ * @param content - Raw C++ header file content as a string
+ * @returns UhtValidationResult with valid flag and collected errors
+ *
+ * Never throws. Returns { valid: true, errors: [] } for empty or no-UCLASS content.
+ */
+export function validateUhtRules(content) {
+    const errors = [];
+    try {
+        // Guard: null/undefined or whitespace-only input is considered valid (nothing to check)
+        if (!content || typeof content !== 'string' || !content.trim()) {
+            return { valid: true, errors: [] };
+        }
+        const parseResult = parseCppFile(content);
+        if (!parseResult.success) {
+            return {
+                valid: false,
+                errors: [`UHT validator: failed to parse C++ content: ${parseResult.error}`],
+            };
+        }
+        const { classes, includes } = parseResult.data;
+        // No UCLASS declarations found — nothing to validate
+        if (classes.length === 0) {
+            return { valid: true, errors: [] };
+        }
+        // -------------------------------------------------------------------------
+        // Rule 2: generated.h must be the LAST include
+        // -------------------------------------------------------------------------
+        // Find the last include that ends with '.generated.h'
+        const generatedIdx = includes.findIndex((inc) => inc.endsWith('.generated.h'));
+        if (generatedIdx >= 0 && generatedIdx !== includes.length - 1) {
+            errors.push(`${includes[generatedIdx]} must be the last #include in the file (UHT requirement)`);
+        }
+        // -------------------------------------------------------------------------
+        // Per-class rules
+        // -------------------------------------------------------------------------
+        const lines = content.split('\n');
+        for (const cls of classes) {
+            const className = cls.name;
+            // -----------------------------------------------------------------------
+            // Rule 1: GENERATED_BODY() must appear in the class body
+            // Search from the class declaration line forward, stopping when the
+            // top-level class brace closes.
+            // cls.line is 1-based; convert to 0-based index.
+            // -----------------------------------------------------------------------
+            const classStartLine = cls.line - 1; // 0-based
+            let foundGenBody = false;
+            let braceDepth = 0;
+            let inBody = false;
+            let bodyDone = false;
+            for (let i = classStartLine; i < lines.length && !bodyDone; i++) {
+                const ln = lines[i] ?? '';
+                // Check for GENERATED_BODY() on this line before brace accounting
+                if (ln.includes('GENERATED_BODY()')) {
+                    foundGenBody = true;
+                }
+                // Track brace depth to find the end of the class body
+                for (const ch of ln) {
+                    if (ch === '{') {
+                        braceDepth++;
+                        inBody = true;
+                    }
+                    else if (ch === '}') {
+                        braceDepth--;
+                        if (inBody && braceDepth <= 0) {
+                            bodyDone = true;
+                            break;
+                        }
+                    }
+                }
+            }
+            if (!foundGenBody) {
+                errors.push(`Class ${className}: GENERATED_BODY() macro is missing from class body`);
+            }
+            // -----------------------------------------------------------------------
+            // Rule 3: No duplicate UPROPERTY names within a class
+            // -----------------------------------------------------------------------
+            const seenPropNames = new Set();
+            for (const prop of cls.properties) {
+                if (seenPropNames.has(prop.name)) {
+                    errors.push(`Class ${className}: duplicate UPROPERTY name '${prop.name}'`);
+                }
+                else {
+                    seenPropNames.add(prop.name);
+                }
+            }
+            // -----------------------------------------------------------------------
+            // Rule 4: No duplicate UFUNCTION names within a class
+            // -----------------------------------------------------------------------
+            const seenFnNames = new Set();
+            for (const fn of cls.functions) {
+                if (seenFnNames.has(fn.name)) {
+                    errors.push(`Class ${className}: duplicate UFUNCTION name '${fn.name}'`);
+                }
+                else {
+                    seenFnNames.add(fn.name);
+                }
+            }
+            // -----------------------------------------------------------------------
+            // Rule 5: UPROPERTY specifier allowlist (bare-word specifiers only)
+            // Compound specifiers (containing '=' or '(') are always allowed.
+            // -----------------------------------------------------------------------
+            for (const prop of cls.properties) {
+                for (const spec of prop.specifiers) {
+                    // Skip compound specifiers — they contain '=' or '(' and are valid by convention
+                    if (spec.includes('=') || spec.includes('('))
+                        continue;
+                    if (!VALID_UPROPERTY_SPECIFIERS.has(spec)) {
+                        errors.push(`Class ${className}, property ${prop.name}: unknown UPROPERTY specifier '${spec}'`);
+                    }
+                }
+            }
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { valid: false, errors: [`UHT validator internal error: ${msg}`] };
+    }
+    return { valid: errors.length === 0, errors };
+}

package/dist/index.js

@@ -0,0 +1,89 @@
+// src/index.ts
+// MCP server entry point for the Ultimate Unreal Engine MCP.
+// Registers all domain tool modules and connects the StdioServerTransport.
+//
+// Logging: ALL output goes to stderr via logger.ts — never console.log.
+// Reason: stdout is the MCP JSON-RPC channel; any non-JSON stdout output
+// corrupts the protocol stream and disconnects the client (PITFALLS.md Pitfall 8).
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { SERVER_VERSION, PLUGIN_PORT } from './config.js';
+import { log } from './utils/logger.js';
+import { registerKnownIssuesTools } from './tools/known-issues/index.js';
+import { registerCppTools } from './tools/cpp/index.js';
+import { registerConfigTools } from './tools/config/index.js';
+import { registerDocsTools } from './tools/docs/index.js';
+import { registerBuildTools } from './tools/build/index.js';
+import { registerBlueprintTools } from './tools/blueprint/index.js';
+import { registerEditorTools } from './tools/editor/index.js';
+import { registerViewportTools } from './tools/viewport/index.js';
+import { registerSequencerTools } from './tools/sequencer/index.js';
+import { registerInputTools } from './tools/input/index.js';
+import { registerMaterialTools } from './tools/material/index.js';
+import { registerValidationTools } from './tools/validation/index.js';
+import { registerAnimationTools } from './tools/animation/index.js';
+import { registerWorldPartitionTools } from './tools/worldpartition/index.js';
+import { registerSelectionTools } from './tools/selection/index.js';
+import { registerCollisionPhysicsTools } from './tools/collision-physics/index.js';
+import { registerImportExportTools } from './tools/import-export/index.js';
+import { registerAISystemsTools } from './tools/ai-systems/index.js';
+import { registerLiveLinkTools } from './tools/livelink/index.js';
+import { registerAudioTools } from './tools/audio/index.js';
+import { registerPCGTools } from './tools/pcg/index.js';
+import { registerGASTools } from './tools/gas/index.js';
+import { registerChaosTools } from './tools/chaos/index.js';
+import { registerMotionDesignTools } from './tools/motion-design/index.js';
+import { registerMovieRenderTools } from './tools/movie-render/index.js';
+import { registerNetworkingTools } from './tools/networking/index.js';
+// ---------------------------------------------------------------------------
+// Main async IIFE — wraps the full startup sequence.
+// Any unhandled error triggers a clean process.exit(1) with a stderr message.
+// ---------------------------------------------------------------------------
+(async () => {
+    log('Starting ultimate-unreal-engine-mcp v' + SERVER_VERSION);
+    log('Plugin connection will be attempted on port ' + PLUGIN_PORT);
+    const server = new McpServer({
+        name: 'ultimate-unreal-engine-mcp',
+        version: SERVER_VERSION,
+    });
+    // Register all domain tool modules in dependency order:
+    // 1. KNOWN_ISSUES tools (infrastructure — must come first so other tools can surface issues)
+    // 2. File-system tool domains (no plugin dependency)
+    // 3. Plugin-dependent tool domains (return structured errors when plugin is absent)
+    registerKnownIssuesTools(server);
+    registerCppTools(server);
+    registerConfigTools(server);
+    registerDocsTools(server);
+    registerBuildTools(server);
+    registerBlueprintTools(server);
+    registerEditorTools(server);
+    registerViewportTools(server);
+    registerSequencerTools(server);
+    registerInputTools(server);
+    registerMaterialTools(server); // Material & Shader tools (Phase 15)
+    // Validation tools (VAL-01..04)
+    registerValidationTools(server);
+    registerAnimationTools(server); // Animation tools (ANIM-01..05)
+    registerWorldPartitionTools(server); // World Partition tools (WP-01..04)
+    registerSelectionTools(server); // Selection tools (SEL-01..04)
+    registerCollisionPhysicsTools(server); // Collision & Physics tools (PHY-01..04)
+    registerImportExportTools(server); // Import/Export tools (IMP-01..04)
+    registerAISystemsTools(server); // AI system tools (AI-01..05)
+    registerLiveLinkTools(server); // Live Link tools (LL-01..04)
+    registerAudioTools(server); // Audio tools (AUD-01..04)
+    registerPCGTools(server); // PCG Framework tools (PCG-01..04)
+    registerGASTools(server); // GAS tools (GAS-01..04)
+    registerChaosTools(server); // Chaos physics tools (CHAOS-01..04)
+    registerMotionDesignTools(server); // Motion Design tools (MD-01..04)
+    registerMovieRenderTools(server); // Movie Render Pipeline tools (MRP-01..04)
+    registerNetworkingTools(server); // Networking & Replication tools (NET-01..04)
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log('Server ready — connected via stdio');
+})().catch((err) => {
+    // Fatal startup error — log to stderr and exit with non-zero code.
+    // Do NOT rethrow: unhandled rejection leaves the process in limbo,
+    // which can cause the MCP host to wait indefinitely for a response.
+    console.error('[UE MCP] Fatal startup error:', err);
+    process.exit(1);
+});