Heap Seance

Heap Seance

ヒープに保持されたオブジェクトを呼び起こし、消えようとしないものを問いただします。

jcmd、jmap、jstat、jfr、Eclipse MAT、async-profilerの能力を体系的なリーク調査ワークフローに集約するMCP サーバー＋CLIツールキットです。Claude Code内での実行を想定して設計されています。

2つのスラッシュコマンド。8つのMCPツール。デフォルトでは保守的に動作します。

仕組み • クイックスタート • MCPツール • ワークフロー • 前提条件 • コントリビュート

仕組み

Heap Seanceは2段階のエスカレーションモデルに従います。証拠が求めない限り、詳細なフォレンジック調査は行いません。

 /leak-scan                          /leak-deep
     |                                   |
     v                                   v
  3x class histogram               (all of scan, plus)
  + GC pressure snapshot            JFR recording
     |                              heap dump
     v                              MAT leak suspects
  monotonic growth?                 async-profiler alloc profile
  old-gen pressure?                     |
     |                                  v
     +--- both true? -----> auto-escalate to deep
     |
     +--- otherwise ------> verdict + next steps

確信度は積み上げるものであり、前提とするものではありません。 highには、少なくとも2つの独立した強い兆候が必要です。増加しているクラスが1つだけならwatchです。増加にGC負荷が加わるとsuspiciousです。MATのドミネーターまたはJFRの相関情報を加えると、probable_memory_leakになります。

クイックスタート

uv、Python 3.10以降、およびツール用のJDK 17以降が必要です（対象アプリは任意のJavaバージョンで実行できます）。

1. クローン

git clone https://github.com/your-org/heap-seance.git

2. Javaプロジェクトに.mcp.jsonを追加する

調査対象のプロジェクトで、.mcp.jsonを作成します。

{
  "mcpServers": {
    "heap-seance": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/heap-seance", "python", "-m", "heap_seance_mcp.server"],
      "env": {
        "JAVA_HOME": "/path/to/jdk-17",
        "MAT_BIN": "/path/to/ParseHeapDump.sh",
        "ASYNC_PROFILER_BIN": "/path/to/asprof"
      }
    }
  }
}

--directoryにはHeap Seanceをクローンした場所を指定します。uv runが仮想環境と依存関係を自動的に処理します。ASYNC_PROFILER_BINは任意です。設定されていない場合、ディープモードはJFRとMATを使って続行します。

3. Claude Codeのコマンドをコピーする

.claude/commands/フォルダーをJavaプロジェクトにコピーすると、/leak-scanおよび/leak-deepスラッシュコマンドを使用できます。

cp -r /path/to/heap-seance/.claude/commands/ .claude/commands/

4. 実行

/leak-scan my-service        # conservative scan
/leak-deep 12345             # full forensics by PID

Heap Seanceは対象プロセスを特定して証拠を収集し、構造化された判定結果を返します。

MCPツール

すべてのツールは同じ統一スキーマを返します。

{
  "status": "ok | warn | error",
  "evidence": ["..."],
  "metrics": {},
  "confidence": "none | low | medium | high",
  "next_recommended_action": "...",
  "raw_artifact_path": "..."
}

調査ワークフロー

1. アプリを起動し、初期化が完了するまで待ちます。
2. /leak-scan <name-or-pid> — 最初のヒストグラムスナップショットを取得します。
3. 疑わしい動作を実行します — スキャンでは、3 回のヒストグラムサンプルの間に、リークの疑いがある操作（ビューの開閉、リクエストの送信、ワークフローの繰り返し）を行うよう促されます。これは重要です。サンプル間に負荷をかけないと、リークは検出できません。
4. 判定を確認します。 Confidence、Key Evidence、Suspect Types に注目してください。
5. 増加が検出された場合、または詳細なフォレンジック調査を行いたい場合は、/leak-deep <name-or-pid> を実行します。
6. 修正して再スキャンします。 上限付きキャッシュ、弱参照、リスナーのクリーンアップなどを行い、シグナルが低下したことを確認するため、もう一度 /leak-scan を実行します。
7. 成果物を保管します。 .jfr、.hprof、MAT レポートはチームでのレビュー用に保存されます。

出力内容

/leak-scan の出力：判定、信頼度、主な証拠、疑わしい型、成果物、次のステップ。

/leak-deep では、さらに詳細な情報が得られます：判定、信頼度、ルート保持者の仮説（増加するオブジェクトをどのオブジェクトが、どのフィールド／チェーン経由で保持しているか）、裏付けとなる証拠、成果物、修正の仮説（具体的な修正案）、検証計画。

信頼度の段階

前提条件

ツール用 JDK（必須）：

• jcmd、jmap、jstat には JDK 17 以降が必要です — .mcp.json の JAVA_HOME で設定します
• 対象アプリケーションは、任意の Java バージョン（Java 8 を含む）で実行できます

詳細なフォレンジック調査（/leak-deep 用）：

• Eclipse MAT CLI（ParseHeapDump.sh / .bat）— 詳細モードに必須です
• async-profiler — 同程度の候補を絞り込むための任意ツールです

任意のツール：

• jfr CLI — 利用可能な場合は JFR の要約に使用し、それ以外の場合は jcmd JFR.view にフォールバックします。Java 8 の対象では、JFR は形式に互換性がないため完全にスキップされます。

セットアップを確認します：

./scripts/check_prereqs.sh          # macOS / Linux
scripts\check_prereqs.bat           # Windows

環境変数による上書き

.mcp.json の env ブロック（推奨）またはシェル変数に設定します：

MCP_TRANSPORT の代わりに、CLI フラグ --sse と --streamable-http を使用できます。

設定テンプレートの全体については .mcp.json.example を参照してください。

互換性に関する注意

• Java 8 の対象：ヒストグラム、GC、MAT はすべて完全に動作します。JFR はスキップされます（v0.9 形式は最新ツールと互換性がありません）。
• Windows：MAT は ParseHeapDump.bat 経由で動作します。async-profiler は任意です。見つからない場合も、詳細モードは JFR + MAT を使用して続行します。jstat の出力におけるロケール固有の小数点記号（コンマまたはピリオド）は自動的に処理されます。
• MAT + JAVA_HOME：MAT は JAVA_HOME の JDK で起動するため、システムのデフォルト Java が MAT にとって古すぎる場合でも動作します。

CLI の使用方法（Claude Code なし）

uv run heap-seance --mode scan --match your-app
uv run heap-seance --mode deep --pid 12345 --output json

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

python3 -m venv .venv
source .venv/bin/activate       # Windows: .\.venv\Scripts\Activate.ps1
pip install -e .

heap-seance --mode scan --match your-app

python3 -m unittest discover -s tests -p "test_*.py"

検証用の Java シナリオ例は examples/java-scenarios/ にあります。実際のリーク、上限のあるキャッシュ（リークなし）、バーストアロケーター（リークなし）です。

コントリビューション

コントリビューションを歓迎します！ツール、シグナル、スキルの追加方法については、CONTRIBUTING.md をご覧ください。

ライセンス

このプロジェクトは、以下のいずれかのライセンスのもとでデュアルライセンスされています。

• Apache License, Version 2.0
• MIT License

お好きなライセンスをお選びください。