roz-mcp

roz is an MCP server that gives C# coding agents the compiler's view of a solution. It finds every real reference to a symbol, including the edges text search misses: overrides, interface dispatch, DI registrations. It renames a symbol across the whole solution in one call, previews the blast radius of a proposed change, and makes edits that verify themselves against the compiler in the same round trip. roz runs as a .NET global tool over stdio; one roz-mcp setup command configures Claude Code, Cursor, VS Code Copilot Chat, or Codex CLI.

roz was developed for and dogfooded on large legacy financial codebases, and it is for that sort of work that it shines. It is most probably not worth the (inherent to the MCP protocol) token overhead for clean greenfield work; When it helps (and when it doesn't) has the measurements.

Quickstart

roz requires the .NET 10 SDK.

dotnet tool install -g Zphil.Roz
cd path/to/your/solution
roz-mcp setup

Restart the AI client, then ask it something that needs the compiler:

"Find all implementations of IRepository in this solution and show me each class's Save method."

setup auto-detects which AI clients the project uses (via the .claude/, .cursor/, .vscode/, and .codex/ marker directories), writes the matching MCP config file(s), and appends a short usage snippet to the corresponding project rules file. If several markers are present, choose explicitly with --client=claude,cursor. Setup is idempotent: re-running it updates roz's entries without disturbing sibling MCP servers or user-added environment variables, and it refreshes the # roz-mcp rules section in place without touching the rest of the file.

VS Code and Cursor users can also add the server in one click, once the tool is installed:

The badges wire the server into the client config only. roz-mcp setup is the fuller path: it also writes the project rules snippet and, for Claude Code, the permission defaults that route write tools through a confirmation prompt.

Two defaults are worth knowing before your first session:

• Solution discovery walks up from the working directory; pin a specific .sln/.slnx with ROZ_SOLUTION_PATH in the MCP config's env block.
• Tool surface: the default set is 13 of the 20 tools; most write tools are opt-in. Seed a different surface at onboarding with roz-mcp setup --tools=all (everything) or --tools=read (read-only), and see Configuration for finer control.

From source

git clone https://github.com/andypgray/roz-mcp
cd roz-mcp
dotnet pack src/Zphil.Roz/Zphil.Roz.csproj -c Release
dotnet tool install -g --add-source src/Zphil.Roz/bin/Release Zphil.Roz

roz installs as roz-mcp on your PATH.

Install as a Claude Code plugin

Claude Code users can skip the global tool install: this repository doubles as a single-plugin marketplace, and one install delivers the server with its tools, prompts, and guide resources, plus a skill carrying the usage rules that roz-mcp setup would otherwise write into CLAUDE.md:

/plugin marketplace add andypgray/roz-mcp
/plugin install roz-mcp@roz-mcp

The plugin starts the server with dotnet dnx, which fetches Zphil.Roz from nuget.org on first use. You still need the .NET 10 SDK. The plugin's launch command is global, so per-project settings go in a .roz.json file (see Configuration); the bundled skill includes a recommended permission block that keeps the write tools behind a confirmation prompt (SKILL.md).

Enable the plugin per project rather than globally: roz is measured overhead on work that never needs the compiler's view (see When it helps). A team can check the marketplace and plugin enablement into the project's .claude/settings.json, which prompts teammates to install on their next session:

{
  "extraKnownMarketplaces": {
    "roz-mcp": { "source": { "source": "github", "repo": "andypgray/roz-mcp" } }
  },
  "enabledPlugins": { "roz-mcp@roz-mcp": true }
}

The server should be registered once per project. With the plugin enabled, roz-mcp setup detects it and configures around it: permission rules under the plugin's tool-name prefix, --tools written to .roz.json, no .mcp.json entry, and a warning if a leftover classic entry would register the server twice. --plugin and --no-plugin force either mode.

Tools

roz ships 20 tools across 7 categories. Read tools are forgiving: a cursor near a declaration snaps to the nearest enclosing symbol, and the worst case is information about the wrong symbol. Write tools are conservative: symbol names are authoritative, and an ambiguous target fails with a disambiguation error.

Read tools accept includeDocs=true and (where applicable) includeBody=true; locations are either cursors (path:line:col, or path:line for member-on-line snap) or symbol names (with optional FQN, containingType, kind, or project substring filter).

The default set is 13 tools. The write tools (edit_symbol, replace_content, apply_code_fix, change_signature, move_symbol, add_usings, remove_unused_usings) are opt-in via ROZ_TOOLS (see Configuration).

The six editing tools accept a verify mode that collapses the edit → build → re-read loop into one round trip: verify=DryRun applies the batch to an in-memory fork and reports the new-and-resolved compiler-error delta without writing anything, and verify=Delta commits first, then reports. Verified writes exist because an agent's own success report is not evidence: silently asserting completion while the state says otherwise is a pattern reported across the agent literature (Advani 2026, agentic benchmarks rather than code audits specifically).

Batched read tools (find_references, analyze_change_impact, analyze_method, find_implementations, find_overloads, get_type_hierarchy) accept many items per call; one round trip with symbolNames=["A","B","C"] is almost always cheaper than three separate calls.

Prompts

roz registers 10 user-invoked slash commands (/mcp__roz__<name> in a direct Claude Code install; plugin installs prefix the name differently). Each packages a multi-step Roslyn workflow into one recipe.

Resources

roz exposes three reference guides as MCP resources, so the detail loads on demand rather than in every session. Claude Code can @-mention a resource to attach it, and recent builds let the model list and read resources itself.

When it helps (and when it doesn't)

roz was A/B-measured against no-MCP baselines across four model tiers before 1.0, then re-baselined in August 2026 on Haiku 4.5, Sonnet 5 and Opus 5 with MCP tool delivery pinned to the deferred mode Claude Code actually uses. The write-ups are linked from each paragraph below and indexed in Evidence and methodology. Figures dated 2026-07 or earlier were taken before that fix; where the re-baseline moved a number, both are given.

Mechanical refactors are the clearest win, at every tier measured. A 22-reference solution-wide rename via rename_symbol beat a careful text-editing baseline at all three re-baselined tiers: −23.1% (Haiku 4.5), −36.9% (Sonnet 5), −29.4% (Opus 5), with the rename verified identical in both arms of every run. The same Haiku cell measured −57.5% in July 2026 and −60.9% at the earlier frontier anchor (Opus 4.7, 2026-04); the margin narrowed because the baseline got better, not the tool, so read the durable figure as 23–58% across two sweeps. Write-up.

roz can preserve live code that text search would delete, but that advantage did not reproduce. A deletion task planted five traps reachable only through Razor markup, DI, dispatch, startup, or the public API, alongside three genuinely dead symbols. In July 2026 the roz arm kept all five traps at every tier while the Sonnet 5 baseline deleted the Razor-only and public-API traps in one rep of three. The August re-baseline found no separation: at Sonnet both arms averaged 4.33 of 5 kept, and at Opus 5 both arms were perfect across all six runs. Treat trap safety as unproven on current models. The cleanup_dead_code and tighten_accessibility prompts still drive this workflow with the blind-spot checks built in. Write-up.

Audit reports cite real numbers, but they cost more at every tier. roz-armed audits scored count plausibility 0.97–1.00 versus 0.62–0.77 for a grep baseline whose cited caller counts drift or are fabricated (2026-07). The cost premium is the most reliably replicated result in the evidence set: +19.7% to +47.6% in July 2026, and +12.6% (Haiku 4.5), +39.7% (Opus 5), +132.4% (Sonnet 5) in the August re-baseline, where judged quality came out at or below the baseline every time. MCP tool results are billed as input tokens (tool-use pricing), while a locally-run grep never enters the context window. Wall-clock is mixed rather than the uniform win July showed: −30.0% at Haiku and −8.7% at Opus, but +47.0% at Sonnet. Buy this for trustworthy, not for cheap or fast. Write-up.

Greenfield, pattern-following feature work does not pay. At the frontier it cost +17% and 2.1× the wall-clock for comparable code (Opus 4.7, 2026-04-18), and the August re-baseline puts it at +12.5% (Sonnet 5) and +17.3% (Opus 5). Haiku 4.5 came out at −6.7%, which is indistinguishable from zero, and shows why: it made zero roz calls and zero tool-search calls on this task in every rep, and under deferred delivery a tool the model never searches for costs nothing. Don't load roz for this. Write-up.

Pick the tool surface for the work (ROZ_TOOLS):

Tier matters less than it did (Haiku 4.5 / Sonnet 5 / Opus 5, 2026-08). The rename win now lands within 14 points across all three tiers, so the executor is the pitch everywhere rather than a budget-tier speciality. What still separates them is the audit premium, which is worst at the mid tier by a wide margin.

One thing does not vary by tier: the project-instructions snippet that roz-mcp setup writes is what makes the tools reachable at all. Removed, a Fable 5 arm made zero tool-search calls and zero roz calls on both tasks tested, producing identical output for 30.7% more (2026-08). Under deferred tool delivery an unrouted server contributes nothing.

Configuration

All configuration is via environment variables, typically set in the MCP client's config env block.

The same variables can live in a .roz.json file at the project root, keyed by the exact variable names ({"ROZ_TOOLS": "read"}). At startup roz uses the nearest file up the directory tree and applies any key the environment leaves unset; an environment variable always wins. The file keeps per-project settings working when the launch command is configured globally and carries no per-project env block.

roz-mcp setup --tools=<value> seeds ROZ_TOOLS into the generated MCP config's env block so subsequent sessions pick it up automatically.

The table lists the most common variables; the full reference for every variable roz reads, including the .roz.json rules, is the roz://guides/configuration resource (see Resources).

Works well with

roz is a C# specialist and pairs with, rather than replaces, adjacent tools:

• Serena: when your work spans multiple languages or a polyglot repo, a cross-language LSP server covers ground a Roslyn-only tool cannot.
• ilspycmd: reads the body of a compiled BCL/NuGet symbol; the decompile_symbol prompt drives it.
• ReSharper CLI / dotnet format: whole-file style and formatting passes, which roz leaves alone.

Evidence and methodology

Every quantitative claim on this page resolves to a primary-source evaluation in docs/evidence/: the A/B studies that drove ship/hold decisions and the stress tests that shaped the design, published verbatim as dated historical records.

The harness that produced the A/B numbers is public: scripts/ab-test/. Run it on your own codebase before you trust ours.

Stress tests

roz was stress-tested against seven open-source C# codebases before 1.0.0, and each surfaced a distinct bug class that was then fixed. The reports keep roz's former name (roslyn-mcp) and period-correct tool counts, and some clones were deliberately broken to stress error handling.

Contributing

Contributions are welcome. Bug reports reproduced on public codebases, new conservative executors, client-compatibility fixes, and evaluation or harness improvements land best. See CONTRIBUTING.md for dev setup (.NET 10 SDK, Windows or Linux) and the test architecture. Default-preset changes want an A/B run, and HOLD verdicts are normal here (two of our own tools have them). The deep dive on internals (error-handling conventions, location/FQN resolution, DI-container detection, verified writes, and precision limits) is in ARCHITECTURE.md. To report a security issue privately, see SECURITY.md. roz collects nothing and processes everything locally; PRIVACY.md states that as policy.

License

MIT; see LICENSE.