English | Русский

netcoredbg-mcp

netcoredbg-mcp gives AI coding agents a real debugger for .NET applications. Through the Model Context Protocol, an agent can launch or attach to a process, set breakpoints, step through code, inspect variables, evaluate expressions, read debug output, and operate Windows UI Automation surfaces such as WPF, WinForms, and Avalonia windows without opening an IDE.

103 MCP tools · 8 prompts · 4 resources · 968 collected tests · release v0.14.0

Quick Links

• Start: Quick Start · Installation · Client Setup

• Use: First Debug Session · GUI App Debugging · Visual Inspection

• Reference: Available Tools · Resources · Prompts · Architecture

• Project: Contributing · Changelog · License

Related MCP server: MCP Debugger

What's New in v0.14.0

• Runtime smoke v2 state oracle — run_runtime_smoke now accepts netcoredbg.runtime_smoke.v2 plans with baseline setup, case transitions, before/after probes, diffs, cleanup aggregation, and compact evidence.

• Probe and template expansion — v2 adds UI property/text/grid probes, debug evaluation, tracepoints, output checks, JSONPath file assertions, process metrics, key-sequence actions, and generated A/B cases.

• Release-gated fixture coverage — critical tests and manual smoke entries now cover WPF and Avalonia state-oracle scenarios with runnable JSON examples.

• Adapter failure hardening — bridge and process-registry failures now return structured BLOCKED evidence instead of crashing the smoke runner or producing false PASS results.

Highlights

Quick Start

# 1. Install the MCP server
pipx install netcoredbg-mcp

# 2. Run first-time setup
netcoredbg-mcp --setup

# 3. Register it in Claude Code
claude mcp add netcoredbg -- netcoredbg-mcp --project-from-cwd

Then ask your agent:

Set a breakpoint in Program.cs, run the app, and inspect local variables when it stops.

Critical Notes

Installation

Requirements

• Windows for GUI automation and FlaUI/pywinauto workflows.

• Python 3.10 or newer.

• .NET SDK/runtime for the target application.

• netcoredbg; use netcoredbg-mcp --setup unless you need a custom install.

• An MCP client such as Claude Code, Cursor, Cline, Roo Code, Windsurf, Continue, or Claude Desktop.

Recommended Install

pipx install netcoredbg-mcp
netcoredbg-mcp --setup
netcoredbg-mcp --version

The setup wizard downloads or discovers netcoredbg, scans dbgshim versions, builds the FlaUI bridge when needed, and prints a ready-to-use MCP configuration snippet.

Manual Install

pip install netcoredbg-mcp
$env:NETCOREDBG_PATH = "C:\Tools\netcoredbg\netcoredbg.exe"
netcoredbg-mcp --project-from-cwd

Use a manual install when you pin a locally managed netcoredbg build or when a corporate environment blocks automatic downloads.

Upgrading

pipx upgrade netcoredbg-mcp
netcoredbg-mcp --setup

Run setup after an upgrade when the target .NET runtime changed, when you need a new FlaUI bridge build, or when MCP client snippets should be regenerated.

Configuration

Project Launch Profiles

start_debug can read .netcoredbg-mcp.launch.json from the resolved project root and apply profile environment variables to the debuggee process. The build process environment is not changed.

{
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "env": {
        "DOTNET_ENVIRONMENT": "Development",
        "APP_MODE": "Debug"
      },
      "inherit": ["PATH"]
    }
  }
}

Precedence is deterministic:

1. inherit copies only explicitly named variables from the MCP server process.

2. Profile env values override inherited values.

3. Direct start_debug(env={...}) values override the profile.

env values set to null are passed through to DAP as explicit nulls to request variable removal or unset semantics where the adapter supports it. Tool responses include only variable names, counts, profile name, source path, and redacted metadata; they never echo environment values.

The repository .gitignore excludes .netcoredbg-mcp.launch.json by default. Commit a profile only when it contains non-secret, shareable values.

Base Server Configuration

Use --project-from-cwd for CLI-based agents that start the server from the workspace. Use --project when the MCP client starts from a stable global location and you want to constrain all debug paths explicitly.

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"]
    }
  }
}

If setup did not install a managed netcoredbg, add NETCOREDBG_PATH:

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"],
      "env": {
        "NETCOREDBG_PATH": "C:\\Tools\\netcoredbg\\netcoredbg.exe"
      }
    }
  }
}

Project-Scoped Config

Use a project-local MCP config when a client supports it. Keep machine-specific secrets and binary paths outside git.

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project", "C:\\Work\\MyDotNetApp"]
    }
  }
}

Client Setup

Claude Code

claude mcp add netcoredbg -- netcoredbg-mcp --project-from-cwd

Cursor, Cline, Roo Code, Windsurf, Continue, Claude Desktop

Add the same server shape to the client-specific MCP configuration file:

{
  "mcpServers": {
    "netcoredbg": {
      "command": "netcoredbg-mcp",
      "args": ["--project-from-cwd"]
    }
  }
}

Common configuration locations:

First Debug Session

The Long-Poll Pattern

Execution tools wait for a meaningful debugger event. start_debug, continue_execution, step_over, step_into, and step_out return when the debuggee stops, exits, terminates, or times out.

Typical Workflow

1. Add a breakpoint in the code path you want to inspect.
2. Start debugging with pre_build=true.
3. Wait for state=stopped.
4. Read call stack, scopes, and variables.
5. Evaluate focused expressions or step to the next line.
6. Continue or terminate the session.

Pre-Build Launch Example

{
  "program": "bin/Debug/net8.0/MyApp.dll",
  "build_project": "MyApp.csproj",
  "pre_build": true,
  "stop_at_entry": false
}

For .NET 6+ applications, passing a built .exe is accepted when a matching .dll and .runtimeconfig.json exist. The server resolves the DLL target to avoid deps.json conflicts.

GUI App Debugging

The Rule

Do not use debugger inspection tools while a GUI app is running normally. First stop at a breakpoint or pause the process; otherwise stack, scopes, and variables are unavailable by design.

GUI Workflow

1. Launch the app.
2. Use ui_take_screenshot or ui_get_window_tree to observe the running UI.
3. Use UI tools to click, type, select, or wait for state changes.
4. Set a breakpoint before the code path you need to inspect.
5. Trigger the UI action.
6. When state=stopped, inspect variables and call stack.

Stealth Mode

Use stealth mode when the user should keep focus in another application while the agent launches and inspects the debuggee in the background.

start_debug(
    program="bin/Debug/net8.0/App.dll",
    build_project="App.csproj",
    stealth_mode=True,
)
ui_get_window_tree()
ui_click(automation_id="btnSave")

In stealth mode, UIA tree reads and automation-id clicks avoid activating the debuggee window. ui_send_keys and blank-screenshot fallbacks may use flash-focus: the bridge briefly brings the debuggee forward, performs the operation, and restores the previous foreground window. Call ui_bring_to_front() when the debuggee should explicitly leave stealth mode.

Visual Inspection

Screenshots return MCP image content, so vision-capable agents can inspect layout and state. Annotated screenshots add Set-of-Mark labels for elements that can be clicked with ui_click_annotated.

ui_take_screenshot()
ui_take_annotated_screenshot()
ui_click_annotated(element_id=3)

Runtime Smoke Evidence

For repeatable agent-side verification, use the runtime smoke tools together: debug_hygiene_preflight clears stale debugger state, output_checkpoint and output_assert_since prove output changed after a known point, verify_debug_freshness checks that the live process still matches the expected workspace and artifacts, and run_runtime_smoke executes a bounded scenario plan with cleanup.

The manual smoke fixtures now cover the baseline console/WinForms app, tests/fixtures/WpfSmokeApp, and tests/fixtures/AvaloniaSmokeApp. Build all three fixture projects before claiming full GUI smoke coverage; missing fixture binaries intentionally skip their corresponding manual scenarios.

For WPF product-smoke workflows, start from docs/examples/runtime-smoke-wpf-workflow-plan.json. It shows the accepted netcoredbg.runtime_smoke.v1 schema, steps operations for DataGrid snapshots/assertions, scoped ListBox item actions, output checkpoints, focus assertions, and cleanup.restore_files with graceful debug stop. The example launches the WPF fixture DLL through dotnet, so freshness expects expected_process_name: "dotnet" and expected_modules: ["WpfSmokeApp.dll"]. The matching manual scenario is WPF One-Call Runtime Smoke Workflow.

The WPF workflow now connects UI automation eagerly after launch, chooses a stable usable top-level window, merges structured GridPattern cell evidence with descendant text fallback, and restores fixture files even when Windows briefly holds attributes or locks. Avalonia remains a first-class compatibility target: its manual fixture is expected to produce bounded UNSUPPORTED or BLOCKED evidence for UIA gaps instead of being omitted from release checks.

For WPF DataGrid drag/drop and edge-scroll release proof, start from docs/examples/runtime-smoke-v2-drag-drop-grid.json. The v2 example shows ui.drag, before/after ui.grid.viewport probes, selected payload identity checks, negative no-op expectations, and fail-closed BLOCKED behavior when real pointer route or viewport evidence is unavailable. WinForms dragList primitive smoke is not a substitute for WPF DataGrid CR-001 acceptance.

Edit-and-Continue

apply_code_change applies supported source edits to a stopped .NET debug session without restarting the process. It is intended for method-body changes found during a live investigation; it is not a replacement for rebuilding when the shape of the program changes.

EnC Setup

Build an EnC-capable netcoredbg with the bundled setup flow:

netcoredbg-mcp setup --enc

The command runs scripts/build-netcoredbg-enc.ps1, installs the maintained thebtf/netcoredbg fork build with ncdbhook.dll, and places it in the managed ~/.netcoredbg-mcp/netcoredbg path that accepts the custom DAP applyDeltas request. On Windows x64, setup downloads the published 3.1.3-1062-enc.2 EnC build by default; pass -BuildFromSource to the script for a local source build. If ncdbhook.dll is missing, apply_code_change returns an actionable error instead of crashing.

Runtime Code Change Workflow

find_code_symbol(name="OrderService")
get_source_context(file="Services/OrderService.cs", line=42, radius=8)
apply_code_change(
    file="Services/OrderService.cs",
    edits=[{"start_line": 42, "end_line": 44, "new_text": "return fixedValue;"}],
)
continue_execution()

The debug session must be in STOPPED state. Successful changes update the source file and apply IL/metadata/PDB deltas through netcoredbg; the session remains STOPPED until you continue or step.

Rude edits such as adding fields, changing method signatures, or changing generics are rejected before runtime application. Use restart_debug(rebuild=True) for those changes.

Available Tools

MCP Resources

MCP Prompts

Multi-Agent Safety

When served through mcp-mux, mutating debug tools are session-owned. One agent can control a live debug session while other agents keep read-only observability through state, output, screenshot, and inspection tools. Ownership auto-releases after the configured inactivity timeout.

Architecture Overview

graph TB
    subgraph MCP["MCP Server"]
        MAIN["__main__.py"]
        SERVER["server.py"]
        PROMPTS["prompts.py"]
        TOOLS["tools/*"]
        SESSION["session/*"]
        BUILD["build/*"]
        UI["ui/*"]
        SETUP["setup/*"]
    end

    subgraph DAP["Debug Adapter Protocol"]
        CLIENT["dap/client.py"]
        PROTOCOL["dap/protocol.py"]
        EVENTS["dap/events.py"]
    end

    MAIN --> SERVER
    SERVER --> PROMPTS
    SERVER --> TOOLS
    TOOLS --> SESSION
    TOOLS --> BUILD
    TOOLS --> UI
    SESSION --> CLIENT
    CLIENT --> PROTOCOL
    CLIENT --> EVENTS
    CLIENT <-->|stdio JSON-RPC| NETCOREDBG["netcoredbg"]
    NETCOREDBG --> APP[".NET debuggee"]
    SETUP --> NETCOREDBG

How It Works

1. __main__.py parses CLI flags, configures project-root policy, and starts the FastMCP stdio server.

2. server.py registers tools, prompts, resources, progress notifications, and session ownership checks.

3. Tool modules keep debugger control, breakpoints, inspection, memory, output, process cleanup, and UI automation separate.

4. SessionManager owns debugger state, path validation, event handling, snapshots, tracepoints, output buffers, and process cleanup.

5. DAPClient speaks JSON-RPC over stdio to netcoredbg.

6. UI automation uses a FlaUI bridge on Windows, with pywinauto fallback where supported.

Command Line Options

netcoredbg-mcp --help
netcoredbg-mcp --version
netcoredbg-mcp --setup
netcoredbg-mcp setup --enc
netcoredbg-mcp --project C:\Work\MyApp
netcoredbg-mcp --project-from-cwd

--project and --project-from-cwd are mutually exclusive.

Environment Variables

Troubleshooting

netcoredbg is not found

Symptom: startup or start_debug reports that netcoredbg cannot be found.

Cause: setup has not installed a managed debugger and NETCOREDBG_PATH is not set.

Fix: run netcoredbg-mcp --setup, or set NETCOREDBG_PATH to the explicit netcoredbg.exe path.

Verify: netcoredbg-mcp --version succeeds and your MCP client can list the server tools.

Breakpoints do not bind

Symptom: a breakpoint stays unverified or the process never stops where expected.

Cause: stale build output, wrong target DLL, optimized Release binaries, or a line without executable IL.

Fix: run with pre_build=True, debug the Debug configuration, confirm the source file matches the built assembly, and inspect list_breakpoints() for DAP-adjusted lines.

Verify: the breakpoint response reports verified=true or includes the DAP line adjustment.

GUI appears frozen

Symptom: a WPF, WinForms, or Avalonia window stops repainting after a debug command.

Cause: the debugger stopped the UI thread at a breakpoint or pause.

Fix: inspect variables while stopped, then call continue_execution() before expecting the GUI to respond to clicks or keystrokes.

Verify: get_debug_state() reports running and screenshots update again.

Path is rejected in a worktree

Symptom: launch or build fails with a path validation error.

Cause: the project root was resolved to a different checkout, or the worktree path is outside the allowed root set.

Fix: use --project-from-cwd from the active worktree, or add the worktree prefix to NETCOREDBG_ALLOWED_PATHS.

Verify: start_debug accepts build and program paths under the worktree.

Limitations

• GUI automation is Windows-focused.

• netcoredbg and DAP capabilities vary by runtime and target application.

• Memory reads and writes require debug adapter support and valid memory references.

• Native debugging, browser automation, and non-.NET runtimes are out of scope.

Contributing

See CONTRIBUTING.md for setup, tests, PR expectations, and sensitive-data rules.

License

MIT. See LICENSE.