Java堆转储MCP服务器
用于分析Java堆转储文件（.hprof）的模型上下文协议（MCP）服务器。该项目提供了一组工具，允许AI助手通过标准化的MCP接口分析Java堆转储。 基于NetBeans Profiler库作为后端。
特性
- 装载堆转储 -解析并加载.hprof堆转储文件
- 查询类 -获取按实例计数/大小排序的类，按名称搜索，或使用带分页的正则表达式模式
- 分析实例 -按保留大小查找最大对象，使用字段值获取实例详细信息
- 参考文献 -获取对实例的所有引用
- GC根分析 -查看带分页的垃圾收集根目录
- 堆摘要 -获取堆的概览统计信息
- 系统属性 -从堆转储访问JVM系统属性
- OQL支持 -在堆上执行对象查询语言查询
- 基于反射的工具 -工具是由带注释的方法自动生成的
建筑
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (AI) │
└─────────────────────────┬───────────────────────────────────┘
│ MCP Protocol (JSON-RPC)
┌─────────────────────────▼───────────────────────────────────┐
│ MCP Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ HeapDumpTools (MCP Adapter) │ │
│ └─────────────────────────┬─────────────────────────┘ │
└────────────────────────────┼────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ HeapDumpService (Core) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ NetBeans Profiler Heap Analysis API │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘可用工具
| 工具 | 说明 |
|---|---|
load_heap | 加载.hprof堆转储文件 |
get_classes_by_max_instances_count | 按实例计数（降序）排序的列表类，带分页 |
get_classes_by_max_instances_size | 按总实例大小（降序）排序的列表类，带分页 |
get_classes_by_regexp | 使用带分页的正则表达式搜索类 |
get_class_by_name | 获取特定类的详细信息，包括字段、静态字段和超类 |
get_class_by_id | 通过内部ID获取类详细信息，包括字段、静态字段和超类 |
get_instance_by_id | 获取实例详细信息，包括字段值和对象引用 |
get_all_references | 获取对具有分页的实例的所有引用 |
get_biggest_objects | 按保留大小查找最大的对象 |
get_gc_roots | 查看带有分页的GC根引用（from，to args，默认值0-50） |
get_gc_roots_paginated | 查看带有分页的GC根目录，包括种类和实例信息 |
get_summary | 获取堆摘要统计信息 |
get_system_properties | 访问JVM系统属性 |
execute_oql | 执行OQL查询 |
analyze_heap_dump | 按实例计数分析并返回顶级类 |
需求
- Java 17或更高版本
- Maven 3.6+
安装
- 只需从发布部分下载jar
建筑
mvn clean package这将在以下位置创建一个带阴影的JAR target/heap_mcp_nb-1.0-SNAPSHOT-shaded.jar 包括所有依赖项。
跑步
作为MCP服务器（STDIO）
java -jar target/heap_mcp_nb-0.0.1.jar服务器通过STDIO进行通信，使其与Claude Desktop或opencode等MCP客户端兼容。
配置
对于opencode
添加到您的 opencode.json:
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "${workspace}/target/heap_mcp_nb-0.0.1.jar"],
"env": {}
}
}
}适用于克劳德桌面
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "path/to/heap_mcp_nb-0.0.1.jar"],
"env": {}
}
}
}运行测试
mvn test要运行特定测试，请执行以下操作：
mvn test -Dtest=HeapDumpMcpTest
mvn test -Dtest=McpClientIntegrationTest用法示例
在Trae、OpenCode或Qwen CLI等工具中，您只需指向带有堆转储的.hrpof文件，并询问smth like Find possible problems in this heap dump
与MCP客户端一起使用
// Create service and tools
HeapDumpService service = new HeapDumpService();
HeapDumpTools tools = new HeapDumpTools(service);
// Load heap dump
CallToolRequest loadRequest = new CallToolRequest("load_heap", Map.of("file_path", "/path/to/heapdump.hprof"));
tools.loadHeapTool().callHandler().apply(null, loadRequest);
// Get top classes by instance count
CallToolRequest classesRequest = new CallToolRequest("get_classes_by_max_instances_count", Map.of("from", 0, "to", 50));
CallToolResult result = tools.getClassesByMaxInstancesCountTool().callHandler().apply(null, classesRequest);工具响应格式
大多数工具以换行符分隔的文本返回结果。例如：
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基于反射的工具工厂
还可以使用以下工具动态创建工具 ToolsFactory 带注释的类：
@Tool(name = "my_tool", title = "My Tool", description = "Does something")
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.0.0）-MCP Java SDK
- org.netbeans.modules:org netbeans库分析器 （RELEASE200）-堆分析
- org.netbeans.modules:org.netbeans模块分析器oql （RELEASE200）-OQL引擎
- JUnit5 -测试框架
许可证
MIT许可证