Zphil.Roz 1.0.0

roz-mcp

An MCP server that gives C# coding agents the compiler's view of a solution. Claude Code, Cursor, VS Code Copilot Chat, and Codex CLI get Roslyn-backed tools for the work that is risky or slow with text search alone: finding every real reference — including the edges text search cannot see, like overrides, interface dispatch, and DI registrations — renaming a symbol across the whole solution in one call, previewing the blast radius of a change before it lands, and making edits that verify themselves against the compiler in the same round trip.

Roz runs as a .NET global tool over stdio and configures any supported client with one roz-mcp setup command per project. It has been 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. To see whether it will pay off for your work, skip to When it helps (and when it doesn't).

Design philosophy

Read-only actions are forgiving; write operations are extremely conservative. Reads snap to the nearest enclosing symbol so a cursor near a declaration still resolves; the worst case is information about the wrong symbol. Writes take the opposite stance.

Verified writes commit and report in one round trip: DryRun applies the batch to an in-memory fork and reports the new-and-resolved compiler-error delta without writing; Delta commits and 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).

Composes, doesn't reinvent. roz leans on ilspycmd for decompilation and the compiler for verification, rather than duplicating them.

Quickstart

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.

Two defaults 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.
• The default tool set is deliberately lean — 11 of the 19 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

The tool installs as roz-mcp on your PATH.

Tools

19 tools across 7 categories. 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 tool set is 11 tools — the write tools (edit_symbol, replace_content, apply_code_fix, change_signature, add_usings, remove_unused_usings) and get_unused_references are opt-in via ROZ_TOOLS, and analyze_method is held out pending A/B validation (see Configuration). The five mutating tools all accept verify=DryRun (apply to an in-memory fork, report the compiler-error delta, write nothing) or verify=Delta (commit, then report), collapsing the edit → build → re-read loop into one round trip.

Batched read tools (find_references, analyze_change_impact, 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

10 user-invoked slash commands (/mcp__roz__*) that package a multi-step Roslyn workflow into one recipe.

When it helps (and when it doesn't)

Roz has been stress-tested against seven large open-source codebases and A/B-measured against no-MCP baselines across four model tiers before 1.0 — every number in this README traces to a published evaluation.

Mechanical refactors are the headline win, at every tier measured. A 22-reference solution-wide rename via rename_symbol cost −57.5% versus a careful text-editing baseline (Haiku 4.5, 2026-07-03; the tool adopted in 3 of 3 reps, zero churn, zero residual) and −60.9% at the earlier frontier anchor (Opus 4.7, 2026-04). Both arms landed the identical semantic change — the roz arm just paid far less to get there. Write-up.

It preserves live code that text search would kill. A deletion task planted five traps reachable only through Razor markup, DI, dispatch, startup, or the public API — the exact edges a text search cannot follow — alongside three genuinely dead symbols. The roz arm preserved all five traps at every tier tested (Opus 4.8 / Sonnet 5 / Haiku 4.5, 2026-07); only the no-MCP baseline deleted live code (Sonnet 5, the Razor-only and public-API traps, 1 of 3 reps). The honest counterweight: the roz arm over-corrected once at Sonnet and removed nothing that rep. The cleanup_dead_code and tighten_accessibility prompts drive this workflow with the blind-spot checks built in. Write-up.

Audit reports cite real numbers and finish faster — but cost more. 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, and ran −24.2% to −57.3% in wall-clock (Sonnet 5 / Haiku 4.5, 2026-07). They also cost +19.7% to +47.6% more on every current tier — MCP tool results are billed as input tokens (tool-use pricing) while a locally-run grep never enters the context window — and at the budget tier the speed came with shallower coverage. Buy this for trustworthy-and-fast, not for cheap. 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); down-tier, neither Sonnet 5 nor Haiku 4.5 called a single roz tool on the task — their +5.2% / +23.6% deltas were pure snippet and tool-schema overhead. Don't load roz for this. Write-ups.

Pick the tool surface for the work (ROZ_TOOLS, seeded at onboarding with roz-mcp setup --tools=<value>):

And calibrate to your model tier — from the down-tier grid (Opus 4.8 / Sonnet 5 / Haiku 4.5, 2026-07):

Configuration

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

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

Battle-tested against

roz was stress-tested against seven real open-source C# codebases before 1.0.0, each of which surfaced a distinct bug class that was then fixed. These are published verbatim as dated historical records — they use the tool's former name (roslyn-mcp) and period-correct tool counts, and some clones were deliberately broken to stress error handling.

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 — for reading the body of a compiled BCL/NuGet symbol; the decompile_symbol prompt drives it.
• ReSharper CLI / dotnet format — for whole-file style and formatting passes, which roz deliberately 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 rather than trusting ours.

Contributing

Contributions are welcome — bug reports reproduced on public codebases, new conservative executors, client-compatibility fixes, and evaluation/harness improvements land best. See CONTRIBUTING.md for dev setup (.NET 10 SDK, Windows or Linux), the test architecture, and the evidence-first culture (default-preset changes want an A/B run; 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.

License

MIT — see LICENSE.