jdwp-mcp

Debuggen Sie laufende JVMs über JDWP – von jedem MCP-kompatiblen Agenten aus.

Verbinden Sie sich mit einem laufenden Java-Prozess, pausieren Sie Threads, untersuchen Sie Stacks und Objekte, setzen Sie Breakpoints und werten Sie den Status aus – alles per natürlicher Sprache. Ein einziger Prompt startet eine agentengesteuerte Diagnose-Schleife mit Live-Laufzeitdaten.

Funktioniert mit Claude Code, Codex, Cursor oder jedem anderen MCP-kompatiblen Agenten.

In Aktion erleben

Eine Service-Abfrage hängt. Finden Sie die Ursache:

> Attach to localhost:5005 and find out why a query is stuck.

Der Agent verbindet sich, pausiert alle Threads und sucht nach dem Problem:

connected localhost:5005
paused
24 threads, 2 blocked

Thread pool-3-thread-7 is waiting for a monitor lock:
#0 RolapResult.loadMembers:142
  monitor=@3f2a  state=BLOCKED
#1 RolapResult.execute:89

Lock is held by pool-3-thread-2, which is running:
#0 SqlStatement.execute:218
  sql="SELECT ... FROM fact_table"   -- full scan on 36M rows

Root cause: the query bypassed the aggregate table and fell back to
a full fact-table scan. Thread-7 is waiting for thread-2 to finish.

Ein Prompt. Sechs Tool-Aufrufe. Sperrkonflikte und die Ursache wurden identifiziert.

Schnellstart

1. Installation

pip install jdwp-mcp

# Pre-built binary
curl -fsSL https://raw.githubusercontent.com/dronsv/jdwp-mcp/main/install.sh | sh

# Cargo (requires Rust)
cargo install --git https://github.com/dronsv/jdwp-mcp

# From source
git clone https://github.com/dronsv/jdwp-mcp && cd jdwp-mcp && cargo build --release

2. Konfigurieren Sie Ihren Agenten

claude mcp add jdwp jdwp-mcp

Für Codex, Cursor oder andere MCP-kompatible Agenten fügen Sie dies zu .mcp.json hinzu:

{
  "mcpServers": {
    "jdwp": {
      "command": "jdwp-mcp"
    }
  }
}

3. Starten Sie Ihre Java-App mit JDWP

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

4. Debuggen

Attach to localhost:5005 and set a breakpoint at com.example.MyService line 42

5. Automatische Genehmigung (optional)

Das Debuggen beinhaltet viele schnelle Tool-Aufrufe. Die automatische Genehmigung eliminiert Bestätigungsaufforderungen:

# Allow all jdwp tools for this project
claude config set --project allowedTools 'mcp__jdwp__*'

claude config set allowedTools 'mcp__jdwp__*'

Aktivieren Sie dies nur für Projekte, denen Sie vertrauen – JDWP-Tools können Threads pausieren, Variablen ändern und Methoden auf der Ziel-JVM aufrufen.

Prompt-Pakete

Wählen Sie das Paket, das zu Ihrer Situation passt:

App hängt oder ist langsam

Attach to localhost:5005
Pause the JVM and find all blocked or waiting threads
Show the stack for the blocked thread with variables
Who holds the lock? Show their stack too

Exception in den Logs

Attach to localhost:5005
Set an exception breakpoint for NullPointerException
Wait for the exception to fire
Show the stack and all local variables at the throw site

Code-Pfad verstehen

Attach to localhost:5005
Trace method calls on com.example.service
[send your HTTP request]
Show the trace result — which methods were called?

Breakpoint-gesteuertes Debugging

Attach to localhost:5005
Find classes matching UserService
List methods of UserService with line numbers
Set a breakpoint at UserService line 45
When it hits, show the stack with all variables
Step over to the next line

Claude Code Befehle

Wenn Sie dieses Repo klonen, erhalten Sie fertige Slash-Befehle:

• /investigate-hang — Diagnose einer hängenden JVM (pausieren, blockierte Threads finden, Locks verfolgen)

• /investigate-exception — eine Live-Exception abfangen und den Ort des Auftretens untersuchen

• /trace-request — verfolgen, welche Methoden eine Anfrage durchläuft

Sowie einen autonomen Untersuchungs-Agenten (.claude/agents/jdwp-investigator.md), der gestartet werden kann, um Hänger, Deadlocks, Exceptions und unerwartete Code-Pfade zu diagnostizieren.

Siehe .claude/settings.example.json für die empfohlene Konfiguration zur automatischen Genehmigung und Update-Prüfung.

Beste erste Anwendungsfälle

• Hängende Anfragen und Deadlocks

• Blockierte Thread-Pools

• Verdächtige SQL-Abfragen oder Diskrepanzen im Laufzeitstatus

• Breakpoint-gesteuerte Diagnose ohne IDE-Zugriff

• Remote-Debugging via kubectl port-forward

Warum dies statt jstack oder einer IDE?

• Funktioniert innerhalb Ihres Agenten — kein Tool-Wechsel, kein separates Debugger-Fenster

• Kombiniert Anhängen + Untersuchen + Schlussfolgern in einer Schleife — der Agent entscheidet, was als Nächstes zu prüfen ist

• Konversationell — beschreiben Sie das Problem, der Agent führt die Debug-Sitzung durch

• Ground Truth für große Codebasen — in komplexen Projekten mit tiefen Framework-Stacks (Spring, Hibernate, OLAP-Engines) können sich Agenten beim statischen Verfolgen von Code-Pfaden verirren. Live-Debugging liefert dem Agenten den tatsächlichen Laufzeitstatus: Welcher Thread hält den Lock, welches SQL wurde generiert, welchen Wert hat eine Variable gerade jetzt

Tools

Verbindung und Steuerung attach, disconnect, pause, continue, step into/over/out

Breakpoints und Ereignisse set_breakpoint (mit Bedingungen), clear, list, exception_breakpoint, watch (Feldänderung), wait_for_event

Untersuchung get_stack (löst Objekte automatisch auf), get_variable, inspect, eval, set_value, snapshot, find_class, list_methods, list_threads, vm_info

Tracing trace (Methoden-Tracing für ein Paket aktivieren), trace_result (den Aufrufpfad abrufen)

Nicht verwenden für

• Post-Mortem-Heap-Analyse

• Permanente Produktions-Observability

• Umgebungen, in denen JDWP-Anhänge oder das Pausieren von Threads betrieblich unsicher sind

Betrieblicher Hinweis

JDWP verändert das Laufzeitverhalten. Das Pausieren von Threads und das Setzen von Breakpoints kann störend wirken. Verwenden Sie es in der Produktion mit Vorsicht; bevorzugen Sie Staging-Umgebungen oder kontrollierte Wartungsfenster.

Bereitstellungsszenarien

Siehe docs/deploy.md für die Einrichtung mit Maven, Gradle, Tomcat, Docker, Kubernetes (Port-Forwarding) und SSH-Tunneln.

Beispiele

• Debugging einer hängenden Abfrage — vollständige Anleitung: Sperrkonflikte, Thread-Analyse, Identifizierung der Ursache

• Observability-Debugging — Untersuchung von Problemen mit dem Spring Boot ObservationRegistry

Architektur

Agent  -->  MCP Server  -->  JDWP Client  -->  TCP  -->  JVM
              |
        Translates tool calls to JDWP,
        tracks session state, summarizes
        runtime objects for the agent.

Aus dem Quellcode bauen

cargo build --release
cargo test

Lizenz

MIT