ASP.NET Core Debugger — MCP Server for AI Agents

ASP.NET Core 调试 MCP 服务

跨平台 .NET 调试 MCP——可在 Linux、macOS 和 Windows 上运行。

一款采用 MIT 许可证的 MCP 服务，可让 AI Agent（Claude 等）调试你的 .NET / ASP.NET Core 应用——已为所有平台捆绑 netcoredbg，无需安装其他内容。

不再是“我觉得 bug 在第 42 行附近，试试这个”，Agent 会运行你的代码、暂停执行、读取实际运行时值、修改状态来测试修复方案，并根据实际观察到的情况给出回答。

目录

• 实际演示 — 5 段对话展示 Agent 的工作方式
• 工作原理 — 架构图
• 3 步上手 — 安装并在 Claude 中注册
• 平台 — 支持的操作系统 / 架构矩阵
• 工具（27 个） — 按用途分组的完整工具列表
• 对比 — 与其他 .NET / DAP MCP 的比较
• 文档 — 安装、示例、工具参考、限制
• 许可证

实际演示

为什么我的 EF Core 查询返回空结果？

你

GET /users/active 返回 []，但我知道数据库中有活跃用户。实际执行的查询是什么？

Claude

我会在 UserRepository.GetActiveAsync 内暂停，并读取 EF Core 实际发送的内容。

SELECT u.*
FROM Users AS u
WHERE u.IsActive = 1 AND u.TenantId = @__tenantId_0

@__tenantId_0 = 0

SQL 没问题，参数却错了。TenantId = 0，但你的租户 ID 从 1 开始。 ICurrentUser.TenantId 在存储库构造函数中读取——此时请求作用域尚未解析它。修复方法：在查询中读取租户（或通过 IHttpContextAccessor 使用 HasQueryFilter 应用租户条件），不要在构造时捕获它。

为什么我的 JWT 身份验证返回 401？

你

Anna 访问 /admin/users 时收到 401，但她的令牌看起来有效。身份验证处理程序实际看到了什么？

Claude

我会在她的请求到达后，在 JwtBearerHandler.HandleAuthenticateAsync 内设置断点。

Token signature: ✓ valid
Claims built:
  name : anna
  role : User
  iss  : https://auth.staging.example
  aud  : app-api
  exp  : 2026-05-26T14:12:00Z      (not expired)

令牌验证没有问题——但声明是 role=User。你的终结点使用了 [Authorize(Roles="Admin")]。所以返回 401 是正确的：Anna 在上游实际上还不是管理员。 要么需要更新她的 IdP 记录，要么这个策略有误。

无需重启即可测试修复

你

我认为将 discount 上限设为 100 就能修复这个 bug。请验证这个猜想，不要让我改代码。

Claude

我会在下一次结账时于 ApplyDiscount 中暂停，并直接修改 discount 的值。

已在 PricingService.cs:47 暂停
  discount = 250        ← bug：叠加了两种促销

已将 discount 设为 100，并继续运行。

结果：
  subtotal = $400
  final    = $300
  refund-service 投诉数：0

将上限设为 100 能让后续流程恢复正常。猜想已确认——现在可以正式修改代码，并决定上限应放在哪里（ApplyDiscount 本身，还是上游的 PromoEngine）。

我的应用卡住了——到底是什么在阻塞？

你

staging 环境中的 /reports 一直卡住。请附加到进程并告诉我原因。

Claude

已附加。运行了 hang_analyze。

线程 12（HTTP 请求）
  → blockedOnTask    位于 ReportService.cs:38   Task.Wait() 等待 T#14

线程 14（工作线程）
  → blockedOnMonitor 位于 SqlConnectionPool.cs:91
                      正在等待 SqlConnection
                      （池上限=5，已占用=5）

这是典型的同步等待异步任务导致的死锁。线程 12 对一个任务调用 .Wait()，而该任务本身需要从已被占满的连接池中打开另一个 SqlConnection。它持有的连接要等任务完成后才能释放；而任务又必须等到有连接释放才能继续。修复方法：在 ReportService 中一路使用 await，或者不要在等待调用期间持有连接。

慢请求的时间到底花在哪里？

你

GET /order/42 耗时 800ms。我不想在各处都设置断点——只要告诉我时间花在哪里就行。

Claude

我会为你的订单处理管线自动插桩并发出请求。每个入口都会记录时间戳和参数，然后继续运行——代码运行速度接近正常水平。

[+   4ms] → OrderController.GetOrder()       id=42
[+   6ms] --→ OrderService.LookupOrder()     id=42
[+   9ms] ----→ OrderRepository.FetchById()  id=42
[+  14ms] ------→ SqlClient.ExecuteQuery()   sql="SELECT * FROM orders WHERE id=42"
[+ 287ms] ----→ EnrichmentService.Enrich()   raw="rows(...)"
[+ 781ms] ------→ HttpClient.PostAsync()     url="https://crm.internal/enrich"

耗时集中在 CRM 数据增强 HTTP 调用上——HttpClient.PostAsync 内部耗时 500ms。数据库本身只用了 5ms。可以考虑缓存 EnrichmentService.Enrich 的结果，或将其移出请求处理路径。

更多示例 →

工作原理

Claude (MCP client)
   │  MCP  (stdio / JSON-RPC)
   ▼
aspnetcore-debugger-mcp        ← this server
   │  DAP  (Debug Adapter Protocol)
   ▼
netcoredbg                     ← Samsung's MIT-licensed .NET debugger, child process
   │  ICorDebug
   ▼
target .NET process

这是一个协议桥接层，其上提供了便于 Agent 使用的组合工具——exception_autopsy、stack_explore、hang_analyze 和跟踪工具——可将多个 DAP 请求打包为一次工具调用。

3 步即可使用

1. 安装工具——需要 .NET 10 SDK。

   dotnet tool install -g AspNetCoreDebuggerMcp --prerelease
   

   软件包内置了适用于 linux-x64、linux-arm64、win-x64、osx-x64 和 osx-arm64 的预编译 netcoredbg——无需单独安装。
2. 向 Claude 注册——可以使用快速 CLI 命令：

   claude mcp add aspnetcore-debugger -- aspnetcore-debugger-mcp
   

   ……也可以直接编辑 .mcp.json（项目级）/ ~/.claude.json（全局）/ claude_desktop_config.json（Claude Desktop）：

   {
     "mcpServers": {
       "aspnetcore-debugger": {
         "command": "aspnetcore-debugger-mcp"
       }
     }
   }
   

3. 直接与 Claude 对话。 /mcp 可确认连接状态。之后只需描述你的需求——“这个端点为什么返回 null”——Agent 就会选择合适的工具。

完整安装说明与故障排查 →

平台

运行时会自动选择内置的 netcoredbg 二进制文件——无需针对不同平台分别安装。

操作系统	架构	状态
Linux	x64、arm64	✅ 支持（Samsung 预编译）
macOS	Intel（x64）、Apple Silicon（arm64）	✅ 支持（arm64 由我们构建，因为 Samsung 未提供）
Windows	x64	✅ 支持（Samsung 预编译）

主机上需要安装 .NET 10 SDK。MCP 服务本身是跨平台的 .NET 全局工具——所有平台使用相同的安装命令。

工具（27）

类别	工具	用途
会话	debug_launch, debug_attach, debug_disconnect, debug_state	启动、附加到或停止调试会话
执行	debug_continue, debug_pause, debug_step, breakpoint_wait	控制被调试程序并等待其停止
断点	breakpoint_set, breakpoint_set_function, breakpoint_set_exception, breakpoint_set_data, breakpoint_remove, breakpoint_list	行断点、函数断点、异常断点和数据断点
检查	threads_list, stacktrace_get, variables_get, variables_set, evaluate, stack_explore	检查和修改程序状态
异常剖析	exception_autopsy	一次调用：异常链 + 顶部堆栈帧 + 局部变量 + 源代码片段
挂起 / 死锁	hang_analyze	自动暂停，并对每个线程的阻塞模式进行分类（Monitor / Task / Semaphore / async / …）
请求追踪	trace_start, trace_get, trace_stop	服务端请求追踪 — 自动插桩调用链，并捕获每次进入时的参数
进程 I/O	process_read_output	读取被调试程序的 stdout/stderr
健康状态	debugger_health	快速检查 netcoredbg 是否已加载，以及随附的二进制文件是否可访问

完整工具参考（含参数）→

项目对比

项目	许可证	平台	实现方式	.NET
aspnetcore-debugger-mcp （本项目）	MIT	Linux + macOS + Windows	通过 DAP 使用 netcoredbg，并提供面向 ASP.NET 的组合工具（请求追踪、挂起分析）	原生，.NET 10
debug-mcp	AGPL-3.0	仅 Linux（计划支持 Win/macOS）	直接使用 ICorDebug、Roslyn 代码导航	原生，.NET 10
mcp-debugger	—	跨平台	DAP	通过外部调试器
dap-mcp	—	跨平台	DAP	通过外部调试器
LLDB MCP	NCSA	跨平台	原生 LLDB	否

各有侧重：本项目是采用 MIT 许可证、支持跨平台的选项，并在 DAP 之上提供面向 ASP.NET 的组合工具。debug-mcp 通过 ICorDebug 深入运行时内部，但目前仅支持 Linux，且采用 AGPL 许可证。

文档

• 安装与配置 — 3 个步骤，适用于 Claude Code 和 Desktop，并包含故障排查
• 可以用它做什么 — 可以让 Claude 帮你做的 7 件事
• 完整工具参考 — 每个工具的所有参数
• 已知限制 — 不适合使用此工具的情况，以及适配器和追踪限制
• macOS Apple Silicon — 构建 netcoredbg
• 参与贡献 — 仓库布局、测试和开发流程

许可证

MIT — 详见 LICENSE。基于 netcoredbg（MIT） 和 ModelContextProtocol SDK（MIT）构建。