Content
# 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
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available