blueprint-extractor-mcp 1.2.0 → 1.4.0

package/dist/compactor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compacts Blueprint extraction JSON by stripping low-value fields and minifying.
+ * Reduces size by ~50-70% for LLM consumption.
+ */
+/**
+ * Compacts a parsed Blueprint extraction result.
+ * - Removes positional data (posX, posY), GUIDs, empty fields
+ * - Replaces nodeGuid with sequential short IDs (n0, n1, ...)
+ * - Rewrites connection references to use short IDs
+ * - Replaces exec pin type objects with the string "exec"
+ */
+export declare function compactBlueprint(data: unknown): unknown;

package/dist/compactor.js

@@ -0,0 +1,100 @@
+/**
+ * Compacts Blueprint extraction JSON by stripping low-value fields and minifying.
+ * Reduces size by ~50-70% for LLM consumption.
+ */
+/**
+ * Compacts a parsed Blueprint extraction result.
+ * - Removes positional data (posX, posY), GUIDs, empty fields
+ * - Replaces nodeGuid with sequential short IDs (n0, n1, ...)
+ * - Rewrites connection references to use short IDs
+ * - Replaces exec pin type objects with the string "exec"
+ */
+export function compactBlueprint(data) {
+    if (!data || typeof data !== 'object')
+        return data;
+    const root = data;
+    const bp = root.blueprint;
+    if (!bp)
+        return data;
+    const functions = bp.functions;
+    if (!Array.isArray(functions))
+        return data;
+    for (const graph of functions) {
+        compactGraph(graph);
+    }
+    return data;
+}
+function compactGraph(graph) {
+    // Remove graphGuid at graph level
+    delete graph.graphGuid;
+    const nodes = graph.nodes;
+    if (!Array.isArray(nodes))
+        return;
+    // Build guidToShortId map
+    const guidToShortId = new Map();
+    for (let i = 0; i < nodes.length; i++) {
+        const guid = nodes[i].nodeGuid;
+        if (guid) {
+            guidToShortId.set(guid, `n${i}`);
+        }
+    }
+    // Process each node
+    for (let i = 0; i < nodes.length; i++) {
+        const node = nodes[i];
+        // Replace nodeGuid with short ID
+        delete node.nodeGuid;
+        node.id = `n${i}`;
+        // Remove positional data
+        delete node.posX;
+        delete node.posY;
+        // Remove empty nodeComment
+        if (node.nodeComment === '') {
+            delete node.nodeComment;
+        }
+        // Process pins
+        const pins = node.pins;
+        if (Array.isArray(pins)) {
+            for (const pin of pins) {
+                compactPin(pin, guidToShortId);
+            }
+        }
+    }
+}
+function compactPin(pin, guidToShortId) {
+    // Remove pinId
+    delete pin.pinId;
+    // Remove autogeneratedDefaultValue
+    delete pin.autogeneratedDefaultValue;
+    // Remove empty defaultValue
+    if (pin.defaultValue === '') {
+        delete pin.defaultValue;
+    }
+    // Process type object
+    const type = pin.type;
+    if (type && typeof type === 'object') {
+        // Remove empty sub_category
+        if (type.sub_category === '') {
+            delete type.sub_category;
+        }
+        // Replace exec pin type with string "exec"
+        if (type.category === 'exec') {
+            pin.type = 'exec';
+        }
+    }
+    // Rewrite connection nodeGuid references to short IDs
+    const connections = pin.connections;
+    if (Array.isArray(connections)) {
+        if (connections.length === 0) {
+            // Remove empty connections arrays
+            delete pin.connections;
+        }
+        else {
+            for (const conn of connections) {
+                const connGuid = conn.nodeGuid;
+                if (connGuid && guidToShortId.has(connGuid)) {
+                    conn.nodeGuid = guidToShortId.get(connGuid);
+                }
+            }
+        }
+    }
+}

package/dist/index.js

@@ -3,10 +3,11 @@ 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';
+import { compactBlueprint } from './compactor.js';
 const client = new UEClient();
 const server = new McpServer({
     name: 'blueprint-extractor',
-    version: '1.2.0',
+    version: '1.4.0',
 });
 // Shared scope enum with detailed descriptions
 const scopeEnum = z.enum([
@@ -40,6 +41,9 @@ server.resource('extraction-scopes', 'blueprint://scopes', {
                 '',
                 'Start with the narrowest scope that answers your question.',
                 'Full scope on complex Blueprints can exceed 200KB and will be truncated.',
+                '',
+                'Note: Scopes only apply to Blueprint extraction (extract_blueprint and extract_cascade).',
+                'DataAsset, DataTable, and StateTree always extract fully — no scope parameter is needed.',
             ].join('\n'),
         }],
 }));
@@ -59,11 +63,15 @@ USAGE GUIDELINES:
   * FullWithBytecode — + raw bytecode hex dump (largest, rarely needed)
 - Only escalate to Full when you need to understand graph logic (node connections, pin values, execution flow).
 - Full scope on complex Blueprints can exceed 200KB and will be truncated. If truncated, use a narrower scope or inspect specific functions via the graph names from FunctionsShallow.
+- Use FunctionsShallow scope first to get graph names, then request specific graphs with graph_filter to reduce output size.
+- Use compact=true to reduce JSON size by ~50-70% for LLM consumption.
 
 RETURNS: JSON object with the extracted Blueprint data at the requested scope level.`,
     inputSchema: {
         asset_path: z.string().describe('UE content path to the Blueprint asset. Must start with /Game/ (e.g. /Game/Blueprints/BP_Character). Use search_assets to find paths.'),
         scope: scopeEnum.default('Variables').describe('Extraction depth. Start with ClassLevel or Variables — only use Full when you need graph/node details.'),
+        graph_filter: z.array(z.string()).optional().describe('Filter to specific graphs by name. Use FunctionsShallow scope first to discover graph names, then pass the names you want here. Empty/omitted = extract all graphs. Example: ["EventGraph", "CalculateDamage"]'),
+        compact: z.boolean().default(false).describe('When true, strips low-value fields and minifies JSON to reduce size by ~50-70%. Removes: pinId, posX/posY, graphGuid, autogeneratedDefaultValue, nodeComment (when empty), empty connections, empty default_value, empty sub_category. Replaces full exec pin type objects with the string "exec".'),
     },
     annotations: {
         title: 'Extract Blueprint',
@@ -72,14 +80,21 @@ RETURNS: JSON object with the extracted Blueprint data at the requested scope le
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ asset_path, scope }) => {
+}, async ({ asset_path, scope, graph_filter, compact }) => {
     try {
-        const result = await client.callSubsystem('ExtractBlueprint', { AssetPath: asset_path, Scope: scope });
-        const parsed = JSON.parse(result);
+        const result = await client.callSubsystem('ExtractBlueprint', {
+            AssetPath: asset_path,
+            Scope: scope,
+            GraphFilter: graph_filter ? graph_filter.join(',') : '',
+        });
+        let 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 (compact) {
+            parsed = compactBlueprint(parsed);
+        }
+        const text = compact ? JSON.stringify(parsed) : 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 (ClassLevel, Variables, or FunctionsShallow).\n\n${text.substring(0, 200_000)}...\n[TRUNCATED]` }] };
         }
@@ -123,10 +138,82 @@ RETURNS: JSON object with schema, state hierarchy, tasks, conditions, transition
         return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
     }
 });
-// Tool 3: extract_cascade
+// Tool 3: extract_dataasset
+server.registerTool('extract_dataasset', {
+    title: 'Extract DataAsset',
+    description: `Extract a UE5 DataAsset to structured JSON. Serializes all user-defined UPROPERTY fields using UE reflection.
+
+USAGE GUIDELINES:
+- Use search_assets first with class_filter "DataAsset" or a specific DataAsset subclass name to find the asset path.
+- Returns all user-defined properties with their types and current values.
+- Works with any UDataAsset or UPrimaryDataAsset subclass.
+
+RETURNS: JSON object with the DataAsset's class info and all property values.`,
+    inputSchema: {
+        asset_path: z.string().describe('UE content path to the DataAsset (e.g. /Game/Data/DA_ItemDatabase). Use search_assets to find paths.'),
+    },
+    annotations: {
+        title: 'Extract DataAsset',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ asset_path }) => {
+    try {
+        const result = await client.callSubsystem('ExtractDataAsset', { 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 4: extract_datatable
+server.registerTool('extract_datatable', {
+    title: 'Extract DataTable',
+    description: `Extract a UE5 DataTable asset to structured JSON. Includes the row struct schema and all row data.
+
+USAGE GUIDELINES:
+- Use search_assets first with class_filter "DataTable" to find the asset path.
+- Returns the row struct type, property schema, row count, and all row data with names and values.
+- Useful for understanding game data tables (items, abilities, stats, etc.).
+
+RETURNS: JSON object with row struct info, schema, and all rows.`,
+    inputSchema: {
+        asset_path: z.string().describe('UE content path to the DataTable (e.g. /Game/Data/DT_WeaponStats). Use search_assets to find paths.'),
+    },
+    annotations: {
+        title: 'Extract DataTable',
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ asset_path }) => {
+    try {
+        const result = await client.callSubsystem('ExtractDataTable', { AssetPath: asset_path });
+        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 — large DataTable.\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 5: extract_cascade
 server.registerTool('extract_cascade', {
     title: 'Extract Cascade',
-    description: `Extract multiple Blueprint/StateTree assets with automatic reference following. Follows parent classes, interfaces, component classes, and other Blueprint references up to max_depth levels deep.
+    description: `Extract multiple assets (Blueprint, AnimBlueprint, StateTree, DataAsset, DataTable) with automatic reference following for Blueprints and StateTrees. Follows parent classes, interfaces, component classes, and other Blueprint references up to max_depth levels deep.
 
 USAGE GUIDELINES:
 - Use when you need to understand an asset AND its dependencies (parent Blueprints, referenced Blueprints, etc.).
@@ -139,6 +226,8 @@ RETURNS: Summary with extracted_count and output_directory path. Read the output
         asset_paths: z.array(z.string()).describe('Array of UE content paths to extract (e.g. ["/Game/Blueprints/BP_Character", "/Game/Blueprints/BP_Weapon"])'),
         scope: scopeEnum.default('Full').describe('Extraction depth applied to all assets. Full is the default since cascade is typically used for deep analysis.'),
         max_depth: z.number().int().min(0).max(10).default(3).describe('How many levels deep to follow references (0 = only the listed assets, 3 = default)'),
+        graph_filter: z.array(z.string()).optional().describe('Filter to specific graphs by name. Use FunctionsShallow scope first to discover graph names, then pass the names you want here. Empty/omitted = extract all graphs. Example: ["EventGraph", "CalculateDamage"]'),
+        compact: z.boolean().default(false).describe('When true, strips low-value fields and minifies JSON to reduce size by ~50-70%. Removes: pinId, posX/posY, graphGuid, autogeneratedDefaultValue, nodeComment (when empty), empty connections, empty default_value, empty sub_category. Replaces full exec pin type objects with the string "exec".'),
     },
     annotations: {
         title: 'Extract Cascade',
@@ -147,12 +236,13 @@ RETURNS: Summary with extracted_count and output_directory path. Read the output
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ asset_paths, scope, max_depth }) => {
+}, async ({ asset_paths, scope, max_depth, graph_filter, compact }) => {
     try {
         const result = await client.callSubsystem('ExtractCascade', {
             AssetPathsJson: JSON.stringify(asset_paths),
             Scope: scope,
             MaxDepth: max_depth,
+            GraphFilter: graph_filter ? graph_filter.join(',') : '',
         });
         const parsed = JSON.parse(result);
         if (parsed.error) {
@@ -164,20 +254,20 @@ RETURNS: Summary with extracted_count and output_directory path. Read the output
         return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
     }
 });
-// Tool 4: search_assets
+// Tool 6: search_assets
 server.registerTool('search_assets', {
     title: 'Search Assets',
-    description: `Search for UE5 assets by name. This is a lightweight lookup — use it FIRST to find correct asset paths before calling extract_blueprint or extract_statetree.
+    description: `Search for UE5 assets by name. This is a lightweight lookup — use it FIRST to find correct asset paths before calling extract_blueprint, extract_statetree, extract_dataasset, or extract_datatable.
 
 USAGE GUIDELINES:
-- Always call this before extract_blueprint/extract_statetree if you don't already have the exact asset path.
+- Always call this before any extract_* tool if you don't already have the exact asset path.
 - Searches asset names (not full paths) — partial matches work (e.g. "Character" finds "BP_Character").
-- Filter by class to narrow results: "Blueprint" (default), "StateTree", "WidgetBlueprint", "DataAsset", or empty string for all.
+- Filter by class to narrow results: "Blueprint" (default), "AnimBlueprint", "StateTree", "DataTable", "WidgetBlueprint", "DataAsset", or empty string for all.
 
 RETURNS: JSON array of objects with path, name, and class for each matching asset.`,
     inputSchema: {
         query: z.string().describe('Search term to match against asset names. Partial matches work (e.g. "Player" finds "BP_PlayerCharacter").'),
-        class_filter: z.string().default('Blueprint').describe('Filter by asset class. Common values: "Blueprint", "WidgetBlueprint", "StateTree", "DataAsset", or "" for all asset types.'),
+        class_filter: z.string().default('Blueprint').describe('Filter by asset class. Common values: "Blueprint", "AnimBlueprint", "WidgetBlueprint", "StateTree", "DataTable", "DataAsset", or "" for all asset types.'),
     },
     annotations: {
         title: 'Search Assets',
@@ -199,7 +289,7 @@ RETURNS: JSON array of objects with path, name, and class for each matching asse
         return { content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
     }
 });
-// Tool 5: list_assets
+// Tool 7: list_assets
 server.registerTool('list_assets', {
     title: 'List Assets',
     description: `List UE5 assets under a package path. Use this to browse directory contents when you don't know asset names. If you know (part of) the asset name, prefer search_assets instead — it's faster and doesn't require knowing the directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blueprint-extractor-mcp",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "MCP server for UE5 BlueprintExtractor plugin",
   "type": "module",
   "main": "dist/index.js",