mcp-jdwp-java: Instructions file for Claude Code

CLAUDE.md

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

Build Commands

# Run from the reactor root. Builds both modules.
# Prefer ./mvnw (the bundled Maven Wrapper) — it pins the Maven version and
# does not require Maven to be installed system-wide. Plain `mvn` works too
# if it is on PATH.
./mvnw compile                                    # Compile only
./mvnw clean package -DskipTests                  # Full build (produces jdwp-mcp-server/target/mcp-jdwp-java.jar)

# Build only the MCP server (skips the sandbox module entirely):
./mvnw -pl jdwp-mcp-server -am clean package -DskipTests

The repository is a 2-module Maven reactor:

• jdwp-mcp-server/ — the real MCP server. Contains all genuine unit tests; ./mvnw -pl jdwp-mcp-server test runs them.
• jdwp-sandbox/ — deliberately broken Java classes used as JDWP debugging targets ("test flights"). Sandbox tests are expected-to-fail by design and are skipped by default so a normal ./mvnw test stays green. Run them explicitly during a test flight with: ./mvnw -pl jdwp-sandbox test -DskipTests=false.

The compiler requires --add-modules jdk.jdi (configured in jdwp-mcp-server/pom.xml). At runtime, the JAR must also be launched with --add-modules jdk.jdi.

Architecture

This is a Spring Boot MCP Server that lets Claude Code inspect and control running Java applications via JDWP (Java Debug Wire Protocol). It connects directly to a target JVM's JDWP port (default 5005).

Claude Code ──MCP/STDIO──> Spring Boot MCP Server ──JDI──> Target JVM (port 5005)

Core Components

• JDWPTools — Exposes 50 MCP tools via @McpTool annotations. This is the main interface: connection, thread/stack/variable inspection, breakpoints, stepping, and watcher evaluation. All tool methods return formatted String responses.
• JDIConnectionService — Singleton holding the persistent VirtualMachine (JDI) connection. Manages object caching (ConcurrentHashMap<Long, ObjectReference>) and smart collection rendering (ArrayList, HashMap, HashSet internals). Also drives classpath discovery for expression evaluation.
• BreakpointTracker — Maintains a registry of breakpoints with synthetic integer IDs (since JDI BreakpointRequest has no user-facing ID). Keeps the last published stop's report for display; which stop is current is SuspensionSession's call.
• JdiEventListener — Daemon thread consuming the JDI event queue; the event sets are processed in order on a jdi-event-dispatcher thread, except a set raised inside an MCP-driven evaluation, which the listener suppresses and releases at once. Handlers only propose stop candidates; SuspensionSession.finish publishes the first one or releases the set. A published stop stays suspended for user inspection.
• SuspensionSession (#45) — One per connection; every routed event set is a context (QUEUED → PROCESSING → HELD | RELEASED) and only its context releases its suspension. Tools release only stops a tool has presented, plus jdwp_suspend_thread holds — never blindly. It also runs steps, the jdwp_reset generation and invocation leases (admission, exemptions, ownership transfer). SuspensionWatchdog frees a dispatcher evaluation stuck on a monitor a queued set's thread holds; InvocationRunner bounds a tool's invocation at 20 s ([STILL_RUNNING], later EVALUATION_COMPLETED_LATE). See docs/event-pipeline.md § 14.