Debugger Net MCP

调试器NetMcp

用于交互的MCP服务器。NET调试通过ICorDebug——在Linux内核6.12+上运行，没有脆弱的解决方法。

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code (LLM)                         │
└───────────────────────────┬─────────────────────────────────────┘
                            │ MCP stdio (JSON-RPC)
┌───────────────────────────▼─────────────────────────────────────┐
│               DebuggerNetMcp.Mcp (MCP Server)                    │
│  DebuggerTools.cs — 15 [McpServerTool] methods                   │
└───────────────────────────┬─────────────────────────────────────┘
                            │ C# method calls
┌───────────────────────────▼─────────────────────────────────────┐
│             DebuggerNetMcp.Core (Debug Engine)                   │
│  DotnetDebugger.cs — ICorDebug dispatch thread + event channel   │
│  PdbReader.cs      — Portable PDB source mapping                 │
│  VariableReader.cs — ICorDebugValue recursive inspection         │
└───────────┬──────────────────────────────────────────┬──────────┘
            │ P/Invoke                                  │ COM
┌───────────▼──────────┐                  ┌────────────▼──────────┐
│  libdbgshim.so       │                  │  ICorDebug (COM)       │
│  (DbgShim 10.0.14)   │                  │  ManagedCallbackHandler│
└──────────────────────┘                  └────────────┬──────────┘
                                                       │ ICorDebug API
                                          ┌────────────▼──────────┐
                                          │   .NET Process         │
                                          │   (debuggee)           │
                                          └───────────────────────┘

MCP服务器公开了15个工具，用于驱动 DotnetDebugger 发动机。发动机与通信。NET运行时通过两个渠道： libdbgshim.so （P/Invoke，引导调试会话）和 ICorDebug （COM，用于所有运行时控制和检查）。

先决条件

• .NET SDK 10.0(dotnet --version 应该显示 10.0.x)
• libdbgshim.so 从NuGet包 Microsoft.Diagnostics.DbgShim.linux-x64 （版本10.x或稳定版9.x）
• Linux（内核6.12+通过 strace 包装器脚本中的解决方法）
• strace --内核>=6.12所需： sudo apt install strace

安装libdbgshim.so

libdbgshim.so 已从中删除。NET 7+运行时，现在作为单独的NuGet包分发。

选项A：从NuGet（稳定版，.NET 9）下载：

mkdir -p /tmp/dbgshim && cd /tmp/dbgshim
dotnet new console -n tmp --no-restore
cd tmp
dotnet add package Microsoft.Diagnostics.DbgShim --version 9.0.*
cp ~/.nuget/packages/microsoft.diagnostics.dbgshim/*/runtimes/linux-x64/native/libdbgshim.so ~/.local/bin/

选项B：每晚下载（用于.NET 10预览版）：

每晚的饲料是： https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/flat2

包名称： Microsoft.Diagnostics.DbgShim.linux-x64

下载 .nupkg，提取并复制 runtimes/linux-x64/native/libdbgshim.so 到 ~/.local/bin/.

安装后，设置环境变量：

export DBGSHIM_PATH=~/.local/bin/libdbgshim.so
# Add to ~/.bashrc or ~/.zshrc for persistence

注： ~/.local/bin/ 不在默认设置中 libdbgshim.so 搜索路径。您必须设置 DBGSHIM_PATH 否则服务器将无法加载 DllNotFoundException.

构建

./build.sh

这编译了：

• 原生ptrace包装(libdotnetdbg.so)通过CMake
• DebuggerNetMcp.Core 和 DebuggerNetMcp.Mcp 处于释放模式

发布二进制文件位于： src/DebuggerNetMcp.Mcp/bin/Release/net10.0/DebuggerNetMcp.Mcp

安装

./install.sh

将MCP服务器在Claude Code中注册为 debugger-net 通过 claude mcp add.包装器脚本(debugger-net-mcp.sh)应用 strace -f -e trace=none Linux内核>=6.12兼容性所需的解决方法。

安装的先决条件：

• DBGSHIM_PATH 必须设置env-var（见上文）
• claude CLI必须位于PATH中

安装后，重新启动Claude Code以获取新的注册。通过以下方式进行验证：

claude mcp list

工具

所有15个工具都作为MCP工具公开。必须停止该进程（在断点、步骤或之后 debug_launch)在调用检查工具之前。

debug_launch

构建并启动一个。NET项目下的调试器。退货 state=stopped 一旦创建了流程并在入口处暂停。立即设置断点（它们将在模块加载时激活），然后调用 debug_continue 跑步。

参数：

• projectPath （string）--指向的路径 .csproj 文件或项目目录
• appDllPath （string）--编译后的路径 .dll （例如。 bin/Debug/net10.0/App.dll)
• firstChanceExceptions （bool，可选）——如果为true，在捕获每个抛出的异常之前停止它；默认值为FALSE

debug_attach

将调试器附加到运行中。NET进程按进程ID返回 state=attached 一旦建立了运行时连接。该过程继续运行；使用 debug_pause 停止检查。

参数：

• processId （number）--要附加的进程ID

debug_launch_test

使用以下命令在调试模式下启动xUnit测试项目 VSTEST_HOST_DEBUG=1.附于 testhost 处理并返回处理信息。调用此命令后，使用以下命令设置断点 debug_set_breakpoint 然后打电话 debug_continue.

参数：

• projectPath （string）--指向xUnit测试项目目录的绝对路径或 .csproj 文件
• filter （字符串，可选）--传递给的测试筛选器表达式 --filter （例如。 FullyQualifiedName~MyTest)

debug_disconnect

断开与被调试对象的连接并结束调试会话。将状态重置为空闲。

debug_status

返回当前调试器状态： idle （无会话）， running （进程运行）， stopped （在断点或步骤处），或 exited （进程已终止）。还返回服务器版本。

debug_set_breakpoint

在源文件行设置断点。返回稍后删除它所需的断点ID。

参数：

• dllPath （string）--编译的完整路径 .dll
• sourceFile （string）--源文件名（例如。 Program.cs)
• line （number）--从1开始的源行号

debug_remove_breakpoint

按ID删除以前设置的断点。

参数：

• breakpointId （number）--返回的断点ID debug_set_breakpoint

debug_continue

继续执行并等待下一个调试事件（断点命中、步骤完成、异常或进程退出）。返回事件。

debug_step_over

跳过当前源代码行，而不输入调用的方法。返回结果调试事件。

debug_step_into

进入当前源代码行，输入任何调用的方法。返回结果调试事件。

debug_step_out

退出当前方法并返回给调用者。返回结果调试事件。

debug_pause

暂停正在运行的进程。退货 state=stopped 立即（不触发任何事件-- ICorDebugController.Stop() 是同步的）。

debug_variables

获取当前停止位置的局部变量。适用于异步状态机——被提升的本地变量以其原始名称显示。

参数：

• thread_id （number，可选）——待检查的螺纹ID；0或省略使用当前停止的线程

debug_stacktrace

获取调用堆栈。没有 thread_id，返回所有活动线程的帧。随着 thread_id，返回该特定线程的帧。每个帧包括源文件、行号和方法名称（通过便携式PDB解析）。

参数：

• thread_id （number，可选）——获取堆栈的线程ID；0或省略返回所有活动线程

debug_evaluate

在当前停止位置计算局部变量名或简单表达式。

参数：

• expression （string）--要计算的变量名或简单的点表示法表达式

典型调试会话

从启动到退出的完整工作流程：

1. debug_launch(projectPath, appDllPath)
   → returns state=stopped (process suspended at entry)

2. debug_set_breakpoint(dllPath, "Program.cs", 42)
   → returns breakpoint id=1

3. debug_continue()
   → returns {type:"breakpointHit", breakpointId:1, topFrame:{file:"Program.cs", line:42}}

4. debug_variables()
   → returns [{name:"counter", type:"Int32", value:"0"}, ...]

5. debug_evaluate("counter")
   → returns {name:"counter", type:"Int32", value:"0"}

6. debug_step_over()
   → returns {type:"stopped", reason:"step", topFrame:{file:"Program.cs", line:43}}

7. debug_stacktrace()
   → returns all threads with their frame lists

8. debug_continue()
   → returns {type:"exited", exitCode:0}

9. debug_disconnect()
   → returns state=idle

运行测试

dotnet test

测试套件需要 DBGSHIM_PATH 待设置（与服务器要求相同）：

export DBGSHIM_PATH=~/.local/bin/libdbgshim.so
dotnet test

测试套件包括：

• 数学测试 --xUnit调试工作流的单元测试（与 debug_launch_test)
• Pdb阅读器测试 --PDB正向/反向查找的单元测试（不需要调试器）
• 调试器集成测试 --端到端：启动、断点、检查、步进、退出
• 调试器高级测试 --异常、多线程检查、过程附加

集成测试通过以下方式使用30秒超时 CancellationTokenSource.HelloDebug必须在调试模式下构建，然后才能运行：

dotnet build tests/HelloDebug -c Debug
dotnet test

故障排除

DllNotFoundException: libdbgshim.so

服务器找不到 libdbgshim.so.Set DBGSHIM_PATH:

export DBGSHIM_PATH=~/.local/bin/libdbgshim.so

默认搜索路径不包括 ~/.local/bin/。即使文件存在，也无法找到，除非 DBGSHIM_PATH 已明确设置。

Linux内核上的服务器崩溃>=6.12

包装器脚本(debugger-net-mcp.sh)应用 strace -f -e trace=none -o /dev/null Claude Code通过以下方式启动服务器时自动解决方法 install.sh.

如果您直接运行二进制文件（而不是通过Claude Code），请在前面加上strace：

strace -f -e trace=none -o /dev/null ./DebuggerNetMcp.Mcp

测试无限期挂起

集成测试使用30秒超时。如果测试挂起且从未超时，请确保 DBGSHIM_PATH 已设置--缺失 libdbgshim.so 在中导致静默初始化失败 DotnetDebugger 建设者。

debug_launch_test 未命中断点

确保xUnit项目首先在调试模式下构建：

dotnet build tests/MyTests -c Debug

这 VSTEST_HOST_DEBUG=1 机制要求 testhost 在执行测试代码之前等待调试器附加的进程。发布版本可能已经内联或优化了断点目标的确切IL偏移。

许可证

麻省理工学院