javaperf

javaperf

JDK ユーティリティ（jcmd、jfr、jps）を使用して Java アプリケーションをプロファイリングする MCP（Model Context Protocol）サーバー

AI アシスタントが、手動でコマンドラインを使わずにパフォーマンスの診断、スレッドの分析、JFR 記録の調査を行えるようにします。

📦 インストール: npm install -g javaperf または npx 経由で使用 🌐 npm: https://www.npmjs.com/package/javaperf

Claude Desktop／IDE への接続方法

MCP 設定にサーバーを追加します。claude_desktop_config.json の例：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

Cursor IDE の場合：Settings → Features → Model Context Protocol → Edit Config の順に進み、mcpServers 内に同じブロックを追加します。その他のオプション（ローカル開発、カスタムの JAVA_HOME など）については、統合セクションを参照してください。

要件

• Node.js v18+
• JFR をサポートする JDK 8u262+ または 11+

JDK ツール（jps、jcmd、jfr）は、JAVA_HOME または which java を使って自動検出されます。見つからない場合は、JAVA_HOME に JDK のルートを設定してください。

クイックスタート

ユーザー向け（npm パッケージを使用）

# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below

開発者向け

1. リポジトリをクローンします：

git clone https://github.com/theSharque/mcp-jperf.git
cd mcp-jperf

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

使用方法

開発モード

npm run dev

本番モード

npm start

MCP Inspector

MCP Inspector でデバッグとテストを行います：

npx @modelcontextprotocol/inspector node dist/index.js

統合

Cursor IDE

1. Cursor Settings → Features → Model Context Protocol を開きます
2. 「Edit Config」ボタンをクリックします
3. 以下の設定のいずれかを追加します

オプション 1：npm 経由（推奨）

npm レジストリから自動的にインストールします：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

オプション 2：npm link 経由（開発用）

変更を即座に反映させるローカル開発向けです：

{
  "mcpServers": {
    "javaperf": {
      "command": "javaperf"
    }
  }
}

必要なコマンド：cd /path/to/mcp-jperf && npm link -g

オプション 3：直接パス

{
  "mcpServers": {
    "javaperf": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "${workspaceFolder}",
      "env": {
        "JAVA_HOME": "/path/to/your/jdk"
      }
    }
  }
}

list_java_processes が「jps not found」エラーで失敗する場合、MCP サーバーがシェルの JAVA_HOME を継承していない可能性があります。上記の env ブロックに、JDK のルートパス（例：/usr/lib/jvm/java-17 または ~/.sdkman/candidates/java/current）を追加してください。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

Continue.dev

.continue/config.json を編集します：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

ツール

ツール	説明
list_java_processes	実行中の Java プロセス（pid、mainClass、args）を一覧表示します。topN（デフォルト 10）で件数を制限します。
start_profiling	JFR を開始します。pid、duration（秒）を渡します。オプション：preset（デフォルトの有効値：profile）、settingsFile（.jfc へのパス。preset とは併用できません）、memorysize、stackdepth（デフォルト 128）。
profile_jfr_network	.jfr からソケット I/O（jdk.SocketRead、jdk.SocketWrite）の概要を表示します。オプション：filepath（デフォルト new_profile）、topN。
profile_jfr_file_io	ファイルの読み書き（jdk.FileRead、jdk.FileWrite）の概要を表示します。オプション：filepath、topN。
profile_jfr_locks	モニター競合（JavaMonitorBlocked）と j.u.c のパーキング（ThreadPark）を表示します。オプション：filepath、topN。実行中の待機状態：analyze_threads structured=true。
profile_jfr_native	ネイティブメソッドの CPU ホットスポット（jdk.NativeMethodSample）を表示します。オプション：filepath、topN。
native_memory_summary	jcmd VM.native_memory summary — -XX:NativeMemoryTracking=summary または detail を指定した JVM が必要です。pid を渡します。
gc_class_stats	利用可能な場合に jcmd GC.class_stats を実行します（JDK 21 以降で利用できることが多いです）。pid を渡します。
gc_finalizer_info	jcmd GC.finalizer_info を実行します。pid を渡します。
compiler_codecache	jcmd Compiler.codecache を実行します。pid を渡します。
compiler_queue	jcmd Compiler.queue を実行します。pid を渡します。
list_jfr_recordings	プロセスのアクティブな JFR 記録を一覧表示します。recordingId を取得するため、stop_profiling の前に使用します。
stop_profiling	記録を停止し、recordings/new_profile.jfr に保存します。pid と recordingId が必要です。
check_deadlock	Java レベルのデッドロックを確認します。スレッド、ロック、サイクルを含む構造化 JSON を返します。
analyze_threads	デッドロックの概要付きスレッドダンプ（jstack）を取得します。pid、オプションで topN（デフォルト 10）、structured（JSON 形式のロック待機チェーン）を渡します。実行中のスナップショットです。過去のロックについては profile_jfr_locks を使用します。
heap_histogram	クラスヒストグラム（GC.class_histogram）を取得します。pid、オプションで topN（20）、all（フル GC を実行し、アプリが一時停止する可能性があります）を渡します。静的スナップショットです。増加を調べるには heap_live_histogram_diff を使用します。
heap_live_histogram_diff	intervalSeconds（デフォルト 5）間隔で 2 つのヒストグラムを取得します。インスタンス数またはバイト数の増加が大きいクラスを表示します。メモリーリークのワークフローの最初のステップです。pid、オプションで topN、all、minInstanceDelta を渡します。
heap_dump	MAT/VisualVM 用の .hprof を作成します。heap_live_histogram_diff の後に、MAT の Path to GC Roots を使用します。pid を渡します。recordings/heap_dump.hprof に保存されます。
heap_info	ヒープの概要を表示します。pid を渡します。
vm_info	JVM 情報（稼働時間、バージョン、フラグ）を表示します。pid を渡します。
trace_method	.jfr からメソッドの呼び出しツリーを作成します。className、methodName を渡します。オプション：filepath（デフォルト new_profile）、topN。
parse_jfr_summary	.jfr を解析して、上位メソッド、GC 統計、異常を含む概要を作成します。オプション：filepath（デフォルト new_profile）、events、topN。
profile_memory	メモリープロファイルを取得します。バイト数／回数別の上位アロケーター、割り当てスタック、クラス別の OldObjectSample を表示します。オプション：filepath、topN、sortBy（bytes／count）。gc_efficiency、heap_live_histogram_diff と組み合わせて使用します。
gc_efficiency	.jfr から GC 効率を取得します。コレクターごとの一時停止時間と解放バイト数を表示します。オプション：filepath、topN。stop_profiling の後に使用します。
profile_time	CPU ボトルネックのプロファイル（ボトムアップ）を取得します。オプション：filepath（デフォルト new_profile）、topN。
profile_frequency	呼び出し頻度のプロファイル（リーフフレーム）を取得します。オプション：filepath（デフォルト new_profile）、topN。

ワークフローの例

1. プロセスを一覧表示 → list_java_processes
2. 記録を開始 → pid と duration（例：60）を指定して start_profiling
3. duration 秒待ちます（または、そのまま実行します）
4. 記録を確認（任意）→ list_jfr_recordings で recordingId を取得します
5. 停止して保存 → pid と recordingId を指定して stop_profiling
6. 分析 → parse_jfr_summary、profile_memory、gc_efficiency、profile_time、profile_frequency、trace_method、profile_jfr_network、profile_jfr_file_io、profile_jfr_locks、または profile_jfr_native（記録にイベントが存在する必要があります。適切なプリセット、または settingsFile 経由で .jfc を指定して start_profiling を使用してください）

ワークフローの例：メモリリークの仮説

1. プロセスを一覧表示 → list_java_processes
2. 増加中のクラスを特定 → pid と intervalSeconds: 5 を指定して heap_live_histogram_diff
3. 負荷をかけて記録 → start_profiling → 待機 → stop_profiling
4. 割り当てをプロファイル → new_profile に対して profile_memory を実行します（疑わしいクラスについて oldObjectSamplesByClass を確認します）
5. GC の負荷 → 同じ .jfr に対して gc_efficiency を実行します
6. 保持を確認 → heap_dump → Eclipse MAT → GC ルートへのパス（弱参照／ソフト参照を除外します）
7. AI が統合した結果から一貫性のあるリーク仮説を構築します（専用ツールはありません）

リモート JVM（stdio MCP）

javaperf は stdio MCP を使用し、ローカルの jps／jcmd 経由で JVM にアタッチします。これは、MCP プロセスが実行されている OS アカウントおよびホスト上でのみ機能します。

別のマシン上の JVM を診断するには：

• MCP サーバー（IDE コネクター、Cursor、または Claude Desktop）をそのマシン上で実行します。たとえば、SSH リモートワークスペース、Codespaces、サーバー上の CI ランナーでのチェックアウト、またはプロセスと同じホスト上のシェルセッションを使用します。
• 別のホストからプレーンな SSH 経由で jcmd をパイプする方法には依存しないでください。MCP をそこで実行することを意図的に選択しない限り、ホスト間のアタッチはこのサーバーの対象範囲外です。

制限事項に記載されている要件（同じユーザー、ローカルアタッチ）が引き続き適用されます。

制限事項

• サンプリング：JFR のサンプリング間隔は約 10ms です。実行時間の短いメソッドは ExecutionSample に現れない場合があります
• ローカルのみ：MCP を起動したマシン上で実行されます
• 権限：jcmd でアクセスするには、対象の JVM と同じユーザーとして実行する必要があります