jdwp-mcp

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.

Features

• 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

Quick Start

1. Start your Java app with JDWP enabled

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

2. Build the MCP server

cargo build --release

3. Configure Claude Code

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"
    }
  }
}

4. Debug with natural language

> 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

Available Tools

Example: Debugging with kubectl port-forward

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

Architecture

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

Development

Project Structure

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

Testing

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.

Building

# Debug build
cargo build

# Release build
cargo build --release

# Run tests
cargo test

Status

✅ Core Functionality Complete - Ready for MCP integration

Implemented Features

• 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)

Working Examples

• 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

Next Steps

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

References

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

License

MIT