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:

/mcp
/skills

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

Tool surfaces

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.

Topic	Guide
CodeLLDB on Windows	docs/CODELLDB_WINDOWS.md
LLVM lldb-dap	docs/lldb-dap.md
GNU GDB DAP	docs/gdb-dap.md
Remote debugging	docs/remote-debugging.md
Hang/deadlock analysis	docs/hang-debugging.md
Differential debugging	docs/differential-debugging.md
Runtime debugging v2	docs/runtime-debugging-v2.md
Agent vs full toolsets	docs/toolsets.md
HOL Guard integration	docs/hol-guard.md
Publishing / releases	docs/publishing.md

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.