使用说明
Java堆转储MCP服务器
用于分析Java堆转储文件（.hprof）的模型上下文协议（MCP）服务器。提供工具，允许AI助手通过NetBeans Profiler库支持的标准化MCP接口分析Java堆转储。
特性
- 装载堆转储 -解析并加载.hprof堆转储文件
- 阶级分析 -浏览按实例数/大小排序的类，按确切名称、正则表达式或BM25全文排名搜索
- 实例分析 -使用字段值获取实例详细信息，按类对实例进行分页，计算保留大小（单独的工具来隔离昂贵的计算）
- 参考文献 -获取对具有分页的实例的所有引用
- GC根分析 -查看带分页的垃圾收集根目录
- 堆摘要和属性 -从堆转储中获取概述统计信息和JVM系统属性
- OQL支持 -在堆上执行对象查询语言查询
- 基于反射的工具注册 -工具由自动生成
@Tool-带注释的方法
建筑
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (AI) │
└─────────────────────────┬───────────────────────────────────┘
│ MCP Protocol (JSON-RPC)
┌─────────────────────────▼───────────────────────────────────┐
│ MCP Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ HeapDumpTools (MCP Adapter) │ │
│ └─────────────────────────┬─────────────────────────┘ │
└────────────────────────────┼────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ HeapDumpService (Core) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ NetBeans Profiler Heap Analysis API │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
可用工具
| 工具 | 说明 |
|---|---|
load_heap |
加载.hprof堆转储文件并返回其摘要 |
get_summary |
获取堆摘要统计信息 |
get_classes_by_max_instances_count |
按实例计数降序排列的列表类（分页，默认为0-50） |
get_classes_by_max_instances_size |
按实例总大小降序排列的列表类（分页，默认为0-50） |
get_class_by_name |
通过完全限定名（字段、静态字段、超类）获取类详细信息 |
get_class_by_id |
通过内部类ID获取类详细信息 |
get_classes_by_regexp |
搜索与正则表达式匹配的类（分页） |
search_classes |
全文搜索类使用BM25对名称、字段、超类进行排名；拆分CamelCase/snake_case，过滤停用词 |
get_instances |
按类名分页类的实例（默认每页10个） |
get_instance_by_id |
获取实例详细信息，包括字段值和对象引用 |
get_instance_retained_size |
按ID计算实例的保留大小（与 get_instance_by_id 因为保留大小计算成本高昂并且可能失败） |
get_biggest_objects |
按保留大小查找最大的对象 |
get_all_references |
获取对具有分页的实例的所有引用 |
get_gc_roots |
查看带分页的GC根引用（默认值0-50） |
get_gc_roots_paginated |
查看带有分页的GC根目录，包括种类和实例信息 |
get_system_properties |
访问堆转储中捕获的JVM系统属性 |
execute_oql |
执行OQL查询（例如。， select s.value from java.lang.String s) |
analyze_heap_dump |
一步：加载堆转储并按实例计数返回顶级类 |
需求
- Java 17或更高版本
- Maven 3.6+
安装
从下载JAR 发布页面.
建筑
mvn clean package
这将在以下位置创建一个带阴影的JAR target/heap_mcp_nb-0.0.3.jar 包括所有依赖项。
跑步
作为MCP服务器（STDIO）
java -jar target/heap_mcp_nb-0.0.3.jar
服务器通过STDIO进行通信，与任何MCP客户端兼容。
配置
对于opencode
添加到您的 opencode.json:
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "${workspace}/target/heap_mcp_nb-0.0.3.jar"],
"env": {}
}
}
}
适用于克劳德桌面
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "path/to/heap_mcp_nb-0.0.3.jar"],
"env": {}
}
}
}
运行测试
mvn test
要运行特定测试，请执行以下操作：
mvn test -Dtest=HeapDumpMcpTest
mvn test -Dtest=McpClientIntegrationTest
使用示例
在Trae、opencode或Qwen CLI等工具中，您可以指向.hprof文件并询问例如“在此堆转储中查找可能的问题”。
典型工作流程
1. load_heap(file_path="dump.hprof") → Load the dump
2. get_summary() → Overview statistics
3. get_classes_by_max_instances_count() → Top classes by count
4. get_class_by_name(name="com.example.MyLeakyClass") → Inspect a suspicious class
5. get_instances(class_name="com.example.MyLeakyClass", from=0, to=5) → Browse instances
6. get_instance_by_id(id=12345) → Full details of a specific instance
7. get_instance_retained_size(id=12345) → Compute retained size (costly, separate call)
8. get_all_references(id=12345) → Find what holds this instance
工具响应格式
大多数工具以换行符分隔的文本返回结果。例如：
get_class_by_name:
Name: java.util.HashMap
Instances: 152
Total Size: 24320
Superclass: java.util.AbstractMap
Static Fields:
int DEFAULT_INITIAL_CAPACITY = 16
float loadFactor = 0.75 (Instance ID: 123456789)
Fields:
java.util.HashMap$Node[] table
int size
int threshold
float loadFactor
基于反射的工具工厂
工具是通过中方法的注释定义的 HeapDumpTools 并由以下人员自动注册 ToolsFactory:
@Tool(name = "my_tool", title = "My Tool", decription = "Does something")
@Printer(impl = MyPrinter.class)
public String myToolMethod(
@Required("param1") String param1,
@Default(name = "param2", value = "50") int param2) {
// implementation
}
看 src/main/java/com/onpositive/analyzer/mcp/reflection/ 用于注释定义。
依赖项
- io.modelcontextprotocol.sdk:mcp （1.1.2）-MCP Java SDK
- org.netbeans.modules:org netbeans库分析器 （RELEASE200）-堆分析
- org.netbeans.modules:org.netbeans模块分析器oql （RELEASE200）-OQL引擎
- org.openjdk.纳什：纳什核心 （15.4）-OQL的JavaScript引擎
- JUnit5 -测试框架
许可证
MIT许可证
