Heap MCP Nb
HeapDump .hprof file analysis MCP server using NetBeans Profiler as a backend library
Ask AI about Heap MCP Nb
Powered by Claude Β· Grounded in docs
I know everything about Heap MCP Nb. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Java Heap Dump MCP Server
A Model Context Protocol (MCP) server for analyzing Java heap dump files (.hprof). This project provides a set of tools that allow AI assistants to analyze Java heap dumps through a standardized MCP interface. Based on NetBeans Profiler library as a backend.
Features
- Load Heap Dumps - Parse and load .hprof heap dump files
- Query Classes - Get classes sorted by instance count/size, search by name, or use regex patterns with pagination
- Analyze Instances - Find biggest objects by retained size, get instance details with field values
- References - Get all references to an instance
- GC Root Analysis - View garbage collection roots with pagination
- Heap Summary - Get overview statistics of the heap
- System Properties - Access JVM system properties from the heap dump
- OQL Support - Execute Object Query Language queries on the heap
- Reflection-based Tools - Tools are automatically generated from annotated methods
Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Client (AI) β
βββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββ
β MCP Protocol (JSON-RPC)
βββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββ
β MCP Server β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β HeapDumpTools (MCP Adapter) β β
β βββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ
β
ββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββ
β HeapDumpService (Core) β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β NetBeans Profiler Heap Analysis API β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Available Tools
| Tool | Description |
|---|---|
load_heap | Load a .hprof heap dump file |
get_classes_by_max_instances_count | List classes sorted by instance count (descending) with pagination |
get_classes_by_max_instances_size | List classes sorted by total instance size (descending) with pagination |
get_classes_by_regexp | Search classes using regex with pagination |
get_class_by_name | Get details of a specific class including fields, static fields, and superclass |
get_class_by_id | Get class details by internal ID including fields, static fields, and superclass |
get_instance_by_id | Get instance details including field values and object references |
get_all_references | Get all references to an instance with pagination |
get_biggest_objects | Find largest objects by retained size |
get_gc_roots | View GC root references with pagination (from, to args, defaults 0-50) |
get_gc_roots_paginated | View GC roots with pagination, including kind and instance info |
get_summary | Get heap summary statistics |
get_system_properties | Access JVM system properties |
execute_oql | Execute OQL queries |
analyze_heap_dump | Analyze and return top classes by instance count |
Requirements
- Java 17 or higher
- Maven 3.6+
Installing
- Just download jar from the releases section
Building
mvn clean package
This creates a shaded JAR at target/heap_mcp_nb-1.0-SNAPSHOT-shaded.jar with all dependencies included.
Running
As MCP Server (STDIO)
java -jar target/heap_mcp_nb-0.0.1.jar
The server communicates via STDIO, making it compatible with MCP clients like Claude Desktop or opencode.
Configuration
For opencode
Add to your opencode.json:
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "${workspace}/target/heap_mcp_nb-0.0.1.jar"],
"env": {}
}
}
}
For Claude Desktop
{
"mcpServers": {
"heap-analyzer": {
"command": "java",
"args": ["-jar", "path/to/heap_mcp_nb-0.0.1.jar"],
"env": {}
}
}
}
Running Tests
mvn test
To run specific tests:
mvn test -Dtest=HeapDumpMcpTest
mvn test -Dtest=McpClientIntegrationTest
Usage Examples
In tools like Trae, OpenCode or Qwen CLI you can just point to .hrpof file with your heap dump and ask smth like Find possible problems in this heap dump
Using with MCP Client
// 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);
Tool Response Format
Most tools return results as newline-separated text. For example:
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
Reflection-based Tool Factory
Tools can also be created dynamically using the ToolsFactory class with annotations:
@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
}
See src/main/java/com/onpositive/analyzer/mcp/reflection/ for the annotation definitions.
Dependencies
- io.modelcontextprotocol.sdk:mcp (1.0.0) - MCP Java SDK
- org.netbeans.modules:org-netbeans-lib-profiler (RELEASE200) - Heap analysis
- org.netbeans.modules:org-netbeans-modules-profiler-oql (RELEASE200) - OQL engine
- JUnit 5 - Testing framework
License
MIT License
