English | Русский

netcoredbg-mcp

Debug .NET applications from an MCP-capable coding agent without leaving the agent workflow. netcoredbg-mcp combines netcoredbg, the Debug Adapter Protocol, and Windows UI Automation so an agent can observe a running app, stop it deliberately, and inspect the state that explains the behavior.

Python 3.10+ · Windows GUI automation · 135 tools · 8 prompts · 4 resources · v0.23.17

The prepared v0.23.17 PATCH fixes nullable launch environments (#362): string overrides survive beside null, and null removes inherited variables, including Windows case variants. An idle adapter uses guarded drain/restart; with pre_build=False, removal requests refuse an active debuggee without stopping it. The parent and pre-build environments stay unchanged. Python remains the default. Upgrade and restart the MCP server; this does not hot-reload shared receivers. See the release notes for scope and verification boundaries; preparation is not publication.

What it enables

The Python package remains the default consumer entry point. Its wheel does not bundle the opt-in .NET preview executable. Corrected preview delivery is separate; B3 native step_over and Native Scene Probe work remain modern-host source-only and add no tools to the Python catalog.

In the source-built stateful host, start_debug also accepts an optional breakpoints array of up to 256 {file, line} entries. Each source file must exist; relative paths resolve from the host's working directory, and lines are one-based. The optional initialBreakpoints result records the debugger's initial verification only: verified: false can become bound after launch. Use the returned debugSessionId and, when available, the observed state.currentThreadId to inspect or step a stopped thread. This input is not part of the published read-only preview or the Python tool contract.

After launch, add_breakpoint(debugSessionId, file, line) adds an unconditional source breakpoint while the session is running or stopped. Each update sends the full requested set for that source, preserving earlier initial and runtime entries. A session holds at most 256 requested entries. Paths are normalized lexically; use the same path for a source rather than relying on symlink or hard-link aliases to identify it. The returned verified and optional actualLine are the adapter's current response, not proof of a hit. A refused update leaves the host's last confirmed requested set intact, but the adapter's applied set is not guaranteed; a later successful update resends the full set. A cancelled update with a possibly sent but unconfirmed request closes the session; cancellation after a fully written and confirmed response does not itself close it. remove_breakpoint(debugSessionId, file, line) removes all requested entries for that exact normalized source and requested line, including initial duplicates. It sends the remaining full source set to DAP, or an empty set for the last entry. A missing entry returns removed: false without a DAP write; the source file does not have to still exist. The same refusal, cancellation, and uncertain-write rules apply. Conditions, hit counts, and runtime listing are not yet supported by this native path.

To inspect a stopped frame, call get_call_stack with includeInspectionContext: true, then pass its inspectionContextId with the frame ID to get_scopes and with each returned reference to get_variables. Keep each numeric ID paired with the context from the same observation; a zero variable reference is a leaf. After a step, continuation, or other invalidation, fetch a new stack and context: the debugger may reuse numeric references. This source-built path does not yet support variable paging or filtering.

The source-built stateful host exposes get_output(debugSessionId, clear?, category?) for retained DAP output. It concatenates events in reader order; categories console, stdout, stderr, and telemetry are retained, and an omitted event category means console. Filtering is case-sensitive. A clear returns the current snapshot and empties the buffer only when category is omitted, null, or empty; a nonempty filter never clears it. After automatic terminal or reader-failure cleanup, both output tools remain available with the same token, while debugger control and UI operations are unavailable. Call stop_debug after reading to release the retained buffer; subsequent calls return DEBUG_SESSION_NOT_FOUND. Retained output is process-local and is lost when the host exits. Output not delivered by the adapter cannot be recovered.

By default, each event retains at most 100,000 Unicode code points before the ... [truncated] suffix, and the session retains at most 10,000,000 code points, evicting whole oldest events. NETCOREDBG_MAX_OUTPUT_ENTRY and NETCOREDBG_MAX_OUTPUT_BYTES override those limits at host startup; despite the latter name, the unit is code points, not encoded bytes. An invalid limit stops the host before it serves requests and names the variable on stderr without its value. Native search_output remains unavailable; Python remains the default.

get_output_tail(debugSessionId, lines?, category?) reads the same buffer without clearing it. It filters by category before splitting lines, returns totalLines, returnedLines, and LF-joined output, and defaults to the last 50 lines. For compatibility with the existing Python slicing behavior, lines: 0 returns all lines and a negative lines: -N skips the first N lines.

For a stopped session, continue_execution(debugSessionId, threadId) sends a DAP continue request without singleThread, so it resumes all threads. It waits up to 30 seconds after the write for the next observed stop or terminal event. An acknowledged timeout does not itself close the session; check state again before further inspection. An unacknowledged possible write closes the session rather than retrying an uncertain execution request. If stop_debug retires the session while a continue is waiting, an internal drain deadline still forces owned process-tree cleanup. The stop reports success only after cleanup completes; the owner-aborted continue returns DEBUG_SESSION_NOT_FOUND, not a DAP protocol error. Explicit caller/host cancellation and genuine cleanup/protocol failures remain failures.

The source-built Windows stateful host also exposes ui_invoke(debugSessionId, automationId) when FLAUI_BRIDGE_PATH points to its built FlaUI bridge. These are the only two arguments: both must be nonblank strings, and the exact, case-sensitive AutomationId is limited to 256 characters (no trimming or alternate selectors). The action requires exactly one readable match in the session's current bound debuggee main window and UIA InvokePattern; there is no mouse/keyboard fallback or dialog/window selection. Unreadable, incomplete (over 4,096 nodes), missing, ambiguous, changed, or unsupported targets are refused before invocation. Process incarnation and HWND ownership are rechecked after preparation and immediately before the UIA call; these checks are not an atomic UI-tree snapshot or a guarantee against later application changes.

Each action uses a separate one-shot helper with a 10-second lifetime and bounded cleanup. The EXE or dotnet-hosted DLL helper is created atomically inside a host-owned Windows kill-on-close Job using PROC_THREAD_ATTRIBUTE_JOB_LIST; there is no unassigned suspended-child interval. This action requires that attribute's documented Windows 10 / Server 2016-or-later support. Windows Server 2012/R2 support is not claimed for ui_invoke; unsupported atomic ownership refuses the action before dispatch, without a weaker fallback. The established debugger launcher retains its previous assignment path and compatibility. Host exit closes the helper Job. Debugger state, continue, and stop remain independently callable even if a UIA provider blocks at a breakpoint or modal handler. Session retirement or an observed DAP terminal event revokes action authority and cancels its in-flight helper; Native Scene observation identity remains available. If dispatch may have occurred but its result is lost, the result is UI_INVOKE_OUTCOME_UNKNOWN with outcome: "unknown", not a claim that no action ran. Never automatically retry it: inspect debugger/application state first. Success confirms only that InvokePattern returned, not arbitrary business completion. Native Scene IPC stays observation-only; this subset neither changes the Python default/catalog nor adds UI actions to the published read-only preview.

The separate native read-only preview exposes find_code_symbol, find_code_references and get_source_context. Each schema-2 manifest binds its exact proof generation; historical schema-1 A1 assets retain their one-tool meaning. The legacy-diagnostic preview, published as stateless-preview-v0.23.17-preview.3, uses preview-only MCP 2.3.0: missing/malformed required metadata returns correlated -32602, and unsupported versions return exact -32022; an ordinary corrected request continues in the same process. clientInfo remains optional. The retained candidate and freshly downloaded public package each passed all 18 generation-bound scenarios, including unchanged installed-Python rollback. Use the generation-bound instructions for the selected asset. Python remains the default. The accepted modern-only Program A/A3 boundary is below; deferred conformance and runtime servicing are not closed.

Preview control-plane policy

Program A/A3 establishes this opt-in, local, read-only front door on published preview.3. It does not establish full MCP conformance or complete the stateful .NET migration. The existing public 18-scenario consumer proves the supported journeys; source evidence and untested limits are distinguished below.

Earlier assets retain their own proof generations, including preview.2's 17 scenarios. Self-contained runtime 8.0.32 still contains the reviewed affected Brotli/socket components; no supported trigger was found on the inspected stdio route. runtime8-security-servicing remains open; replacing the system runtime does not repair this executable. Reassess these limits before expanding transport, trust, plugins or stateful behavior. Program B/C, default selection and Python retirement still require their own acceptance and authority.

Quick start

Install the package, let the setup wizard provision or discover the debugger, then register the public CLI with your MCP client. The command below is for Claude Code:

pipx install netcoredbg-mcp
netcoredbg-mcp --setup
claude mcp add --scope user netcoredbg -- netcoredbg-mcp --project-from-cwd

Restart the MCP client after changing its configuration. From a .NET workspace, ask the agent:

Set a breakpoint in Program.cs, run the application, and show the local values when it stops.

--project-from-cwd searches upward from the server's startup directory for a solution or .NET project. Use --project instead when the server must be pinned to one explicit project root.

Requirements

• Python 3.10 or later.
• pipx (recommended) or pip to install the package.
• A .NET SDK/runtime suitable for the application being debugged.
• netcoredbg. The setup wizard can download or discover it and scans compatible

dbgshim.dll files.

• An MCP client, such as Claude Code, Cursor, Cline, Roo Code, Windsurf,

Continue, or Claude Desktop.

• Windows for the GUI automation paths. Debugger functionality remains subject

to the target runtime and netcoredbg capabilities.

Install and configure

Recommended installation

pipx keeps the command-line server isolated from project environments:

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

The setup flow checks for a .NET SDK, provisions or finds netcoredbg, scans dbgshim candidates, builds the FlaUI bridge on Windows when required, and prints a client configuration snippet.

Package-managed installation

Use pip when your environment owns Python packages directly:

pip install --upgrade netcoredbg-mcp
$env:NETCOREDBG_PATH = "C:\Tools\netcoredbg\netcoredbg.exe"
netcoredbg-mcp --project C:\Work\MyDotNetApp

Run netcoredbg-mcp --setup after an upgrade if the target runtime changed or you need a new managed debugger or FlaUI bridge.

Client configuration

Use --project-from-cwd only when the client launches the server from the .NET workspace or supplies local MCP roots. When no explicit --project or operator environment pin is configured, local MCP roots take precedence. If there is neither an operator pin nor a usable local root, the server searches its startup directory for a solution, project, or Git marker and falls back to that startup directory when no marker exists.

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

For a client that starts servers from a stable global location, pin the target project explicitly instead of relying on that server startup directory:

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

If the debugger is managed outside the setup flow, set its path in the client process environment rather than committing it to a repository. Use the same project-selection mode that fits the client; this globally launched example pins its target explicitly:

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

Keep .mcp.json, .netcoredbg-mcp.launch.json, credentials, and local project paths out of source control.

Run from a source checkout

The installed CLI is the consumer route. Use a source checkout only while developing the server itself:

uv sync --locked --project C:\Work\netcoredbg-mcp
cd C:\Work\MyDotNetApp
uv run --no-sync --project C:\Work\netcoredbg-mcp netcoredbg-mcp --project-from-cwd

--no-sync prevents a supervised server restart from changing the shared virtual environment. Synchronize explicitly after changing dependencies or the lockfile.

First debugging session

start_debug launches the debug session and normally returns with it running. continue_execution, step_over, step_into, and step_out are long-poll operations: they return when the debuggee stops, exits, terminates, or reaches their timeout.

For console programs, use this sequence:

1. Add a breakpoint in the code path of interest.
2. Call start_debug with the program and, when appropriate, pre_build=true.
3. Wait for state=stopped.
4. Read get_call_stack, get_scopes, and get_variables.
5. Evaluate or step only while stopped.
6. Continue or terminate the session.

For WPF, Avalonia, and WinForms targets, use the Desktop UI sequence below instead. It starts the application without breakpoints, waits for the window to load, and only then adds a breakpoint; a pre-launch breakpoint can make the window appear hung.

A representative launch request is:

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

For .NET 6+ targets, a built .exe is accepted when its matching .dll and .runtimeconfig.json are present. Use inspect_debug_launch_compatibility(program) before launch when you need to inspect the selected runtime and shim without starting the process.

Desktop UI and visual evidence

While a GUI debuggee is RUNNING, use UI tools to observe and operate it. Once the UI thread is stopped at a breakpoint or pause, stack and variable inspection become available but the window will not respond normally until you continue.

start_debug(...)
ui_get_window_tree() # Wait for the application window to load.
add_breakpoint(file="MainWindow.xaml.cs", line=42)
ui_find_element(automation_id="saveButton")
ui_click(automation_id="saveButton")
# Trigger the breakpoint, then inspect state after it reports STOPPED.

Selected windows and query ownership

All UI and UI-evidence tools registered by one server share the same lazy backend and selected-window state. A successful ui_switch_window therefore scopes subsequent ui_find_element and ui_query calls to the same live window.

On the Windows FlaUI backend, unrooted element searches stay inside the selected window while it remains live. If that window closes, searches can use the sole remaining live top-level window of the connected process without reconnecting or changing the selected-window pointer. With no live windows, or with multiple live windows and a closed selection, unrooted searches fail explicitly; the bridge does not guess the first or largest window. Use ui_switch_window to select a live window, or pass a unique root_id (rootAutomationId on the bridge wire). Explicit roots do not change the selection and still reject ambiguous matches or windows outside the connected process. Window discovery is bound to the process instance opened at connect, not just its numeric PID. After that instance exits, a fresh connection is required; PID reuse cannot revive the old connection.

For ui_query(fields=["window"]), each result's window identifies the actual owning live top-level window of that resolved element, including explicit container roots and queries without an element selector. If ownership cannot be proven, title and automation_id are empty strings rather than the retained selected window's metadata.

Physical numeric keypad input

On the default Python server's Windows FlaUI path, ui_send_keys(keys="{NUMPAD1}", automation_id="myInput") sends the physical keypad 1 key, not the text "1" or the top-row digit key. ui_send_keys_focused(keys="{NUMPADENTER}") sends keypad Enter, distinct from {ENTER}. ui_send_keys_batch(keys=["{NUMPAD1}", "{NUMPADADD}", "{NUMPADENTER}"], automation_id="myInput") sends them in order; ui_key_sequence(keys=["NUMPAD1", "NUMPADENTER"], modifiers=[], automation_id="myInput") accepts names without braces.

Supported physical keys: {NUMPAD0}–{NUMPAD9}, {NUMPADADD}, {NUMPADSUBTRACT}, {NUMPADMULTIPLY}, {NUMPADDIVIDE}, {NUMPADDECIMAL}, {NUMPADENTER}, and {NUMLOCK} (17 keys). {NUMLOCK} presses and releases the lock key; it does not set a chosen lock state. Physical-key delivery is scoped to the Windows FlaUI backend, not the alternative UI backend or the opt-in .NET preview.

Screenshot modes

ui_take_screenshot() returns a WebP navigation preview with evidence_grade=preview_only. It is useful for locating the next UI action, not for asserting lossless visual evidence.

For an artifact that preserves the original raster and integrity metadata, opt in explicitly:

ui_take_screenshot(evidence=true)

Normally this mode returns evidence_grade=lossless_raster, persists a session-scoped PrintWindow PNG, and includes SHA-256 and geometry provenance. For a strict physical target, a probable-black PrintWindow raster may make one verified BitBlt attempt. That response is explicitly method=BitBlt, fallback=flash-focus, fallback_reason=probable_black_printwindow, and evidence_grade=typed_bitblt_fallback; it records the GetWindowDC authority, ROP, target PID, stable geometry/DPI, and foreground activation/restoration proof. Any malformed, black, unstable, mismatched, or incompletely proven fallback persists nothing. Any raw-derived crop requires evidence=true; preview-only captures do not provide it.

Without an expected target, persisted evidence reports target_comparability.status=UNASSERTED: it is valid lossless evidence, but does not prove a resize target. Supply all three physical target fields to compare the raw raster, not a derivative:

ui_take_screenshot(evidence=true, expected_hwnd=..., expected_physical_width=..., expected_physical_height=...)

The response reports MATCHED or MISMATCH; only MATCHED persists raw evidence. max_width affects only the preview and HD derivative, never this comparison. ui_resize_window() reports request-versus-readback target_comparability.status as MATCHED, MISMATCH, or UNAVAILABLE; resized=true confirms request completion, not target equality.

Use ui_take_annotated_screenshot() to receive Set-of-Mark labels, then invoke ui_click_annotated(element_id=...). Use ui_bring_to_front() only when the debuggee should intentionally leave stealth mode.

Tool map

The published MCP catalog has 135 tools.

The server also exposes four resources: debug://state, debug://breakpoints, debug://output, and debug://threads.

Eight prompts provide guided workflows: debug, debug-gui, debug-exception, debug-visual, debug-mistakes, investigate, debug-scenario, and dap-escape-hatch.

Process cleanup boundary

cleanup_processes(force=True) invokes the retained cleanup owners for debugger adapters and the FlaUI bridge created by this server. It does not turn a numeric PID, a DAP process event, or a saved record into permission to terminate a process. Old PID files are left untouched and inert; startup no longer sweeps their PIDs.

Stopping or cleaning up an attached debug session detaches from the target rather than terminating it. An explicit terminate_debug request remains a separate action. Cleaning up the FlaUI bridge does not grant ownership of the UI app. Cleanup failures remain incomplete results, not successful removal of records.

On Windows, cleanup uses retained process and Job handles. On POSIX, a private guardian controls its own live process group, including ordinary descendants that remain in that group. This is not a guarantee for daemonized or group-escaped descendants. In the force-cleanup response, terminated counts only confirmed forced terminations of owned roots caused by cleanup. It excludes natural or graceful exits and is not a count of callbacks, all stopped processes, or the whole-tree population. On POSIX, terminated remains 0 because the cleanup result does not establish the cause of the root's exit. This excludes unconfirmed causality; it does not mean that no processes were stopped. The whole-tree count remains unknown. tree_terminated is null because no whole-tree count is supplied. complete, remaining_owners, and errors report completion and unfinished cleanup; a failure returns an error with the same cleanup data. An empty observation registry alone does not prove that an operating-system tree drained.

Code search boundary

find_code_symbol, find_code_references, and get_source_context execute in the MCP server process. For search_source, source-file enumeration and the synchronous wait remain in that process; per-file source reading/scanning and regex matching run in a bounded dedicated Python subprocess, with a default five-second timeout and a maximum of 1,000 results. It honors only the project root .gitignore; nested ignore files are not consulted.

Runtime-smoke verification

Use runtime-smoke tools when you need a bounded, replayable verification rather than an ad hoc debugging conversation. Start with debug_hygiene_preflight, create an output checkpoint, run a validated plan, and close the run with its cleanup contract. verify_debug_freshness can prove that the live process still matches the expected workspace and artifacts.

For long-lived orchestration, use the lifecycle family: runtime_smoke_start, runtime_smoke_tail_events, runtime_smoke_get_result, and runtime_smoke_stop. See the production testing playbook for the consumer-mode release gate and the examples in docs/examples/ for WPF workflow, WPF DataGrid drag/drop, and diagnostic-plan shapes.

Input provenance

Runtime-smoke plans can distinguish the runner's own input from operator or foreign input. For an operator-free product verdict, set both input_policy.no_global_input=true and run_confidence.no_operator=true. The first setting prevents runner-controlled global input; the second requires input-monitor confidence evidence for the action window.

The resulting run_confidence classification is CLEAN_PROVEN when the monitor proves no operator input, DIRTY_UNPROVEN when it observes physical or foreign input or receives malformed/unattributable input evidence, or UNPROVEN when monitor evidence is unavailable or incomplete. Only CLEAN_PROVEN permits a product verdict.

When a plan permits runner-controlled global input, such as ui.drag, set input_policy.no_global_input=false and retain run_confidence.no_operator=true when a product verdict needs confidence evidence. Every covered input event must carry runner_injected provenance. A foreign_injected or physical event yields DIRTY_UNPROVEN; the caller must not treat that run as a product verdict.

Command-line reference

--project and --project-from-cwd are mutually exclusive. --enc must be used with setup or --setup.

Configuration reference

An explicit --project or project-root environment variable takes precedence over MCP client roots. Network/UNC client roots are rejected.

Explicit paths to existing DLL/EXE targets, source files, and build projects, plus output paths, need no separate debug permission, even outside the default project or worktree. Project-root selection provides context, not a directory allowlist. This removes MCP-wrapper policy, not a native Samsung netcoredbg operating-system sandbox. File and .NET target validity checks remain, as do the independent evidence, restore, and source-search guards.

Architecture

graph TB
    Client[MCP client] --> Server[netcoredbg-mcp stdio server]
    Server --> Tools[Debug, inspection, UI, smoke, and search tools]
    Tools --> Session[Session manager and process registry]
    Session --> DAP[DAP client]
    DAP --> Debugger[netcoredbg]
    Debugger --> App[.NET debuggee]
    Tools --> UI[Windows UI automation bridge]

The public console script starts a FastMCP stdio server. Its tool modules share one session manager, which owns debugger state, default project context, process cleanup, output, snapshots, and trace evidence. The DAP client talks to netcoredbg; Windows UI operations use the FlaUI bridge when available, with a pywinauto fallback for supported operations.

Troubleshooting

netcoredbg is not found

Symptom: startup or start_debug reports that the debugger cannot be found.

Cause: setup did not install a managed debugger and NETCOREDBG_PATH is not set.

Fix: run netcoredbg-mcp --setup, or set NETCOREDBG_PATH to the full netcoredbg.exe path in the MCP client environment.

Verify: run netcoredbg-mcp --setup again and confirm its output reports a found or provisioned debugger. Then confirm that the MCP client can list the server tools.

A breakpoint remains unverified

Symptom: the process does not stop at the requested source line.

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

Fix: use pre_build=true, debug a Debug build, verify that source and assembly match, and inspect list_breakpoints() for DAP-adjusted locations.

Verify: the response reports verified=true or gives the adjusted line.

A GUI appears frozen

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

Cause: its UI thread is stopped at a breakpoint or pause.

Fix: inspect state while stopped, then call continue_execution() before expecting the window to accept UI input.

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

Limitations

• GUI automation is Windows-focused.
• netcoredbg and DAP behavior depends on the target runtime and debugger

support.

• Memory tools require valid adapter-supported memory references.
• Native debugging, browser automation, and non-.NET runtimes are out of scope.

Contributing

See CONTRIBUTING.md for development setup, test expectations, sensitive-data rules, and pull-request requirements.

License

MIT. See LICENSE.