RoslynMcpServer

RoslynMcpServer

[🇷🇺 Читать на русском (Russian Version)](#russian-version)

Why use this over standard FileSystem MCPs? Unlike basic file-reading servers, this Model Context Protocol (MCP) server leverages Roslyn. Your AI agent (Cursor, Cline, etc.) doesn't just read plain text—it sees C# code through the eyes of the compiler. It can get precise diagnostics without a full rebuild, apply built-in Roslyn code fixes (add using, implement interface, fix typos), find symbol references, and perform safe semantic refactoring, drastically reducing LLM hallucinations.

It is designed for AI-driven C# development (with secondary Python support), focusing on:

• Parsing and analyzing *.sln/*.csproj via Roslyn.
• Safe, context-aware file read/write operations.
• CLI integration: running dotnet build, dotnet test, and custom commands.
• Compact responses optimized for LLM context windows, backed by detailed server-side logging.

⚠️ Security Disclaimer

This server grants the AI agent read, write, and execution privileges (via the dotnet CLI) within your workspace. Always use source control (Git) to track changes. Do not run the server as Administrator.

Prerequisites

• Strictly .NET 10 SDK installed on your machine. (Earlier SDK versions are not supported and will fail to build).
• An MCP-compatible IDE or client (e.g., Cursor, OpenCode, VS Code with Cline).

Setup & Connection (Local)

It is highly recommended to run the published executable. This ensures instant startup without the overhead of dotnet run. The project is configured with ReadyToRun enabled and PublishSingleFile disabled (to ensure Roslyn can dynamically load MSBuild and analyzer dependencies).

1. Publish the Server (Run once or after code updates)

From the repository root (replace the RID if you are not on Windows x64):

dotnet publish RoslynMcpServer.csproj -c Release -r win-x64

Your compiled binary will be at:

• Windows x64: bin/Release/net10.0/win-x64/publish/RoslynMcpServer.exe
• Linux/macOS: Same relative path under your specified -r flag.

2. Configure the MCP Client

Option A: Via Cursor UI

1. Go to Cursor Settings -> Features -> MCP -> + Add New MCP Server.
2. Type: stdio.
3. Command: Enter the absolute path to your published executable (e.g., D:\Devel\RoslynMcpServer\bin\Release\net10.0\win-x64\publish\RoslynMcpServer.exe).

Option B: Via mcp.json Add the absolute path to your configuration file (see the provided mcp.json and .cursor/mcp.json examples in the repo). Optional: Pass env with ROSLYN_MCP_WORKSPACE set to the repository root (folder containing global.json) so MSBuild.Locator and run_dotnet_build use the same SDK as your solution.

Option C: OpenCode (install2opencode.ps1)

After dotnet publish, the publish folder contains [install2opencode.ps1](install2opencode.ps1) and [AGENTS.md.sample](AGENTS.md.sample) next to RoslynMcpServer.exe.

From the root of the project you want to configure (your application repo):

cd D:\Devel\YourApp
& "D:\Devel\RoslynMcpServer\bin\Release\net10.0\win-x64\publish\install2opencode.ps1"

The script:

• Creates or updates opencode.json in the target directory, registering RoslynMcpServer as a local MCP server (type: local, enabled: true).
• Creates or updates AGENTS.md: if Roslyn MCP behavioral rules are not already present, merges content from the bundled AGENTS.md.sample (creates a new file or appends to an existing one).

| Parameter | Description | | --- | --- | | -BinaryPath | Optional. Absolute path to RoslynMcpServer.exe. When omitted, the script uses the binary next to itself. | | -ProjectPath | Optional. Target project root. Defaults to the current working directory. |

Restart OpenCode or reload MCP servers after running the script.

Agent tools by version

Tracks MCP tools relevant to [AGENTS.md.sample](AGENTS.md.sample) (copy into app repos as AGENTS.md). Current server version: see RoslynMcpServer.csproj.

v1.0.14

| Tool / behavior | Notes | |-----------------|--------| | run_dotnet_run | SDK-pinned dotnet run, separate stdout/stderr, timeout, truncated output (stderr tail for progress) | | run_nuget_audit | Structured vulnerability table from dotnet list package --vulnerable | | get_changed_files | Git porcelain status + suggested test projects (no diff body) | | load_workspace | Workspace health block: SDK/global.json, restore assets, tool count | | execute_dotnet_command | SDK pinning + truncated stdout/stderr | | find_usages / find_symbol_references | find_references family; prefer find_usages when only symbolName is known | | get_project_graph / list_projects | Project dependency graph | | rename_symbol | previewOnly=true default workflow | | run_format | dotnet format wrapper |

v1.0.13

| Tool / behavior | Notes | |-----------------|--------| | AssemblyReferenceResolver | Exact {name}.dll; deps.json + NuGet fallback | | DecompilerHost | NuGet / BCL / runtime pack resolver for ILSpy tools |

v1.0.10–v1.0.12

Build/test SDK pinning, VSTest parser, decompiler assemblyPath, MCP_MSBUILD_SDK_MISMATCH — see git history.

Not implemented (see AGENTS.md §7)

• Read-only TFS / HTTP probe MCP tools
• MCP «secret configured: yes/no» without reading values
• Unified diff in get_changed_files (use host/shell git diff when allowed)

Agent Initialization (How to force tool usage)

Even if the MCP is active, AI clients don't always load the tools into the current chat context. To ensure the agent utilizes RoslynMcpServer reliably, add the following instructions to your project rules (e.g., .cursor/rules/mcp.mdc or AGENTS.md).

OpenCode users: install2opencode.ps1 (see Option C above) writes or merges these rules into AGENTS.md automatically.

Canonical copy-paste file: this repo ships [AGENTS.md.sample](AGENTS.md.sample) with the same rules—copy it into your application repository as AGENTS.md or merge fragments into Cursor rules. When changing these instructions, update AGENTS.md.sample and the two collapsible AI Agent Behavioral Rules blocks below (English + Russian) together so they stay identical.

INITIALIZATION SEQUENCE: AI Agent Behavioral Rules — expand to read (same text as AGENTS.md.sample)

INITIALIZATION SEQUENCE: AI Agent Behavioral Rules

You are a Senior C# Developer and Architect. You have access to a specialized Roslyn MCP Server. To interact with this codebase safely and efficiently, you MUST strictly adhere to the following rules. Failure to do so will result in context window collapse or broken code.

Every time you start a new conversation or receive the first prompt in this project, you MUST silently perform the following steps before answering the user. THIS IS A STRICT BLOCKER:

1. Call the MCP server to list available tools.
2. Call load_workspace with workspacePath set to the absolute path of the solution or project file (e.g., d:/Devel/YourRepo/YourSolution.sln). CRITICAL: Tools like find_symbol_definition will fail or hallucinate if you skip this step. In MCP config, set ROSLYN_MCP_WORKSPACE to the repo root (folder with global.json) when possible.
3. Use manage_agent_scratchpad with action: read to recall previous state notes (omit if you do not use the scratchpad).

1. The Terminal Ban (Strict Tool Enforcement)

Do not run searches through raw shells (PowerShell, Bash, CMD) — the workspace might be locked or too large. Never invoke grep, Select-String, find, or similar from a terminal session.

• Semantic search (after load_workspace): You MUST call find_symbol_definition with symbolName. If you are looking for where an interface, class, or method is declared, DO NOT use text search. Do not invent generic tool names like search.
• Text search: Use the built-in grep tool provided by your environment. Do NOT use bash or PowerShell to run grep/Select-String.
• Directory layout: Use list_directory_tree.

2. Build & Test Protocol

NEVER use raw terminal commands (PowerShell, Bash, CMD) to execute dotnet build or dotnet test. Doing so bypasses our diagnostic parsers and can crash the context window with raw MSBuild output.

• To Build: YOU MUST use run_dotnet_build. Analyze the structured diagnostics (and any truncated console excerpt — head + tail when output is long) the tool returns.
• To Test: YOU MUST use run_dotnet_test for full suites. For a single test class or method during TDD/bug fixes, use run_specific_test — never hand-write VSTest --filter via execute_dotnet_command.

3. Explore Before Build (Global Context Awareness)

Before writing new utility classes, helper methods, or standard validation logic, you MUST verify how the project already handles this. Do not reinvent the wheel.

• Use get_code_skeleton (for files/directories) or get_class_skeleton (for loaded workspaces) to understand architecture without loading full method bodies.
• Use find_usages with symbolName (after load_workspace) for usages across the solution, or find_symbol_references with filePath + symbolName when you already know the declaring file — then mirror the team’s patterns.
• Use find_implementations with symbolName to list classes that implement an interface or derive from a base class — do not use text search or find_usages for this.

For C# edits, ALWAYS prefer get_class_skeleton, get_code_skeleton, get_method_body, explore_assembly, decompile_type, get_decompiled_class_skeleton, get_decompiled_method_body, run_dotnet_build, and get_diagnostics_for_file instead of inventing code from memory. When fixing compiler/analyzer errors, call get_code_fixes and apply_code_fix before guessing a manual patch—Roslyn already knows the correct fix for most standard diagnostics. Persisting edits to disk follows section 6 (IDE-native tools vs this MCP server's file tools).

4. Third-Party Code / NuGet Investigation

If you encounter a bug originating from a compiled .dll or NuGet package, DO NOT guess or hallucinate its implementation.

• Before adding or upgrading packages, use search_nuget_registry to verify the package id and latest stable version — never invent library names or versions.
• Use list_nuget_packages to inspect installed and transitive dependencies across projects (JSON) before changing .csproj files.
• Use explore_assembly with assemblyName (after load_workspace) or assemblyPath (absolute .dll, e.g. from NuGet cache) — provide one, not neither.
• Use decompile_type / get_decompiled_class_skeleton / get_decompiled_method_body with the same assemblyName or assemblyPath rules.
• Use decompile_type to read the exact C# source code. For large types, use get_decompiled_class_skeleton; for a specific method overload, use get_decompiled_method_body.
• Propose a fix only after reading the decompiled material.

5. Execution Loop

Think step-by-step. If a tool fails or returns an error, read the error message carefully, adjust your parameters, and try the appropriate MCP tool again. Do not fallback to raw shell commands. For MCP server diagnostics use tail_tool_log (or read_log_tail without filePath); optional filterKeyword such as Failure or ERR. Only after these steps are complete, respond to the user's actual prompt.

6. Environment-Specific File Editing Protocol

Before editing any files, identify your host environment:

• If you are running in a UI-based IDE (Cursor, OpenCode, Windsurf): You MUST use the built-in native file editing tools (such as edit, write, or equivalent operations) provided by your environment so the user can review changes in the IDE diff viewer. Do NOT use this Roslyn MCP server's apply_patch or update_file_content when those native tools are available—they bypass the host review workflow.

• If you are running in a headless/CLI environment (e.g., Aider) or your client does not expose first-class edit tools: You MUST persist changes using this MCP server's apply_patch and/or update_file_content (or the file-write mechanism your CLI integration documents). Do not use raw shell redirection to invent files.
• For C# insertions (usings, methods, properties, fields): prefer add_using, add_method_to_class, add_property_to_class, add_field_to_class, organize_usings over apply_patch.
• For method body edits: read with get_method_body, write with update_method_body — not apply_patch.
• Bug investigation: use get_call_graph to see callers/callees before loading many method bodies.
• Packages: use search_nuget_registry + add_package_reference — not hand-edited versions in csproj.
• After server rebuild: call get_mcp_server_info; run publish-and-verify.ps1.

Logs

• Main log: logs/mcp-*.log (relative to AppContext.BaseDirectory).
• Global incoming JSON-RPC logging is enabled by default.
• Tool output: logged as a one-line summary plus separate warning/error lines (not a duplicated full MCP response). Set ROSLYN_MCP_LOG_TOOL_OUTPUT=full to log entire tool responses at Information level.
• Environment Variables:
• ROSLYN_MCP_WORKSPACE — repo root for MSBuild/SDK discovery at startup (see MCP config above).
• ROSLYN_MCP_LOG_TOOL_OUTPUT=full — verbose tool response logging.
• MCP_LOG_INCOMING_RPC=0 (disable incoming RPC logging).
• MCP_LOG_INCOMING_RPC_MAX_CHARS= (limit payload log length, 0 = unlimited).

Reference: MCP Tools

Parameter Naming Rules:

• filePath — a single file (read/edit/diagnostics/logs).
• directoryPath — root folder (list_directory_tree, optional root for search_code).
• includeExtensions — optional extension filter for search_code (.cs by default; * = all files).
• workspacePath — .sln / .csproj (and sometimes a directory): load_workspace, run_dotnet_test, run_specific_test, run_format, optional reload for list_projects / get_project_graph. run_dotnet_build accepts only a .csproj or .sln file path, not a directory.
• symbolName — C# identifier for find_symbol_definition, find_symbol_references, find_usages, and find_implementations (exact name; matching is case-insensitive for definition/usages/implementations).
• diagnosticId — compiler/analyzer id from get_diagnostics_for_file (e.g. CS0246) for get_code_fixes / apply_code_fix.
• fixIndex — 0-based index from get_code_fixes for apply_code_fix.
• path — .cs file or directory for get_code_skeleton (absolute path; disk-based, no workspace required).

When a tool accepts filePath, relative values are resolved against the loaded workspace root after load_workspace; if no workspace is loaded, fallback is Environment.CurrentDirectory.

There are 55 registered tools (see list below) and 1 MCP prompt (RefactoringAssistantPrompt).

Workspace / Roslyn

load_workspace — Loads .sln/.csproj into MSBuildWorkspace.

Parameters:

• workspacePath: string

resetworkspace — Clears the in-memory MSBuildWorkspace/solution cache. Call before loadworkspace again after building the loaded solution on disk.

Parameters: (none)

getfilecontent — Reads the entire file (safe preview for large files).

Parameters:

• filePath: string

getclassskeleton — Returns the C# file structure without method bodies.

Parameters:

• filePath: string

getcodeskeleton — Parses .cs from disk and returns full-file syntax with bodies stripped (signatures + empty blocks); optional directory scan (max 20 files, skips bin/obj/Test/Tests path segments).

Parameters:

• path: string — absolute path to one .cs fi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VuDZ
• Source: VuDZ/RoslynMcpServer
• License: MIT

Install and usage instructions live in the source repository linked above.