@perfonext/build-mcp 0.2.0 → 0.4.0

package/dist/tools/how-to-collect-stats.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+const NEXT_CONFIG_WEBPACK_SNIPPET = `// next.config.ts — write .next/stats.json only when ANALYZE=true
+import type { NextConfig } from "next";
+import { StatsWriterPlugin } from "webpack-stats-plugin";
+
+const nextConfig: NextConfig = {
+  webpack(config) {
+    if (process.env.ANALYZE === "true") {
+      config.plugins.push(
+        new StatsWriterPlugin({
+          filename: "stats.json", // -> .next/stats.json
+          // ids + large modulesSpace are required: without them webpack drops
+          // chunk ids and collapses the module list, yielding empty attribution.
+          stats: {
+            all: false,
+            modules: true,
+            chunks: true,
+            chunkModules: true,
+            reasons: true,
+            ids: true,
+            nestedModules: true,
+            modulesSpace: Infinity,
+            chunkModulesSpace: Infinity,
+          },
+        }),
+      );
+    }
+    return config;
+  },
+};
+
+export default nextConfig;`;
+function buildManualResponse(scenario) {
+    if (scenario === 'turbopack') {
+        return turbopackResponse();
+    }
+    return {
+        method: 'manual',
+        steps: [
+            {
+                step: 1,
+                title: 'Add the dev dependency',
+                command: 'npm install --save-dev webpack-stats-plugin',
+            },
+            {
+                step: 2,
+                title: 'Emit stats behind an ANALYZE flag in next.config',
+                snippet: NEXT_CONFIG_WEBPACK_SNIPPET,
+            },
+            {
+                step: 3,
+                title: 'Build with the flag set',
+                command: 'ANALYZE=true next build',
+            },
+        ],
+        producesFile: '.next/stats.json',
+        nextStep: 'Once .next/stats.json exists, call load_webpack_stats with the same buildDir and the buildId from load_build_stats.',
+    };
+}
+function buildAutomaticResponse(scenario) {
+    if (scenario === 'turbopack') {
+        return turbopackResponse();
+    }
+    return {
+        method: 'automatic',
+        actions: [
+            {
+                action: 'add-dev-dependency',
+                run: 'npm install --save-dev webpack-stats-plugin',
+            },
+            {
+                action: 'edit-next-config',
+                description: 'Add a webpack hook gated behind ANALYZE=true that writes .next/stats.json.',
+                snippet: NEXT_CONFIG_WEBPACK_SNIPPET,
+            },
+            {
+                action: 'add-package-script',
+                script: { analyze: 'ANALYZE=true next build' },
+            },
+            {
+                action: 'run-build',
+                run: 'npm run analyze',
+            },
+            {
+                action: 'verify-output',
+                description: 'Confirm .next/stats.json exists before loading it.',
+            },
+        ],
+        producesFile: '.next/stats.json',
+        nextStep: 'After .next/stats.json exists, call load_webpack_stats with the same buildDir and the buildId from load_build_stats.',
+    };
+}
+function turbopackResponse() {
+    return {
+        method: 'unavailable',
+        scenario: 'turbopack',
+        summary: 'Turbopack has no webpack module graph, so .next/stats.json cannot be produced and trace_import cannot run.',
+        guidance: 'Run a one-off webpack build (omit --turbopack) with the stats hook to use trace_import, or stay on the manifest-only tools.',
+        manifestOnlyTools: [
+            'load_build_stats',
+            'get_largest_routes',
+            'get_shared_chunks',
+            'compare_builds',
+            'explain_growth',
+        ],
+        nextStep: 'Rebuild with webpack to produce .next/stats.json, or continue with get_largest_routes / get_shared_chunks on the build you already loaded.',
+    };
+}
+export function registerHowToCollectStats(server) {
+    server.registerTool('how_to_collect_stats', {
+        title: 'How To Collect Webpack Stats',
+        description: 'Explain how to generate the webpack stats file (.next/stats.json) required by the bundle attribution ' +
+            'tools. Choose manual (a recipe you apply yourself) or automatic (an action plan Copilot executes).',
+        inputSchema: {
+            method: z
+                .enum(['manual', 'automatic'])
+                .describe('manual: return a recipe to apply yourself. automatic: return an action plan for Copilot to execute.'),
+            scenario: z
+                .enum(['webpack', 'turbopack'])
+                .optional()
+                .describe('Collection context. Defaults to webpack. Use turbopack if the app builds with --turbopack.'),
+        },
+    }, async ({ method, scenario }) => {
+        const resolvedScenario = scenario ?? 'webpack';
+        const resolvedMethod = method;
+        const payload = resolvedMethod === 'manual'
+            ? buildManualResponse(resolvedScenario)
+            : buildAutomaticResponse(resolvedScenario);
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(payload, null, 2),
+                }],
+        };
+    });
+}
+//# sourceMappingURL=how-to-collect-stats.js.map

package/dist/tools/how-to-collect-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"how-to-collect-stats.js","sourceRoot":"","sources":["../../src/tools/how-to-collect-stats.ts"],"names":[],"mappings":"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"}

package/dist/tools/load-webpack-stats.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerLoadWebpackStats(server: McpServer): void;
+//# sourceMappingURL=load-webpack-stats.d.ts.map

package/dist/tools/load-webpack-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-webpack-stats.d.ts","sourceRoot":"","sources":["../../src/tools/load-webpack-stats.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAOpE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAiDhE"}

package/dist/tools/load-webpack-stats.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { parseWebpackStats } from '../parser/webpack-stats.js';
+import { getBuildStats, storeWebpackStats } from '../store.js';
+import { statsTextResult } from './webpack-shared.js';
+export function registerLoadWebpackStats(server) {
+    server.registerTool('load_webpack_stats', {
+        title: 'Load Webpack Stats',
+        description: 'Parse the webpack module stats file (.next/stats.json) and link it to a build loaded with ' +
+            'load_build_stats. Unlocks the stats-powered tools: suggest_optimizations (enriched), ' +
+            'find_duplicates, explain_shared_chunks, and trace_import.',
+        inputSchema: {
+            buildId: z.string().describe('Build ID returned by load_build_stats; the stats.json is read from that build directory'),
+        },
+    }, async ({ buildId }) => {
+        const build = getBuildStats(buildId);
+        if (!build) {
+            throw new Error(`Build "${buildId}" not found. Call load_build_stats first and pass the buildId it returns.`);
+        }
+        const stats = await parseWebpackStats(build.buildDir, buildId);
+        if (!stats) {
+            return statsTextResult({
+                buildId,
+                webpackStatsLoaded: false,
+                message: `No stats.json found in ${build.buildDir}. A stock next build does not emit one.`,
+                nextStep: 'Call how_to_collect_stats to generate .next/stats.json, then load_webpack_stats again.',
+            });
+        }
+        storeWebpackStats(stats);
+        const looksCollapsed = stats.parsedModuleCount === 0 || stats.chunks.length === 0;
+        return statsTextResult({
+            buildId,
+            webpackStatsLoaded: true,
+            statsPath: stats.statsPath,
+            moduleCount: stats.moduleCount,
+            parsedModuleCount: stats.parsedModuleCount,
+            chunkCount: stats.chunks.length,
+            ...(looksCollapsed
+                ? {
+                    warning: 'The stats file parsed but contains no usable modules/chunks. This usually means the stats ' +
+                        'config collapsed the module graph (webpack groups modules once `modulesSpace` is exceeded and ' +
+                        'omits chunk ids unless `ids: true`). Re-run how_to_collect_stats for the corrected config and rebuild.',
+                }
+                : {}),
+            nextStep: looksCollapsed
+                ? 'Call how_to_collect_stats again, apply the corrected stats config, rebuild, then load_webpack_stats.'
+                : 'Now call suggest_optimizations for ranked, evidence-backed fixes (now enriched with this stats data). ' +
+                    'Drill in with find_duplicates, explain_shared_chunks, or trace_import on a specific package.',
+        });
+    });
+}
+//# sourceMappingURL=load-webpack-stats.js.map

package/dist/tools/load-webpack-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-webpack-stats.js","sourceRoot":"","sources":["../../src/tools/load-webpack-stats.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,UAAU,wBAAwB,CAAC,MAAiB;IACxD,MAAM,CAAC,YAAY,CAAC,oBAAoB,EAAE;QACxC,KAAK,EAAE,oBAAoB;QAC3B,WAAW,EACT,4FAA4F;YAC5F,uFAAuF;YACvF,2DAA2D;QAC7D,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,yFAAyF,CAAC;SACxH;KACF,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,2EAA2E,CAAC,CAAC;QAChH,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,eAAe,CAAC;gBACrB,OAAO;gBACP,kBAAkB,EAAE,KAAK;gBACzB,OAAO,EAAE,0BAA0B,KAAK,CAAC,QAAQ,yCAAyC;gBAC1F,QAAQ,EAAE,wFAAwF;aACnG,CAAC,CAAC;QACL,CAAC;QAED,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACzB,MAAM,cAAc,GAAG,KAAK,CAAC,iBAAiB,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;QAClF,OAAO,eAAe,CAAC;YACrB,OAAO;YACP,kBAAkB,EAAE,IAAI;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;YAC1C,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;YAC/B,GAAG,CAAC,cAAc;gBAChB,CAAC,CAAC;oBACE,OAAO,EACL,4FAA4F;wBAC5F,gGAAgG;wBAChG,wGAAwG;iBAC3G;gBACH,CAAC,CAAC,EAAE,CAAC;YACP,QAAQ,EAAE,cAAc;gBACtB,CAAC,CAAC,sGAAsG;gBACxG,CAAC,CAAC,wGAAwG;oBACxG,8FAA8F;SACnG,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/suggest-optimizations.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSuggestOptimizations(server: McpServer): void;
+//# sourceMappingURL=suggest-optimizations.d.ts.map

package/dist/tools/suggest-optimizations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-optimizations.d.ts","sourceRoot":"","sources":["../../src/tools/suggest-optimizations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQpE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA0CpE"}

package/dist/tools/suggest-optimizations.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { formatBytes } from '../format.js';
+import { suggestOptimizations } from '../parser/analysis.js';
+import { getBuildStats, getWebpackStats } from '../store.js';
+import { statsTextResult } from './webpack-shared.js';
+export function registerSuggestOptimizations(server) {
+    server.registerTool('suggest_optimizations', {
+        title: 'Suggest Optimizations',
+        description: 'Aggregate route, chunk, and (when loaded) webpack-stats evidence into severity-ranked, ' +
+            'evidence-backed bundle optimizations tied to concrete Next.js actions. Works on manifests alone; ' +
+            'load_webpack_stats first for dedupe, shared-chunk, and package-import suggestions.',
+        inputSchema: {
+            buildId: z.string().describe('Build ID returned by load_build_stats'),
+            limit: z.number().int().positive().max(50).optional().describe('Maximum suggestions to return. Defaults to 15.'),
+        },
+    }, async ({ buildId, limit }) => {
+        const build = getBuildStats(buildId);
+        if (!build) {
+            throw new Error(`Build "${buildId}" not found. Call load_build_stats first.`);
+        }
+        const stats = getWebpackStats(buildId) ?? null;
+        const report = suggestOptimizations(build, stats, limit ?? 15);
+        return statsTextResult({
+            buildId,
+            webpackStatsUsed: report.webpackStatsUsed,
+            suggestionCount: report.suggestionCount,
+            suggestions: report.suggestions.map(suggestion => ({
+                kind: suggestion.kind,
+                severity: suggestion.severity,
+                title: suggestion.title,
+                bytes: suggestion.bytes,
+                bytesText: formatBytes(suggestion.bytes),
+                evidence: suggestion.evidence,
+                recommendedAction: suggestion.recommendedAction,
+                packageName: suggestion.packageName,
+                chunkPath: suggestion.chunkPath,
+                routePath: suggestion.routePath,
+            })),
+            ...(report.note ? { note: report.note } : {}),
+            nextStep: report.webpackStatsUsed
+                ? 'Use trace_import on a flagged package to see its import chain, or find_duplicates / explain_shared_chunks for more detail.'
+                : 'Run how_to_collect_stats then load_webpack_stats to unlock dedupe, shared-chunk, and package-import suggestions.',
+        });
+    });
+}
+//# sourceMappingURL=suggest-optimizations.js.map

package/dist/tools/suggest-optimizations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest-optimizations.js","sourceRoot":"","sources":["../../src/tools/suggest-optimizations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,MAAM,UAAU,4BAA4B,CAAC,MAAiB;IAC5D,MAAM,CAAC,YAAY,CAAC,uBAAuB,EAAE;QAC3C,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EACT,yFAAyF;YACzF,mGAAmG;YACnG,oFAAoF;QACtF,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;YACrE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;SACjH;KACF,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,2CAA2C,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;QAC/C,MAAM,MAAM,GAAG,oBAAoB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAE/D,OAAO,eAAe,CAAC;YACrB,OAAO;YACP,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;gBACjD,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,KAAK,EAAE,UAAU,CAAC,KAAK;gBACvB,SAAS,EAAE,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC;gBACxC,QAAQ,EAAE,UAAU,CAAC,QAAQ;gBAC7B,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;gBAC/C,WAAW,EAAE,UAAU,CAAC,WAAW;gBACnC,SAAS,EAAE,UAAU,CAAC,SAAS;gBAC/B,SAAS,EAAE,UAAU,CAAC,SAAS;aAChC,CAAC,CAAC;YACH,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,QAAQ,EAAE,MAAM,CAAC,gBAAgB;gBAC/B,CAAC,CAAC,4HAA4H;gBAC9H,CAAC,CAAC,kHAAkH;SACvH,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/trace-import.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTraceImport(server: McpServer): void;
+//# sourceMappingURL=trace-import.d.ts.map

package/dist/tools/trace-import.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-import.d.ts","sourceRoot":"","sources":["../../src/tools/trace-import.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAQpE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAqC3D"}

package/dist/tools/trace-import.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { formatBytes } from '../format.js';
+import { traceImport } from '../parser/webpack-stats.js';
+import { getBuildStats } from '../store.js';
+import { resolveWebpackStats, statsTextResult } from './webpack-shared.js';
+export function registerTraceImport(server) {
+    server.registerTool('trace_import', {
+        title: 'Trace Import',
+        description: 'Explain why a module is bundled by tracing its import chain from an entry point to the module. ' +
+            'Requires load_webpack_stats first.',
+        inputSchema: {
+            buildId: z.string().describe('Build ID returned by load_build_stats'),
+            moduleName: z.string().describe('Module or package name to search for (case-insensitive substring), e.g. "lodash"'),
+            limit: z.number().int().positive().max(25).optional().describe('Maximum matching modules to trace. Defaults to 10.'),
+        },
+    }, async ({ buildId, moduleName, limit }) => {
+        const build = getBuildStats(buildId);
+        if (!build) {
+            throw new Error(`Build "${buildId}" not found. Call load_build_stats first.`);
+        }
+        const resolved = resolveWebpackStats(buildId);
+        if ('breadcrumb' in resolved) {
+            return statsTextResult(resolved.breadcrumb);
+        }
+        const result = traceImport(resolved.stats, moduleName, limit ?? 10);
+        return statsTextResult({
+            buildId,
+            query: result.query,
+            matchCount: result.matchCount,
+            traces: result.traces.map(trace => ({
+                moduleName: trace.moduleName,
+                packageName: trace.packageName,
+                sizeBytes: trace.sizeBytes,
+                sizeBytesText: formatBytes(trace.sizeBytes),
+                chunkFiles: trace.chunkFiles,
+                importChain: trace.importChain,
+            })),
+        });
+    });
+}
+//# sourceMappingURL=trace-import.js.map

package/dist/tools/trace-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-import.js","sourceRoot":"","sources":["../../src/tools/trace-import.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3E,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,YAAY,CAAC,cAAc,EAAE;QAClC,KAAK,EAAE,cAAc;QACrB,WAAW,EACT,iGAAiG;YACjG,oCAAoC;QACtC,WAAW,EAAE;YACX,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;YACrE,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,kFAAkF,CAAC;YACnH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;SACrH;KACF,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,UAAU,OAAO,2CAA2C,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,QAAQ,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,YAAY,IAAI,QAAQ,EAAE,CAAC;YAC7B,OAAO,eAAe,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QAC9C,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACpE,OAAO,eAAe,CAAC;YACrB,OAAO;YACP,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClC,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,aAAa,EAAE,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC;gBAC3C,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tools/webpack-shared.d.ts

@@ -0,0 +1,21 @@
+import type { ParsedWebpackStats } from '../parser/types.js';
+/**
+ * Resolve loaded webpack stats for a build, or a machine-readable breadcrumb when they are absent.
+ * The attribution tools degrade gracefully: a missing stats file is guidance, not an error.
+ */
+export declare function resolveWebpackStats(buildId: string): {
+    stats: ParsedWebpackStats;
+} | {
+    breadcrumb: Record<string, unknown>;
+};
+export declare function statsTextResult(payload: Record<string, unknown>): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function withBytesText(bytes: number): {
+    sizeBytes: number;
+    sizeBytesText: string;
+};
+//# sourceMappingURL=webpack-shared.d.ts.map

package/dist/tools/webpack-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webpack-shared.d.ts","sourceRoot":"","sources":["../../src/tools/webpack-shared.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,GACd;IAAE,KAAK,EAAE,kBAAkB,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAiBzE;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;EAO/D;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAEzF"}

package/dist/tools/webpack-shared.js

@@ -0,0 +1,33 @@
+import { formatBytes } from '../format.js';
+import { getWebpackStats } from '../store.js';
+/**
+ * Resolve loaded webpack stats for a build, or a machine-readable breadcrumb when they are absent.
+ * The attribution tools degrade gracefully: a missing stats file is guidance, not an error.
+ */
+export function resolveWebpackStats(buildId) {
+    const stats = getWebpackStats(buildId);
+    if (stats) {
+        return { stats };
+    }
+    return {
+        breadcrumb: {
+            buildId,
+            webpackStatsLoaded: false,
+            message: 'Webpack module stats are not loaded for this build, so import-level attribution is unavailable.',
+            nextStep: 'Generate .next/stats.json via how_to_collect_stats, then call load_webpack_stats with this buildId. ' +
+                'The manifest-based tools (get_largest_routes, get_shared_chunks, compare_builds, explain_growth) work without it.',
+        },
+    };
+}
+export function statsTextResult(payload) {
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(payload, null, 2),
+            }],
+    };
+}
+export function withBytesText(bytes) {
+    return { sizeBytes: bytes, sizeBytesText: formatBytes(bytes) };
+}
+//# sourceMappingURL=webpack-shared.js.map

package/dist/tools/webpack-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webpack-shared.js","sourceRoot":"","sources":["../../src/tools/webpack-shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe;IAEf,MAAM,KAAK,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACvC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,KAAK,EAAE,CAAC;IACnB,CAAC;IAED,OAAO;QACL,UAAU,EAAE;YACV,OAAO;YACP,kBAAkB,EAAE,KAAK;YACzB,OAAO,EACL,iGAAiG;YACnG,QAAQ,EACN,sGAAsG;gBACtG,mHAAmH;SACtH;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAgC;IAC9D,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;aACvC,CAAC;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perfonext/build-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "MCP server for analyzing Next.js build artifacts, route bundle footprint, and shared chunks",
   "type": "module",
   "main": "dist/index.js",