内容
# mcp-netcoredbg
MCP 服务器，用于通过 [netcoredbg](https://github.com/Samsung/netcoredbg) 进行 .NET 调试。
使 AI 代理（例如 Claude）能够在 .NET 应用程序中设置断点、单步执行代码和检查变量。
## 架构
```
┌─────────┐ MCP ┌─────────────────┐ DAP ┌─────────────┐
│ Claude │ ──────────► │ mcp-netcoredbg │ ──────────► │ netcoredbg │
│ │ (工具) │ (此仓库) │ (标准输入/输出) │ (三星) │
└─────────┘ └─────────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ .NET 应用程序 │
└─────────────┘
```
## 工具
### 会话管理（v2.0 新增）
| 工具 | 描述 |
|------|-------------|
| `list_sessions` | 列出所有活动调试会话 |
| `select_session` | 设置默认会话以供命令使用 |
| `terminate_session` | 终止特定会话 |
### 启动和附加
| 工具 | 描述 |
|------|-------------|
| `launch` | 启动 .NET 应用程序的调试（DLL 路径） |
| `launch_watch` | **启动调试并启用热重载**，通过 `dotnet watch` |
| `stop_watch` | 停止热重载调试模式 |
| `attach` | 附加到正在运行的 .NET 进程 |
| `invoke` | **调用程序集中的特定方法**（可选调试） |
| `restart` | 重新启动被调试的程序（适用于 `launch` 模式） |
| `terminate` | 停止调试会话 |
### 断点
| 工具 | 描述 |
|------|-------------|
| `set_breakpoint` | 在文件:行设置断点（支持条件） |
| `remove_breakpoint` | 删除断点 |
| `list_breakpoints` | 列出所有活动断点 |
### 执行控制
| 工具 | 描述 |
|------|-------------|
| `continue` | 继续执行 |
| `pause` | 暂停执行 |
| `step_over` | 跳过当前行 |
| `step_into` | 进入函数调用 |
| `step_out` | 跳出当前函数 |
### 检查
| 工具 | 描述 |
|------|-------------|
| `stack_trace` | 获取当前调用栈 |
| `scopes` | 获取栈帧的变量范围 |
| `variables` | 从范围中获取变量 |
| `evaluate` | 在调试上下文中评估表达式 |
| `threads` | 列出所有线程 |
| `output` | 获取最近的程序输出 |
| `status` | 获取调试器状态 |
**注意：** 所有工具都接受可选的 `sessionId` 参数以针对特定会话。如果省略，则使用默认会话。
## 多会话调试（v2.0）
2.0 版本引入了对多个同时调试会话的支持。这允许您同时调试多个 .NET 应用程序 - 例如，一个 API 和一个后台工作器。
### 自动生成的会话 ID
当您在未指定 `sessionId` 的情况下启动调试会话时，会自动从项目/程序名称中派生一个：
- `TopServer.Service.Api` → 会话 ID：`api`
- `TopServer.Service.Worker` → 会话 ID：`worker`
- `MyApp.Web` → 会话 ID：`web`
- 自定义：显式指定 `sessionId` 参数
### 示例：同时调试 API + 工作器
```
# 启动 API 调试
launch_watch projectPath=/path/to/MyApp.Api launchProfile=https
→ 会话 'api' 已创建
# 在第二个会话中启动工作器
launch_watch projectPath=/path/to/MyApp.Worker launchProfile=default
→ 会话 'worker' 已创建
# 列出所有会话
list_sessions
→ api（默认）：watch - /path/to/MyApp.Api [运行中]
worker：watch - /path/to/MyApp.Worker [运行中]
# 在 API 中设置断点
set_breakpoint file=/path/to/ApiController.cs line=42 sessionId=api
# 在工作器中设置断点
set_breakpoint file=/path/to/WorkerService.cs line=100 sessionId=worker
# 继续 API 执行
continue sessionId=api
# 检查工作器状态
status sessionId=worker
# 切换默认会话
select_session sessionId=worker
# 现在，无需 sessionId 的命令将发送到工作器
continue # 继续工作器
```
### 会话管理命令
| 命令 | 描述 |
|---------|-------------|
| `list_sessions` | 显示所有活动会话及其状态 |
| `select_session` | 更改默认接收命令的会话 |
| `terminate_session` | 停止特定会话 |
### 向后兼容性
如果您只使用一个会话，其行为与 v1.x 相同 - 不需要 `sessionId` 参数。
## 方法调用（`invoke`）
`invoke` 工具允许您在 .NET 程序集中运行特定方法，而无需启动完整应用程序。这对于：
- 隔离测试单个方法
- 运行实用程序
- 在不通过整个应用程序的情况下调试特定代码路径
### 参数
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `assembly` | 字符串 | 是 | .NET DLL 的路径 |
| `type` | 字符串 | 是 | 完全限定的类型名称（例如，`MyApp.Services.Calculator`） |
| `method` | 字符串 | 是 | 要调用的方法名称 |
| `args` | 数组 | 否 | 方法参数作为 JSON 数组 |
| `ctorArgs` | 数组 | 否 | 构造函数参数（适用于实例方法） |
| `debug` | 布尔值 | 否 | 在调试器下启动以支持断点（默认：false） |
| `cwd` | 字符串 | 否 | 工作目录 |
### 示例
**静态方法：**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.StringUtils",
"method": "FormatName",
"args": ["John", "Doe"]
}
```
**带构造函数参数的实例方法：**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.Calculator",
"method": "Add",
"args": [5],
"ctorArgs": [10]
}
```
**启用调试（支持断点）：**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.Calculator",
"method": "Add",
"args": [5],
"debug": true
}
```
### 功能
- **静态方法**：只需提供类型、方法和参数
- **实例方法**：自动构造类型（如果需要，提供 `ctorArgs`）
- **自动 ILogger 注入**：`ILogger<T>` 参数自动解析
- **异步支持**：自动等待返回 Task 的方法
- **控制台捕获**：捕获 `Console.WriteLine` 输出
- **日志捕获**：捕获执行期间进行的 `ILogger` 调用
- **丰富的错误信息**：在失败时，显示可用的构造函数/方法以帮助您修复调用
### 输出格式
该工具返回结构化的 JSON 结果：
```json
{
"success": true,
"method": "MyApp.StringUtils.FormatName",
"args": ["John", "Doe"],
"returnType": "string",
"returnValue": "Doe, John",
"durationMs": 2.5,
"logs": [
{"level": "Information", "message": "Processing..."}
],
"stdout": ""
}
```
在错误时，它提供有帮助的诊断信息：
```json
{
"success": false,
"error": "Method not found",
"errorDetails": {
"type": "MyApp.StringUtils",
"reason": "Method 'DoSomething' not found",
"methods": [
{"name": "FormatName", "params": ["string firstName", "string lastName"], "returnType": "string", "isStatic": true}
]
}
}
```
## 热重载调试（`launch_watch`）
`launch_watch` 工具通过 `dotnet watch` 启用调试并支持热重载。当您进行代码更改时，应用程序会自动重启，调试器会重新连接 - 保留您的断点。
### 参数
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `projectPath` | 字符串 | 是 | .NET 项目目录的路径（包含 .csproj） |
| `launchProfile` | 字符串 | 否 | `Properties/launchSettings.json` 中的启动配置文件名称 |
| `args` | 数组 | 否 | 传递给 `dotnet watch` 的附加参数 |
### 示例
**基本用法：**
```json
{
"projectPath": "/path/to/MyApp"
}
```
**使用启动配置文件（推荐用于 ASP.NET 应用程序）：**
```json
{
"projectPath": "/path/to/MyApp.Api",
"launchProfile": "https"
}
```
启动配置文件对于 ASP.NET 应用程序很重要，因为它设置了：
- `ASPNETCORE_ENVIRONMENT`（例如，Development）
- `applicationUrl`（例如，https://localhost:7179）
- 其他正常运行所需环境变量
### 工作原理
1. 使用指定的项目启动 `dotnet watch run`
2. 等待应用程序构建并启动
3. 自动将调试器附加到正在运行的进程
4. 当您编辑代码并保存时，`dotnet watch` 会重建并重启
5. 调试器检测到重启并自动重新连接
6. 断点在重启期间保留
### 停止热重载模式
使用 `stop_watch` 以干净地终止调试器和 `dotnet watch` 进程。
### 状态信息
使用 `status` 查看热重载特定信息：
- 监视进程 PID
- 子应用程序 PID
- 调试器当前是否正在重新连接
## 先决条件
- [netcoredbg](https://github.com/Samsung/netcoredbg) 已安装并在 PATH 中
- Node.js 18+
- .NET SDK 8.0+（用于构建托管和目标应用程序）
## 安装
```bash
# 安装 netcoredbg（Linux x64 示例）
curl -sLO https://github.com/Samsung/netcoredbg/releases/download/3.1.3-1062/netcoredbg-linux-amd64.tar.gz
tar xzf netcoredbg-linux-amd64.tar.gz
sudo mv netcoredbg /opt/netcoredbg
sudo ln -sf /opt/netcoredbg/netcoredbg /usr/local/bin/netcoredbg
# 构建此 MCP 服务器
npm install
npm run build
# 方法调用托管程序在首次使用时自动构建
```
## 与 Claude Code 结合使用
**快速安装：**
```bash
# 克隆并构建
git clone https://github.com/AerialByte/mcp-netcoredbg.git
cd mcp-netcoredbg && npm install && npm run build
# 添加到 Claude Code
claude mcp add netcoredbg -- node $(pwd)/dist/index.js
```
**或手动** 将以下内容添加到您的 Claude Code MCP 设置中：
```json
{
"mcpServers": {
"netcoredbg": {
"command": "node",
"args": ["/path/to/mcp-netcoredbg/dist/index.js"]
}
}
}
```
## 安全
此工具启动并控制调试器。按照设计，它可以：
- 执行任意 .NET 应用程序
- 在被调试的进程中评估表达式
- 检查内存和变量
仅与您信任的代码一起使用。不要调试不受信任的应用程序。
## 示例会话
### 完整应用程序调试
1. 使用调试符号构建 .NET 应用程序：`dotnet build --configuration Debug`
2. 使用 DLL 路径启动调试器：`launch`
3. 在文件:行设置断点：`set_breakpoint`
4. 继续/单步执行代码
5. 使用 `scopes` 和 `variables` 检查变量
6. 使用 `evaluate` 评估表达式
7. 完成后终止
### 方法调用（快速测试）
1. 构建目标程序集：`dotnet build`
2. 使用类型和方法名称调用 `invoke`
3. 如果失败，请检查错误以获取可用的构造函数/方法
4. 用于调试：首先设置断点，然后使用 `invoke` 并启用 `debug: true`
## 代理指南
在使用此 MCP 服务器作为 AI 代理时：
### 在 `launch` 和 `invoke` 之间选择
- 使用 **`invoke`** 时，您希望隔离测试特定方法
- 使用 **`launch`** 时，您需要运行完整应用程序或调试复杂场景
### 有效使用 `invoke`
1. **从简单开始**：尝试不使用 `ctorArgs` - 托管程序将使用无参数构造函数或自动注入 `ILogger<T>`
2. **迭代处理错误**：如果调用失败，错误响应包括可用的方法/构造函数。使用此信息来纠正调用。
3. **用于调试特定方法**：
```
1. 首先在源文件中设置断点
2. 调用 invoke 并启用 debug: true
3. 使用 continue/step_over/step_into 导航
4. 使用 output 查看最终结果
```
4. **参数是 JSON**：将参数作为 JSON 数组传递。托管程序处理类型转换：
- 字符串：`"hello"`
- 数字：`42`、`3.14`
- 布尔值：`true`、`false`
- 空值：`null`
- 对象：`{"name": "Alice", "age": 30}`
### 常见模式
**测试实用程序方法：**
```
invoke assembly=/path/to.dll type=MyApp.Utils method=Parse args=["input"]
```
**使用构造函数注入测试：**
```
invoke assembly=/path/to.dll type=MyApp.Service method=Process ctorArgs=[100] args=["data"]
```
**调试失败的方法：**
```
1. set_breakpoint file=/path/to/Service.cs line=42
2. invoke assembly=/path/to.dll type=MyApp.Service method=Process args=["bad-input"] debug=true
3. （断点命中）
4. variables variablesReference=1
5. continue
6. output
```
## 许可证
MIT
