mcp-debugger

Servidor MCP para depuración multilingüe: dales a tus agentes de IA superpoderes de depuración 🚀

🎯 Descripción general

mcp-debugger es un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona herramientas de depuración como llamadas a API estructuradas. Permite que los agentes de IA realicen depuración paso a paso de múltiples lenguajes de programación utilizando el Protocolo de Adaptador de Depuración (DAP).

🆕 Versión 0.19.0: ¡Depuración de Java mediante puente JDI con modos de lanzamiento y conexión! Además de depuración de Go con Delve.

🆕 Versión 0.17.0: ¡Soporte para depuración de Rust! Depura programas de Rust con CodeLLDB en Linux/macOS, incluyendo proyectos de Cargo, código asíncrono e inspección completa de variables; además, los comandos de paso ahora devuelven el contexto de origen activo para que los agentes mantengan su posición automáticamente.

🔥 Versión 0.16.0: ¡Soporte para depuración de JavaScript/Node.js! Capacidades completas de depuración con js-debug incluido, soporte para TypeScript y cero dependencias en tiempo de ejecución mediante una distribución mejorada de npx.

🎬 Video de demostración: ¡Mira al depurador en acción!

Grabación en curso - Esto mostrará a un agente de IA descubriendo y corrigiendo el error de intercambio de variables en tiempo real

✨ Características clave

• 🌐 Soporte multilingüe – Patrón de adaptador limpio para cualquier lenguaje

• 🐍 Depuración de Python mediante debugpy – Soporte completo del protocolo DAP

• 🟨 Depuración de JavaScript (Node.js) mediante js-debug – El depurador probado de VSCode

• 🦀 Depuración de Rust mediante CodeLLDB – Depura proyectos de Rust y Cargo (Linux/macOS/Windows con cadena de herramientas GNU)

• 🐹 Depuración de Go mediante Delve – Soporte completo de DAP para programas en Go

• ☕ Depuración de Java mediante puente JDI – Modos de lanzamiento y conexión con JDK 21+

• 🔷 Depuración de .NET/C# mediante netcoredbg – Depura aplicaciones .NET con soporte completo de DAP

ADVERTENCIA: En Windows, utiliza la cadena de herramientas GNU para una inspección completa de variables. Ejecuta mcp-debugger check-rust-binary <ruta-al-exe> para verificar tu compilación y consulta Depuración de Rust en Windows para obtener una guía detallada. NOTA: El paquete npm publicado incluye el tiempo de ejecución de CodeLLDB para Linux x64 para mantenerse dentro de los límites de tamaño del registro. En macOS o Windows, apunta la variable de entorno CODELLDB_PATH a una instalación existente de CodeLLDB (por ejemplo, desde la extensión de VSCode) o clona el repositorio y ejecuta pnpm --filter @debugmcp/adapter-rust run build:adapter para incluir los binarios de tu plataforma localmente.

Script de configuración de Rust en Windows

Si estás en Windows y quieres el camino más rápido hacia una configuración funcional de la cadena de herramientas GNU + dlltool, ejecuta:

pwsh scripts/setup/windows-rust-debug.ps1

El script instala la cadena de herramientas stable-gnu (a través de rustup), configura dlltool.exe (prefiriendo MSYS2/MinGW cuando está disponible, recurriendo a la copia autocontenida de rustup), compila los ejemplos de Rust incluidos y ejecuta las pruebas de humo de Rust por defecto. Añade -SkipTests para optar por no ejecutar pruebas. Añade -UpdateUserPath si deseas que la ruta de dlltool persista en tus variables PATH/DLLTOOL de usuario.

El script también intentará aprovisionar una cadena de herramientas MinGW-w64 basada en MSYS2 (a través de winget + pacman) para que cargo +stable-gnu tenga una pila dlltool/ld/as completamente funcional. Si MSYS2 ya está instalado, simplemente lo reutiliza; de lo contrario, te guía a través de su instalación (o te advierte para que puedas instalarlo manualmente).

• 🧪 Adaptador simulado para pruebas – Prueba sin dependencias externas

• 🔌 Modos de transporte STDIO y SSE – Funciona con cualquier cliente MCP

• 📦 Cero dependencias en tiempo de ejecución – Paquetes autocontenidos mediante esbuild + tsup

• ⚡ Listo para npx – Ejecuta directamente con npx @debugmcp/mcp-debugger - no requiere instalación

• 📊 Más de 1266 pruebas superadas – Probado en batalla de extremo a extremo

• 🐳 Docker y paquetes npm – Despliega en cualquier lugar

• 🤖 Creado para agentes de IA – Respuestas JSON estructuradas para un análisis sencillo

• 🛡️ Validación de rutas – Evita bloqueos por archivos inexistentes

• 📝 Contexto de línea consciente de la IA – Colocación inteligente de puntos de interrupción con contexto de código

🚀 Inicio rápido

Para clientes MCP (Claude Desktop, etc.)

Añade a tu configuración de ajustes de MCP:

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "node",
      "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

Para la CLI de Claude Code

Para los usuarios de Claude Code, proporcionamos un script de instalación automatizado:

Requisito previo: La CLI de Claude debe estar instalada y disponible en tu PATH antes de ejecutar el script de instalación. Consulta la documentación de Claude Code para obtener instrucciones de instalación.

# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list

Importante: El argumento stdio es necesario para evitar que la salida de la consola corrompa el protocolo JSON-RPC. Consulta CLAUDE.md para obtener información detallada sobre la configuración y la resolución de problemas.

Uso de Docker

docker run -v $(pwd):/workspace debugmcp/mcp-debugger:latest

⚠️ La imagen de Docker incluye adaptadores para Python, JavaScript, Go, Java y .NET. La depuración de Rust requiere despliegues locales, SSE o empaquetados donde el adaptador se ejecuta junto a tu cadena de herramientas. Ten en cuenta que los adaptadores se cargan dinámicamente en tiempo de ejecución: solo aquellos cuya cadena de herramientas esté instalada y detectada serán reportados como disponibles por list_supported_languages.

Uso de npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

O úsalo sin instalación mediante npx:

npx @debugmcp/mcp-debugger --help

📸 Captura de pantalla: Integración de MCP en acción

Esta captura de pantalla mostrará la comunicación del protocolo MCP en tiempo real con llamadas a herramientas y respuestas JSON fluyendo entre el agente de IA y el depurador.

📚 Cómo funciona

mcp-debugger expone las operaciones de depuración como herramientas MCP que pueden ser llamadas con parámetros JSON estructurados:

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "javascript", "rust", "go", "java", "dotnet", or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

📸 Captura de pantalla: Sesión de depuración activa

Esta captura de pantalla mostrará el depurador pausado en un punto de interrupción con el seguimiento de pila visible en el panel izquierdo, las variables locales en el panel derecho y el código fuente con resaltado de línea en el centro.

🛠️ Herramientas disponibles

📸 Captura de pantalla: Depuración multisesión

Esta captura de pantalla mostrará al depurador gestionando múltiples sesiones de depuración simultáneas, demostrando cómo los agentes de IA pueden depurar diferentes scripts simultáneamente con una gestión de sesiones aislada.

🏗️ Arquitectura: Carga dinámica de adaptadores

La versión 0.10.0 introduce un patrón de adaptador limpio que separa la funcionalidad central agnóstica del lenguaje de las implementaciones específicas del lenguaje:

┌─────────────┐     ┌────────────────┐     ┌──────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
└─────────────┘     └────────────────┘     └──────────────┘     └─────────────────┘
                            │                      │
                            ▼                      ▼
                    ┌──────────────┐      ┌─────────────────┐
                    │ ProxyManager │◀─────│ Language Adapter│
                    └──────────────┘      └─────────────────┘
                                                   │
                          ┌──────────────┴──────────────────────────────────────────┐
                          │                                                          │
              ┌───────────┼───────────┬───────────┬───────────┬───────────┐          │
              │           │           │           │           │           │          │
        ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
        │Python    ││JavaScript││Rust      ││Go        ││Java      ││Dotnet    ││Mock      │
        │Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   │
        └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────���───┘

Añadir soporte de lenguaje

¿Quieres añadir soporte de depuración para tu lenguaje favorito? ¡Consulta la Guía de desarrollo de adaptadores!

💡 Ejemplo: Depuración de código Python

Aquí tienes un ejemplo completo de sesión de depuración:

# buggy_swap.py
def swap_variables(a, b):
    a = b  # Bug: loses original value of 'a'
    b = a  # Bug: 'b' gets the new value of 'a'
    return a, b

Paso 1: Crear una sesión de depuración

// Tool: create_debug_session
// Request:
{
  "language": "python",
  "name": "Swap Bug Investigation"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: Swap Bug Investigation"
}

Paso 2: Establecer puntos de interrupción

// Tool: set_breakpoint
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "file": "buggy_swap.py",
  "line": 2
}
// Response:
{
  "success": true,
  "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2,
  "verified": false,
  "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}

Paso 3: Iniciar la depuración

// Tool: start_debugging
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scriptPath": "buggy_swap.py"
}
// Response:
{
  "success": true,
  "state": "paused",
  "message": "Debugging started for buggy_swap.py. Current state: paused",
  "data": {
    "message": "Debugging started for buggy_swap.py. Current state: paused",
    "reason": "breakpoint"
  }
}

Paso 4: Inspeccionar variables

Primero, obtén los ámbitos:

// Tool: get_scopes
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "frameId": 3
}
// Response:
{
  "success": true,
  "scopes": [
    {
      "name": "Locals",
      "variablesReference": 5,
      "expensive": false,
      "presentationHint": "locals",
      "source": {}
    },
    {
      "name": "Globals", 
      "variablesReference": 6,
      "expensive": false,
      "source": {}
    }
  ]
}

Luego obtén las variables locales:

// Tool: get_variables
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scope": 5
}
// Response:
{
  "success": true,
  "variables": [
    {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
    {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  ],
  "count": 2,
  "variablesReference": 5
}

📸 Captura de pantalla: La inspección de variables revela el error

Esta captura de pantalla mostrará el visualizador TUI después de pasar por encima de la línea 4, donde ambas variables muestran incorrectamente el valor 20, demostrando claramente el error de intercambio de variables. El panel izquierdo muestra el estado de ejecución, el centro muestra el código resaltado y el panel derecho muestra los valores incorrectos de las variables.

📖 Documentación

• 📘 Referencia de herramientas – Documentación completa de la API

• 🚦 Guía de inicio – Configuración inicial

• 🏗️ Descripción general de la arquitectura – Diseño multilingüe

• 🔧 Desarrollo de adaptadores – Añadir nuevos lenguajes

• 🔌 Arquitectura de carga dinámica – Descubrimiento en tiempo de ejecución, carga diferida, almacenamiento en caché

• 🧩 Referencia de la API del adaptador – Contratos de adaptador, fábrica, cargador y registro

• 🔄 Guía de migración – Actualización a v0.15.0 (carga dinámica)

• 🐍 Guía de depuración de Python – Características específicas de Python

• 🟨 Guía de depuración de JavaScript – Características de JavaScript/TypeScript

• 🐹 Guía de depuración de Go – Depuración de Go con Delve

• ☕ Guía de depuración de Java – Depuración de Java con puente JDI

• Depuración de Rust en Windows - Requisitos de la cadena de herramientas y resolución de problemas

• 🔧 Resolución de problemas – Problemas comunes y soluciones

🤝 Contribución

¡Damos la bienvenida a las contribuciones! Consulta CONTRIBUTING.md para conocer las directrices.

# Development setup
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Install dependencies and vendor debug adapters
pnpm install
# All debug adapters (JavaScript js-debug, Rust CodeLLDB) are automatically downloaded

# Build the project
pnpm build

# Run tests
pnpm test

# Check adapter vendoring status
pnpm vendor:status

# Force re-vendor all adapters (if needed)
pnpm vendor:force

Vendoring de adapt