blueprint-extractor-mcp 2.1.0 → 2.3.0

package/README.md

@@ -4,7 +4,7 @@ MCP server for the Unreal Engine `BlueprintExtractor` plugin.
 
 This package exposes the `blueprint-extractor` server over stdio and talks to a running Unreal Editor through the Remote Control HTTP API.
 
-The current v2 MCP contract exposes 80 tools, 13 resources, 2 resource templates, and 4 prompts.
+The current v2 MCP contract exposes 87 tools, 12 resources, 4 resource templates, and 4 prompts.
 Public tools use canonical `snake_case` inputs and return structured JSON success or error envelopes.
 
 Current surface area includes:
@@ -13,7 +13,8 @@ Current surface area includes:
 - explicit-save authoring tools for the supported editor-side asset families, including compact widget extraction, incremental widget-structure ops, widget class-default routing, composable material authoring (`set_material_settings`, `add_material_expression`, `connect_material_expressions`, `bind_material_property`), and the advanced `modify_material` escape hatch
 - dedicated Enhanced Input authoring tools for `InputAction` and `InputMappingContext` assets (`create_input_action`, `modify_input_action`, `create_input_mapping_context`, `modify_input_mapping_context`)
 - async import and reimport tools with polling for generic assets plus typed texture and mesh helpers
-- host-side project automation tools for external builds, Live Coding requests, restart/reconnect orchestration, and a thin window-polish helper
+- host-side project automation tools for external builds, Live Coding requests, restart/reconnect orchestration, a thin window-polish helper, and runtime automation artifacts that surface verification screenshots back to the caller
+- a shared visual-verification artifact contract across widget captures, capture diffs, and automation-run screenshots so the caller can inspect rendered results instead of relying on semantic success alone
 - static guidance resources, resource templates, and prompts for authoring conventions, selector rules, font roles, project automation, example payloads, widget patterns, unsupported surfaces, safe UI redesign, and classic material graph guidance
 
 ## Requirements
@@ -63,7 +64,7 @@ npm install
 npm run build
 npm test
 npm run test:pack-smoke
-npm publish --dry-run
+npm run test:publish-gate
 ```
 
 For the gated live smoke test:

package/dist/automation-controller.d.ts

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process';
+export type AutomationRunStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
+export interface AutomationArtifact {
+    name: string;
+    path: string;
+    mimeType: string;
+    resourceUri: string;
+    relativePath?: string;
+}
+export interface AutomationRunSummary {
+    successful: boolean;
+    totalTests?: number;
+    passedTests?: number;
+    failedTests?: number;
+    skippedTests?: number;
+    warningCount?: number;
+    reportAvailable: boolean;
+}
+export interface AutomationRunResult {
+    success: boolean;
+    operation: 'run_automation_tests' | 'get_automation_test_run';
+    runId: string;
+    automationFilter: string;
+    status: AutomationRunStatus;
+    terminal: boolean;
+    engineRoot: string;
+    projectPath: string;
+    projectDir: string;
+    target?: string;
+    reportOutputDir: string;
+    command: {
+        executable: string;
+        args: string[];
+    };
+    diagnostics: string[];
+    startedAt?: string;
+    completedAt?: string;
+    durationMs?: number;
+    exitCode?: number;
+    timeoutMs: number;
+    nullRhi: boolean;
+    artifacts: AutomationArtifact[];
+    summary?: AutomationRunSummary;
+}
+export interface AutomationRunListResult {
+    success: boolean;
+    operation: 'list_automation_test_runs';
+    includeCompleted: boolean;
+    runCount: number;
+    runs: AutomationRunResult[];
+}
+export interface RunAutomationTestsRequest {
+    engineRoot: string;
+    projectPath: string;
+    target?: string;
+    automationFilter: string;
+    reportOutputDir?: string;
+    timeoutMs?: number;
+    nullRhi?: boolean;
+}
+export interface AutomationControllerLike {
+    runAutomationTests(request: RunAutomationTestsRequest): Promise<AutomationRunResult>;
+    getAutomationTestRun(runId: string): Promise<AutomationRunResult | null>;
+    listAutomationTestRuns(includeCompleted?: boolean): Promise<AutomationRunListResult>;
+    readAutomationArtifact(runId: string, artifactName: string): Promise<AutomationArtifactReadResult | null>;
+}
+export interface AutomationArtifactReadResult {
+    artifact: AutomationArtifact;
+    data: Buffer;
+}
+export interface AutomationControllerOptions {
+    env?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    now?: () => Date;
+    spawnProcess?: typeof spawn;
+    resolveEditorCommand?: (engineRoot: string, platform: NodeJS.Platform) => Promise<string>;
+}
+export declare class AutomationController implements AutomationControllerLike {
+    private readonly env;
+    private readonly platform;
+    private readonly now;
+    private readonly spawnProcess;
+    private readonly resolveEditorCommandFn;
+    private readonly runs;
+    constructor(options?: AutomationControllerOptions);
+    runAutomationTests(request: RunAutomationTestsRequest): Promise<AutomationRunResult>;
+    getAutomationTestRun(runId: string): Promise<AutomationRunResult | null>;
+    listAutomationTestRuns(includeCompleted?: boolean): Promise<AutomationRunListResult>;
+    readAutomationArtifact(runId: string, artifactName: string): Promise<AutomationArtifactReadResult | null>;
+    private cloneRun;
+    private registerArtifact;
+    private collectReportArtifacts;
+    private buildRunSummary;
+}

package/dist/automation-controller.js

@@ -0,0 +1,348 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import { resolveCommandInvocation, resolveEditorExecutable } from './project-controller.js';
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+function defaultNow() {
+    return new Date();
+}
+function sanitizeSegment(value) {
+    const sanitized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '_')
+        .replace(/^_+|_+$/gu, '');
+    return sanitized.length > 0 ? sanitized : 'automation';
+}
+function inferMimeType(filePath) {
+    switch (extname(filePath).toLowerCase()) {
+        case '.json':
+            return 'application/json';
+        case '.html':
+        case '.htm':
+            return 'text/html';
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.txt':
+        case '.log':
+            return 'text/plain';
+        default:
+            return 'application/octet-stream';
+    }
+}
+async function collectFilesRecursive(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = await Promise.all(entries.map(async (entry) => {
+        const fullPath = join(root, entry.name);
+        if (entry.isDirectory()) {
+            return await collectFilesRecursive(fullPath);
+        }
+        return [fullPath];
+    }));
+    return files.flat();
+}
+function firstNumericRecord(value, keys) {
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    const record = value;
+    for (const key of keys) {
+        const candidate = record[key];
+        if (typeof candidate === 'number' && Number.isFinite(candidate)) {
+            return candidate;
+        }
+    }
+    for (const nested of Object.values(record)) {
+        const found = firstNumericRecord(nested, keys);
+        if (typeof found === 'number') {
+            return found;
+        }
+    }
+    return undefined;
+}
+function buildSummaryFromReport(report, successful) {
+    return {
+        successful,
+        totalTests: firstNumericRecord(report, ['totalTests', 'total', 'numTotal']),
+        passedTests: firstNumericRecord(report, ['passedTests', 'succeeded', 'numSucceeded', 'passCount']),
+        failedTests: firstNumericRecord(report, ['failedTests', 'failed', 'numFailed', 'failCount']),
+        skippedTests: firstNumericRecord(report, ['skippedTests', 'skipped', 'numSkipped']),
+        warningCount: firstNumericRecord(report, ['warningCount', 'warnings', 'numWarnings']),
+        reportAvailable: true,
+    };
+}
+async function tryReadJson(filePath) {
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildResourceUri(runId, artifactName) {
+    return `blueprint://test-runs/${encodeURIComponent(runId)}/${encodeURIComponent(artifactName)}`;
+}
+async function resolveEditorCommand(engineRoot, platform) {
+    return await resolveEditorExecutable(engineRoot, platform, 'commandlet');
+}
+export class AutomationController {
+    env;
+    platform;
+    now;
+    spawnProcess;
+    resolveEditorCommandFn;
+    runs = new Map();
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.platform = options.platform ?? process.platform;
+        this.now = options.now ?? defaultNow;
+        this.spawnProcess = options.spawnProcess ?? spawn;
+        this.resolveEditorCommandFn = options.resolveEditorCommand ?? resolveEditorCommand;
+    }
+    async runAutomationTests(request) {
+        if (!request.engineRoot) {
+            throw new Error('run_automation_tests requires engine_root');
+        }
+        if (!request.projectPath) {
+            throw new Error('run_automation_tests requires project_path');
+        }
+        if (!request.automationFilter) {
+            throw new Error('run_automation_tests requires automation_filter');
+        }
+        const started = this.now();
+        const filterSlug = sanitizeSegment(request.automationFilter);
+        const runId = `${filterSlug}_${started.getTime()}_${randomUUID().slice(0, 8)}`;
+        const projectDir = dirname(request.projectPath);
+        const runRoot = request.reportOutputDir
+            ? resolve(request.reportOutputDir)
+            : resolve(projectDir, 'Saved', 'BlueprintExtractor', 'AutomationRuns', runId);
+        const reportOutputDir = resolve(runRoot, 'reports');
+        const stdoutPath = resolve(runRoot, 'stdout.log');
+        const stderrPath = resolve(runRoot, 'stderr.log');
+        const summaryPath = resolve(runRoot, 'summary.json');
+        const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const nullRhi = request.nullRhi ?? true;
+        await mkdir(reportOutputDir, { recursive: true });
+        const editorCmd = await this.resolveEditorCommandFn(request.engineRoot, this.platform);
+        const args = [
+            request.projectPath,
+            '-unattended',
+            '-nop4',
+            '-nosplash',
+            ...(nullRhi ? ['-NullRHI'] : []),
+            '-RCWebControlEnable',
+            '-RCWebInterfaceEnable',
+            `-ReportExportPath=${reportOutputDir}`,
+            `-ExecCmds=Automation RunTests ${request.automationFilter};Quit`,
+        ];
+        const invocation = resolveCommandInvocation(editorCmd, args, this.platform, this.env);
+        const run = {
+            success: true,
+            operation: 'run_automation_tests',
+            runId,
+            automationFilter: request.automationFilter,
+            status: 'queued',
+            terminal: false,
+            engineRoot: request.engineRoot,
+            projectPath: request.projectPath,
+            projectDir,
+            target: request.target,
+            reportOutputDir,
+            command: {
+                executable: invocation.executable,
+                args: invocation.args,
+            },
+            diagnostics: [],
+            timeoutMs,
+            nullRhi,
+            artifacts: [],
+            artifactMap: new Map(),
+        };
+        this.runs.set(runId, run);
+        const stdoutStream = createWriteStream(stdoutPath, { encoding: 'utf8' });
+        const stderrStream = createWriteStream(stderrPath, { encoding: 'utf8' });
+        const child = this.spawnProcess(invocation.executable, invocation.args, {
+            cwd: projectDir,
+            env: this.env,
+            shell: false,
+            windowsVerbatimArguments: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        run.status = 'running';
+        run.startedAt = started.toISOString();
+        child.stdout?.on('data', (chunk) => {
+            stdoutStream.write(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderrStream.write(chunk);
+        });
+        const finalize = async (status, exitCode, diagnostic) => {
+            if (run.terminal) {
+                return;
+            }
+            run.status = status;
+            run.exitCode = exitCode;
+            run.completedAt = this.now().toISOString();
+            run.durationMs = new Date(run.completedAt).getTime() - started.getTime();
+            run.success = status !== 'failed' && status !== 'timed_out' && status !== 'cancelled';
+            if (diagnostic) {
+                run.diagnostics.push(diagnostic);
+            }
+            await Promise.all([
+                new Promise((resolveClose) => stdoutStream.end(resolveClose)),
+                new Promise((resolveClose) => stderrStream.end(resolveClose)),
+            ]);
+            this.registerArtifact(run, 'stdout', stdoutPath, 'text/plain');
+            this.registerArtifact(run, 'stderr', stderrPath, 'text/plain');
+            const reportFiles = await this.collectReportArtifacts(runId, reportOutputDir);
+            for (const artifact of reportFiles) {
+                this.registerArtifact(run, artifact.name, artifact.path, artifact.mimeType, artifact.relativePath);
+            }
+            const summary = await this.buildRunSummary(run, reportOutputDir);
+            run.summary = summary;
+            await writeFile(summaryPath, JSON.stringify({
+                runId,
+                automationFilter: run.automationFilter,
+                status: run.status,
+                exitCode: run.exitCode,
+                durationMs: run.durationMs,
+                diagnostics: run.diagnostics,
+                reportOutputDir: run.reportOutputDir,
+                summary,
+            }, null, 2), 'utf8');
+            this.registerArtifact(run, 'summary', summaryPath, 'application/json');
+            run.terminal = true;
+        };
+        const timeoutHandle = setTimeout(() => {
+            if (!run.terminal) {
+                child.kill('SIGTERM');
+            }
+        }, timeoutMs);
+        child.on('error', async (error) => {
+            clearTimeout(timeoutHandle);
+            await finalize('failed', 1, error.message);
+        });
+        child.on('close', async (code, signal) => {
+            clearTimeout(timeoutHandle);
+            const status = signal === 'SIGTERM' && !run.terminal
+                ? 'timed_out'
+                : (code ?? 1) === 0
+                    ? 'succeeded'
+                    : 'failed';
+            const diagnostic = signal === 'SIGTERM' && status === 'timed_out'
+                ? `Automation run exceeded timeout of ${timeoutMs}ms`
+                : undefined;
+            await finalize(status, code ?? 1, diagnostic);
+        });
+        return this.cloneRun(run, 'run_automation_tests');
+    }
+    async getAutomationTestRun(runId) {
+        const run = this.runs.get(runId);
+        return run ? this.cloneRun(run, 'get_automation_test_run') : null;
+    }
+    async listAutomationTestRuns(includeCompleted = true) {
+        const runs = Array.from(this.runs.values())
+            .filter((run) => includeCompleted || !run.terminal)
+            .sort((left, right) => {
+            const leftTime = left.startedAt ? Date.parse(left.startedAt) : 0;
+            const rightTime = right.startedAt ? Date.parse(right.startedAt) : 0;
+            return rightTime - leftTime;
+        })
+            .map((run) => this.cloneRun(run, 'get_automation_test_run'));
+        return {
+            success: true,
+            operation: 'list_automation_test_runs',
+            includeCompleted,
+            runCount: runs.length,
+            runs,
+        };
+    }
+    async readAutomationArtifact(runId, artifactName) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            return null;
+        }
+        const artifact = run.artifactMap.get(artifactName);
+        if (!artifact) {
+            return null;
+        }
+        const data = await readFile(artifact.path);
+        return {
+            artifact,
+            data,
+        };
+    }
+    cloneRun(run, operation) {
+        return {
+            ...run,
+            operation,
+            artifacts: [...run.artifacts],
+        };
+    }
+    registerArtifact(run, name, filePath, mimeType, relativePath) {
+        const existing = run.artifactMap.get(name);
+        const artifact = {
+            name,
+            path: filePath,
+            mimeType,
+            relativePath,
+            resourceUri: buildResourceUri(run.runId, name),
+        };
+        if (existing) {
+            const index = run.artifacts.findIndex((candidate) => candidate.name === name);
+            if (index >= 0) {
+                run.artifacts[index] = artifact;
+            }
+        }
+        else {
+            run.artifacts.push(artifact);
+        }
+        run.artifactMap.set(name, artifact);
+    }
+    async collectReportArtifacts(runId, reportOutputDir) {
+        try {
+            const files = await collectFilesRecursive(reportOutputDir);
+            return files.map((filePath) => {
+                const rel = relative(reportOutputDir, filePath).replaceAll('\\', '/');
+                const lowerRel = rel.toLowerCase();
+                const name = lowerRel === 'index.json'
+                    ? 'report'
+                    : lowerRel === 'index.html'
+                        ? 'report_html'
+                        : `report__${sanitizeSegment(rel.replaceAll('/', '__'))}`;
+                return {
+                    name,
+                    path: filePath,
+                    mimeType: inferMimeType(filePath),
+                    relativePath: rel,
+                    resourceUri: buildResourceUri(runId, name),
+                };
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    async buildRunSummary(run, reportOutputDir) {
+        const reportArtifact = run.artifactMap.get('report');
+        if (!reportArtifact) {
+            return {
+                successful: run.status === 'succeeded',
+                reportAvailable: false,
+            };
+        }
+        const parsed = await tryReadJson(reportArtifact.path);
+        if (!parsed) {
+            return {
+                successful: run.status === 'succeeded',
+                reportAvailable: true,
+            };
+        }
+        return buildSummaryFromReport(parsed, run.status === 'succeeded');
+    }
+}

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { UEClient } from './ue-client.js';
 import { type ProjectControllerLike } from './project-controller.js';
+import { type AutomationControllerLike } from './automation-controller.js';
 export type UEClientLike = Pick<UEClient, 'callSubsystem'> & Partial<Pick<UEClient, 'checkConnection'>>;
 type ToolExample = {
     title: string;
@@ -22,5 +23,5 @@ type PromptCatalogEntry = {
 };
 export declare const exampleCatalog: Record<string, ExampleFamily>;
 export declare const promptCatalog: Record<string, PromptCatalogEntry>;
-export declare function createBlueprintExtractorServer(client?: UEClientLike, projectController?: ProjectControllerLike): McpServer;
+export declare function createBlueprintExtractorServer(client?: UEClientLike, projectController?: ProjectControllerLike, automationController?: AutomationControllerLike): McpServer;
 export {};