qwen-dap-mcp

Dale a Qwen Code un depurador nativo real.

Un puente agnóstico respecto al depurador Debug Adapter Protocol (DAP) → Model Context Protocol (MCP) para la depuración nativa en tiempo de ejecución, el análisis de fallos y bucles autónomos acotados de corrección/verificación.

Publicado en npm como @slp-dev1/qwen-dap-mcp y en el registro MCP oficial como io.github.SLP-DEV1/qwen-dap-mcp.

Por qué existe

Los agentes de codificación son buenos leyendo y editando código fuente, pero los fallos nativos a menudo necesitan evidencia que solo un depurador puede proporcionar: marcos de pila, registros, variables locales, desensamblado, estado de excepción, memoria, módulos y volcados de memoria.

qwen-dap-mcp expone esa evidencia a través de MCP para que Qwen Code y otros clientes MCP puedan razonar sobre fallos nativos sin incrustar un protocolo de depurador dentro del agente.

Qué puede hacer

• Depuración autónoma de fallos — diagnosticar → inspeccionar el código fuente → proponer una corrección → aplicar la corrección → compilar → reproducir → verificar.

• Evidencia real de depurador nativo — pila, registros, variables locales, estado de excepción, módulos, desensamblado, memoria y correlación con el código fuente.

• Integración con CodeLLDB — iniciar o adjuntarse a objetivos nativos locales autorizados mediante DAP.

• Integración con lldb-dap de LLVM upstream — depuración en vivo de primera clase e inspección de archivos core sin tratar lldb-dap como un alias de CodeLLDB.

• Minivolcados de Windows / depuración post mórtem — abrir archivos .dmp existentes y recuperar evidencia estructurada.

• Rastreo inverso de la causa raíz en tiempo de ejecución — seguir valores sospechosos a través de marcos de llamada acotados hacia candidatos productores probablemente controlados por el proyecto.

• Huellas de verificación — distinguir entre reproducciones corregidas, del mismo fallo, con fallo cambiado y no concluyentes.

• Límites de seguridad — sin shell arbitrario, sin primitiva de escritura de código fuente, sin primitiva general de escritura de memoria, ni estado autónomo oculto dentro del servidor MCP.

Related MCP server: Debug-MCP

Ejemplo en 30 segundos

You: Debug why app.exe crashes with --repro

Qwen Code
  ↓
starts CodeLLDB or upstream lldb-dap through qwen-dap-mcp
  ↓
finds the native failure and first project-controlled frame
  ↓
correlates instruction operands ↔ registers ↔ locals
  ↓
backtracks runtime evidence toward a likely producer
  ↓
reads the relevant source
  ↓
applies a minimal evidence-backed fix
  ↓
builds and repeats the same reproduction
  ↓
verifies the original crash fingerprint no longer reproduces

Instalación en Qwen Code

Instala directamente desde el release de GitHub:

qwen extensions install SLP-DEV1/qwen-dap-mcp

O instala la extensión npm de ámbito publicada:

qwen extensions install @slp-dev1/qwen-dap-mcp

Luego verifica la extensión y el servidor MCP:

/mcp
/skills

Deberías ver el servidor MCP qwen-dap-mcp y la Skill native-runtime-debug incluida.

El archivo del release de GitHub es autocontenido: las dependencias npm de tiempo de ejecución están empaquetadas en dist/index.js.

Uso desde otro cliente MCP stdio

Para clientes MCP que aceptan un comando stdio local, el paquete npm publicado se puede lanzar con:

npx -y @slp-dev1/qwen-dap-mcp

Una configuración típica de cliente tiene este aspecto:

{
  "mcpServers": {
    "qwen-dap-mcp": {
      "command": "npx",
      "args": ["-y", "@slp-dev1/qwen-dap-mcp"]
    }
  }
}

Qwen Code es la integración principal y la ruta cubierta por el empaquetado de extensiones y la validación de releases del proyecto. El propio servidor MCP se comunica a través de stdio local.

Distribución

Adaptadores de depurador

CodeLLDB y lldb-dap de LLVM upstream son ambas rutas de adaptador de primera clase. Los flujos de trabajo existentes de CodeLLDB siguen siendo compatibles; usa debug_this_crash(mode="lldb-dap") cuando quieras el adaptador de depurador incluido con el propio LLVM. La ruta lldb-dap admite lanzamiento/adjunción en vivo, además de análisis de archivos core de solo lectura mediante dumpAdapter="lldb-dap".

La detección admite un adapterPath explícito, LLDB_DAP_PATH, binarios PATH canónicos o versionados, directorios comunes de la cadena de herramientas LLVM / LLVM_HOME, y xcrun --find lldb-dap en macOS. Consulta docs/lldb-dap.md para ver ejemplos, el comportamiento post mórtem y los asistentes manuales del conjunto de herramientas completo.

Depuración autónoma de fallos

El flujo de trabajo de alto nivel debug_this_crash puede impulsar un ciclo autónomo de depuración acotado:

Diagnose
  ↓
select project frame
  ↓
operand ↔ register ↔ variable evidence
  ↓
call-chain / runtime provenance backtrack
  ↓
inspect source
  ↓
propose minimal fix
  ↓
apply fix
  ↓
build
  ↓
reproduce
  ↓
verify fingerprint + evidence quality
  ├── fixed → stop
  ├── same crash → revise fix
  ├── changed crash → re-baseline active failure
  ├── inconclusive → finish reproduction, do not edit
  └── budget exhausted / weak evidence → stop and report

Inicia un ciclo autónomo:

debug_this_crash(
  mode="codelldb",
  program="C:\\build\\app.exe",
  args=["--repro"],
  cwd="C:\\repo\\app",
  analysis={
    projectRoots:["C:\\repo\\app"],
    projectModules:["app.exe"],
    callerDepth:3
  },
  workflow={
    stage:"autonomous",
    maxIterations:3
  }
)

La primera llamada devuelve workflow.autonomousAgent con estado serializable explícito, nextActions con conocimiento de dependencias, huellas de fallo raíz y activas, historial acotado, evidencia de rastreo inverso en tiempo de ejecución, calidad de verificación y estado de parada/continuación.

El servidor no conserva memoria oculta del bucle autónomo. Qwen Code realiza las ediciones de código fuente, compilaciones, pruebas y operaciones de control de versiones solicitadas a través de sus herramientas autorizadas normales.

Estados autónomos

Diagnóstico inteligente

La capa de diagnóstico separa los hechos crudos del depurador de la inferencia e informa de:

• classification — familia actual del fallo/parada,

• faultLocation — marco de parada literal del depurador,

• projectFrame — primer marco probablemente controlado por la aplicación,

• frameSelection — evidencia de marcos de pila puntuada y exclusiones de tiempo de ejecución/sistema,

• operandAnalysis — operandos de instrucción, registros referenciados, operandos de memoria y enlaces registro↔local,

• callChain — llamantes del proyecto, límites de tiempo de ejecución, marcos repetidos y pistas de procedencia,

• hypotheses — explicaciones clasificadas con confianza explícita,

• fixWorkflow — ubicación candidata en el código fuente y dirección de corrección precisa respaldada por evidencia,

• verificationBaseline — firma de fallo compacta,

• rootCauseBacktrack — procedencia de tiempo de ejecución acotada hacia candidatos productores,

• verificationQuality — solidez de la evidencia del depurador después de la verificación.

Una puntuación alta de marco de proyecto significa «probablemente código del proyecto», no «causa raíz probada». Las afirmaciones causales deben seguir vinculadas al estado de excepción, a los operandos/registros/variables locales, a la procedencia del llamante, a la confirmación en el código fuente y a la reproducción.

Volcados de memoria / minivolcados

Abre y diagnostica un volcado existente en una única llamada de alto nivel:

debug_this_crash(
  mode="dump",
  dumpPath="C:\\crashes\\app.dmp",
  program="C:\\build\\app.exe",
  sourceMap={"D:/agent/_work/project/src":"C:/work/project/src"},
  analysis={projectRoots:["C:\\repo\\app"]}
)

Una sesión de volcado está congelada/solo lectura. Un volcado histórico puede establecer evidencia para el fallo capturado, pero una corrección de código fuente todavía necesita una reproducción en vivo reconstruida o un volcado recién generado para la verificación.

Arquitectura

Qwen Code / MCP client
        │
        │ MCP over stdio
        ▼
   qwen-dap-mcp
        │
        ├── lifecycle/concurrency guard
        ├── bounded DAP snapshot layer
        ├── crash classification
        ├── project-frame scoring
        ├── operand/register/local correlation
        ├── call-chain provenance
        ├── runtime root-cause backtracking
        ├── verification fingerprints + quality scoring
        └── autonomous action state machine
        │
        │ DAP over stdio
        ▼
 CodeLLDB / lldb-dap / DAP adapter
        │
        ├── authorized live target
        └── crash dump / core file

El servidor MCP no tiene listener HTTP. El adaptador se lanza localmente sin shell y se comunica a través de stdio.

Conjuntos de herramientas MCP

El conjunto de herramientas agent predeterminado expone deliberadamente solo las nueve herramientas de alto nivel que se indican a continuación para que los agentes de codificación no gasten contexto en cada primitiva de depurador de bajo nivel. Establece QWEN_DAP_MCP_TOOLSET=full cuando necesites intencionadamente la superficie DAP manual completa. Consulta docs/toolsets.md.

Herramientas agent predeterminadas

El conjunto de herramientas full expone además gestión manual de puntos de interrupción/puntos de vigilancia, ejecución paso a paso, evaluación, hilos/pilas/ámbitos/variables, módulos, desensamblado, lecturas de memoria acotadas, controles de excepción, lanzamiento/adjunción DAP genéricos y primitivas de ciclo de vida de CodeLLDB / lldb-dap.

Modelo de verificación

La verificación separa deliberadamente la evidencia del depurador de las garantías externas, como el éxito de la compilación, las pruebas del proyecto y las entradas exactas de reproducción.

Veredictos:

• fixed — la reproducción completa alcanzó un resultado terminal limpio y exitoso,

• not-fixed — se reprodujo la misma familia/firma de fallo,

• changed-failure — la ejecución seguía fallando, pero la firma de fallo activa cambió,

• inconclusive — evidencia insuficiente para afirmar éxito o fracaso.

Una parada por punto de interrupción, una parada de entrada, una pausa, un paso o una parada por excepción configurada/de primera oportunidad no es deliberadamente prueba de una corrección.

Validación real en Windows

El repositorio contiene flujos de trabajo de pruebas de humo reales de CodeLLDB en Windows. La ruta de pruebas de humo con minivolcados:

1. compila un objetivo de fallo MSVC C++ con símbolos PDB,

2. provoca intencionadamente una violación de acceso,

3. escribe un .dmp real con MiniDumpWriteDump,

4. inicia CodeLLDB real,

5. abre el volcado a través de DAP,

6. verifica la recuperación de pila/código fuente/registros/módulos/desensamblado,

7. ejecuta el diagnóstico inteligente de marcos del proyecto,

8. valida la generación de estado/huellas/acciones autónomas a partir del volcado real.

Desarrollo

Requisitos:

• Node.js 20+

• npm

Ejecuta la comprobación completa:

npm ci --ignore-scripts
npm run check

npm run check realiza la compilación de TypeScript, las pruebas y la preparación del paquete de extensión. CI ejecuta Node 20 y 22.

Modelo de seguridad

• solo transporte MCP stdio local,

• sin servicio de depurador HTTP remoto integrado,

• sin primitiva MCP de shell arbitrario/escritura de código fuente,

• sin primitiva MCP de escritura de memoria arbitraria,

• sin reversión automática de código fuente sin evidencia externa,

• adjunción en vivo destinada solo a objetivos locales autorizados,

• volcados post mórtem congelados frente a operaciones de control de ejecución,

• presupuesto autónomo de corrección acotado con condiciones de detención deterministas,

• la evidencia débil/no concluyente no desencadena otra edición de código fuente,

• las paradas por excepción de primera oportunidad/configuradas no se tratan automáticamente como fatales.

Contribuciones

Las issues y los pull requests son bienvenidos. Consulta CONTRIBUTING.md para obtener orientación sobre desarrollo.

Si el proyecto te resulta útil, darle una estrella al repositorio ayuda a que otros usuarios de Qwen Code y MCP lo descubran.

Licencia

Apache License 2.0. Ver LICENSE.