jdwp-mcp

Depura JVMs en ejecución a través de JDWP, desde cualquier agente compatible con MCP.

Conéctate a un proceso Java en ejecución, pausa hilos, inspecciona pilas y objetos, establece puntos de interrupción y evalúa el estado mediante lenguaje natural. Un solo prompt inicia un ciclo de diagnóstico impulsado por el agente con datos de tiempo de ejecución en vivo.

Funciona con Claude Code, Codex, Cursor o cualquier agente compatible con MCP.

Véalo en acción

Una consulta de servicio se ha quedado bloqueada. Encuentra la causa raíz:

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

El agente se conecta, pausa todos los hilos y busca el problema:

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.

Un prompt. Seis llamadas a herramientas. Contención de bloqueo y causa raíz identificadas.

Inicio rápido

1. Instalar

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. Configura tu agente

claude mcp add jdwp jdwp-mcp

Para Codex, Cursor u otros agentes compatibles con MCP, añade a .mcp.json:

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

3. Inicia tu aplicación Java con JDWP

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

4. Depurar

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

5. Aprobación automática (opcional)

La depuración implica muchas llamadas rápidas a herramientas. La aprobación automática elimina los mensajes de confirmación:

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

claude config set allowedTools 'mcp__jdwp__*'

Actívalo solo para proyectos en los que confíes: las herramientas jdwp pueden pausar hilos, modificar variables e invocar métodos en la JVM de destino.

Paquetes de prompts

Elige el paquete que coincida con tu situación:

La aplicación se bloquea o va lenta

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

Excepción en los registros

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

Necesito entender una ruta de código

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

Depuración basada en puntos de interrupción

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

Comandos de Claude Code

Si clonas este repositorio, obtendrás comandos de barra diagonal listos para usar:

• /investigate-hang — diagnostica una JVM bloqueada (pausar, encontrar hilos bloqueados, rastrear bloqueos)

• /investigate-exception — captura una excepción en vivo e inspecciona el lugar donde se lanzó

• /trace-request — rastrea por qué métodos pasa una solicitud

Y un agente investigador autónomo (.claude/agents/jdwp-investigator.md) que puede ser generado para diagnosticar bloqueos, interbloqueos, excepciones y rutas de código inesperadas.

Consulta .claude/settings.example.json para conocer la configuración recomendada de aprobación automática y comprobación de actualizaciones.

Mejores casos de uso iniciales

• Solicitudes bloqueadas e interbloqueos

• Grupos de hilos bloqueados

• SQL sospechoso o discrepancia en el estado de tiempo de ejecución

• Diagnóstico basado en puntos de interrupción sin acceso al IDE

• Depuración remota mediante kubectl port-forward

¿Por qué esto en lugar de jstack o un IDE?

• Funciona dentro de tu agente: sin cambio de herramientas, sin ventana de depurador separada

• Combina conexión + inspección + razonamiento en un solo ciclo: el agente decide qué mirar a continuación

• Conversacional: describe el problema, el agente ejecuta la sesión de depuración

• Fuente de verdad para bases de código grandes: en proyectos complejos con pilas de marcos profundas (Spring, Hibernate, motores OLAP), los agentes pueden perderse al rastrear rutas de código estáticamente. La depuración en vivo le da al agente el estado real de tiempo de ejecución: qué hilo tiene el bloqueo, qué SQL se generó, qué valor tiene realmente una variable en este momento

Herramientas

Conexión y control attach, disconnect, pause, continue, step into/over/out

Puntos de interrupción y eventos set_breakpoint (con condiciones), clear, list, exception_breakpoint, watch (modificación de campo), wait_for_event

Inspección get_stack (resuelve objetos automáticamente), get_variable, inspect, eval, set_value, snapshot, find_class, list_methods, list_threads, vm_info

Rastreo trace (activar rastreo a nivel de método en un paquete), trace_result (obtener la ruta de llamada)

No lo uses para

• Análisis de montón post-mortem

• Observabilidad de producción siempre activa

• Entornos donde la conexión JDWP o la pausa de hilos no sean operativamente seguras

Nota operativa

JDWP cambia el comportamiento en tiempo de ejecución. Pausar hilos y establecer puntos de interrupción puede ser disruptivo. Úsalo con cuidado en producción; prefiere entornos de ensayo o ventanas de mantenimiento controladas.

Escenarios de despliegue

Consulta docs/deploy.md para la configuración con Maven, Gradle, Tomcat, Docker, Kubernetes (port-forward) y túneles SSH.

Ejemplos

• Depuración de una consulta bloqueada — tutorial completo: contención de bloqueo, análisis de hilos, identificación de la causa raíz

• Depuración de observabilidad — investigación de problemas de Spring Boot ObservationRegistry

Arquitectura

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

Construcción desde el código fuente

cargo build --release
cargo test

Licencia

MIT