dotnet-mcp

dotnet-mcp

An MCP (Model Context Protocol) server for .NET workspaces. It gives coding agents compiler-accurate symbol navigation, source-generator attribution, Avalonia/MAUI XAML queries, and a restricted Workspace Edit surface (rename / diagnostic fix / code refactoring). It is not a generic file writer, shell, or LSP proxy.

Package id on NuGet: `Skymly.DotNetMcp` (CLI command: dnmcp). Requires .NET 10+.

What it can do

• Load .sln / .slnx / .slnf / SDK-style .csproj / .vbproj / .fsproj
• C# and VB.NET via Roslyn; F# via an FCS stack beside the Roslyn snapshot
• Resolve a name to a checksummed SymbolHandle, then go to definition, members, references, implementations, callers, type hierarchy
• Attribute handwritten vs source-generated members (generator assembly + type + version)
• Project diagnostics; list generators / generated sources / generator diagnostics; list dynamic invocations
• Avalonia .axaml and MAUI .xaml: class, xmlns, x:Name, compiled-binding path, XAML diagnostics
• Restricted writes: preview then apply for rename, diagnostic fix (including project Fix all), and code refactoring

What it does not do

• Generic write / patch / create / delete file tools
• Shell, process, HTTP, or package-download tools
• WPF / WinUI XAML
• F# source-generator attribution (symbol_attribution on an F# handle returns GeneratorLanguageNotSupported), generator queries, dynamic invocation queries, diagnostic fix, or code refactoring
• Cross-language F# reads and writes — F# handles search the defining project plus its F# dependents (or every F# project with entireSolution), but C#/VB consumers are named, not searched, and a visible F# symbol with C#/VB dependents cannot be renamed
• Extract-method / change-signature UIs
• Opening untrusted repositories safely — workspace_open runs MSBuild evaluation and project analyzers/generators

Tool names are locked by a snapshot test. Domain vocabulary: CONTEXT.md.

Quick Start

Trusted roots are required. The process working directory is never an implicit trusted root. On Windows, separate multiple roots with ;. You can also set DOTNET_MCP_TRUSTED_ROOTS. When both are set, startup uses their union; neither replaces the other. --roots=path is the same as --roots path; an empty value is rejected. A missing or empty roots configuration exits with code 1 and writes one JSON object to stderr (error, message, suggestedAction) instead of a stack trace.

Skymly.DotNetMcp is published on NuGet. dnx is the preferred install. A source build or a local pack works too.

dnx Skymly.DotNetMcp --yes -- --roots /path/to/repo

MCP client (stdio):

{

"mcpServers": { "dnmcp": { "command": "dnx", "args": ["Skymly.DotNetMcp", "--yes", "--", "--roots", "/path/to/repo"] } } }

Equivalent: dotnet tool exec Skymly.DotNetMcp --yes -- --roots /path/to/repo, or dotnet tool install -g Skymly.DotNetMcp then dnmcp --roots /path/to/repo.

Development run

From a clone of this repo:

dotnet run --project src/DotNetMcp.Server -- --roots /path/to/repo

{

"mcpServers": { "dnmcp": { "command": "dotnet", "args": ["run", "--project", "src/DotNetMcp.Server", "--", "--roots", "/path/to/repo"] } } }

Local pack

dotnet pack src/DotNetMcp.Server -c Release -o ./artifacts

dotnet tool exec --source ./artifacts --yes Skymly.DotNetMcp -- --roots /path/to/repo

stdio only. Framework-dependent .NET tool; NativeAOT is not required.

Typical agent loop: workspace_open (returns immediately) → poll workspace_status until ready → symbol_resolve → navigation / attribution. Prefer a .slnf or a single project for a large solution. .slnf entries already in the workspace (duplicates, or projects an earlier entry pulled in transitively) are skipped and named in the load warnings rather than failing the open.

For agent setup, docs/agent-guidance.md holds a copy-paste block for a consuming repo's AGENTS.md / CLAUDE.md — the loop, the 1-based position model, and the preview → apply write rule. The server also sends the same brief in the initialize result instructions and ships trace_symbol / safe_rename prompts that walk an agent through the two core workflows.

MCP tools

diagnostics_list_fixes and symbol_list_refactorings return epoch. fixIndex and refactoringIndex are valid only for that epoch. After it advances, preview fails with FixListEpochMismatch or RefactoringListEpochMismatch instead of selecting another action.

If a code-action provider throws, diagnostics_preview_fix and symbol_preview_refactoring still return FixApplyFailed or RefactoringApplyFailed, but the message says the provider threw. That is not the same as a fix that produced no handwritten change. Fix all stops with FixApplyFailed instead of skipping that occurrence.

project_diagnostics without projectId reports a failed project as error plus suggestedAction, not as a Severity=Error diagnostic. Do not pass that row to diagnostics_list_fixes.

project_diagnostics sets degraded plus a degradedReason when the compilation reports CS0006 or CS0012 — metadata references that did not resolve — computed over the project's full diagnostic set before paging. Listed errors may then be workspace artifacts rather than real code defects; verify with dotnet build before trusting fix previews. Both fields are omitted otherwise. On paged results (items / truncated / nextCursor), message is optional and omitted when there is nothing to add.

symbol_find_references also merges Exact XAML usage points (bindings, x:Class, element types, x:Name fields, event handlers) for C#/VB handles. Source hits page first; XAML hits follow in the same paged stream and carry xamlUsage naming the usage kind — source hits omit the field. Name-matched Unverified points are never included, and the XAML scan covers the same scope as source references (defining project plus dependents, or every project with entireSolution). One soft budget covers both lanes and the cursor walks both stages.

symbol_resolve_at accepts positions inside registered XAML documents too: a covering usage point resolves to its target handle with resolvedFrom = Reference and matched set to the exact usage span, while a position outside every usage returns NoSymbolAtPosition.

symbol_preview_rename keeps XAML in sync for C#/VB handles: Exact usage points in registered XAML documents (bindings, x:Class, element/attribute names, x:DataType, markup type refs, x:Name values, event-handler values) become ordinary old/new slices in the same preview — each edits only the symbol's simple-name occurrence inside its span — and symbol_apply_rename writes them through the same pipeline (WriteSuppression, encoding/BOM preserved, no files added or removed). Name-matched Unverified usages are reported under unverifiedXamlMentions without being written. The Origin = SourceGenerator refusal stays, with one exception: a generated x:Name field is renamed through its XAML value plus handwritten references, and the generator re-emits the field on its next run. Diagnostic fix and code refactoring previews never slice XAML documents.

Rename's write set is compiler-visible references plus those Exact XAML usages. It does not rewrite metadata-name strings (a GetTypeByMetadataName or ForAttributeWithMetadataName argument, for example), short attribute names the compiler did not bind, documentation, comments, or PublicAPI lists. Those hits are not listed — unverifiedMentions is not a field — so do not expect a whole-repository rename.

All located outputs share one position model: line and column are 1-based, columns count UTF-16 code units (a tab is one column), and endColumn is exclusive — the same file(line,col) convention the compilers print. start/length remain as UTF-16 offsets for slicing. Locations without a source position (InMetadata, None) omit the position fields, and positions in source-generated documents are coordinates inside the generated text. A position reported by one tool feeds the next tool verbatim — for example a project_diagnostics row's line/column/endLine/endColumn are exactly the locator arguments of diagnostics_list_fixes and diagnostics_preview_fix.

symbol_attribution reports a third axis beside declaration availability and generator identity: triggers[] on the root symbol and every member name the handwritten code that caused a generated member — a PartialDefinition counterpart bound by the compiler (C# and VB), an Attribute declaration such as [ObservableProperty], [RelayCommand], or [JsonSerializable], or a XamlElement (x:Name field or the x:Class document root, resolved through the XAML usage index). Each trigger carries confidence (Exact for compiler-bound evidence, Convention for unique name-inverse lookups), the unified position quad, detail, and a handle that re-resolves through symbol_summary for code triggers. Handwritten symbols return triggers: []; a generated member whose generator matches no rule and has no partial counterpart returns triggers: [] plus a triggerMessage instead of a guessed location.

An empty or whitespace path to workspace_open or an XAML tool is an empty-path error (InvalidWorkspacePath or XamlDocumentNotFound), not PathOutsideTrustedRoots. workspace_open returns the same progress fields as workspace_status, including errorCode when the open fails before the background load. A null errorCode is omitted.

A source generator or analyzer that references a newer Microsoft.CodeAnalysis than the server bundles is refused by Roslyn, and its output silently drops out of project_list_generators, project_list_generated_sources, and symbol_attribution. Once the workspace is ready, workspace_status.warnings carries an AnalyzerReferencesNewerCompiler entry that names the file (not its path). It is read from the assembly's metadata, so the analyzer is not loaded to find out. The fix is a dotnet-mcp release that bundles a newer Roslyn.

An analyzer path MSBuild declared but that resolves to no loadable assembly — an OutputItemType="Analyzer" project reference whose output is not built, or a DLL missing on disk — is not a silent miss either: project_list_generators lists it under unresolvedAnalyzerReferences with a message saying to build the analyzer project and reopen the workspace. Generator identities are only ever reported for assemblies that actually loaded.

Security

1. Trusted roots — every path is canonicalized (including parent reparse points). Unresolvable links fail closed. Loaded project graphs and apply-paths are re-checked. Configure --roots / --roots=path or DOTNET_MCP_TRUSTED_ROOTS. When bo