qwen-dap-mcp
Give coding agents a real native debugger.
qwen-dap-mcp is a local Debug Adapter Protocol (DAP) → Model Context Protocol (MCP) bridge for native crash debugging, hang/deadlock triage, crash dumps, differential runtime analysis, remote targets, and bounded fix/verify workflows.
Built for Qwen Code, usable from any stdio MCP client, and designed to expose debugger evidence without turning MCP into a general-purpose shell.
Quick start · Capabilities · Debugger support · Safety · Docs · Contributing
Why this exists
Coding agents can read source and propose patches, but native failures often cannot be diagnosed reliably from source alone. The useful evidence lives at runtime: thread stacks, registers, locals, disassembly, exception state, modules, memory, wait states, symbols, and crash dumps.
qwen-dap-mcp makes that evidence available through MCP and adds agent-oriented workflows on top of raw debugger primitives:
- Evidence first — inspect the actual failing process instead of guessing from source.
- High-level workflows — crash, hang, differential, causal tracing, progress probing, runtime-report, dump, and verification tools are designed for agents rather than humans driving a debugger console.
- Bounded automation — autonomous fix/verify state is explicit, serializable, iteration-limited, and re-checks the original reproduction.
- Small default surface — 18 core agent tools stay visible by default; forensic workflows and raw DAP controls are separate opt-in tiers.
- Local by default — the MCP server communicates over stdio and debugger adapters run locally unless you explicitly configure a validated remote target.
Quick start
Qwen Code
Install directly from GitHub:
qwen extensions install SLP-DEV1/qwen-dap-mcp
Or install the published npm package:
qwen extensions install @slp-dev1/qwen-dap-mcp
Then verify the extension:
You should see the qwen-dap-mcp server and the bundled native-runtime-debug skill.
Any stdio MCP client
npx -y @slp-dev1/qwen-dap-mcp
Typical configuration:
{
"mcpServers": {
"qwen-dap-mcp": {
"command": "npx",
"args": ["-y", "@slp-dev1/qwen-dap-mcp"]
}
}
}
CLI discovery is available without starting the stdio server:
qwen-dap-mcp --help
qwen-dap-mcp --version
30-second example
You: Debug why app.exe crashes with --repro
Coding agent
↓
qwen-dap-mcp starts a DAP debugger
↓
captures the native failure + project-controlled frame
↓
correlates stack + registers + locals + disassembly
↓
backtracks runtime evidence toward the likely producer
↓
agent applies a minimal source fix
↓
builds and repeats the original reproduction
↓
verifies whether the original crash fingerprint is gone
The MCP server supplies debugger evidence and bounded workflow state. Source editing, builds, tests, and source-control operations stay with the coding agent's normal authorized tools.
What it does
| Problem | Agent-oriented capability |
|---|
| Native crash | Diagnose a stopped process, identify project frames, collect runtime evidence, and drive bounded fix/verify loops |
| Hang or deadlock | Observe, pause when needed, capture all-thread stacks, classify waits, and surface conservative deadlock candidates |
| Good run vs bad run | Compare stopped sessions semantically while suppressing raw ASLR/address noise |
| Suspicious value | Trace real writers with data breakpoints/watchpoints and bounded temporal tracing |
| Runtime causality | Build a bounded suspicious-value consumer → writer/producer chain with debug_causal_trace |
| Suspected busy loop | Resume/pause sample a live target with debug_progress_probe to distinguish repeated state from observed execution movement |
| Record/replay target | Move backward with capability-gated debug_reverse_execution using DAP stepBack / reverseContinue |
| Crash fleet triage | Build debug_runtime_report fingerprints, cluster them with debug_cluster_crashes, and classify regression reproductions with debug_regression_oracle |
| Child/fork signal | Inspect fail-closed adapter startDebugging requests with debug_child_requests without auto-spawning child sessions |
| Crash dump | Inspect Windows minidumps and supported LLDB/GDB postmortem targets without launching the failed program |
| Remote native target | Attach through validated gdbserver / lldb-server gdbserver endpoints with loopback-first policy |
| Multiple targets | Keep isolated DAP sessions and route requests by sessionId |
| Agent safety | Keep the default surface high-level and optionally gate executable/mutating DAP actions with HOL Guard |
| Object lifetime / UAF | Correlate pointer writers, sanitizer evidence, reverse stepping, and allocation/free hints |
| Symbol mismatch | Compare adapter symbol state with bounded local binary/PDB identity evidence |
| Crash fleets | Batch postmortem analysis plus exact/semantic/family grouping |
| Offline handoff | Export structured evidence and SARIF without keeping the target alive |
The default agent toolset intentionally exposes 18 core tools so coding models spend less context and selection effort on rarely needed forensic workflows.
| Core tool | Purpose |
|---|
debug_this_crash | High-level native crash diagnosis and bounded autonomous verification |
debug_this_hang | High-level hang/deadlock triage |
debug_compare_runs | Semantic comparison of baseline and failing stopped sessions |
debug_trace_value | Bounded temporal tracing of a suspicious value |
debug_causal_trace | Consumer-to-writer producer evidence for suspicious runtime state |
debug_progress_probe | Resume/pause sampling for no-progress and busy-loop triage |
debug_runtime_report | Fingerprints, symbols, sanitizer evidence, memory hazards, ABI/API analysis, hypotheses, and breakpoint planning |
debug_trace_lifetime | Object/pointer lifetime and writer provenance |
debug_adaptive_evidence | Cheap → medium → full bounded evidence collection |
debug_diagnose_stop | Diagnose the current debugger stop |
debug_source_disassembly | Correlate source with nearby native instructions |
debug_find_writer | Stop at the code that writes a watched value |
debug_run_to_stop | Continue/launch toward a bounded meaningful stop |
debug_open_dump | Open supported postmortem dump/core targets |
debug_snapshot | Capture structured runtime evidence |
debug_status | Inspect debugger/session state |
debug_disconnect | Cleanly end a debugger session |
debug_sessions | Create, inspect, and remove isolated sessions |
Set QWEN_DAP_MCP_TOOLSET=forensics when deeper investigation is needed. It keeps the raw manual DAP surface hidden while adding:
| Forensics-only tool | Purpose |
|---|
debug_reverse_execution | Capability-gated reverseContinue / stepBack |
debug_cluster_crashes | Cluster normalized crash reports |
debug_regression_oracle | Classify original/changed/inconclusive reproductions |
debug_child_requests | Inspect fail-closed child/fork reverse requests |
debug_adopt_child | Explicitly adopt one reviewed startDebugging child into an isolated session when QWEN_DAP_MCP_CHILD_DEBUG=1 |
debug_time_travel | Bounded rr recording/replay planning and reverse workflows |
debug_thread_timeline | Multi-thread progress and explicit-owner lock graph |
debug_symbol_doctor | Binary identity, local symbols, and PDB/DWARF mismatch diagnosis |
debug_dump_batch | Bounded crash-dump fleet analysis |
debug_crash_families | Exact/semantic/family crash comparison |
debug_cpp_object | Read-only C++ object/vtable inspection |
debug_evidence_bundle | JSON/Markdown/SARIF evidence handoff |
debug_adapter_doctor | Adapter capability, rr, and security-profile audit |
Set QWEN_DAP_MCP_TOOLSET=full only when raw stacks/scopes/variables, manual breakpoints/watchpoints, evaluate, memory reads, stepping, or adapter-specific controls are intentionally required. See docs/toolsets.md.
Debugger support
| Adapter / target | Supported use |
|---|
| CodeLLDB | Local native launch/attach and Windows minidump workflows |
LLVM lldb-dap | Native launch/attach, core-file inspection, and lldb-server gdbserver remote attach |
| GNU GDB 14+ DAP | Native launch/attach, core-file workflows, and hardened gdbserver remote attach |
Adapter discovery, prerequisites, and platform-specific setup are documented in docs/README.md.
More than raw DAP
Raw DAP is intentionally low level. qwen-dap-mcp keeps raw debugger access available in the full toolset, but its default surface focuses on workflows an agent can reason about directly.
| Source only | Raw DAP | qwen-dap-mcp agent tools |
|---|
| Runtime debugger evidence | — | ✓ | ✓ |
| High-level crash diagnosis | — | — | ✓ |
| All-thread hang triage | — | manual | ✓ |
| Good-vs-bad semantic diff | — | manual | ✓ |
| Explicit bounded fix/verify state | — | — | ✓ |
| Verification fingerprinting | — | — | ✓ |
| Causal writer chain | — | manual | ✓ |
| Progress sampling / busy-loop triage | — | manual | ✓ |
| Sanitizer + symbols + ABI report correlation | — | manual | ✓ |
Safety by design
A debugger can execute and mutate target state, so the bridge treats that power explicitly.
- No arbitrary shell tool is exposed by the MCP server.
- No source-writing primitive is exposed by the MCP server.
- No general memory-write primitive is part of the default agent surface.
- Remote endpoints are validated and non-loopback access requires explicit allowlisting.
- Autonomous workflow state is explicit rather than hidden inside a background loop.
- Optional HOL Guard 2.2+ integration can fail closed before protected adapter startup or executable/mutating DAP actions cross the debugger boundary.
Read the full policy and threat model in docs/hol-guard.md and SECURITY.md.
Repro labs and benchmark harness
The repository includes deterministic native fixtures so behavior can be tested instead of demonstrated only with screenshots:
npm run demo:build -- null-pointer
npm run demo:repro -- null-pointer
npm run demo:hang:build -- deadlock
npm run demo:hang:repro -- deadlock
benchmark/ also contains a reproducible comparison harness for source-only, dap-raw, and qwen-dap-mcp workflows. It deliberately ships without invented performance numbers; publishable results should record the exact model, settings, commit, reproduction, raw outcome, and verification status.
Documentation
Start with the documentation index.
Development
Requirements: Node.js 20+.
git clone https://github.com/SLP-DEV1/qwen-dap-mcp.git
cd qwen-dap-mcp
npm ci
npm run check
npm run check builds TypeScript, runs the test suite, and validates the self-contained Qwen extension package. CI additionally exercises native crash/hang fixtures, adapter-specific real smoke tests, package output, HOL Guard compatibility, and the container build.
See CONTRIBUTING.md before opening a pull request.
Distribution
Published as:
- npm:
@slp-dev1/qwen-dap-mcp
- MCP Registry:
io.github.SLP-DEV1/qwen-dap-mcp
- Qwen Code extension:
qwen extensions install SLP-DEV1/qwen-dap-mcp
- GitHub Releases: self-contained extension archives
Current release details are in CHANGELOG.md and GitHub Releases.
Contributing
Bug reports, reproducible native failure cases, adapter compatibility findings, documentation fixes, and focused feature proposals are welcome. Please keep additions evidence-driven and prefer high-level agent workflows over expanding the default surface with raw debugger commands.
If this project saves you a debugging session, consider starring the repository — it helps other MCP and coding-agent users discover it.
License
Apache-2.0. See LICENSE and NOTICE.