This repository has moved to https://git.navicore.tech/navicore/jdwp-mcp.

The GitHub copy is archived and no longer maintained.

Java debugging for LLMs via JDWP and Model Context Protocol

An MCP server that enables Claude Code and other LLM tools to debug Java applications through the Java Debug Wire Protocol (JDWP). Attach to running JVMs, set breakpoints, inspect variables, and step through code—all through natural language.

• Remote Debugging: Connect to any JVM started with JDWP enabled
• Breakpoint Management: Set, list, and clear breakpoints by class and line
• Stack Inspection: Get summarized stack frames with local variables
• Execution Control: Step over/into/out, continue, pause
• Expression Evaluation: Evaluate Java expressions in frame context
• Thread Management: List and control thread execution
• Smart Summarization: Handles large data structures without overwhelming the LLM

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar myapp.jar

cargo build --release

The easiest way to enable the MCP server for your project:

# From your Java project directory
claude mcp add --scope project jdwp /path/to/jdwp-mcp/target/release/jdwp-mcp

Adjust the path to match where you cloned this repository. The --scope project flag makes the debugger available only in your current Java project.

Alternative: Manual configuration via .mcp.json:

{
  "mcpServers": {
    "jdwp": {
      "command": "/path/to/jdwp-mcp/target/release/jdwp-mcp"
    }
  }
}

> Attach to the JVM at localhost:5005
> Set a breakpoint at com.example.HelloController line 65
> When it hits, show me the stack and the value of requestCount

For Kubernetes-deployed Java apps:

# Forward JDWP port from pod
kubectl port-forward pod/my-app-pod 5005:5005

Then in Claude Code:

> Attach to localhost:5005
> Set a breakpoint in the processRequest method

Claude Code → MCP Server → JDWP Client → TCP Socket → JVM
                ↓
         Summarization &
         Context Filtering

The MCP server handles:

• Protocol Translation: MCP JSON-RPC ↔ JDWP binary protocol
• Smart Summarization: Truncates large objects, limits depth
• State Management: Tracks breakpoints, threads, sessions

jdwp-mcp/
├── jdwp-client/        # JDWP protocol implementation
│   ├── connection.rs   # TCP + handshake
│   ├── protocol.rs     # Packet encoding/decoding
│   ├── commands.rs     # JDWP command constants
│   ├── types.rs        # JDWP type definitions
│   └── events.rs       # Event handling
├── mcp-server/         # MCP server
│   ├── main.rs         # Stdio transport
│   ├── protocol.rs     # MCP JSON-RPC
│   ├── handlers.rs     # Request routing
│   ├── tools.rs        # Tool definitions
│   └── session.rs      # Debug session state
└── examples/           # Usage examples

Use the companion java-example-for-k8s as a test target:

cd ../java-example-for-k8s
mvn clean package
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 \
  -jar target/probe-demo-0.0.1-SNAPSHOT.jar

Then test MCP tools against this running app.

# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

✅ Core Functionality Complete - Ready for MCP integration

• Project structure
• JDWP protocol (handshake, packets, encoding/decoding)
• MCP server skeleton with 13 debug tools
• VirtualMachine commands (Version, IDSizes, AllThreads, Suspend/Resume)
• ClassesBySignature (find classes by name)
• ReferenceType.Methods (get method info)
• Method.LineTable (map source lines to bytecode)
• Method.VariableTable (get variable metadata)
• EventRequest.Set (breakpoints with location modifiers)
• ThreadReference.Frames (get call stacks)
• StackFrame.GetValues (read variable values)
• Value formatting and display
• Architecture independence (big-endian protocol, works on Intel & ARM M1/M2/M3)

• test_connection - Basic JDWP handshake
• test_vm_commands - Query JVM version and ID sizes
• test_find_class - Find classes and methods with line tables
• test_breakpoint - Set breakpoints at specific source lines
• test_manual_stack - Suspend and inspect thread stacks with variables

• Event loop for async breakpoint notifications
• Stepping commands (step over/into/out)
• Expression evaluation
• String and object dereferencing
• Full MCP server integration

• JDWP Specification
• Model Context Protocol
• Claude Code MCP Documentation

MIT