Heap Seance

Heap Seance

Summoning retained objects from the heap — so you can interrogate what refuses to die.

An MCP server + CLI toolkit that channels the spirits of jcmd, jmap, jstat, jfr, Eclipse MAT, and async-profiler into a structured leak investigation workflow — designed to run inside Claude Code.

2 slash commands. 8 MCP tools. Conservative by default.

______________________________________________________________________

How It Works • Quick Start • MCP Tools • Workflow • Prerequisites • Contributing

______________________________________________________________________

运作原理

Heap-Seance遵循两阶段升级模型。除非证据要求，否则没有深入的取证。

 /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 需要至少两个独立的强信号。一个不断壮大的阶级是 watch增长加上GC压力 suspicious.添加MAT支配者或JFR相关性，您将得到 probable_memory_leak.

快速开始

需要 紫外线Python 3.10+，以及用于工具的JDK 17+（目标应用程序可以运行任何Java版本）。

1.克隆

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

2.添加 .mcp.json 到您的Java项目

在要调查的项目中，创建 .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/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 --拍摄第一个直方图快照。
3. 练习可疑行为 --扫描会提示您在3个直方图样本之间执行您怀疑正在泄漏的操作（打开/关闭视图、发送请求、重复工作流）。这一点至关重要——在样品之间没有负载的情况下，泄漏保持不可见。
4. 宣读判决书。 专注于 Confidence, Key Evidence, Suspect Types.
5. /leak-deep 如果扫描标志着增长，或者不管你是否想要完整的取证。
6. 修复并重新扫描。 有界缓存、弱引用、监听器清理——然后 /leak-scan 再次确认信号下降。
7. 保留文物。 .jfr, .hprof，MAT报告将保存以供团队审查。

你得到了什么

/leak-scan 返回：判决、信心、关键证据、嫌疑人类型、人工制品、下一步行动。

/leak-deep 更进一步：判决、置信度、根持有者假说（谁保留了生长的对象以及通过哪个字段/链）、支持证据、伪影、补救假说（具体的修复建议）、验证计划。

信心阶梯

先决条件

工具JDK （必填）：

• JDK 17+for jcmd, jmap, jstat --通过设置 JAVA_HOME 在 .mcp.json
• 目标应用程序可以运行任何Java版本（包括Java 8）

深度取证 （为 /leak-deep):

• Eclipse MAT命令行界面 (ParseHeapDump.sh / .bat)--深度模式需要
• 异步分析器 --可选断领带器

可选工具：

• jfr CLI——用于JFR摘要（如果可用），可追溯到 jcmd JFR.view 否则。对于Java 8目标（不兼容格式），完全跳过JFR。

检查您的设置：

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

环境覆盖

将这些设置在您的 .mcp.json env block（推荐）或作为shell变量：

CLI标志 --sse 和 --streamable-http 可以代替 MCP_TRANSPORT.

看 .mcp.json.example 获取完整的配置模板。

兼容性说明

• Java 8目标：直方图+GC+MAT工作充分。跳过JFR（v0.9格式与现代工具不兼容）。
• 视窗：MAT通过以下方式工作 ParseHeapDump.bat.async分析器是可选的——如果缺少，深度模式将继续使用JFR+MAT。特定于区域设置的十进制分隔符（逗号vs点） jstat 输出是自动处理的。
• MAT+JAVA_HOME：MAT与JDK一起从 JAVA_HOME，因此即使系统默认Java对于MAT来说太旧，它也能工作。

CLI用法（不含Claude代码）

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

Installing uv

# 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"

Manual setup (without uv)

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/ --真正的泄漏、有界缓存（无泄漏）和突发分配器（无泄露）。

贡献

欢迎投稿！看 贡献.md 有关添加工具、信号和技能的指南。

许可证

该项目在以下任一情况下获得双重许可

• Apache许可证，版本2.0
• MIT许可证

由您选择。