Perfonext Profiler MCP

// Input
{ "scenario": "next-server" } // or "script"; defaults to "next-server"

// Output
{
  "scenario": "next-server",
  "summary": "Profile a production Next.js server while it handles a single request. ...",
  "command": "node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start",
  "steps": [ "...", "load_profile({ filePath: \"./.perf-profiles/<file>.cpuprofile\" })" ],
  "outputDir": "./.perf-profiles",
  "nextStep": "After stopping the server, call load_profile with the .cpuprofile ..."
}

next-server は、単一のリクエストを処理する本番環境の Next.js サーバーをプロファイルします。next start でスタンドアロン出力がサポートされていないと表示された場合は、.next/standalone/server.js を指定して script シナリオを使用してください。script は、そのスタンドアロンサーバー（または別の Node エントリ）をプロファイルします。シナリオは単一のルートと単一のアクセスにしてください。Node はプロセス／ワーカースレッドごとに 1 つの .cpuprofile を出力ディレクトリに書き込みます。Next サーバーのコマンドでは NODE_OPTIONS ではなく Node CLI フラグを使用するため、Unix と Windows で同じように動作します。

read_source_context の詳細

// Input
{ "profileId": "<id>", "functionName": "myFn", "contextLines": 10 }

// Output (per line)
{
  "lineNumber": 42,
  "content": "  for (let i = 0; i < items.length; i++) {",
  "ticks": 18,      // V8 samples that landed on this line
  "isHot": true     // true when ticks >= 50% of peak ticks for this function
}

返される範囲は、宣言の周囲の固定範囲ではなく、関数の実際のホットラインをカバーするように設定されます。関数の実際のボトルネックは、多くの場合、その function 行よりもかなり先にあります。 contextLines（デフォルトは 10）は、宣言とホットラインの両方の周囲に設ける最小の余白を指定します。返される範囲の外にティックが残っている場合、トップレベルの結果に hiddenTicks（件数）と、より大きな contextLines で再試行するよう促す warning が含まれます。 explain_function でも、includeSource: true を指定して呼び出す場合は contextLines を受け付けます。

読み取り可能なのは、現在の作業ディレクトリ内のファイルのみです。file:// URL と絶対パスの両方を処理します。http://、node: の組み込みモジュール、およびプロジェクトルート外のパスは拒否されます。

suggest_optimizations の詳細

// Input
{ "profileId": "<id>", "limit": 5 }

// Output (per function)
{
  "function": "processData",
  "file": "file:///app/src/processor.js",
  "line": 10,
  "selfPercent": "18.2%",
  "patterns": [
    {
      "pattern": "high-fan-in",
      "detail": "Called from 6 distinct call sites (e.g. renderRow, buildTree, …)",
      "suggestion": "This function is a shared hot path. Ensure it is well-optimised and monomorphic …"
    },
    {
      "pattern": "hot-caller",
      "detail": "84% of calls come from \"renderRow\"",
      "suggestion": "Focus optimisation effort on \"renderRow\" rather than this function …"
    }
  ],
  "topSuggestion": "This function is a shared hot path …"
}

検出されるパターン（同じ関数に複数のパターンが当てはまる場合があります）：

複数の呼び出し箇所に現れる関数は、順位付けの前に自動的に統合されるため、同じ論理関数が重複して報告されることはありません。

get_package_costs の詳細

// Input
{ "profileId": "<id>", "limit": 10 }

// Output (per package)
{
  "rank": 1,
  "package": "lodash",
  "selfTime": "42.3ms",
  "selfPercent": "14.1%",
  "totalTimeIncludingCallbacks": "58.0ms",
  "totalPercentIncludingCallbacks": "19.3%",
  "topFunctions": [
    { "function": "chunk", "file": "lodash/chunk.js", "line": 41, "selfTime": "28.0ms", "selfPercent": "9.3%" }
  ]
}

selfTime は、パッケージ自身のコード内で費やされた時間です。totalTimeIncludingCallbacks は、そのパッケージが呼び出したすべての処理もカウントします。そこには、パッケージに渡された独自のコールバックも含まれるため、パッケージを削除した場合に実際に削減できる時間を超えることがあります。

スコープ付きパッケージ（@babel/core、@next/env など）も正しく処理されます。ユーザーコードとネイティブの組み込みモジュール（パスに node_modules が含まれないもの）は除外されます。

CPU プロファイルの生成

すぐに実行できる手順を用意するには、Copilot に how_to_collect を呼び出すよう依頼するか、手動で作成してください：

Next.js の本番サーバー（単一のリクエストをプロファイル）：

node --cpu-prof --cpu-prof-dir=./.perf-profiles ./node_modules/next/dist/bin/next start
# hit the route once, then stop the process so it can exit and write the profile

next start でスタンドアロン出力がサポートされていないと表示された場合：

node --cpu-prof --cpu-prof-dir=./.perf-profiles .next/standalone/server.js

Chrome DevTools：

1. DevTools を開き、Performance タブに移動します。
2. 調査したいシナリオを記録します。
3. 記録を停止し、結果を .cpuprofile エクスポートとして保存します。