blueprint-extractor-mcp 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { UEClient } from './ue-client.js';
+const client = new UEClient();
+const server = new McpServer({
+    name: 'blueprint-extractor',
+    version: '1.0.0',
+});
+// Tool 1: extract_blueprint
+server.tool('extract_blueprint', 'Extract a UE5 Blueprint asset to JSON. Returns the full Blueprint structure including class info, variables, components, and graph data.', {
+    asset_path: z.string().describe('UE asset path, e.g. /Game/Blueprints/BP_Character'),
+    scope: z.enum(['ClassLevel', 'Variables', 'Components', 'FunctionsShallow', 'Full', 'FullWithBytecode']).default('Full').describe('Extraction depth'),
+}, async ({ asset_path, scope }) => {
+    try {
+        const result = await client.callSubsystem('ExtractBlueprint', { AssetPath: asset_path, Scope: scope });
+        const parsed = JSON.parse(result);
+        if (parsed.error) {
+            return { content: [{ type: 'text', text: `Error: ${parsed.error}` }], isError: true };
+        }
+        const text = JSON.stringify(parsed, null, 2);
+        if (text.length > 200_000) {
+            return { content: [{ type: 'text', text: `Warning: Response is ${(text.length / 1024).toFixed(0)}KB. Consider using a narrower scope.\n\n${text.substring(0, 200_000)}...\n[TRUNCATED]` }] };
+        }
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+});
+// Tool 2: extract_statetree
+server.tool('extract_statetree', 'Extract a UE5 StateTree asset to JSON. Returns the full state hierarchy, tasks, conditions, and transitions.', {
+    asset_path: z.string().describe('UE asset path to a StateTree, e.g. /Game/AI/ST_BotBehavior'),
+}, async ({ asset_path }) => {
+    try {
+        const result = await client.callSubsystem('ExtractStateTree', { AssetPath: asset_path });
+        const parsed = JSON.parse(result);
+        if (parsed.error) {
+            return { content: [{ type: 'text', text: `Error: ${parsed.error}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+});
+// Tool 3: extract_cascade
+server.tool('extract_cascade', 'Extract multiple Blueprint/StateTree assets with cascade reference following. Writes results to files on disk.', {
+    asset_paths: z.array(z.string()).describe('Array of UE asset paths to extract'),
+    scope: z.enum(['ClassLevel', 'Variables', 'Components', 'FunctionsShallow', 'Full', 'FullWithBytecode']).default('Full').describe('Extraction depth'),
+    max_depth: z.number().int().min(0).max(10).default(3).describe('How many levels deep to follow references'),
+}, async ({ asset_paths, scope, max_depth }) => {
+    try {
+        const result = await client.callSubsystem('ExtractCascade', {
+            AssetPathsJson: JSON.stringify(asset_paths),
+            Scope: scope,
+            MaxDepth: max_depth,
+        });
+        const parsed = JSON.parse(result);
+        if (parsed.error) {
+            return { content: [{ type: 'text', text: `Error: ${parsed.error}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: `Extracted ${parsed.extracted_count} assets to ${parsed.output_directory}` }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+});
+// Tool 4: search_assets
+server.tool('search_assets', 'Search for UE5 assets by name. Returns matching asset paths, names, and classes.', {
+    query: z.string().describe('Search query to match against asset names'),
+    class_filter: z.string().default('Blueprint').describe('Filter by asset class (e.g. Blueprint, StateTree, or empty for all)'),
+}, async ({ query, class_filter }) => {
+    try {
+        const result = await client.callSubsystem('SearchAssets', { Query: query, ClassFilter: class_filter });
+        const parsed = JSON.parse(result);
+        if (parsed.error) {
+            return { content: [{ type: 'text', text: `Error: ${parsed.error}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+});
+// Tool 5: list_assets
+server.tool('list_assets', 'List UE5 assets in a directory. Returns asset paths, names, and classes.', {
+    package_path: z.string().describe('UE package path, e.g. /Game/Blueprints'),
+    recursive: z.boolean().default(true).describe('Search subdirectories'),
+    class_filter: z.string().default('').describe('Filter by asset class (empty for all)'),
+}, async ({ package_path, recursive, class_filter }) => {
+    try {
+        const result = await client.callSubsystem('ListAssets', {
+            PackagePath: package_path,
+            bRecursive: recursive,
+            ClassFilter: class_filter,
+        });
+        const parsed = JSON.parse(result);
+        if (parsed.error) {
+            return { content: [{ type: 'text', text: `Error: ${parsed.error}` }], isError: true };
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(parsed, null, 2) }] };
+    }
+    catch (e) {
+        return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error('Fatal:', e);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,15 @@
+export interface RemoteCallRequest {
+    objectPath: string;
+    functionName: string;
+    parameters: Record<string, unknown>;
+    generateTransaction: boolean;
+}
+export interface RemoteCallResponse {
+    ReturnValue?: string;
+    [key: string]: unknown;
+}
+export interface AssetInfo {
+    path: string;
+    name: string;
+    class: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ue-client.d.ts

@@ -0,0 +1,11 @@
+export declare class UEClient {
+    private host;
+    private port;
+    private subsystemPath;
+    constructor();
+    private get baseUrl();
+    checkConnection(): Promise<boolean>;
+    discoverSubsystem(): Promise<string>;
+    private rawCall;
+    callSubsystem(method: string, params: Record<string, unknown>): Promise<string>;
+}

package/dist/ue-client.js

@@ -0,0 +1,98 @@
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 30010;
+const TIMEOUT_MS = 60_000;
+export class UEClient {
+    host;
+    port;
+    subsystemPath = null;
+    constructor() {
+        this.host = process.env.UE_REMOTE_CONTROL_HOST ?? DEFAULT_HOST;
+        this.port = parseInt(process.env.UE_REMOTE_CONTROL_PORT ?? String(DEFAULT_PORT), 10);
+    }
+    get baseUrl() {
+        return `http://${this.host}:${this.port}`;
+    }
+    async checkConnection() {
+        // GET /remote/info — if it responds, UE is running with Remote Control
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5000);
+            const res = await fetch(`${this.baseUrl}/remote/info`, { signal: controller.signal });
+            clearTimeout(timeout);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async discoverSubsystem() {
+        if (this.subsystemPath)
+            return this.subsystemPath;
+        // Use /remote/object/call to find the subsystem via GEditor
+        // EditorSubsystems are singletons accessible via GEditor->GetEditorSubsystem<T>()
+        // The object path for editor subsystems follows the pattern: /Engine/Transient.UnrealEditorSubsystem_0
+        // We try to call a method directly — if it works, the path is valid
+        // For UEditorSubsystem, the default object path is:
+        // /Engine/Transient.BlueprintExtractorSubsystem
+        // But the exact path depends on the engine. Let's try the standard pattern.
+        const candidatePaths = [
+            '/Script/BlueprintExtractor.Default__BlueprintExtractorSubsystem',
+            '/Engine/Transient.BlueprintExtractorSubsystem',
+            '/Engine/Transient.BlueprintExtractorSubsystem_0',
+        ];
+        for (const path of candidatePaths) {
+            try {
+                // Try calling ListAssets as a health check
+                const res = await this.rawCall(path, 'ListAssets', { PackagePath: '/Game', bRecursive: false, ClassFilter: '' });
+                if (res !== null) {
+                    this.subsystemPath = path;
+                    return path;
+                }
+            }
+            catch {
+                // Try next candidate
+            }
+        }
+        throw new Error('BlueprintExtractor subsystem not found. Ensure the plugin is loaded in the editor.');
+    }
+    async rawCall(objectPath, functionName, parameters) {
+        const body = {
+            objectPath,
+            functionName,
+            parameters,
+            generateTransaction: false,
+        };
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        try {
+            const res = await fetch(`${this.baseUrl}/remote/object/call`, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!res.ok)
+                return null;
+            return await res.json();
+        }
+        catch {
+            clearTimeout(timeout);
+            return null;
+        }
+    }
+    async callSubsystem(method, params) {
+        const connected = await this.checkConnection();
+        if (!connected) {
+            throw new Error(`UE Editor not running or Remote Control not available on ${this.host}:${this.port}`);
+        }
+        const objectPath = await this.discoverSubsystem();
+        const res = await this.rawCall(objectPath, method, params);
+        if (res === null) {
+            throw new Error(`Failed to call ${method} on BlueprintExtractorSubsystem`);
+        }
+        // The subsystem methods return FString, which comes back as ReturnValue
+        const returnValue = res.ReturnValue ?? JSON.stringify(res);
+        return typeof returnValue === 'string' ? returnValue : JSON.stringify(returnValue);
+    }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "blueprint-extractor-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for UE5 BlueprintExtractor plugin",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "blueprint-extractor-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "@types/node": "^22.0.0"
+  }
+}