MCP JS Debugger

MCP JS Debugger

Un servidor MCP (Model Context Protocol) que expone capacidades de depuración del Chrome DevTools Protocol, permitiendo a los asistentes de IA depurar aplicaciones JavaScript y TypeScript.

Características

• Conectarse a cualquier depurador compatible con CDP (Node.js, Chrome, Edge)
• Establecer, listar y eliminar puntos de interrupción
• Avanzar paso a paso por el código (sobre, dentro, fuera)
• Inspeccionar pilas de llamadas con soporte de source maps
• Evaluar expresiones en cualquier marco de pila
• Ver y modificar variables
• Pausar en excepciones
• Soporte completo de source maps para depurar código transpilado

Instalación

npm install
npm run build

Integración con Claude Code

Añade a tu configuración de Claude Code:

claude mcp add mcp-js-debugger -- npx mcp-js-debugger

O añade a .mcp.json:

{
  "mcpServers": {
    "mcp-js-debugger": {
      "command": "npx",
      "args": ["mcp-js-debugger"]
    }
  }
}

Uso

Iniciar un objetivo de depuración

Inicia tu aplicación Node.js con el inspector:

# Pause on first line (recommended for setting initial breakpoints)
node --inspect-brk=9229 your-script.js

# Or start without pausing
node --inspect=9229 your-script.js

Herramientas disponibles

Herramienta	Descripción
connect_debugger	Conectarse a un endpoint CDP mediante URL de WebSocket
disconnect_debugger	Desconectarse de una sesión de depuración
set_breakpoint	Establecer un punto de interrupción por URL y número de línea
remove_breakpoint	Eliminar un punto de interrupción por ID
list_breakpoints	Listar todos los puntos de interrupción en una sesión
resume_execution	Reanudar la ejecución después de una pausa
step_over	Ejecutar paso a paso sobre la declaración actual
step_into	Entrar en una llamada a función
step_out	Salir de la función actual
pause_execution	Pausar la ejecución en curso
get_call_stack	Obtener la pila de llamadas actual con ubicaciones de origen
evaluate_expression	Evaluar una expresión de JavaScript
get_scope_variables	Obtener variables en un ámbito
set_variable_value	Modificar el valor de una variable
set_pause_on_exceptions	Configurar el manejo de excepciones
get_original_location	Mapear la ubicación generada a la ubicación de origen original
get_script_source	Obtener el código fuente del script
list_scripts	Listar los scripts cargados

Flujo de trabajo de ejemplo

1. Inicia tu aplicación con --inspect-brk:

   node --inspect-brk=9229 app.js
   

2. Obtén la URL de WebSocket:

   curl http://localhost:9229/json
   

3. Conecta el depurador:

   connect_debugger(websocket_url: "ws://localhost:9229/<id>")
   

4. Establece puntos de interrupción:

   set_breakpoint(session_id: "...", url: "file:///path/to/app.js", line_number: 10)
   

5. Reanuda la ejecución para alcanzar el punto de interrupción:

   resume_execution(session_id: "...")
   

6. Inspecciona el estado cuando esté en pausa:

   get_call_stack(session_id: "...")
   get_scope_variables(session_id: "...", call_frame_id: "...", scope_index: 0)
   evaluate_expression(session_id: "...", expression: "myVariable")
   

7. Continúa la depuración:

   step_over(session_id: "...")
   resume_execution(session_id: "...")
   

Soporte de source maps

El servidor carga automáticamente los source maps para código transpilado (TypeScript, JavaScript empaquetado, etc.). Cuando los source maps están disponibles:

• Las pilas de llamadas muestran las ubicaciones de origen originales
• Los puntos de interrupción se pueden establecer en archivos de origen originales
• get_original_location mapea las posiciones generadas al origen original
• get_script_source puede devolver el contenido del origen original

Desarrollo

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Watch mode for development
npm run dev

Arquitectura

• cdp-client.ts - Envoltorio de cliente de bajo nivel del protocolo Chrome DevTools Protocol
• session-manager.ts - Gestiona múltiples sesiones de depuración
• source-map-manager.ts - Maneja la carga de source maps y el mapeo de posiciones
• server.ts - Implementación del servidor MCP con manejadores de herramientas
• types.ts - Definiciones de tipos TypeScript

Requisitos

• Node.js 18.0.0 o posterior
• Un objetivo de depuración compatible con CDP (Node.js, Chrome, Edge, etc.)

Licencia

Apache-2.0