调试适配器MCP服务器

dap-mcp-server

An MCP (Model Context Protocol) server that wraps the Debug Adapter Protocol (DAP), enabling AI agents to use real debuggers instead of relying on print statements and log analysis.

What This Is

When AI coding agents encounter bugs, they typically resort to adding console.log statements or reading stack traces. This MCP server gives them access to actual debuggers — setting breakpoints, stepping through code, inspecting variables, and evaluating expressions — through any debug adapter that implements DAP.

The server spawns debug adapters as child processes and exposes a small set of coarse-grained MCP tools optimized for how an AI agent thinks about debugging: "launch this program, stop here, show me what's happening."

Supported Debug Adapters

Any DAP-compliant debug adapter works. Built-in defaults for:

Additional adapters, and project-specific paths for the built-ins, can be registered via configure_adapter or config files.

Launch recipes are built in

The per-language incantations that usually stand between an agent and its first breakpoint ship with the server:

• PHP — the php adapter's launchDefaults carry the xdebug runtimeArgs and listen port. They are merged into a user-configured php entry, so you only supply the phpDebug.js path. If PHP still runs past a breakpoint, the result carries a hint pointing at xdebug.
• Rust — sessions that break in .rs files load lldb_lookup.py from the active toolchain's sysroot, so String, &str, Vec and HashMap render as values instead of raw structs. debug_at defaults program to target/debug/<package name>.
• Go — cwd is mirrored to dlvCwd so delve builds from the module directory.
• Java / JDWP — debug_doctor prints the -agentlib:jdwp=… line to start the JVM with; debug_attach accepts breakpoints so they bind before a suspend=y VM resumes.

debug_doctor and debug_at detect the language from manifests (pyproject.toml, go.mod, Cargo.toml, composer.json, pom.xml, build.gradle, CMakeLists.txt, package.json), from the breakpoint file's extension, and — for manifest-less script directories — from the source files in cwd and cwd/src.

MCP Tools

Installation

npm install -g dap-mcp-server

Or from source:

git clone <repo-url>
cd dap-mcp-server
npm install
npm run build

Usage with Claude Code

Register the server for the current user:

claude mcp add --scope user dap -- npx -y dap-mcp-server

The repository also contains a Claude Code plugin that bundles the MCP declaration and the activation skill. During local development, validate and load it with:

claude plugin validate integrations/claude/dap-debugging
claude --plugin-dir ./integrations/claude/dap-debugging

To configure MCP manually, use a project .mcp.json:

{
  "mcpServers": {
    "dap": {
      "command": "npx",
      "args": ["-y", "dap-mcp-server"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "dap": {
      "command": "dap-mcp-server"
    }
  }
}

A SKILL.md file is included in the package. After a local package install, copy it to the required skill directory layout:

mkdir -p .claude/skills/dap-debugging
cp node_modules/dap-mcp-server/SKILL.md .claude/skills/dap-debugging/SKILL.md

For a global npm install, the source file is under $(npm root -g)/dap-mcp-server/SKILL.md, not the project's node_modules.

Design

Tools are deliberately coarse-grained. debug_doctor makes setup failures actionable and debug_at performs the common detect → launch → stop → inspect → cleanup workflow in one call. A single get_state call returns threads, stack trace, scopes, and variables. The step tool blocks until the debuggee stops again and returns the new state.

Responses are budgeted for an LLM's context window:

• CPU register scopes are never fetched unless asked for by name; skipped scopes are listed in omittedScopes.
• step returns a compact state: frame-local scopes only, a 5-frame stack, no thread list for single-threaded programs, minified JSON.
• A state carries only output that no earlier debug_launch/step response has reported (capped at the newest 50 entries, with outputOmitted); get_output always has the whole buffer.
• debug_doctor details only the selected adapter (verbose: true for all); a not-ready debug_at answers with a one-line summary.

Stops on an exception include exception: { id, description, breakMode }. When the program ends, debug_run, debug_at, debug_launch and step report its exitCode if the adapter provides one.

Session IDs are optional when only one debug session is active. Breakpoints can be set inline with debug_launch for single-call debugging setup.

See docs/plans/2026-03-05-dap-wrapper-mcp-design.md for the full design document.

Configuration

Adapter configurations are stored in:

• ~/.dap-mcp/adapters.json — global defaults
• ./.dap-mcp/adapters.json — project-local overrides

License

MIT