jdwp-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

jdwp-mcp is an MCP (Model Context Protocol) server that enables LLMs to debug Java applications via JDWP (Java Debug Wire Protocol). It's a Rust workspace with two crates:

• jdwp-client: Low-level JDWP protocol client library (TCP connection, binary packet encoding/decoding, event loop)
• mcp-server: MCP server binary (jdwp-mcp) that translates MCP JSON-RPC over stdio into JDWP commands

Build Commands

cargo build                # debug build
cargo build --release      # release build (binary at target/release/jdwp-mcp)
cargo test                 # run all tests
cargo test -p jdwp-client  # test just the client crate
cargo test -p jdwp-mcp     # test just the MCP server crate

Architecture

LLM (Claude Code) --[stdio JSON-RPC]--> mcp-server --[JDWP binary over TCP]--> JVM

jdwp-client crate

The client implements JDWP over an async event loop:

• connection.rs — JdwpConnection: TCP connect, JDWP handshake, entry point for sending commands
• eventloop.rs — EventLoopHandle: tokio task that multiplexes outgoing commands and incoming replies/events on one TCP stream. Commands get routed by packet ID; events go to an mpsc channel. Commands can be sent from multiple tasks; events should be consumed by one.
• protocol.rs — CommandPacket/ReplyPacket: binary encoding/decoding (big-endian, architecture-independent)
• commands.rs — JDWP command set/command constants (mirrors the spec)
• types.rs — Value, Location, Variable, type tags
• events.rs — Event parsing (breakpoint, step, thread start/death, VM death)
• vm.rs, thread.rs, method.rs, reftype.rs, stackframe.rs, object.rs, string.rs — Higher-level command wrappers organized by JDWP command set
• reader.rs — Cursor-based reader for JDWP data with variable-width ID fields
• eventrequest.rs — Event request building (breakpoints, stepping)