DebugMCP (Servidor MCP) - Potenciando a los agentes de IA con capacidades de depuración operativa

Permite que los agentes de IA depuren tu código dentro de VS Code: establezcan puntos de interrupción, avancen paso a paso por la ejecución, inspeccionen variables y evalúen expresiones. Funciona con Codex, GitHub Copilot, GitHub Copilot CLI, Cline, Cursor, Windsurf, Roo Code y cualquier asistente compatible con MCP. Compatible con cualquier lenguaje de programación soportado por VS Code.

⭐ Si encuentras DebugMCP útil, por favor dale una estrella al repositorio en GitHub! Ayuda a otros a descubrir el proyecto y motiva el desarrollo continuo.

📢 Aviso para desarrolladores: Esta extensión es mantenida por ozzafar@microsoft.com y orbarila@microsoft.com. Agradecemos comentarios y contribuciones para mejorar esta extensión.

🎬 Mira DebugMCP en acción: tu asistente de IA establece puntos de interrupción de forma autónoma, avanza paso a paso por el código e inspecciona variables directamente en VS Code.

✨ Novedades

2.2

• Instalación de la habilidad debug-live entre agentes — el flujo de trabajo de depuración sistemática se distribuye como una Agent Skill y ahora se instala en los directorios estándar de habilidades — ~/.agents/skills/ (la ubicación entre agentes reconocida por los entornos compatibles con habilidades, incluido el modo agente de VS Code) y ~/.copilot/skills/ cuando esté presente — para que sea detectable en todas partes en lugar de copiarse junto a la configuración de cada agente donde nada lo escanea (corrige #105, donde VS Code nunca cargaba la habilidad). El servidor también anuncia instructions de MCP y la herramienta start_debugging apunta a la habilidad para el flujo de trabajo completo.

• Pausar programas en ejecución — la nueva herramienta pause_execution interrumpe un programa en ejecución libre y se detiene en su ubicación actual, incluso sin un punto de interrupción establecido (ideal para bucles ocupados y objetivos embebidos/bare-metal), para que luego puedas inspeccionar el estado o avanzar desde allí.

• Depuración robusta mediante la API de Testing de VS Code — start_debugging con un testName utiliza la API de Testing de VS Code para descubrir y lanzar la prueba, produciendo aciertos de puntos de interrupción consistentes dentro de casos de prueba individuales en los ejecutores de pruebas de distintos lenguajes (pytest, Jest/Vitest, Java, .NET, Go, etc.).

Related MCP server: MCP Server for VS Code

🚀 Instalación rápida

Instalar desde VS Code Marketplace o usa el enlace directo: vscode:extension/ozzafar.debugmcpextension

Tabla de contenidos

• Resumen

• Características

• Instalación

• Inicio rápido

• Asistentes de IA compatibles

• Lenguajes compatibles

• Configuración

• Preguntas frecuentes

• Solución de problemas

• Cómo funciona

• Contribuciones

• Licencia

Resumen

DebugMCP es un servidor MCP que brinda a los agentes de IA de codificación control total sobre el depurador de VS Code. En lugar de leer registros o adivinar, tu asistente de IA puede establecer puntos de interrupción de forma autónoma, lanzar sesiones de depuración, avanzar paso a paso por el código línea por línea, inspeccionar valores de variables y evaluar expresiones, tal como lo haría un desarrollador humano. Se ejecuta 100% localmente, no requiere configuración y funciona de inmediato con cualquier asistente de IA compatible con MCP.

Características

🔧 Herramientas

Nota: El servidor MCP expone herramientas para acciones del depurador, mientras que la guía de flujo de trabajo procedimental (cuándo depurar, cómo estructurar una investigación de causa raíz, peculiaridades específicas del lenguaje) reside en la Agent Skill complementaria. Las descripciones de las herramientas son concisas y de comportamiento; la extensión instala la habilidad debug-live en los directorios estándar de habilidades (~/.agents/skills/, además de ~/.copilot/skills/ cuando esté presente) para que los entornos compatibles con habilidades carguen el flujo de trabajo completo bajo demanda. El servidor también anuncia instructions de MCP que apuntan a los agentes hacia ella antes de depurar.

🎯 Mejores prácticas de depuración

DebugMCP sigue prácticas de depuración sistemáticas para una resolución efectiva de problemas:

• Comienza con puntos de entrada: Inicia la depuración en los puntos de entrada de funciones o rutas de ejecución principales

• Sigue el flujo de ejecución: Usa la ejecución paso a paso para entender el flujo del código

• Análisis de causa raíz: No te detengas en los síntomas: encuentra la causa subyacente

🛡️ Seguridad y fiabilidad

• Comunicación segura: Todas las comunicaciones MCP usan protocolos seguros

• Operación local: El servidor MCP se ejecuta 100% localmente sin comunicaciones externas y no requiere credenciales

• Validación de estado: Validación robusta de estados y operaciones de depuración

Instalación

Opciones de instalación rápida

Opción 1: Enlace directo (Más rápido)

• Haz clic en este enlace: vscode:extension/ozzafar.debugmcpextension

• O copia y pega en tu navegador: vscode:extension/ozzafar.debugmcpextension

Opción 2: VS Code Marketplace

• Visita: https://marketplace.visualstudio.com/items?itemName=ozzafar.debugmcpextension

• Haz clic en "Instalar"

Opción 3: Dentro de VS Code

1. Abre VSCode

2. Ve a Extensiones (Ctrl+Shift+X / Cmd+Shift+X)

3. Busca "DebugMCP"

4. Haz clic en Instalar

5. La extensión se activa automáticamente y se registra como servidor MCP

Verificación

Después de la instalación, deberías ver:

• La extensión DebugMCP en tus extensiones instaladas

• El servidor MCP ejecutándose automáticamente en el puerto 3001 (configurable)

• Herramientas de depuración disponibles para los asistentes de IA conectados

📝 Nota: No se necesitan instrucciones adicionales de reglas de depuración: la extensión funciona de inmediato.

💡 Consejo: Habilita la aprobación automática para todas las herramientas de debugmcp en tu asistente de IA para crear flujos de trabajo de depuración fluidos sin interrupciones constantes de aprobación.

Inicio rápido

1. Instala la extensión (consulta Instalación)

2. Abre tu proyecto en VSCode

3. Pídele a tu IA que depure - ¡ahora puede establecer puntos de interrupción, iniciar la depuración y analizar tu código!

Asistentes de IA compatibles

DebugMCP funciona con cualquier asistente de IA compatible con MCP. Detecta automáticamente y ofrece registrarse con:

Idiomas compatibles

DebugMCP admite la depuración de los siguientes idiomas con sus respectivas extensiones de VSCode:

Configuración

Configuración del servidor MCP (recomendada)

La extensión ejecuta un servidor MCP automáticamente. Mostrará un mensaje para auto-registrar el servidor MCP en tu asistente de IA.

También puedes activar el registro manualmente mediante la Paleta de comandos:

• DebugMCP: Show Agent Selection Popup

Registro manual del servidor MCP (opcional)

🔄 Auto-migración: Si configuraste previamente DebugMCP con transporte SSE, la extensión migrará automáticamente tu configuración al nuevo transporte Streamable HTTP al activarse.

Cline

Añade a la configuración de Cline o a cline_mcp_settings.json:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - AI-powered debugging assistant"
    }
  }
}

GitHub Copilot

Añade a la configuración de VS Code (settings.json):

{
  "mcp": {
    "servers": {
      "debugmcp": {
        "type": "http",
        "url": "http://localhost:3001/mcp",
        "description": "DebugMCP - Multi-language debugging support"
      }
    }
  }
}

GitHub Copilot CLI

Añade a ~/.copilot/mcp-config.json (${COPILOT_HOME}/mcp-config.json si COPILOT_HOME está definido):

{
  "mcpServers": {
    "debugmcp": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
      "tools": ["*"]
    }
  }
}

Cursor

Añade a la configuración MCP de Cursor:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Codex

Registra DebugMCP con Codex:

codex mcp add debugmcp --url http://localhost:3001/mcp

O añade la configuración equivalente a ~/.codex/config.toml (${CODEX_HOME}/config.toml si CODEX_HOME está definido):

[mcp_servers.debugmcp]
url = "http://localhost:3001/mcp"

Windsurf

Añade a la configuración MCP de Windsurf (~/.windsurf/mcp_settings.json o .windsurf/mcp_settings.json del espacio de trabajo):

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Roo Code

Añade a la configuración MCP de Roo Code:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Antigravity

Añade a la configuración MCP de Antigravity:

{
  "mcpServers": {
    "debugmcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp",
      "description": "DebugMCP - Debugging tools for AI assistants"
    }
  }
}

Configuración de la extensión

Configura el comportamiento de DebugMCP en la configuración de VSCode:

{
  "debugmcp.serverPort": 3001,
  "debugmcp.timeoutInSeconds": 180,
  "debugmcp.bindHost": ["127.0.0.1", "::1"]
}

Modelo de seguridad

DebugMCP expone primitivas de depurador potentes (evaluate_expression, start_debugging, …) a través de un endpoint HTTP local sin autenticación. Para mantener esa superficie segura, el servidor aplica cuatro controles:

1. Vinculación solo a loopback. El servidor HTTP se vincula a las direcciones de loopback IPv4 e IPv6 (127.0.0.1 y ::1) de forma predeterminada, por lo que otros hosts de tu red no pueden acceder a http://<tu-ip>:3001/mcp. Vincular ambas familias garantiza que los clientes que resuelven localhost a cualquiera de las dos familias se conecten correctamente. La configuración debugmcp.bindHost (cadena o array de cadenas) permite optar por una interfaz diferente (por ejemplo, al reenviar el puerto a un contenedor remoto), pero hacerlo expone el depurador sin autenticación a cualquier cosa que pueda enrutar a esa dirección; no lo apuntes a 0.0.0.0 ni a una dirección LAN en una red no confiable.

2. Validación de cabeceras Host / Origin. Cada solicitud debe incluir una cabecera Host que nombre una dirección de loopback (localhost, 127.0.0.1 o [::1]); cualquier sufijo de puerto en Host también debe coincidir con el puerto de escucha del servidor. Las solicitudes con cualquier otro Host —incluidas las que llegan mediante DNS rebinding desde una página web maliciosa— se rechazan con HTTP 403. La misma comprobación de loopback se aplica a la cabecera Origin cuando está presente.

3. Inspección de variables con privilegios mínimos. get_variables_values requiere una lista explícita de variableNames (máximo 50, sin comodines) y devuelve solo esas variables. Ya no vuelca todas las variables en el ámbito, lo que antes entregaba al agente estado de proceso no relacionado que nunca había solicitado. Usa list_variable_names para descubrir qué existe; esa herramienta devuelve solo nombres y tipos y nunca lee un valor.

4. Redacción de secretos en la inspección de variables. Los valores con nombres que sugieren credenciales o valores que coinciden con una forma de credencial conocida se reemplazan con <redacted: possible secret> antes de que la respuesta salga de la extensión. El resultado evaluado devuelto por evaluate_expression también está cubierto. Cuando get_variables_values o evaluate_expression expanden un valor complejo, los descendientes se enumeran solo por nombre y tipo. Usa evaluate_expression con una ruta de descendiente exacta cuando se necesite su valor. La expansión recursiva está limitada a 100 campos secundarios en total por respuesta. Los valores nulos (None, undefined, '') nunca se redactan, de modo que los errores de "mi token está vacío" sigan siendo depurables. La redacción está siempre activada y no se puede desactivar.

Preguntas frecuentes

DebugMCP funciona con cualquier asistente de IA compatible con MCP, incluidos GitHub Copilot, GitHub Copilot CLI, Cline, Cursor, Codex, Windsurf, Roo Code, Antigravity y otros. Si tu asistente admite el Model Context Protocol, puede usar DebugMCP.

Sí. DebugMCP se ejecuta como una extensión de VS Code con extensionKind: workspace, por lo que se activa en el entorno remoto donde vive tu código. El servidor MCP se ejecuta en localhost dentro de ese contexto remoto.

No. DebugMCP genera automáticamente configuraciones de depuración adecuadas según el idioma/extensión del archivo. Si tienes un launch.json, seleccionará automáticamente la configuración más relevante.

No. DebugMCP se ejecuta 100 % localmente. El servidor MCP se ejecuta en localhost, y ningún código, variable o dato de depuración se envía a ningún servicio externo. El asistente de IA se comunica con el servidor MCP completamente dentro de tu máquina local.

Cambia el puerto en la configuración de VS Code: "debugmcp.serverPort": 3002 (o cualquier puerto disponible). Luego actualiza la configuración MCP de tu asistente de IA para usar el nuevo puerto.

Sí. Pasa el parámetro testName a start_debugging para depurar un método de prueba específico. DebugMCP configurará la sesión de depuración para ejecutarse y pausarse en los puntos de interrupción dentro de esa prueba.

Asegúrate de que DebugMCP esté registrado en la configuración MCP de tu asistente de IA. La extensión debería detectarse automáticamente y ofrecer registrarse. Si no es así, consulta la sección Registro manual del servidor MCP. También habilita la aprobación automática para las herramientas de DebugMCP para un flujo de trabajo más fluido.

Sí. DebugMCP admite archivos .cs y archivos de proyecto .csproj para la depuración de C#/.NET, incluidas las aplicaciones ASP.NET.

Solución de problemas

Problemas comunes

El servidor MCP no se inicia

• Síntoma: el asistente de IA no puede conectarse a DebugMCP

• Solución:

  • Comprueba si el puerto 3001 está disponible

  • Reinicia VSCode

  • Verifica que la extensión esté instalada y activada

La sesión de depuración no se detiene en los puntos de interrupción

• Síntoma: los puntos de interrupción están establecidos pero la ejecución no se pausa

• Solución:

  • Asegúrate de que se esté depurando el archivo correcto

  • Comprueba que el número de línea del punto de interrupción sea correcto

  • Verifica que la extensión de depurador del idioma correspondiente esté instalada

Otra ventana de VS Code toma el foco cuando la depuración se detiene

• Síntoma: con varias ventanas de VS Code abiertas, la ventana que se está depurando pasa a primer plano cuando alcanza un punto de interrupción o completa un paso

• Solución: desactiva el comportamiento nativo de foco al interrumpir de VS Code en la configuración de usuario o del espacio de trabajo:

  {
    "debug.focusWindowOnBreak": false,
    "debug.focusEditorOnBreak": false
  }

  debug.focusWindowOnBreak evita que la ventana depurada tome el foco del sistema operativo. La configuración opcional debug.focusEditorOnBreak también evita que VS Code mueva el foco al editor de código fuente detenido. DebugMCP no cambia estas preferencias persistentes automáticamente.

Configuración no detectada automáticamente

• Síntoma: La extensión no solicita registrarse con tu asistente de IA

• Solución:

  • Ejecuta DebugMCP: Show Agent Selection Popup desde la Paleta de Comandos (Ctrl+Shift+P / Cmd+Shift+P)

  • Agrega manualmente la configuración (consulta Registro manual del servidor MCP)

Cómo funciona

Arquitectura

AI Agent (Copilot/Cline/Cursor/Codex) → MCP/Streamable HTTP → DebugMCPServer → DebuggingHandler → VS Code Debug API

Integración de configuración de lanzamiento

La extensión maneja las configuraciones de depuración de manera inteligente:

• launch.json existente: Si existe un archivo .vscode/launch.json, hará lo siguiente:

  • Buscar una configuración relevante

  • Respetar configurationName cuando el agente lo proporcione explícitamente

  • Compatibilidad con JSONC (JSON con comentarios y comas finales)

• Configuración predeterminada: Si se omite configurationName, o si no se encuentra una configuración con nombre coincidente, crea una configuración predeterminada adecuada para cada idioma según la detección de extensión de archivo.

Requisitos

• VSCode con las extensiones de idioma apropiadas instaladas:

  • Python: Python extension para archivos .py

  • JavaScript/TypeScript: Depurador Node.js integrado o JavaScript Debugger extension

  • Java: Extension Pack for Java

  • C#/.NET: C# extension

  • C/C++: C/C++ extension

  • Go: Go extension

  • Rust: rust-analyzer extension

  • PHP: PHP Debug extension

  • Ruby: Ruby extension con soporte de depuración

• Asistente de IA compatible con MCP (Copilot, Cline, Cursor, Codex, Windsurf, Roo Code, etc.)

Desarrollo

Para compilar la extensión:

npm install
npm run compile

Para ejecutar el linting:

npm run lint

Para ejecutar las pruebas:

npm test

Contribuciones

Este proyecto acepta contribuciones y sugerencias. La mayoría de las contribuciones requieren que aceptes un Acuerdo de Licencia de Colaborador (CLA) que declare que tienes el derecho de, y de hecho lo haces, otorgarnos los derechos para usar tu contribución. Para más detalles, visita https://cla.opensource.microsoft.com.

Cuando envías una solicitud de extracción, un bot de CLA determinará automáticamente si necesitas proporcionar un CLA y decorará el PR adecuadamente (por ejemplo, verificación de estado, comentario). Simplemente sigue las instrucciones proporcionadas por el bot. Solo necesitarás hacer esto una vez en todos los repositorios que usan nuestro CLA.

Este proyecto ha adoptado el Código de Conducta de Código Abierto de Microsoft. Para más información, consulta las Preguntas frecuentes del Código de Conducta o contacta con opencode@microsoft.com si tienes preguntas o comentarios adicionales.

Seguridad

Las vulnerabilidades de seguridad deben informarse siguiendo las pautas en https://aka.ms/SECURITY.md. No informes vulnerabilidades de seguridad a través de problemas públicos de GitHub.

Marcas comerciales

Este proyecto puede contener marcas comerciales o logotipos de proyectos, productos o servicios. El uso autorizado de las marcas comerciales o logotipos de Microsoft está sujeto a y debe seguir las Directrices de marcas comerciales y marcas de Microsoft. El uso de marcas comerciales o logotipos de Microsoft en versiones modificadas de este proyecto no debe causar confusión ni implicar patrocinio de Microsoft. Cualquier uso de marcas comerciales o logotipos de terceros está sujeto a las políticas de esos terceros.

⭐ Apoya a DebugMCP

Si DebugMCP te ha ayudado a depurar más rápido, considera darle una estrella en GitHub. Las estrellas ayudan al proyecto a ganar visibilidad y atraer contribuyentes.

⭐ Da una estrella a DebugMCP en GitHub

Historial de estrellas

Licencia

Licencia MIT - Consulta LICENSE para más detalles

Esta extensión fue creada por Oz Zafar, Ori Bar-Ilan y Karin Brisker.