MCP Dap

mcp-dap

一种MCP服务器，通过调试适配器协议（DAP）将AI代理连接到调试适配器。

概述

mcp-dap 是一个用Rust编写的高性能、单二进制MCP（模型上下文协议）服务器。它允许AI编码代理（如Claude、Cursor或Gemini）跨多种编程语言本地启动、控制和检查调试会话。它没有重新发明调试，而是将MCP工具调用转换为标准DAP请求，利用经过实战测试的调试适配器。

支持的调试适配器

可以通过启用其他适配器 allowed_adapters 配置选项。

特性

• 单静态二进制 --没有Node.js，没有Python运行时，没有 npm install 这是服务器本身所必需的。
• LLM上下文保护 --自动截断大型变量值、数组和深度嵌套对象，以保护代理的上下文窗口。提供分页标记，用于按需检索其他数据。
• 自动上下文注入 --当被调试对象在断点处停止时，服务器读取周围的源代码行并将其包含在响应中，从而消除了额外的往返。
• 完整会话生命周期 --启动程序、附加到正在运行的进程、设置/删除断点、遍历代码、计算表达式、检查线程和调用堆栈，以及干净地断开连接。
• 异步和并发 --基于Tokio构建的调试器在不阻塞代理交互循环的情况下处理异步调试器事件。
• 适配器允许列表 --限制可以生成哪些调试适配器可执行文件，提供安全边界。

安装

快速安装（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/angalato08/mcp-dap/main/install.sh | sh

要安装特定版本或安装到自定义目录，请执行以下操作：

VERSION=0.2.0 INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/angalato08/mcp-dap/main/install.sh | sh

预构建二进制文件

从以下网址下载适用于您平台的二进制文件 页面。

来源

git clone https://github.com/angalato08/mcp-dap.git
cd mcp-dap
cargo install --path .

配置

mcp-dap 接受配置作为JSON对象。所有字段都有合理的默认值，可以省略。

{
  "max_variable_length": 1000,
  "source_context_lines": 5,
  "dap_timeout_secs": 30,
  "max_array_items": 10,
  "max_object_keys": 10,
  "max_nesting_depth": 3,
  "pagination_cache_max_entries": 50,
  "pagination_cache_ttl_secs": 300,
  "auto_context_max_scopes": 3,
  "auto_context_max_vars_per_scope": 20,
  "allowed_adapters": ["codelldb", "debugpy", "dlv", "python", "python3", "node", "lldb-dap"],
  "github_repo": "angalato08/mcp-dap",
  "github_allowed_labels": ["bug", "enhancement", "question"]
}

用法

mcp-dap 使用MCP协议通过stdio进行通信。在AI代理或IDE中将其配置为MCP服务器。

克劳德桌面/克劳德代码

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

光标

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

可用的MCP工具

快速启动工作流

必须按此顺序调用工具——每个步骤都需要前一个步骤：

debug_launch ──► debug_set_breakpoint ──► debug_continue ──► inspect ──► debug_disconnect
                                               ▲                │
                                               │                ▼
                                               ◄── debug_step ◄─┘

1. debug_launch （或 debug_attach)--启动调试会话
2. debug_set_breakpoint --在文件行位置设置断点
3. debug_continue --运行，直到断点命中或程序退出
4. 检查停止状态：

- debug_get_stack --使用源上下文查看调用堆栈 - debug_evaluate --计算表达式或读取变量 - debug_threads --列出所有线程

1. debug_step --介入/退出/重新介入，然后再次检查
2. debug_continue --继续到下一个断点（重复3-5）
3. debug_disconnect --结束会议并清理

一次只能有一个调试会话处于活动状态。呼叫 debug_disconnect 在开始新的之前。

示例会话

调试一个在除以零时死机的Rust程序：

// 1. Launch the program under CodeLLDB
debug_launch({
  "adapter_path": "codelldb",
  "program": "./target/debug/myapp",
  "program_args": ["--input", "data.csv"]
})
// → "Session started (CodeLLDB, pid 48291)"

// 2. Set a breakpoint
debug_set_breakpoint({
  "file": "/home/user/myapp/src/main.rs",
  "line": 42
})
// → "Breakpoint set at src/main.rs:42"

// 3. Run to the breakpoint
debug_continue({})
// → Stopped at src/main.rs:42 — shows source context + local variables

// 4. Inspect a variable
debug_evaluate({ "expression": "divisor" })
// → "divisor = 0 (i32)"

// 5. Step over to the next line
debug_step({ "granularity": "over" })
// → Stopped at src/main.rs:43 — shows updated source context

// 6. Evaluate an expression
debug_evaluate({ "expression": "dividend / (divisor + 1)" })
// → "42 (i32)"

// 7. Clean up
debug_disconnect({})
// → "Session disconnected"

调试适配器设置

mcp-dap要求每种语言都有一个调试适配器。安装所需的适配器：

CodeLLDB（Rust、C、C++）

CodeLLDB作为VS Code扩展分发。要提取独立适配器二进制文件：

# Download the latest release for your platform
# From: https://github.com/nickovs/codelldb-standalone/releases
# Or extract from the VS Code extension:
code --install-extension vadimcn.vscode-codelldb
# The adapter binary is at:
#   ~/.vscode/extensions/vadimcn.vscode-codelldb-*/adapter/codelldb

将适配器添加到您的 PATH，或在中使用完整路径 adapter_path.

debugpy（Python）

pip install debugpy

适配器被调用为 python -m debugpy.adapter.在你的 debug_launch 呼叫：

debug_launch({
  "adapter_path": "python",
  "adapter_args": ["-m", "debugpy.adapter"],
  "program": "my_script.py"
})

深入（Go）

go install github.com/go-delve/delve/cmd/dlv@latest

Delve使用TCP传输——适配器监听端口，mcp-dap连接到端口：

debug_launch({
  "adapter_path": "dlv",
  "adapter_args": ["dap", "--listen", "127.0.0.1:12345"],
  "transport": {"tcp": 12345},
  "program": "./cmd/myapp"
})

高级用法

TCP传输

一些适配器（如Delve）通过TCP而不是stdio进行通信。使用 transport 参数：

debug_launch({
  "adapter_path": "dlv",
  "adapter_args": ["dap", "--listen", "127.0.0.1:12345"],
  "transport": {"tcp": 12345},
  "program": "./main.go"
})

适配器启动，在指定端口上侦听，mcp-dap作为TCP客户端连接到它。

附加到正在运行的进程

使用 debug_attach 通过PID连接到已运行的进程：

debug_attach({
  "adapter_path": "codelldb",
  "pid": 12345
})

这对于调试长时间运行的服务器或难以从冷启动中复制的进程非常有用。适配器必须支持DAP attach 请求（CodeLLDB和debugpy-do；Delve使用不同的连接流）。

额外的启动参数

使用 extra_launch_args 传递合并到DAP启动请求中的适配器特定配置：

debug_launch({
  "adapter_path": "codelldb",
  "program": "./target/debug/myapp",
  "extra_launch_args": {
    "env": {"RUST_LOG": "debug"},
    "sourceMap": {"/build": "/src"},
    "initCommands": ["settings set target.x86-disassembly-flavor intel"]
  }
})

确切的键取决于调试适配器——有关支持的选项，请参阅其文档。

故障排除

建筑

[ AI Agent (Claude / Cursor / Gemini) ]
               |
               v  MCP Protocol (stdio)
               |
+------------------------------+
|           mcp-dap             |
|                              |
|  +------------------------+  |
|  |   MCP Tool Handlers    |  |
|  +-----------+------------+  |
|              |               |
|  +------------------------+  |
|  | Context Optimizer (LLM)|  |  <- Truncation, source injection
|  +-----------+------------+  |
|              |               |
|  +------------------------+  |
|  |   DAP State Machine    |  |
|  +-----------+------------+  |
+--------------+---------------+
               |
               v  DAP Protocol (stdio)
               |
     +---------+---------+
     |   Debug Adapter    |  (CodeLLDB, debugpy, delve)
     +---------+---------+
               |
               v
     [ Target Process ]

许可证

该项目根据 MIT许可证.