Qwen Dap MCP Server

Qwen DAP MCP — Native Debugger MCP for Claude Code, Codex, Qwen and AI Coding Agents

Debug native C/C++ crashes, hangs, deadlocks, Windows minidumps and core dumps with Claude Code, OpenAI Codex CLI, Qwen Code, Gemini CLI and other local MCP-compatible coding agents. Connect a real GDB, LLDB or CodeLLDB debugger through the Debug Adapter Protocol (DAP) and Model Context Protocol (MCP).

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.

Originally designed for Qwen Code, but usable from other local stdio MCP clients including Claude Code and Codex CLI. The AI model may run in the cloud; the debugger bridge and target binary still run where the MCP process is started.

Quick start · Capabilities · Debugger support · Safety · Docs · Contributing

Maintained Apache-2.0 fork of the original project by SLP-DEV1. The maintained source is spk-c/Qwen-dap-mcp; npm distributes @slp-dev1/qwen-dap-mcp. GitHub's main may be ahead of the latest published npm version. See fork notes and TypeScript migration status.

See it in action: C++ crash → evidence → verification

Illustrated architecture/workflow, not a captured AI session or fabricated debugger transcript. Reproduce an actual intentional crash in the project's own C++ fixture, collect a GDB backtrace, apply an illustrative change only in a temporary copy, and rerun the same command:

bash scripts/demo-native-crash.sh

Requires Linux, g++ and gdb. CI also executes the demo with a real debugger. View step-by-step verified demo and Claude/Codex MCP setup.

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 the current published npm version:

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

Or install the newest code directly from the maintained GitHub repository (this can be ahead of npm):

qwen extensions install spk-c/Qwen-dap-mcp

In Qwen Code, run /mcp and /skills to check that the qwen-dap-mcp server and the native-runtime-debug skill were discovered.

Prerequisites: Node.js 20+, and a supported native DAP debugger installed separately (CodeLLDB, LLVM lldb-dap, or GNU GDB DAP). This package is a bridge, not a bundled debugger. See platform setup.

Claude Code

Use a local Claude Code CLI with Node.js 20+ and an installed native DAP debugger:

claude mcp add --transport stdio --scope user qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
claude mcp list

See Claude Code native debugging guide for a setup check, test prompt, Windows notes and safety boundaries.

OpenAI Codex CLI

codex mcp add qwen-dap-mcp -- npx -y @slp-dev1/qwen-dap-mcp
codex mcp list

See Codex CLI + IDE debugging guide and versioned Codex TOML configuration.

Gemini CLI, Cursor, VS Code Copilot and other clients

Use a local stdio MCP entry pointing to npx -y @slp-dev1/qwen-dap-mcp. These clients have different configuration schemas: Gemini CLI and Cursor use mcpServers, while VS Code's .vscode/mcp.json uses servers. See multi-client setup and compatibility matrix and the tested configuration examples.

Cloud execution boundary: Claude Code or Codex CLI may call a cloud AI model while the CLI and debugger remain on your desktop. A browser-only Claude.ai/ChatGPT session or a remote Codex task cannot automatically access your PC's local stdio MCP server or Windows processes. Remote debugging requires separately authorized local execution or a protected connection; never expose a raw debugger port to the public internet.

Other stdio MCP clients

Run the published package with npx:

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

Configure a trusted local MCP client with:

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

When started without --help or --version, the CLI operates as a local stdio MCP server. Client configuration syntax may vary.

Update an existing installation

Update the npm-backed Qwen extension using the extension manager in your installed Qwen Code version, or reinstall the package with the command above. For npx, restart the MCP client to use newly resolved versions. npm releases are immutable: README changes appear on npmjs.com only after publishing a new package version, not when GitHub's README changes.

MCP client compatibility

The project includes automatic protocol-level stdio initialize + tools/list smoke tests with Claude Code, Codex CLI and Gemini client identities. These prove the shared MCP server protocol and example configuration consistency, not full end-to-end verification inside proprietary client applications. Native debugger E2E checks run separately. Run npm run test:clients from a built checkout.

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

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.

Set QWEN_DAP_MCP_TOOLSET=forensics when deeper investigation is needed. It keeps the raw manual DAP surface hidden while adding:

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 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.

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.

Development and reproducible verification

The repository includes native crash, hang, postmortem, Windows minidump, and remote-debugger fixtures. On a development checkout:

npm ci
npm run check
npm run check:pack

The checks include source/build integrity, MCP tests, document consistency, and inspection of the actual npm tarball. Native adapter end-to-end tests run in dedicated CI jobs and require their debugger/toolchain prerequisites. See the integration tests and the benchmark harness; no performance claims are made without recorded, reproducible results.

Practical debugging tutorials

These focused tutorials describe setup, expected debugger evidence and limitations with real native targets; the MCP bridge does not bundle a debugger.

• C/C++ crash debugging with Qwen Code — reproduce a native crash, capture stack/register/local evidence and verify a fix.
• Windows minidump debugging with CodeLLDB — inspect a crash dump with matching executable and symbols, without rerunning the crashing process.
• GDB/LLDB MCP setup and troubleshooting — install a DAP-capable adapter, discover MCP tools and resolve common adapter issues.
• Reproducible native crash and fix-verification demo — build a real owned C++ test fixture, collect a GDB SIGSEGV backtrace, apply a temporary guard, and rerun the same argument.

MCP Registry discovery

The maintained package publishes its MCP metadata under io.github.spk-c/qwen-dap-mcp when a matching npm version and official registry publication succeed. This is separate from any historical registry listing for the original author. See publishing and registry verification; a listing is not proof of a particular feature until its exact package version is verified.

Discover the maintained fork: Official MCP Registry · npm · Source and checksums · Directory-ready listing and attribution.

Documentation

Start with the documentation index.

Contributing and source build

Requirements: Node.js 20+.

git clone https://github.com/spk-c/Qwen-dap-mcp.git
cd qwen-dap-mcp
npm ci
npm run check

src/**/*.ts is the source of truth for 51 runtime modules; generated JavaScript mirrors and declarations are checked by CI. The full TypeScript strict: true migration is complete (issue #24, PRs #52–#56). CI enforces zero strict compiler diagnostics; native debugger support remains limited to the adapters and scenarios tested in CI.

See CONTRIBUTING.md before opening a pull request.

Distribution and release status

• npm: @slp-dev1/qwen-dap-mcp — installable published versions; verify the npm version before assuming a GitHub change is included.
• Maintained source and Qwen extension: spk-c/Qwen-dap-mcp — qwen extensions install spk-c/Qwen-dap-mcp.
• Release archives and changelog: GitHub Releases and CHANGELOG.md.
• Publishing: Releases are triggered by an intentional vX.Y.Z tag on a verified main commit or by manual workflow dispatch; npm Trusted Publishing uses GitHub Actions OIDC without a long-lived npm publication token.

The npm listing is updated from the README inside the published tarball. The GitHub README and npm README can temporarily differ until the next release.

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.