# mcp-netcoredbg
MCP server for .NET debugging via [netcoredbg](https://github.com/Samsung/netcoredbg).
Enables AI agents (Claude, etc.) to set breakpoints, step through code, and inspect variables in .NET applications.
## Architecture
```
┌─────────┐ MCP ┌─────────────────┐ DAP ┌─────────────┐
│ Claude │ ──────────► │ mcp-netcoredbg │ ──────────► │ netcoredbg │
│ │ (tools) │ (this repo) │ (stdio) │ (Samsung) │
└─────────┘ └─────────────────┘ └──────┬──────┘
│
▼
┌─────────────┐
│ .NET App │
└─────────────┘
```
## Tools
### Session Management (NEW in v2.0)
| Tool | Description |
|------|-------------|
| `list_sessions` | List all active debug sessions |
| `select_session` | Set the default session for commands |
| `terminate_session` | Terminate a specific session |
### Launch & Attach
| Tool | Description |
|------|-------------|
| `launch` | Start debugging a .NET application (DLL path) |
| `launch_watch` | **Start debugging with hot reload** via `dotnet watch` |
| `stop_watch` | Stop hot reload debugging mode |
| `attach` | Attach to a running .NET process |
| `invoke` | **Invoke a specific method** in an assembly (with optional debugging) |
| `restart` | Restart the debugged program (for `launch` mode) |
| `terminate` | Stop debugging session |
### Breakpoints
| Tool | Description |
|------|-------------|
| `set_breakpoint` | Set breakpoint at file:line (supports conditions) |
| `remove_breakpoint` | Remove a breakpoint |
| `list_breakpoints` | List all active breakpoints |
### Execution Control
| Tool | Description |
|------|-------------|
| `continue` | Continue execution |
| `pause` | Pause execution |
| `step_over` | Step over current line |
| `step_into` | Step into function call |
| `step_out` | Step out of current function |
### Inspection
| Tool | Description |
|------|-------------|
| `stack_trace` | Get current call stack |
| `scopes` | Get variable scopes for a stack frame |
| `variables` | Get variables from a scope |
| `evaluate` | Evaluate expression in debug context |
| `threads` | List all threads |
| `output` | Get recent program output |
| `status` | Get debugger status |
**Note:** All tools accept an optional `sessionId` parameter to target a specific session. If omitted, the default session is used.
## Multi-Session Debugging (v2.0)
Version 2.0 introduces support for multiple simultaneous debug sessions. This allows you to debug multiple .NET applications concurrently - for example, an API and a background worker.
### Auto-Generated Session IDs
When you launch a debug session without specifying a `sessionId`, one is automatically derived from the project/program name:
- `TopServer.Service.Api` → session ID: `api`
- `TopServer.Service.Worker` → session ID: `worker`
- `MyApp.Web` → session ID: `web`
- Custom: specify `sessionId` parameter explicitly
### Example: Debugging API + Worker Simultaneously
```
# Start API debugging
launch_watch projectPath=/path/to/MyApp.Api launchProfile=https
→ Session 'api' created
# Start Worker in a second session
launch_watch projectPath=/path/to/MyApp.Worker launchProfile=default
→ Session 'worker' created
# List all sessions
list_sessions
→ api (default): watch - /path/to/MyApp.Api [running]
worker: watch - /path/to/MyApp.Worker [running]
# Set breakpoint in API
set_breakpoint file=/path/to/ApiController.cs line=42 sessionId=api
# Set breakpoint in Worker
set_breakpoint file=/path/to/WorkerService.cs line=100 sessionId=worker
# Continue API execution
continue sessionId=api
# Check Worker status
status sessionId=worker
# Switch default session
select_session sessionId=worker
# Now commands without sessionId go to worker
continue # continues worker
```
### Session Management Commands
| Command | Description |
|---------|-------------|
| `list_sessions` | Show all active sessions with status |
| `select_session` | Change which session receives commands by default |
| `terminate_session` | Stop a specific session |
### Backward Compatibility
If you only use one session, the behavior is unchanged from v1.x - no `sessionId` parameter needed.
## Method Invocation (`invoke`)
The `invoke` tool lets you run a specific method from a .NET assembly without launching the full application. This is useful for:
- Testing individual methods in isolation
- Running utility functions
- Debugging specific code paths without going through the whole app
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `assembly` | string | Yes | Path to the .NET DLL |
| `type` | string | Yes | Fully qualified type name (e.g., `MyApp.Services.Calculator`) |
| `method` | string | Yes | Method name to invoke |
| `args` | array | No | Method arguments as JSON array |
| `ctorArgs` | array | No | Constructor arguments (for instance methods) |
| `debug` | boolean | No | Launch under debugger for breakpoint support (default: false) |
| `cwd` | string | No | Working directory |
### Examples
**Static method:**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.StringUtils",
"method": "FormatName",
"args": ["John", "Doe"]
}
```
**Instance method with constructor arguments:**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.Calculator",
"method": "Add",
"args": [5],
"ctorArgs": [10]
}
```
**With debugging (breakpoints supported):**
```json
{
"assembly": "/path/to/MyApp.dll",
"type": "MyApp.Calculator",
"method": "Add",
"args": [5],
"debug": true
}
```
### Features
- **Static methods**: Just provide type, method, and args
- **Instance methods**: Automatically constructs the type (provide `ctorArgs` if needed)
- **Auto ILogger injection**: `ILogger<T>` parameters are automatically resolved
- **Async support**: Automatically awaits Task-returning methods
- **Console capture**: Captures `Console.WriteLine` output
- **Log capture**: Captures `ILogger` calls made during execution
- **Rich errors**: On failure, shows available constructors/methods to help you fix the call
### Output Format
The tool returns a structured JSON result:
```json
{
"success": true,
"method": "MyApp.StringUtils.FormatName",
"args": ["John", "Doe"],
"returnType": "string",
"returnValue": "Doe, John",
"durationMs": 2.5,
"logs": [
{"level": "Information", "message": "Processing..."}
],
"stdout": ""
}
```
On error, it provides helpful diagnostics:
```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}
]
}
}
```
## Hot Reload Debugging (`launch_watch`)
The `launch_watch` tool enables debugging with hot reload support via `dotnet watch`. When you make code changes, the app automatically restarts and the debugger reconnects - preserving your breakpoints.
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `projectPath` | string | Yes | Path to the .NET project directory (containing .csproj) |
| `launchProfile` | string | No | Name of a launch profile from `Properties/launchSettings.json` |
| `args` | array | No | Additional arguments to pass to `dotnet watch` |
### Examples
**Basic usage:**
```json
{
"projectPath": "/path/to/MyApp"
}
```
**With launch profile (recommended for ASP.NET apps):**
```json
{
"projectPath": "/path/to/MyApp.Api",
"launchProfile": "https"
}
```
The launch profile is important for ASP.NET applications as it sets:
- `ASPNETCORE_ENVIRONMENT` (e.g., Development)
- `applicationUrl` (e.g., https://localhost:7179)
- Other environment variables needed for proper operation
### How It Works
1. Starts `dotnet watch run` with the specified project
2. Waits for the app to build and start
3. Automatically attaches the debugger to the running process
4. When you edit code and save, `dotnet watch` rebuilds and restarts
5. The debugger detects the restart and reconnects automatically
6. Breakpoints are preserved across restarts
### Stopping Hot Reload Mode
Use `stop_watch` to cleanly terminate both the debugger and the `dotnet watch` process.
### Status Information
Use `status` to see hot reload specific information:
- Watch process PID
- Child app PID
- Whether the debugger is currently reconnecting
## Prerequisites
- [netcoredbg](https://github.com/Samsung/netcoredbg) installed and in PATH
- Node.js 18+
- .NET SDK 8.0+ (for building the harness and target applications)
## Installation
```bash
# Install netcoredbg (example for 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
# Build this MCP server
npm install
npm run build
# The method invocation harness is auto-built on first use
```
## Usage with Claude Code
**Quick install:**
```bash
# Clone and build
git clone https://github.com/AerialByte/mcp-netcoredbg.git
cd mcp-netcoredbg && npm install && npm run build
# Add to Claude Code
claude mcp add netcoredbg -- node $(pwd)/dist/index.js
```
**Or manually** add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"netcoredbg": {
"command": "node",
"args": ["/path/to/mcp-netcoredbg/dist/index.js"]
}
}
}
```
## Security
This tool launches and controls a debugger. By design, it can:
- Execute arbitrary .NET applications
- Evaluate expressions within the debugged process
- Inspect memory and variables
Only use this with code you trust. Do not debug untrusted applications.
## Example Session
### Full Application Debugging
1. Build your .NET app with debug symbols: `dotnet build --configuration Debug`
2. Launch debugger: `launch` with the DLL path
3. Set breakpoints: `set_breakpoint` at file:line
4. Continue/step through code
5. Inspect variables with `scopes` and `variables`
6. Evaluate expressions with `evaluate`
7. Terminate when done
### Method Invocation (Quick Testing)
1. Build the target assembly: `dotnet build`
2. Use `invoke` with the type and method name
3. If it fails, check the error for available constructors/methods
4. For debugging: set breakpoints first, then use `invoke` with `debug: true`
## Agent Guidelines
When using this MCP server as an AI agent:
### Choosing Between `launch` and `invoke`
- Use **`invoke`** when you want to test a specific method in isolation
- Use **`launch`** when you need to run the full application or debug complex scenarios
### Using `invoke` Effectively
1. **Start simple**: Try without `ctorArgs` first - the harness will use parameterless constructors or auto-inject `ILogger<T>`
2. **Handle errors iteratively**: If invocation fails, the error response includes available methods/constructors. Use this to correct your call.
3. **For debugging specific methods**:
```
1. Set breakpoints in the source files first
2. Call invoke with debug: true
3. Use continue/step_over/step_into to navigate
4. Use output to see the final result
```
4. **Arguments are JSON**: Pass args as a JSON array. The harness handles type conversion:
- Strings: `"hello"`
- Numbers: `42`, `3.14`
- Booleans: `true`, `false`
- Null: `null`
- Objects: `{"name": "Alice", "age": 30}`
### Common Patterns
**Testing a utility method:**
```
invoke assembly=/path/to.dll type=MyApp.Utils method=Parse args=["input"]
```
**Testing with constructor injection:**
```
invoke assembly=/path/to.dll type=MyApp.Service method=Process ctorArgs=[100] args=["data"]
```
**Debugging a failing method:**
```
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. (breakpoint hits)
4. variables variablesReference=1
5. continue
6. output
```
## License
MIT
