Perfonext Build MCP

perfonext-build-mcp

Next.js のビルド成果物を分析し、サイズの大きいルート、共有チャンク、バンドルの増加を特定します。

perfonext-build-mcp は、GitHub Copilot、Claude Desktop、Claude Code などの MCP クライアントに、Next.js のパフォーマンス改善に役立つ構造化されたバンドル分析を提供する Model Context Protocol（MCP）サーバーです。.next のビルド成果物を読み込み、ルートサイズのランキング、共有チャンクや重複に関する調査結果、深刻度順の修正案に変換します。生の .next マニフェストを調べる代わりに、エージェントが推論に利用できる根拠を提供します。

クイックスタート

perfonext-build-mcp は標準的な MCP stdio サーバーなので、あらゆる MCP 互換クライアント（VS Code の GitHub Copilot、Claude Desktop、Claude Code、Cursor など）で動作します。npx で直接実行できます。

npx -y @perfonext/build-mcp

または、グローバルにインストールします。

npm install -g @perfonext/build-mcp

インストール後も、実行可能なコマンドは perfonext-build-mcp のままです。

VS Code

サーバーを .vscode/mcp.json（ワークスペースの MCP 設定ファイル）に追加します。

{
  "servers": {
    "perfonext-build": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

VS Code ウィンドウを再読み込みし、MCP: List Servers を実行して起動するか、信頼を確認するプロンプトが表示されたら承認します。

Claude Desktop

サーバーを claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "perfonext-build": {
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

新しいサーバーを読み込むため、Claude Desktop を再起動します。

Claude Code

CLI でサーバーを追加します。

claude mcp add perfonext-build -- npx -y @perfonext/build-mcp

または、.mcp.json に直接追加します。

{
  "mcpServers": {
    "perfonext-build": {
      "command": "npx",
      "args": ["-y", "@perfonext/build-mcp"]
    }
  }
}

その他の MCP クライアント

stdio MCP サーバーに対応しているクライアントであれば、同じコマンドと引数の組み合わせで起動できます。 command: npx、args: ["-y", "@perfonext/build-mcp"] を指定します。MCP サーバーの設定ファイルの場所については、使用しているクライアントのドキュメントを参照してください。

ローカルでビルドしたチェックアウトを使う場合は、上記のいずれかの設定で、command／args を node とリポジトリの dist/index.js を指定するようにします。

その後、アシスタントに「./.next の Next.js ビルドを読み込み、サイズの大きいルートを表示してください」と尋ねます。

トラブルシューティング

macOS の nvm 使用時に発生する spawn npx ENOENT／spawn node ENOENT

spawn npx ENOENT（または spawn node ENOENT）でサーバーの起動に失敗する場合、エディターやアプリが Dock／Finder から起動され、nvm を認識できていない可能性があります。macOS の GUI アプリはシェル設定（.zshrc／.bashrc）を読み込まないため、nvm 経由でインストールした npx／node が PATH に含まれません。これは VS Code、Claude Desktop、その他 macOS 上の GUI MCP クライアントに当てはまります。

MCP 設定に npx の絶対パスと、同じ Node の bin ディレクトリ（dirname $(which npx)）を含む PATH を指定して修正します。

{
  "command": "/Users/YOU/.nvm/versions/node/v<version>/bin/npx",
  "args": ["-y", "@perfonext/build-mcp"],
  "env": {
    "PATH": "/Users/YOU/.nvm/versions/node/v<version>/bin:/usr/bin:/bin"
  }
}

上記の command／args／env フィールドを、クライアントのサーバーエントリーにマージします（例：VS Code では servers の下、Claude Desktop／Code では mcpServers の下）。

機能

• .next ディレクトリから Next.js のビルド成果物を読み込みます
• 出力されたバンドルのサイズを基に、ユーザー向けルートのうちサイズの大きいものを順位付けします
• 複数のルートに影響する、サイズの大きい共有チャンクを特定します
• 2 つのビルドを比較し、どのルートやチャンクがバンドルの増加につながったかを説明します。深刻度順に並べた、根拠に基づく修正案も提示します
• Next.js がファイル名にコンテンツハッシュを付けていても、ビルド間でチャンクを照合します
• オプションの webpack stats ファイルが収集されている場合、指定されたモジュールや npm パッケージがバンドルに含まれる理由を追跡します（インポートチェーンのエントリー → モジュール）
• チャンク間で重複している npm パッケージを見つけ、共有チャンクのサイズを主に占める要因を説明します
• これらをすべて集約し、具体的な Next.js のアクションに結び付いた、深刻度順の根拠に基づく最適化案を提示します
• 読み込んだビルドのスナップショットをメモリ内に保持するため、MCP クライアントは同じビルドを再読み込みせずに調査できます

ツール

ツール	説明
load_build_stats	Next.js の .next ディレクトリを解析し、ビルドスナップショットをメモリに読み込みます
get_largest_routes	出力されたチャンクの合計バイト数に基づいて、ユーザー向けの最も重いルートを順位付けします
get_shared_chunks	共有チャンクをサイズ順に順位付けし、それらに依存するルートを表示します
compare_builds	ベースラインと現在のビルドスナップショットを比較し、増減したルートとチャンクを表示します
explain_growth	2 つのビルド間のバンドル増加を引き起こしたルートとチャンクを深刻度順に順位付けし、根拠に基づく修正案を提示します
how_to_collect_stats	.next/stats.json を生成するための手順（手動）または実行計画（自動）を返します
load_webpack_stats	.next/stats.json を解析して読み込み済みのビルドに関連付けます。trace_import の前に必要です
trace_import	インポートチェーンをエントリまでたどり、モジュールまたは npm パッケージがバンドルされる理由を説明します
find_duplicates	コードが複数のチャンクに出力される npm パッケージを、無駄になったバイト数で順位付けします
explain_shared_chunks	多数のルートで読み込まれる共有チャンクを、どのパッケージとアプリコードが支配しているか表示します
suggest_optimizations	ルート、チャンク、webpack stats の根拠を集約し、深刻度順に根拠に基づく修正案を提示します

出力は機械可読形式を保ち、生のバイト数を含みます。これにより、MCP クライアントはリグレッションを説明し、修正の優先順位を決め、依存関係やインポートレベルでの具体的な追加調査を提案できます。

suggest_optimizations の各検出結果は emittedBytes（実際にディスク上に出力されたチャンクのバイト数）でサイズが示されるため、種類の異なる提案も同じ基準で順位付けできます。最小化されていない webpack モジュールのサイズは、そのように明記された箇所（moduleSizeBytes、shareOfChunkModuleBytes）にのみ表示されます。

Next.js は出力ファイル名にコンテンツハッシュを使用するため（framework-<hash>.js や、ハッシュのみの CSS ファイル名）、compare_builds と explain_growth はハッシュを正規化した識別子でビルド間のチャンクを照合します。これにより、再ハッシュされただけで変更のないチャンクが削除・再作成されたと誤って報告されるのを防ぎながら、本当に新しいチャンクは引き続き検出します。

入力

コアツールは、next build の実行後に開発者がすでに持っているビルド成果物を読み取ります。

• .next/build-manifest.json
• 存在する場合は .next/prerender-manifest.json
• 存在する場合は .next/app-build-manifest.json
• 存在する場合は .next/app-path-routes-manifest.json — App Router のマニフェストキー（/gallery/page）を、prerender マニフェストのキーとなる実際のパス（/gallery）に対応付けます。これにより、ルートの type、isPrerendered、prerenderBlockedReason はパスから推測するのではなく、ビルドから読み取られます
• ビルド所要時間を算出するための、任意のキャプチャ済み next build 出力テキスト

インポートレベルの帰属（trace_import、find_duplicates、explain_shared_chunks）と、suggest_optimizations による stats 強化された提案には、.next/stats.json にある webpack モジュール stats ファイルも必要です。通常の next build ではこのファイルは出力されません。生成手順は how_to_collect_stats が返します。上記のマニフェストツールはこのファイルを読み取らないため、ファイルの有無にかかわらず動作します。

バンドルの詳細な帰属分析（任意）

マニフェストツールはセットアップ不要です。「なぜこのパッケージがバンドルに含まれているのか」を調べるには、まず webpack の stats ファイルを収集します。

1. how_to_collect_stats({ method: 'manual' | 'automatic' }) を呼び出し、返された手順を適用します。この手順では、webpack-stats-plugin と cross-env を追加し、next.config のフックを ANALYZE=true && !isServer の条件下で有効にして、cross-env ANALYZE=true next build --webpack で再ビルドします。Turbopack によるビルドでは .next/stats.json は生成されません。
2. load_build_stats({ buildDir }) を呼び出して buildId を取得します。
3. load_webpack_stats({ buildId }) を呼び出して、生成された .next/stats.json を解析します。
4. trace_import({ buildId, moduleName }) を呼び出して、そのモジュールを取り込んでいるインポートチェーンを確認します。
5. find_duplicates({ buildId }) を呼び出して、複数のチャンクにバンドルされたパッケージを確認し、explain_shared_chunks({ buildId }) を呼び出して、多くのルートで読み込まれるチャンクを占めているものを確認します。
6. suggest_optimizations({ buildId }) を呼び出して、重要度順に並んだ、根拠に基づく推奨事項を取得します。これはマニフェストのみでも機能し、stats の読み込み後には重複排除、共有チャンク、パッケージのインポートに関する分析結果が追加されます。コード分割に関する提案は、Next.js のフレームワークルート（/404、/500、/_error、/_app、/_document）に合わせて調整されます。これらのルートには next/dynamic による分割が適用されないため、インポートを削減して軽量化するように示されます。

アプリを Turbopack でビルドする場合、webpack のモジュールグラフは存在しません。そのため、how_to_collect_stats はその旨を伝え、マニフェストのみを使うツールを案内します。stats ファイルが読み込まれていない場合、分析ツールは状況を示す手がかりを添えて、無理なく機能を縮小します。エラーになることはありません。

プロンプトの例

• 「./.next の Next.js ビルドを読み込んで、最も大きなルートを表示してください。」
• 「このビルドで最も多くのルートに影響している共有チャンクはどれですか？」
• 「ビルドの容量を要約して、最も多くの JavaScript を含むルートを教えてください。」
• 「ベースラインと現在の .next ビルドを比較して、最も大きくなったルートや共有チャンクを表示してください。」
• 「ベースラインから現在の .next ビルドの間に何が大きくなったのかを説明して、最初に修正すべき点を教えてください。」
• 「パッケージがバンドルに含まれる理由を確認できるように、webpack の stats 収集を設定してください。」
• 「なぜ axios がバンドルに含まれているのですか？インポートチェーンを追跡してください。」
• 「複数のチャンクに重複している npm パッケージはどれで、何バイトが無駄になっていますか？」
• 「共有チャンクの容量を最も占めているのは何ですか？」
• 「このビルドで最も効果の高いバンドル最適化を提案してください。」

関連する Perfonext ツール

• perfonext-profiler-mcp — Next.js サーバー向け CPU プロファイリング（V8／Chrome）
• perfonext-render-mcp — Next.js アプリ向け React レンダリング分析

開発

npm install
npm run build
npm test

ローカル検証用のサンプルフィクスチャは tests/fixtures/ にあります。

ライセンス

MIT