Debugmcpserver

    

调试MCP服务器

模型上下文协议（MCP）服务器，使用 调试适配器协议（DAP）.

附加到正在运行的进程、设置断点、遍历代码、检查变量、计算表达式——所有这些都是通过MCP工具调用完成的。支持多个调试适配器（.NET、Python、Node.js、C++）、并行调试会话、通过SSH进行远程调试和全面的转储文件分析（.NET通过ClrMD，本机Windows通过DbgEng/Week，跨平台通过DAP适配器）。

特性

• 多适配器支持 --配置多个调试适配器（netcoredbg、debugpy、js-debug、cpptools），并选择每个会话使用哪个适配器
• 完整的调试工作流程 --附加/启动、断点（行、条件、函数、异常、数据）、步进、变量检查、表达式求值
• 转储文件调试 --通过带有堆栈跟踪、变量检查、内存读取和拆卸的DAP适配器加载崩溃转储和核心转储以进行事后分析
• .NET转储分析（ClrMD） --内置。NET转储分析，无需外部工具。线程枚举、异常链、堆统计、对象检查、GC根分析、内存统计和异步状态机诊断。跨平台，麻省理工学院授权。
• 本地转储分析（DbgEng） --仅限Windows本机 .dmp 使用Winchester引擎（dbgeng.dll）进行分析。运行任何Winchester命令(!analyze -v, k, ~*k, dv, lm无需任何外部工具。
• 平行会议 --通过并发请求处理同时调试多个进程
• 远程调试 --通过SSH调试远程计算机上的进程，无需额外设置
• 存储器访问 --在任意地址读写原始内存
• 源视图 --查看当前停止位置周围的行号源代码
• 人类可读错误 --常见的DAP错误代码被转化为可操作的指导

平台兼容性

MCP服务器在Windows、Linux和macOS上运行。大多数功能适用于所有平台，但有些功能是特定于平台的：

核心调试

过程发现

转储分析

调试适配器

安装

.net工具（推荐）

需要 .NET 8 SDK 或稍后。

dotnet tool install -g DebugMcpServer

这将安装 debug-mcp-server 在PATH上全局命令。

自包含二进制文件

不带no的预构建二进制文件。所需的NET SDK可在 :

从源代码构建

git clone https://github.com/ms-bassem-srouji/DebugMcpServer.git
cd DebugMcpServer
dotnet build

快速开始

先决条件

• DAP兼容的调试适配器：

- .NET: netcoredbg （推荐） - python: 调试 - Node.js: js调试 - C: cpptools

配置

在以下位置创建配置文件 ~/.config/debug-mcp-server/appsettings.json 使用适配器路径：

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "C:\\tools\\netcoredbg\\netcoredbg.exe", "AdapterID": "coreclr", "RemotePath": "/usr/local/bin/netcoredbg" },
      { "Name": "python", "Path": "/usr/bin/debugpy", "AdapterID": "python" }
    ]
  }
}

此用户级配置会覆盖捆绑的默认值，并在工具更新中保留。如果您是从源代码构建的，您还可以编辑 src/DebugMcpServer/appsettings.json 直接。

MCP客户端配置

为您的AI客户端安装

克劳德代码（CLI和VS代码扩展）

添加到您的项目 .mcp.json 文件（或 ~/.claude/settings.json 全球）：

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

或者通过CLI：

claude mcp add debugger -- debug-mcp-server

Alternative: Build from source

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

CLI： claude mcp add debugger -- dotnet run --project /path/to/DebugMcpServer/src/DebugMcpServer

VS代码（GitHub副本）

添加到您的工作区 .vscode/mcp.json:

{
  "servers": {
    "debugger": {
      "type": "stdio",
      "command": "debug-mcp-server"
    }
  }
}

或添加到您的用户设置中(settings.json):

{
  "mcp": {
    "servers": {
      "debugger": {
        "type": "stdio",
        "command": "debug-mcp-server"
      }
    }
  }
}

Alternative: Build from source

{
  "servers": {
    "debugger": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

GitHub Copilot命令行界面

添加 ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "debugger": {
      "type": "stdio",
      "command": "debug-mcp-server"
    }
  }
}

Alternative: Build from source

{
  "mcpServers": {
    "debugger": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

光标

添加到您的项目 .cursor/mcp.json:

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

Alternative: Build from source

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

帆板运动

添加 ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "debugger": {
      "command": "debug-mcp-server"
    }
  }
}

Alternative: Build from source

{
  "mcpServers": {
    "debugger": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/DebugMcpServer/src/DebugMcpServer"]
    }
  }
}

备注：The debug-mcp-server 运行后，命令在PATH上可用 dotnet tool install -g DebugMcpServer。如果您使用的是从源代码配置构建，请替换 /path/to/DebugMcpServer 使用克隆存储库的实际路径。在Windows上，使用反斜杠或正斜杠（例如。， C:/repos/DebugMcpServer/src/DebugMcpServer).

工具

会话管理

断点

执行控制

检查

记忆

逃生舱口

.NET转储分析（ClrMD）

本地转储分析（仅限Windows）

示例提示

这些是您可以给AI助手的自然语言提示。助手将自动将它们翻译成相应的MCP工具调用。

入门指南

你： “您有什么调试适配器？” 你： “查找MyWebApp进程” 你： “使用.NET适配器将调试器附加到进程1234” 你： “发射 bin/Debug/net8.0/MyApp.exe 在调试器下”

设置断点

你： “在Program.cs的第42行设置断点” 你： “当orderId等于100时，在OrderService.cs的第85行添加条件断点” 你： “当我们进入ProcessPayment功能时中断” 你： “中断任何未处理的异常” 你： “在 _balance 变量--更改时中断” 你： “显示所有活动断点”

执行控制

你： “恢复执行” 你： “继续并等待20秒，等待下一个断点” 你： “跨过当前线路” 你： “进入此函数调用” 你： “退出当前功能” 你： “暂停进程”

检查状态

你： “向我展示我们停止的地方的源代码” 你： “调用堆栈是什么？” 你： “显示局部变量” 你： “什么是价值 customer.Name?" 你： “评估 orders.Where(o => o.Status == "Pending").Count()" 你： “扩展 orderItems 变量--显示其属性” 你： “正在运行哪些线程？切换到线程5” 你： “加载了哪些模块？”

修改状态

你： “设置 retryCount 变量为0“ 你： “将0xFF写入内存地址0x7FFE4A3B1000”

断点管理

你： “删除Program.cs中第42行的断点” 你： “清除所有断点并继续”

异常处理

你： “打破所有例外” 你： “刚刚发生了什么异常？显示详细信息和堆栈跟踪” 你： “仅在未处理的异常时中断”

会话管理

你： “进程是否仍在运行或已暂停？” 你： “列出所有调试会话” 你： “停止调试并分离” 你： “终止进程并结束调试会话”

远程调试

你： “列出远程服务器上的进程user@192.168.1.50" 你： “附加到5678号进程user@production-server使用.NET适配器 你： “通过SSH在临时服务器上调试MyApp进程”

转储文件调试

你： “使用cpp适配器在/tmp/core.12345加载崩溃转储” 你： “显示此转储文件中的调用堆栈” 你： “发生崩溃时，哪些线程正在运行？” 你： “在崩溃地址拆解20条指令” 你： “坠机现场的局部变量是什么？” 你： “显示此转储中加载的源文件”

.NET转储分析

你： “打开位于crash_12345.dmp的.NET崩溃转储” 你： “显示所有线程的托管堆栈跟踪” 你： “是什么例外导致了这次事故？” 你： “崩溃线程的堆栈上有哪些对象？” 你： “显示堆统计信息——哪些类型使用的内存最多？” 你： “在堆上查找MyApp.Order的所有实例，并向我显示它们的字段” 你： “是什么让这个物体保持活力？给我看看GC根” 你： “GC堆使用了多少内存？显示生成大小” 你： “是否有任何卡住的异步任务？显示异步状态” 你： “我认为我们有一个异步死锁——显示所有正在等待激活的任务”

本地转储分析（Windows）

你： “在C:\\dumps\\app.dmp加载本机崩溃转储” 你： “运行！analyze-v以获取碰撞分析” 你： “显示所有线程的堆栈跟踪” 你： “崩溃帧的局部变量是什么？” 你： “列出所有加载的模块” 你： “给我看看登记簿” 你： “在崩溃地址处分解功能” 你： “显示地址0x7FFE4A3B1000处的内存” 你： “显示MyStruct的字体布局”

高级工作流

你： “附加到MyApp进程，在以下情况下设置断点 orderTotal > 1000 在CheckoutService.cs的第55行，然后继续并等待它点击“ 你： “我正在调试一个竞争条件——附加到进程，中断所有异常，当它停止时，向我显示调用堆栈和所有局部变量” 你： “通读接下来的5行，并向我展示如何 total 每一步的变量变化” 你： 并排调试两个进程——连接到PID 1234和5678，在两者中设置相同的断点，并恢复两者

使用示例（工具调用）

作为参考，以下是上面的提示如何映射到实际的工具调用：

基本调试

1. list_processes(filter: "MyApp")           → find PID
2. attach_to_process(pid: 1234)              → get sessionId, process paused
3. set_breakpoint(file: "Program.cs", line: 42, condition: "x > 10")
4. continue_execution()                      → hits breakpoint
5. get_source()                              → see code context
6. get_callstack()                           → get frame IDs
7. get_variables(frameId: 1)                 → inspect locals
8. evaluate_expression(expression: "myList.Count")
9. step_over()                               → next line
10. detach_session()                          → done

通过SSH进行远程调试

1. list_processes(host: "user@server", filter: "myapp")
2. attach_to_process(pid: 5678, host: "user@server", adapter: "dotnet")
3. ... all tools work the same — DAP flows through SSH

转储文件调试

1. load_dump_file(dumpPath: "/tmp/core.12345", program: "/app/myapp", adapter: "cpp")
   → sessionId, process paused at crash site
2. get_callstack()                           → see crash stack trace
3. list_threads()                            → see all threads at crash time
4. get_variables(frameId: 0)                 → inspect locals at crash frame
5. disassemble(memoryReference: "0x4015a0")  → see assembly at crash address
6. get_loaded_sources()                      → discover available source files
7. read_memory(memoryReference: "0x7ffd1000") → examine raw memory
8. evaluate_expression(expression: "strlen(buffer)")
9. detach_session()                          → done

支持的适配器和转储格式：

转储调试平台指南

为什么有三种方法？ DAP调试（通过 load_dump_file)提供结构化变量检查、源映射和表达式求值，但需要兼容的调试适配器。ClrMD（通过 load_dotnet_dump)提供。NET特定的深度分析（堆统计、GC根、异常链）直接作为内置库，不需要外部工具或配置。DbgEng（通过 load_native_dump)提供完整的Winchester命令行访问权限，用于本机Windows转储分析，也内置了零配置。

执行控制工具(continue, step_*, pause)在转储会话中自动阻止，并显示明确的错误消息。

.NET转储分析（ClrMD）

为了。NET转储，使用内置的ClrMD集成（MIT许可，不需要外部工具）：

1. load_dotnet_dump(dumpPath: "crash_12345.dmp")
   → sessionId + runtime info (threads, exceptions, app domains)
2. dotnet_dump_threads()                          → all managed threads with stack traces
3. dotnet_dump_exceptions()                       → exceptions with type, message, inner chain
4. dotnet_dump_stack_objects(osThreadId: "0x9F64") → objects on the crashing thread's stack
5. dotnet_dump_heap_stats(filter: "Order")         → find specific types on the heap
6. dotnet_dump_find_objects(typeName: "Order")     → get addresses of all Order instances
7. dotnet_dump_inspect(address: "0x7fff..")        → object fields, array elements, string values
8. dotnet_dump_gc_roots(address: "0x7fff..")       → what's keeping this object alive?
9. dotnet_dump_memory_stats()                      → GC generation sizes, committed memory
10. dotnet_dump_async_state()                      → async Tasks status, stuck awaits
11. detach_session()                               → close session

由...驱动 微软。诊断。运行时（ClrMD） --同一个图书馆 dotnet-dump Visual Studio内部使用。无需安装外部工具。

本地转储分析（DbgEng--Windows）

对于本机Windows .dmp 文件，使用内置的DbgEng集成（使用Windows附带的DbgEng.dll——不需要外部工具）：

1. load_native_dump(dumpPath: "app_crash.dmp")
   → sessionId + thread count, engine version, common commands reference
2. native_dump_command(command: "!analyze -v")    → automated crash analysis
3. native_dump_command(command: "~*k")            → stack traces for all threads
4. native_dump_command(command: "~3s")            → switch to thread 3
5. native_dump_command(command: "dv")             → display local variables
6. native_dump_command(command: "r")              → show registers
7. native_dump_command(command: "lm")             → list loaded modules
8. native_dump_command(command: "u @rip L20")     → disassemble at crash location
9. native_dump_command(command: "dt MyStruct @rbp-0x40")  → display type layout
10. detach_session()                               → close session

由dbgeng.dll提供支持，该引擎与Winchester使用的引擎相同。任何Winchester命令都可以工作： k, ~*k, dv, r, lm, u, dd, db, dt, !analyze, !heap, !locks等等。

平行会议

1. attach_to_process(pid: 1234)  → sessionId: "aaa"
2. attach_to_process(pid: 5678)  → sessionId: "bbb"
3. continue_execution(sessionId: "aaa")           → runs in parallel
4. get_callstack(sessionId: "bbb")                → works immediately
5. list_sessions()                                 → see both sessions

建筑

MCP Client (Claude, etc.)
    │
    │ JSON-RPC over stdio
    │
┌───▼───────────────────────────┐
│  McpHostedService             │  ← Concurrent request dispatch
│  (MCP protocol handler)       │     with stdout write lock
├───────────────────────────────┤
│  Tools (46 total)             │  ← Each tool = one MCP capability
│  AttachToProcessTool          │
│  SetBreakpointTool            │
│  GetVariablesTool  ...        │
├───────────────────────────────┤
│  DapSessionRegistry           │  ← Thread-safe session store
│  (ConcurrentDictionary)       │     (multiple parallel sessions)
├───────────────────────────────┤
│  DapSession                   │  ← DAP protocol over stdin/stdout
│  (per debug adapter process)  │     or piped through SSH
├───────────────────────────────┤
│  Debug Adapter (netcoredbg)   │  ← Local process or remote via SSH
│  Debug Adapter (debugpy)      │
└───────────────────────────────┘

┌───────────────────────────────┐
│  DotnetDumpRegistry           │  ← .NET dump sessions (ClrMD)
│  DotnetDumpSession            │     In-process, no external tools
├───────────────────────────────┤
│  NativeDumpRegistry           │  ← Native dump sessions (DbgEng)
│  DbgEngSession                │     Windows only, WinDbg engine
└───────────────────────────────┘

安全

MCP服务器 仅执行显式配置的调试适配器进程 在 appsettings.json 由用户。它不会从任意位置自动发现、下载或执行二进制文件。

• 无自动发现：服务器不会扫描您的系统以查找调试适配器。每个适配器都必须由用户明确配置。
• 支持两种路径模式:

- 完整路径 （例如。， /usr/local/bin/netcoredbg)：服务器验证文件是否存在。 list_adapters 显示 "status": "found" 或 "not_found". - 裸命令名 （例如。， netcoredbg)：用户已将适配器放置在其PATH上。服务器将其传递给 Process.Start 这从PATH中解析出来。 list_adapters 显示 "status": "bare_command" 因为服务器在不执行二进制文件的情况下无法验证PATH解析。

• 无远程代码执行：调试适配器作为具有与MCP服务器相同权限的本地子进程运行。SSH远程调试仅连接到用户指定的主机。
• 适配器诊断：使用 list_adapters 要查看每个已配置适配器的状态，请安装缺少适配器的提示和配置文件位置。
• 用户配置覆盖：用户级配置(~/.config/debug-mcp-server/appsettings.json)优先于捆绑默认值。

配置

appsettings.json

默认配置附带了裸命令名——如果适配器在PATH上，它就可以开箱即用。在用户配置中用完整路径覆盖以进行显式控制。

{
  "Debug": {
    "Adapters": [
      {
        "Name": "dotnet",
        "Path": "netcoredbg",
        "AdapterID": "coreclr",
        "RemotePath": "/usr/local/bin/netcoredbg",
        "DumpArgumentName": "coreDumpPath"
      },
      {
        "Name": "cpp",
        "Path": "OpenDebugAD7",
        "AdapterID": "cppdbg",
        "DumpArgumentName": "coreDumpPath"
      }
    ],
    "AttachTimeoutSeconds": 30,
    "StepTimeoutSeconds": 3,
    "ContinueTimeoutSeconds": 25,
    "MaxPendingEvents": 100
  }
}

用户级别覆盖(~/.config/debug-mcp-server/appsettings.json)可以使用完整路径：

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "/usr/local/bin/netcoredbg", "AdapterID": "coreclr", "DumpArgumentName": "coreDumpPath" },
      { "Name": "cppvsdbg", "Path": "C:\\Program Files\\VS\\vsdbg.exe", "AdapterID": "cppvsdbg", "DumpArgumentName": "dumpPath" }
    ]
  }
}

测试

dotnet test

该测试套件包括500多个测试：确定性单元测试（无睡眠、无反射、无网络调用）、ClrMD集成测试（生成真实的.NET转储）和DbgEng集成测试（在Windows上生成真实的本机转储）。

项目结构

DebugMcpServer/
├── src/DebugMcpServer/
│   ├── Dap/                  # DAP protocol: session, events, SSH helper, error mapping
│   ├── DbgEng/              # Windows native dump analysis (dbgeng.dll/WinDbg engine)
│   ├── DotnetDump/          # .NET dump analysis (ClrMD / Microsoft.Diagnostics.Runtime)
│   ├── Options/              # Configuration models (adapters, timeouts)
│   ├── Server/               # MCP hosted service (stdio transport, concurrent dispatch)
│   └── Tools/                # All 46 MCP tools
├── tests/DebugMcpServer.Tests/
│   ├── Fakes/                # FakeSession, FakeSessionRegistry
│   └── Tests/                # 500+ unit & integration tests
└── samples/
    ├── SampleTarget/          # Sample .NET app for live debugging
    ├── CrashTarget/           # .NET app that generates a self-dump for testing
    └── NativeCrashTarget/     # C++ app that generates a native dump (CMake)

常见问题解答

我应该使用哪个适配器来转储文件？

Windows上的零配置： 两者都有。NET和本机Windows转储可以开箱即用，无需安装或配置适配器。ClrMD和DbgEng是内置的。

我在哪里可以找到适配器的可执行文件？

如何配置适配器？

将适配器路径添加到 ~/.config/debug-mcp-server/appsettings.json （用户配置，不受git跟踪）：

{
  "Debug": {
    "Adapters": [
      { "Name": "dotnet", "Path": "/usr/local/bin/netcoredbg", "AdapterID": "coreclr", "DumpArgumentName": "coreDumpPath" },
      { "Name": "cpp", "Path": "/path/to/OpenDebugAD7", "AdapterID": "cppdbg", "DumpArgumentName": "coreDumpPath" }
    ]
  }
}

使用 list_adapters 为了验证您的配置，它显示了哪些适配器被找到、丢失或配置为裸命令名。

我需要外部工具吗。NET转储分析？

号码 MCP服务器包括 ClrMD（微软诊断运行时） --Visual Studio和 dotnet-dump 内部使用。只需拨打电话 load_dotnet_dump 带着一个 .dmp 归档并使用结构化工具(dotnet_dump_threads, dotnet_dump_exceptions, dotnet_dump_heap_stats等等）。无需安装外部工具。

许可证

麻省理工学院