RoslynMcp

Give your AI agent a C# compiler instead of grep.
(first battle-test results: 38-69% token savings, bugs found, lessons learned · shared workspace architecture · help wanted)

RoslynMcp is a Model Context Protocol server that gives AI coding agents real Roslyn compiler semantics: type resolution, cross-file references, semantic rename, diagnostics, and 40 tools. Not string matching. Not regex. Actual compiler-level understanding of your C# code.

Agent: "Rename OrderStatus.Pending to OrderStatus.AwaitingApproval"

Without RoslynMcp:  grep + find-and-replace across 50 files. Hope nothing else is named "Pending."
With RoslynMcp:     roslyn_preview_rename -> reviews diff across 3 projects -> roslyn_apply_rename. Done.

Works with any MCP-compatible client: Claude Code, GitHub Copilot, Claude Desktop, Cline, Cursor, Windsurf, Roo Code, Continue, and more.

Security Note: RoslynMcp runs with your user permissions and has unrestricted filesystem access. Only use with trusted agents and on projects you control. See Issue #9.

Quick Start

TL;DR: Download the latest release zip, extract it, and add "command": "/absolute/path/to/RoslynMcp.exe" to your client's MCP config. Tell your agent to pass projectPath with every roslyn_* call. Done. Details below.

1. Get RoslynMcp

Option A — Download and extract (simplest, no SDK required):

Download the latest release from the Releases page — grab RoslynMcp-vX.Y.Z-net10.0.zip (or net8.0 if you prefer). Extract it anywhere and note the full path to RoslynMcp.exe.

Option B — Clone and build (requires .NET 8 or 10 SDK):

git clone https://github.com/MadQ/RoslynMcp.git
cd RoslynMcp
dotnet publish src/RoslynMcp/RoslynMcp.csproj -c Release -f net10.0 -o ./publish/net10.0

The executable will be at ./publish/net10.0/RoslynMcp.exe.

2. Add to your MCP client config.

Claude Code — create .mcp.json in your project root:

{
  "mcpServers": {
    "roslyn": {
      "type": "stdio",
      "command": "/absolute/path/to/RoslynMcp.exe"
    }
  }
}

Global alternative: add the same "mcpServers" block to ~/.claude.json (%USERPROFILE%\.claude.json on Windows).

GitHub Copilot (VS Code / CLI / Visual Studio) — create .mcp.json in your project root:

{
  "servers": {
    "roslyn": {
      "type": "stdio",
      "command": "/absolute/path/to/RoslynMcp.exe"
    }
  }
}

Global alternative: add the same "servers" block to ~/.copilot/mcp-config.json (%USERPROFILE%\.copilot\mcp-config.json on Windows).

See INSTALLATION.md for Claude Desktop, Cursor, Windsurf, Cline, Continue, Roo Code, Zed, and direct CLI usage.

3. Start using it. Every tool accepts a projectPath parameter pointing at your .csproj, .sln, or project directory. Your agent handles this automatically.

"What does the ProcessOrder method do?"
-> Agent calls roslyn_get_member_body("ProcessOrder", projectPath: "src/MyApp")
-> Returns just that method's source. 20 lines, not a 600-line file dump.

[!IMPORTANT]
Tell your agent to use RoslynMcp. Agents default to grep and file reads unless you explicitly instruct them. Add a few lines to your project's CLAUDE.md or AGENTS.md — see Agent Instructions for a quick example, or docs/AGENT-INSTRUCTIONS.md for complete copy-paste instructions covering every tool. Having trouble getting your agent to comply? See #99.
Claude Code users: try our experimental PreToolUse hook to enforce this automatically.

Why RoslynMcp?

AI agents working on C# through file reads and regex have a structural problem: they pattern-match text instead of understanding code. RoslynMcp fixes that by keeping a live Roslyn compilation in-process, incrementally updated as files change.

Find references, not text matches. roslyn_find_references uses Roslyn's semantic model to find every actual usage of a symbol across your entire solution. Grep finds string matches. Roslyn finds the call site in OrderService, the override in PriorityOrderProcessor, and the test mock in OrderServiceTests -- even when they use different names through inheritance.

Read one method, not the whole file. roslyn_get_member_body returns just the source of a single method, property, or field. When your agent needs to understand ProcessPayment, it gets 15 lines instead of reading a 600-line file. Massive token savings, every call.

Rename with confidence. roslyn_preview_rename + roslyn_apply_rename performs semantic rename across your entire solution. It knows that order.Status and IOrder.Status are the same symbol. Grep doesn't.

Build without leaving the process. roslyn_build_project checks Roslyn diagnostics first — fast, in-process, no MSBuild spawn. If there are errors, it returns them instantly. Clean code triggers a real dotnet build for full validation.

Tool Catalog

40 public tools organized by what you need to do (plus 2 debug-only tools not listed here). All tools work in-process using Roslyn APIs unless noted.

Discovery

Navigation

Reading Code

Editing

Refactoring

Build

Diagnostics & Info

Log Viewer

RoslynMcp writes structured NDJSON logs to %LOCALAPPDATA%\RoslynMcp\logs\roslynmcp.{pid}.log. src/RoslynMcp.LogViewer/ is a .NET console app that serves a browser-based log viewer on http://localhost:5123 — run it, then open that URL in any browser to watch tool calls stream in live.

Features: expandable rows with response peek data, JSON and C# syntax highlighting (with rainbow bracket coloring), four themes (Dark, Light, Parchment, Auto), local time display, and a Win95-inspired tree-view UI in Parchment mode.

Useful for understanding what your agent is actually doing, spotting slow tool calls, and debugging unexpected responses.

Agent Instructions

For Claude Code (CLAUDE.md)

Add to your project's CLAUDE.md:

## Tool Preferences

ALWAYS prefer roslyn_* MCP tools over built-in tools when working with C#:
- Use `roslyn_get_member_body` to read methods -- not Read on the whole file
- Use `roslyn_find_references` to find usages -- not Grep
- Use `roslyn_build_project` to build -- never run `dotnet build` directly
- Use `roslyn_replace_in_code` for C# edits -- it validates syntax
- Use `roslyn_search_files` or `roslyn_semantic_search` for code search -- not Grep
- Use `roslyn_preview_rename` + `roslyn_apply_rename` for renames -- semantic, cross-project
- Use `roslyn_get_file_outline` to understand file structure -- not Read on the whole file

For GitHub Copilot (AGENTS.md or copilot-instructions.md)

Add to your project's AGENTS.md or .github/copilot-instructions.md:

When working with C# code, prefer roslyn_* MCP tools:
- `roslyn_get_member_body` to read a single method/property (don't read entire files)
- `roslyn_find_references` for semantic symbol search (not grep)
- `roslyn_build_project` for builds (never `dotnet build` in terminal)
- `roslyn_replace_in_code` for C# edits (validates syntax, preserves formatting)
- `roslyn_search_files` / `roslyn_semantic_search` for code discovery
- `roslyn_preview_rename` + `roslyn_apply_rename` for semantic renames
- `roslyn_get_file_outline` for file structure (don't read the whole file)
- `roslyn_get_diagnostics` with `take: 0` for a fast error count check (no items), or `severity: "errors"` to page through individual errors

For complete instructions covering every tool, see docs/AGENT-INSTRUCTIONS.md — includes a full version, a compact version, and guidance for subagent delegation (subagents don't inherit your instructions).

How It Works

RoslynMcp loads your project through MSBuild (full NuGet resolution, multi-project support, source generators) or falls back to AdhocWorkspace for quick source-only analysis. A FileSystemWatcher keeps the in-memory compilation current as files change on disk.

• MSBuildWorkspace -- when .csproj/.sln is found. Full project semantics.
• AdhocWorkspace -- fallback. Loads .cs files directly. Fast startup, limited resolution.
• Smart MSBuild discovery -- finds your MSBuild installation automatically on most machines.
• Token-based pagination -- large results return a page_token. Pass it back for the next page.
• stdio transport -- runs over stdin/stdout. All logging goes to stderr.

See Workspace Modes Reference for details.

Help Wanted

RoslynMcp works. We use it daily for C# development with AI agents. But it is alpha software and there are areas where outside perspectives would make a real difference.

First-call latency. Loading an MSBuild workspace takes ~10 seconds on first tool call as the solution is parsed and compiled. Subsequent calls are fast (the workspace is cached and incrementally updated). Adding a new .cs file also triggers a full workspace reload (~8-10 seconds on next tool call) because Roslyn's MSBuildWorkspace doesn't support in-place document addition for SDK-style projects (dotnet/roslyn#36781). The cold start pays back quickly: once loaded, roslyn_get_diagnostics runs in-process in milliseconds — 18× faster than dotnet build in our battle-testing. On very large solutions (Orleans with 235 compiled projects hit 7+ minutes), --workspace adhoc cuts cold start to ~22 seconds when full NuGet resolution isn't needed. If you have ideas for improving cold-start or reload time -- lazy compilation, workspace preloading, partial loading strategies -- we would like to hear them.

Platform testing. RoslynMcp is developed and tested on Windows. It should work on Linux and macOS (Roslyn and MSBuild are cross-platform), but it has not been validated. If you run it on a non-Windows platform, your experience report is valuable whether it works perfectly or fails completely.

Large solution testing. The tool catalog has been tested against small and medium projects. If you have a large real-world codebase (50+ projects, 500K+ lines), we want to know how it performs: load times, memory usage, pagination behavior, anything that breaks.

Making agents choose the right tools. Agents default to built-in file tools even when roslyn_* tools are available and better. We're working on enforcement hooks, better tool descriptions, and per-client instruction templates — for Claude Code, GitHub Copilot, Cursor, Windsurf, and others. See #99 for the full wishlist and how to help.

Multi-agent resource usage. Each subagent spawns its own MCP server process with its own Roslyn workspace (~100MB+ RAM, ~10s load time). Parallel subagents multiply this cost. We're designing a shared Workspace Service via named pipes — one workspace per solution, shared across all agents. See #86 and the design doc.

Benchmarks in progress. We're actively benchmarking token usage and correctness across real-world repos — RoslynMcp vs built-in tools, across different model tiers. See initial battle-test results.

If any of this sounds interesting, open an issue or submit a PR.

Contributing

Contributions are welcome at every level. See CONTRIBUTING.md for the full guide.

Small PRs are great. Tool description improvements, documentation fixes, typo corrections -- these directly affect how well agents use the tools. First open-source PR? This is a good place to start.

Larger contributions. New tools, performance improvements, platform fixes. Fork from dev and submit a PR.

# Build
dotnet publish src/RoslynMcp/RoslynMcp.csproj -c Release -f net10.0 -o ./publish/net10.0

# Run the test suite (tests RoslynMcp against itself)
dotnet run --project src/TestHarness/TestHarness.csproj

See CONTRIBUTING.md for the full guide and CODE_OF_CONDUCT.md for community standards.

Requirements

• .NET 8 or .NET 10 SDK (multi-targeted -- use whichever you have installed)

License

MIT License -- see LICENSE for details.