JVMind × MAT — Heapdump 智能分析模块

中文 | English

基于 Eclipse Memory Analyzer (MAT) 内核，为现有 JVMind 平台增加 Java 堆转储（heapdump）分析能力： 上传 → 解析 → 类 MAT 的 Web 查询 → 领域诊断（连接池泄漏等）→ 自然语言 Agent 诊断。

当前状态：Java 侧（解析 + 查询服务）已实测跑通；MCP Server v0.1.1 已发布到 PyPI 与官方 MCP Registry；Python 平台串通待开发。详见 PROJECT-STATUS.md。

🚀 新人 5 分钟入门

1. 想了解项目全貌 → 读本文件 +「mat-study/README.md」（项目蓝图）。

2. 想知道现在做到哪了 → PROJECT-STATUS.md（已完成 / 待办 / 踩坑经验）。

3. 是 Python 团队、要接手开发 → TODO-PYTHON-TEAM.md（任务清单 + 接口契约 + 验收）。

4. 想把查询服务跑起来 → query-service/DEPLOY.md（部署 + curl 验证）。

5. 想跑通解析 → parser-cli/v1-parsehd/README.md（零编译，发行版即可）。

6. 想在 Claude/Cursor/VS Code 里分析堆转储 → mcp-server/README.md（uvx jvmind-mat-mcp，本地 stdio）。

Related MCP server: javaperf

⚡ MCP Server（已发布）

本地 stdio MCP Server，把 MAT 的堆分析能力直接接到 Claude Desktop / Cursor / VS Code。堆转储不出本机，MAT 辅助服务只绑 127.0.0.1。

uvx jvmind-mat-mcp doctor      # 检查 JDK 21 / MAT 1.17 / 权限

能力：open_heapdump → mat_overview / mat_histogram / mat_dominator / mat_threads / mat_object / mat_path2gc / mat_oql / mat_leak_suspects / mat_diagnose_oom 等 17 个工具。

要求：Python 3.10+、JDK 21+、Eclipse MAT 1.17.x（首次使用会自动安装一个小型查询 bundle）。

Tools

所有分析工具都接收 open_heapdump 返回的 report_id。

• open_heapdump — 打开本地 .hprof，后台解析并返回 report_id

• get_heapdump_status — 查询解析状态、进度和阶段

• list_heapdumps — 列出本 MCP 服务已知的堆转储

• close_heapdump — 释放堆转储句柄，可选停止 MAT 辅助进程

• mat_overview — 堆总览：已用/已提交/存活堆、对象/类/类加载器数量、JDK 版本

• mat_histogram — 类直方图，按 shallow / retained / count 排序

• mat_dominator — 支配树，列出 retained 最大的对象并支持按 parent 下钻

• mat_threads — 线程列表，或下钻线程栈帧和 frame locals

• mat_threadlocals — 按 valueClass 或 thread 分组查看 ThreadLocal

• mat_object — 检查单个对象的字段、静态字段、入/出引用和 GC Root

• mat_path2gc — 对象到 GC Root 的最短路径

• mat_oql — 执行 OQL 查询，返回行和可复用的 resultSetId

• mat_leak_suspects — 运行 LeakHunter，返回泄漏嫌疑、retained 大小和描述

• mat_diagnose_oom — 综合 OOM 诊断：泄漏嫌疑 + 线程 SQL + 支配树分析

• mat_connection_pools — 诊断数据库连接池和超时未释放的连接

• mat_top_consumers — 按 retained heap 排序的内存占用 Top

• mat_sql_in_threads — 在线程栈中查找 SQL，定位 OOM 时的慢查询

架构一图

  用户上传 heapdump
        │
   [Python/FastAPI]  ← 待开发(TODO-PYTHON-TEAM.md)
   上传/队列/进度/鉴权/Agent
        ├── fork ─────────────▶ [parser-cli / V1]  hprof → *.index   ✅已实测
        │                              （写 NFS）
        └── 内网反代 ──────────▶ [query-service]    读 index 提供查询  ✅已跑通
                                  (OSGi bundle, :8090)
                                  histogram/支配树/线程树/OQL
                                  + Leak Suspects/path2gc 等
         共享：NFS(dump 文件) + PostgreSQL(任务/报告)

  本机 MCP 路径（v0.1.1 已发布）：
  Claude Desktop / Cursor / VS Code
        │ stdio
        ▼
   [mcp-server] ──HTTP 127.0.0.1──▶ [query-service :8090]
        └── 缺 index 时自动调用 MAT ParseHeapDump（复用 parser-cli V1 逻辑）

目录结构与文档导航

📁 顶层

📁 mat-study/ — 设计文档（从研究到落地）

📁 parser-cli/ — 解析层（hprof → index）

📁 query-service/ — 查询层（OSGi bundle，:8090）✅ 已跑通

📁 mcp-server/ — 本地 stdio MCP（✅ v0.1.1 已发布）

📁 marketplace/ — 市场提交材料（🟡 准备完成，尚未提交）

模块速查

关键事实速记（避免重复踩坑，详见 PROJECT-STATUS.md）

• MAT 依赖不在 Maven Central → 用 Tycho（eclipse-plugin）+ p2/Directory，不写 <dependencies>。

• 版本↔JDK：1.17→JDK21、1.14→JDK17、1.12→JDK11（三处须一致）。

• 部署：jar 放 plugins/ + bundles.info 加一行（auto-start=true）+ -clean 重启（不是 dropins）。

• 查询服务无鉴权，仅内网；由 Python 反代时带 dumpDir（= dump 目录）。

• reopen 需要 hprof + index 都在可随机 seek 的文件系统（NFS 满足）。

• MCP 包名 jvmind-mat-mcp，Registry 名 io.github.kengrary/jvmind-mat；改完 Java 查询层后必须重跑 mcp-server/scripts/vendor-bundle.sh，否则 wheel 里的 bundle 会过期。

• MCP Server 首次使用会把 com.jvmind.mat.query 写入 MAT 的 plugins/ + bundles.info；MAT 安装目录必须可写。

• Smithery 暂跳过（网页端只有远程 URL 入口，CLI 创建接口已移除）；MCPB 材料保留备用。Docker 镜像只用于目录审核，真实分析仍需本机 MAT + JDK 21。

技术栈

• 解析/查询：Java 21 + Eclipse MAT 1.17（OSGi/Equinox）

• MCP Server：Python 3.10+ / MCP Python SDK 2.x / uv / stdio

• 主控/上传/Agent：Python + FastAPI（现有 JVMind 平台）

• 存储：NFS（dump 文件）+ PostgreSQL（任务/报告，双进程共享）

• 分发：PyPI + 官方 MCP Registry；mcp.so/Glama/PulseMCP 材料已准备，Smithery 暂跳过

• 许可证：本项目代码为 MIT（见 LICENSE）；MAT 为 EPL-2.0（复用其 bundle，注意分发声明）