Pprof Analyzer MCP Server

简体中文 | English

Pprof Analyzer MCP Server

これはGoで実装されたModel Context Protocol（MCP）サーバーで、Goのpprofパフォーマンスプロファイルを分析するツールを提供します。公式のModel Context Protocol Go SDKで構築されています。

機能

• analyze_pprof ツール：
  • 指定された Go pprof ファイルを分析し、シリアライズされた分析結果（Top N リストやフレームグラフ JSON など）を返します。
  • 対応するプロファイルの種類：
    • cpu：コード実行中の CPU 時間の消費を分析し、ホットスポットを特定します。
    • heap：現在のメモリ使用量（ヒープ割り当て）を分析し、メモリ消費量の多いオブジェクトや関数を特定します。オブジェクト数、割り当て箇所、型の情報を追加で提供します。
    • goroutine：現在のすべての goroutine のスタックトレースを表示します。デッドロック、リーク、goroutine の過剰使用の診断に使用します。
    • allocs：プログラム実行中のメモリ割り当て（解放済みのものも含む）を分析し、割り当て頻度の高いコードを特定します。割り当て箇所とオブジェクト数の詳細情報を提供します。
    • mutex：ミューテックスの競合を分析し、ブロッキングの原因となるロックを特定します。競合回数、遅延時間、割合などの詳細な統計情報を提供します。
    • block：goroutine のブロッキングを引き起こす操作（チャネル待機やシステムコールなど）を分析します。平均遅延時間の計算を含む、包括的なブロッキング統計情報を提供します。
  • 対応する出力形式：text、markdown、json（Top N リスト）、flamegraph-json（階層型フレームグラフデータ、デフォルト）。
    • text、markdown：人間が読みやすいテキスト形式または Markdown 形式です。
    • json：Top N の結果を構造化 JSON 形式で出力します（cpu、heap、goroutine、allocs、mutex、block で実装済み）。
    • flamegraph-json：d3-flame-graph と互換性のある階層型フレームグラフデータを JSON 形式で出力します（cpu、heap、allocs で実装済み。デフォルト形式）。出力はコンパクトです。
  • Top N の結果数を設定できます（top_n。デフォルトは 5 で、text、markdown、json 形式で有効です）。
• generate_flamegraph ツール：
  • go tool pprof を使用して、指定された pprof ファイルのフレームグラフ（SVG 形式）を生成し、指定されたパスに保存して、パスと SVG コンテンツを返します。
  • 対応するプロファイルの種類：cpu、heap、allocs、goroutine、mutex、block。
  • 出力する SVG ファイルのパスを指定する必要があります。
  • 重要： この機能を利用するには、Graphviz がインストールされている必要があります。
• open_interactive_pprof ツール（macOS のみ）：
  • 指定された pprof ファイルに対して、go tool pprof のインタラクティブな Web UI をバックグラウンドで起動します。http_address が指定されていない場合は、デフォルトでポート :8081 を使用します。
  • 起動に成功すると、バックグラウンドの pprof プロセスのプロセス ID（PID）を返します。
  • macOS のみ： このツールは macOS でのみ動作します。
  • 依存関係： システムの PATH から go コマンドを利用できる必要があります。
  • 制限事項： バックグラウンドの pprof プロセスで発生したエラーはサーバーによって取得されません。リモート URL からダウンロードした一時ファイルは、プロセスが終了するまで自動的に削除されません（disconnect_pprof_session を手動で呼び出すか、MCP サーバーを終了すると削除されます）。
• detect_memory_leaks ツール：
  • 2 つのヒーププロファイルスナップショットを比較し、メモリリークの可能性を特定します。
  • オブジェクトの型と割り当て箇所ごとにメモリ増加を分析します。
  • 絶対値と変化率を含む、メモリ増加の詳細な統計情報を提供します。
  • 増加のしきい値と結果数を設定できます。
  • 異なる時点で取得したプロファイルを比較することで、メモリリークの特定に役立ちます。
• disconnect_pprof_session ツール：
  • PID を使用して、open_interactive_pprof が以前に起動したバックグラウンドの pprof プロセスの終了を試みます。
  • まず Interrupt シグナルを送信し、失敗した場合は Kill シグナルを送信します。
• compare_profiles ツール：
  • 2 つのプロファイルファイル（ベースラインと対象など）を比較し、パフォーマンスの低下や改善を特定します。
  • すべてのプロファイルの種類（cpu、heap、allocs、mutex、block）に対応しています。
  • 改善・低下した関数、追加・削除された関数など、詳細な差分統計情報を提供します。
  • 視覚的な指標：🔴 低下、🟢 改善、🆕 追加、❌ 削除。
  • テキスト、Markdown、JSON の出力形式に対応しています。
• analyze_heap_time_series ツール：
  • 複数のヒーププロファイルを時系列で分析し、メモリ増加の傾向とリークの可能性を特定します。
  • 時系列順に並べたヒーププロファイルが少なくとも 3 つ必要です。
  • 増加率（バイト数、割合、1 分あたりの MB）を計算します。
  • 方向を示す指標（📈 増加、📉 減少、➡️ 安定）を使って、傾向のあるオブジェクトの型を特定します。
  • 各時点にカスタムラベルを設定するか、デフォルトのラベルを自動生成できます。
  • テキスト、Markdown、JSON の出力形式に対応しています。

インストール（ライブラリ／ツールとして）

go install を使って、このパッケージを直接インストールできます。

go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

これにより、pprof-analyzer-mcp 実行可能ファイルが $GOPATH/bin または $HOME/go/bin ディレクトリにインストールされます。コマンドを直接実行できるよう、このディレクトリがシステムの PATH に含まれていることを確認してください。

ソースからのビルド

Go 環境がインストールされていることを確認してください（Go 1.18 以上を推奨します）。

プロジェクトのルートディレクトリ（pprof-analyzer-mcp）で、次を実行します。

go build

これにより、現在のディレクトリに pprof-analyzer-mcp という名前の実行可能ファイル（Windows では pprof-analyzer-mcp.exe）が生成されます。

go install を使用する（推奨）

go install を使って、実行可能ファイルを $GOPATH/bin または $HOME/go/bin ディレクトリにインストールすることもできます。これにより、（このディレクトリがシステムの PATH 環境変数に追加されていれば）コマンドラインから pprof-analyzer-mcp を直接実行できます。

# Installs the executable using the module path defined in go.mod
go install .
# Or directly using the GitHub path (recommended after publishing)
# go install github.com/ZephyrDeng/pprof-analyzer-mcp@latest

Docker で実行する

Docker を使うと、必要な Graphviz 依存関係が含まれるため、サーバーを手軽に実行できます。

1. Docker イメージをビルドする： Dockerfile があるプロジェクトのルートディレクトリで、次を実行します。

   docker build -t pprof-analyzer-mcp .
   

2. Docker コンテナを実行する：

   docker run -i --rm pprof-analyzer-mcp
   

   • -i フラグは STDIN を開いたままにします。これは、この MCP サーバーで使用される stdio トランスポートに必要です。
   • --rm フラグは、コンテナの終了時にコンテナを自動的に削除します。

3. Docker 用に MCP クライアントを設定する： MCP クライアント（Roo Cline など）を Docker 内で実行されているサーバーに接続するには、.roo/mcp.json を更新します。

   {
     "mcpServers": {
       "pprof-analyzer-docker": {
         "command": "docker run -i --rm pprof-analyzer-mcp"
       }
     }
   }
   

   クライアントがこのコマンドを実行する前に、pprof-analyzer-mcp イメージがローカルでビルドされていることを確認してください。

リリース（GitHub Actions による自動化）

このプロジェクトでは、GoReleaser と GitHub Actions を使用してリリースプロセスを自動化しています。リポジトリに v*（例：v0.1.0、v1.2.3）に一致する Git タグがプッシュされると、リリースが自動的に開始されます。

リリース前のチェックリスト：

リリースタグを作成する前に、次の項目を確認してください。

• ✅ すべてのテストに合格している：go test ./...
• ✅ コードが正常にコンパイルできる：go build
• ✅ ドキュメントが最新である（README、CHANGELOG など）
• ✅ コミットメッセージが Conventional Commits 形式に準拠している

リリース手順：

1. 変更を加える： 新機能を開発するか、バグを修正します。
2. 変更をコミットする： Conventional Commits 形式（例：feat: ...、fix: ...、docs: ...）を使って変更をコミットします。これは変更履歴の自動生成に重要です。

   git add .
   git commit -m "feat: Add awesome new feature"
   # or
   git commit -m "fix: Resolve issue #42"
   # or
   git commit -m "docs: Update README for new feature"
   

3. 変更をプッシュする： コミットを GitHub の main ブランチにプッシュします。

   git push origin main
   

4. リリース前のテストを実行する： 必要に応じて、タグ付けの前にローカルでテストを実行します。

   go test ./... -v
   go build -v
   

5. タグを作成してプッシュする： リリースの準備ができたら、新しい Git タグを作成し、GitHub にプッシュします。

   # Example: Create tag v0.2.0
   git tag v0.2.0
   
   # Push the tag to GitHub
   git push origin v0.2.0
   

6. 自動リリース： タグをプッシュすると、.github/workflows/release.yml で定義された GoReleaser GitHub Action が実行されます。この Action は次の処理を行います。
   • Linux、macOS、Windows（amd64 および arm64）向けのバイナリをビルドします。
   • 前回のタグ以降の Conventional Commits に基づいて変更履歴を生成します。
   • 変更履歴を含む新しい GitHub Release を作成し、ビルドしたバイナリとチェックサムをアセットとして添付します。

リリースの確認：

GitHub リポジトリの「Actions」タブで、リリースワークフローの進行状況を確認できます。完了すると、リリースは次の場所で利用できます。

https://github.com/ZephyrDeng/pprof-analyzer-mcp/releases

MCP クライアントの設定

このサーバーは stdio トランスポートプロトコルを使用します。MCP クライアント（例：VS Code 用の Roo Cline 拡張機能）で設定する必要があります。

通常は、プロジェクトのルートにある .roo/mcp.json ファイルに次の設定を追加します。

{
  "mcpServers": {
    "pprof-analyzer": {
      "command": "pprof-analyzer-mcp"
    }
  }
}

注： ビルド方法（go build または go install）と実行ファイルの実際の場所に応じて、command の値を調整してください。MCP クライアントがこのコマンドを見つけて実行できることを確認してください。

設定後、MCP クライアントを再読み込みするか再起動すると、PprofAnalyzer サーバーに自動的に接続されます。

依存関係

• Graphviz：generate_flamegraph ツールで SVG フレームグラフを生成するには Graphviz が必要です（SVG の生成時に go tool pprof コマンドが dot を呼び出します）。Graphviz がシステムにインストールされ、dot コマンドがシステムの PATH 環境変数から利用できることを確認してください。

  Graphviz のインストール：

  • macOS（Homebrew を使用）：

    brew install graphviz
    

  • Debian/Ubuntu：

    sudo apt-get update && sudo apt-get install graphviz
    

  • CentOS/Fedora：

    sudo yum install graphviz
    # or
    sudo dnf install graphviz
    

  • Windows（Chocolatey を使用）：

    choco install graphviz
    

  • その他のシステム： Graphviz 公式ダウンロードページを参照してください。

使用例（MCP クライアント経由）

サーバーに接続すると、プロファイルファイルに対して file://、http://、または https:// URI を使用して、analyze_pprof および generate_flamegraph ツールを呼び出せます。

例：CPU プロファイルを分析する（テキスト形式、上位 5 件）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
  }
}

例：ヒーププロファイルを分析する（Markdown 形式、上位 10 件）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "top_n": 10,
    "output_format": "markdown"
  }
}

例：Goroutine プロファイルを分析する（テキスト形式、上位 5 件）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/goroutine.pprof",
    "profile_type": "goroutine"
  }
}

例：CPU プロファイルのフレームグラフを生成する

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "output_svg_path": "/path/to/save/cpu_flamegraph.svg"
  }
}

例：ヒーププロファイルのフレームグラフを生成する（inuse_space）

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_svg_path": "/path/to/save/heap_flamegraph.svg"
  }
}

例：CPU プロファイルを分析する（JSON 形式、上位 3 件）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu",
    "top_n": 3,
    "output_format": "json"
  }
}

例：CPU プロファイルを分析する（デフォルトのフレームグラフ JSON 形式）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/cpu.pprof",
    "profile_type": "cpu"
    // output_format defaults to "flamegraph-json"
  }
}

例：ヒーププロファイルを分析する（フレームグラフ JSON 形式を明示的に指定）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "file:///path/to/your/heap.pprof",
    "profile_type": "heap",
    "output_format": "flamegraph-json"
  }
}

例：リモート CPU プロファイルを分析する（HTTP URL から）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://example.com/profiles/cpu.pprof",
    "profile_type": "cpu"
  }
}

例：オンライン CPU プロファイルを分析する（GitHub Raw URL から）

{
  "tool_name": "analyze_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu",
    "profile_type": "cpu",
    "top_n": 5
  }
}

例：オンラインヒーププロファイルのフレームグラフを生成する（GitHub Raw URL から）

{
  "tool_name": "generate_flamegraph",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.heap",
    "profile_type": "heap",
    "output_svg_path": "./online_heap_flamegraph.svg"
  }
}

例：オンライン CPU プロファイルのインタラクティブな Pprof UI を開く（macOS のみ）

{
  "tool_name": "open_interactive_pprof",
  "arguments": {
    "profile_uri": "https://raw.githubusercontent.com/google/pprof/refs/heads/main/profile/testdata/gobench.cpu"
    // Optional: "http_address": ":8082" // Example of overriding the default port
  }
}

例：2 つのヒーププロファイル間のメモリリークを検出する

{
  "tool_name": "detect_memory_leaks",
  "arguments": {
    "old_profile_uri": "file:///path/to/your/heap_before.pprof",
    "new_profile_uri": "file:///path/to/your/heap_after.pprof",
    "threshold": 0.05,  // 5% growth threshold
    "limit": 15         // Show top 15 potential leaks
  }
}

例：Pprof セッションを切断する

{
  "tool_name": "disconnect_pprof_session",
  "arguments": {
    "pid": 12345 // Replace 12345 with the actual PID returned by open_interactive_pprof
  }
}

今後の改善（TODO）

• output_format に基づく、MCP 結果での MIME タイプ処理を追加する。
• より堅牢なエラー処理とログレベルの制御を追加する。
• MCP ツールのエンドツーエンドのやり取りに対する統合テストを追加する。
• 大きなプロファイルファイル（>1GB）向けにパフォーマンスを最適化する。

最近完了した項目（v0.3.0）

• ✅ プロファイル間の変化を可視化する差分フレームグラフを実装する。（完了 — compare_profiles ツール）
• ✅ 複数のスナップショットにわたるメモリの増加を追跡する、メモリプロファイルの時系列分析を追加する。（完了 — analyze_heap_time_series ツール）
• ✅ すべての PR でテストを実行する GitHub Actions による自動 CI/CD を追加する。
• ✅ mutex、block プロファイルの分析ロジックを完全に実装する。（v0.2.0 で完了）
• ✅ mutex、block プロファイルタイプの json 出力形式を実装する。（v0.2.0 で完了）
• ✅ 公式の Model Context Protocol Go SDK に移行する。
• ✅ リモート pprof ファイル URI（例：http://、https://）のサポートを検討する。（v0.2.0 で完了）
• ✅ allocs プロファイルの分析ロジックを完全に実装する。（v0.2.0 で完了）
• ✅ allocs プロファイルタイプの json 出力形式を実装する。（v0.2.0 で完了）
• ✅ メモリリーク検出機能を追加する。（v0.2.0 で完了）