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.git2.添加 .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 PIDHeap-Seance解析目标进程，收集证据，并返回结构化判决。
MCP工具
| 工具 | 它做什么 |
|---|---|
java_list_processes() | 通过以下方式发现正在运行的JVM jcmd -l |
java_class_histogram(pid) | 每个类的快照实时对象计数 |
java_gc_snapshot(pid) | 样品 jstat -gcutil 随着时间的推移 |
java_jfr_start(pid) | 捕获JFR录制 |
java_jfr_summary(jfr_file) | 总结JFR事件类型和计数 |
java_heap_dump(pid) | 全堆转储(.hprof) |
java_mat_suspects(heap_dump) | 运行MAT泄漏嫌疑分析 |
java_async_alloc_profile(pid) | 通过异步分析器分配火焰图 |
每个工具都返回相同的统一模式：
{
"status": "ok | warn | error",
"evidence": ["..."],
"metrics": {},
"confidence": "none | low | medium | high",
"next_recommended_action": "...",
"raw_artifact_path": "..."
}调查工作流程
- 启动您的应用程序 并让它完全初始化。
/leak-scan--拍摄第一个直方图快照。- 练习可疑行为 --扫描会提示您在3个直方图样本之间执行您怀疑正在泄漏的操作（打开/关闭视图、发送请求、重复工作流）。这一点至关重要——在样品之间没有负载的情况下，泄漏保持不可见。
- 宣读判决书。 专注于
Confidence,Key Evidence,Suspect Types. /leak-deep如果扫描标志着增长，或者不管你是否想要完整的取证。- 修复并重新扫描。 有界缓存、弱引用、监听器清理——然后
/leak-scan再次确认信号下降。 - 保留文物。
.jfr,.hprof，MAT报告将保存以供团队审查。
你得到了什么
/leak-scan 返回：判决、信心、关键证据、嫌疑人类型、人工制品、下一步行动。
/leak-deep 更进一步：判决、置信度、根持有者假说（谁保留了生长的对象以及通过哪个字段/链）、支持证据、伪影、补救假说（具体的修复建议）、验证计划。
信心阶梯
| 信心 | 这意味着什么 | 需要信号 |
|---|---|---|
none | 无泄漏证据 | -- |
low | 增长缓慢，无GC压力 | 仅直方图 |
medium | 增长+GC正在下降 | 直方图+GC压力 |
high | 可能泄漏，已证实 | 直方图+GC+MAT/JFR |
先决条件
工具JDK （必填）：
- JDK 17+for
jcmd,jmap,jstat--通过设置JAVA_HOME在.mcp.json - 目标应用程序可以运行任何Java版本（包括Java 8）
深度取证 （为 /leak-deep):
- Eclipse MAT命令行界面 (
ParseHeapDump.sh/.bat)--深度模式需要 - 异步分析器 --可选断领带器
可选工具：
jfrCLI——用于JFR摘要（如果可用），可追溯到jcmd JFR.view否则。对于Java 8目标（不兼容格式），完全跳过JFR。
检查您的设置：
./scripts/check_prereqs.sh # macOS / Linux
scripts\check_prereqs.bat # Windows环境覆盖
将这些设置在您的 .mcp.json env block（推荐）或作为shell变量：
| 变量 | 必填 | 描述 |
|---|---|---|
JAVA_HOME | 推荐 | JDK 17+安装路径-- $JAVA_HOME/bin 首先搜索 jcmd, jmap, jstat, jfr。也用于使用正确的Java版本启动MAT。 |
MAT_BIN | 深度模式 | 路径 ParseHeapDump.sh （macOS/Linux）或 .bat （Windows） |
ASYNC_PROFILER_BIN | 可选 | 异步分析器二进制文件的路径——断开证据，深度模式在没有它的情况下工作 |
HEAP_SEANCE_ARTIFACT_DIR | 可选 | 在哪里 .jfr, .hprof，并保存报告（默认：系统临时目录） |
MCP_TRANSPORT | 可选 | 传输协议： stdio （默认）， sse，或 streamable-http |
MCP_HOST | 可选 | SSE/HTTP传输的绑定地址（默认值： 0.0.0.0) |
MCP_PORT | 可选 | SSE/HTTP传输端口（默认值： 8000) |
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 jsonInstalling 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 有关添加工具、信号和技能的指南。
许可证
该项目在以下任一情况下获得双重许可
由您选择。