MCP Java调试工具

Prerequisites

• JDK 17+ (must be a JDK, not a JRE — JDI lives in jdk.jdi)

No separate Maven install is required — the repository ships with the Maven Wrapper (./mvnw), which downloads a pinned Maven 3.9.x into ~/.m2/wrapper/ on first use. The SessionStart hook and every build command in this README use the wrapper.

Dependencies

• Spring Boot 4.0 — Framework
• Spring AI MCP 2.0.0-M4 — MCP protocol integration
• JDI (jdk.jdi module) — Java Debug Interface
• Eclipse JDT Compiler (ECJ) — In-memory expression compilation
• JSpecify + NullAway — Compile-time nullness enforcement

1. Install the plugin

Option A: Plugin marketplace (recommended)

Installs the MCP server, the java-debug skill (debugging workflows, recipes, gotchas), and the .mcp.json configuration in one step:

/plugin marketplace add https://github.com/FgForrest/mcp-jdwp-java.git
/plugin install jdwp-debugging@mcp-jdwp-java

The server JAR is built automatically on first session start via the bundled ./mvnw wrapper (requires JDK 17+ on PATH — no Maven install needed). Restart Claude Code to pick up the plugin.

<details> <summary><strong>Alternative: manual MCP registration (without plugin)</strong></summary>

If you prefer to register the MCP server directly without the plugin (no skill, no auto-build):

1. Build the JAR:

git clone https://github.com/FgForrest/mcp-jdwp-java.git
cd mcp-jdwp-java
./mvnw clean package -DskipTests   # use mvnw.cmd on Windows

2. Register with Claude Code:

claude mcp add jdwp-inspector -s user \
  -e MCP_TIMEOUT=30000 \
  -e MCP_TOOL_TIMEOUT=120000 \
  -- java --add-modules jdk.jdi,jdk.attach -jar /path/to/mcp-jdwp-java.jar

To change the JDWP port (default 5005), add -DJVM_JDWP_PORT=12345 before -jar.

The MCP_TIMEOUT and MCP_TOOL_TIMEOUT environment variables are important — JVM startup is not instant (class loading, Spring context initialization), so the default MCP timeouts will cause Claude Code to give up before the server is ready. MCP_TIMEOUT=30000 gives the server 30 seconds to start, and MCP_TOOL_TIMEOUT=120000 allows up to 2 minutes for long-running tools like first-time expression evaluation (which discovers the target's classpath and compiles bytecode).

Re-installing requires removing first: claude mcp remove jdwp-inspector -s user

Drop -s user to scope to the current project only.

.mcp.json:

{
  "mcpServers": {
    "jdwp-inspector": {
      "command": "java",
      "args": [
        "--add-modules", "jdk.jdi,jdk.attach",
        "-jar", "/path/to/mcp-jdwp-java.jar"
      ],
      "env": {
        "MCP_TIMEOUT": "30000",
        "MCP_TOOL_TIMEOUT": "120000"
      }
    }
  }
}

</details>

Just installed the plugin? Grab the sandbox zip

The fastest path for fresh plugin users is a self-contained zip — no clone, no reactor build:

curl -L -o jdwp-sandbox.zip \
  https://github.com/FgForrest/mcp-jdwp-java/releases/latest/download/jdwp-sandbox.zip
unzip jdwp-sandbox.zip && cd jdwp-sandbox

Inside, you get a parentless Maven project with src/, a pom.xml, a flight-game README.md, and a CLAUDE.md that briefs the agent on the game's house rules. Open the folder in Claude Code and ask it to play flight #1 — the bundled CLAUDE.md keeps it honest (no peeking at source, no spoiler-fetching). Continue with the workflow below.

Quick start

Usage workflows

#4 The Time Traveler's Config

Difficulty: Hard | Test: ConfigurationProviderTest | Package: config

Symptom: expected timeout=5000 but was 0 — the configuration exists but its timeout field is still at the default value.

Hint: The config object is assigned to the shared field before it's fully initialized. A reader thread sees the reference but reads a half-constructed object.

<details> <summary><strong>Reveal root cause</strong></summary>

ConfigurationProvider.getConfig() assigns instance = new Configuration(...) and then signals a latch — but calls instance.init() (which sets timeout=5000) after the latch release. A reader thread waiting on that latch sees instance != null and returns the un-initialized object with timeout=0.

Debug path: Set breakpoints in both the initializer and reader paths of getConfig(). Use jdwp_get_threads() to see both threads, then inspect the Configuration object from each thread's perspective. The initializer hasn't called init() yet when the reader returns.

</details>

---

Tool reference (46 tools)

Core components

Expression evaluation pipeline (`evaluation/`)

1. JdiExpressionEvaluator — Analyzes the stack frame, generates a wrapper class with a UUID name, delegates compilation, caches results.
2. ClasspathDiscoverer — Walks target JVM classloader hierarchy (including Tomcat/container) to find all JARs. Uses JdkDiscoveryService to locate a local JDK matching the target version.
3. InMemoryJavaCompiler — Compiles Java source to bytecode using Eclipse JDT (ECJ), entirely in memory.
4. RemoteCodeExecutor — Injects bytecode via ClassLoader.defineClass() and invokes it.

Troubleshooting