SharpLensMcp

A Model Context Protocol (MCP) server providing 92 AI-optimized tools for .NET/C# semantic code analysis, navigation, refactoring, and code generation using Microsoft Roslyn.

Built for AI coding agents - provides compiler-accurate code understanding that AI cannot infer from reading source files alone.

Installation

Via NuGet (Recommended)

dotnet tool install -g SharpLensMcp

Then run with:

sharplens

Via npm

npx -y sharplens-mcp

Build from Source

dotnet build -c Release
dotnet publish -c Release -o ./publish

Claude Code Setup

1. Install the tool (pick one):

dotnet tool install -g SharpLensMcp
# or
npx -y sharplens-mcp

1. Create `.mcp.json` in your project root:

{
  "mcpServers": {
    "sharplens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sharplens-mcp"],
      "env": {
        "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)"
      }
    }
  }
}

1. Restart Claude Code to load the MCP server

1. Verify by asking Claude to run a health check on the Roslyn server

Why Use This with Claude Code?

Claude Code has native LSP support for basic navigation (go-to-definition, find references). SharpLensMcp adds deep semantic analysis:

Configuration

The pre-1.6.0 ROSLYN_* spellings of these variables are still read as a fallback; the SHARPLENS_* spelling wins when both are set. Boolean values are case-insensitive. A number that does not parse or is below its minimum falls back to the default, and one above its maximum is capped; each case logs a warning to stderr.

Multi-targeted projects

A project built for several target frameworks is one project to every tool: each result is reported once, with a targetFrameworks list where it exists only under some frameworks. projectName accepts the plain name (MyLib) for all frameworks, or a framework-qualified name (MyLib(net8.0)) for one.

If DOTNET_SOLUTION_PATH is not set, you must call the load_solution tool before using other tools.

Migrating from 1.5.x tool names

Tool names no longer carry the roslyn: prefix — the colon violates the MCP tool-name pattern (^[a-zA-Z0-9_-]{1,64}$), which some clients enforce. Every tool keeps its name minus the prefix:

tools/list publishes only the new names. Calls using the old prefixed names are still accepted as aliases for one release and will be removed in the following one.

AI Agent Configuration Tips

AI models may have trained bias toward using their native tools (Grep, Read, LSP) instead of MCP server tools, even when SharpLensMcp provides better capabilities.

To ensure optimal tool usage:

1. Claude Code: Add to your project's CLAUDE.md:

   For C# code analysis, prefer SharpLensMcp tools over native tools:
   - Use `search_symbols` instead of Grep for finding symbols
   - Use `get_method_source` instead of Read for viewing methods
   - Use `find_references` for semantic (not text) references

1. Other MCP clients: Configure tool priority in your agent's system prompt

The semantic analysis from Roslyn is more accurate than text-based search, especially for overloaded methods, partial classes, and inheritance hierarchies.

Agent Responsibility: Document Synchronization

Important: SharpLensMcp maintains an in-memory representation of your solution for fast queries. When files are modified externally (via Edit/Write tools), the agent is responsible for synchronizing changes.

When to call sync_documents:

Usage:

# After editing specific files
sync_documents(filePaths: ["src/MyClass.cs", "src/MyService.cs"])

# After bulk changes - sync all documents
sync_documents()

A full sync also picks up new .cs files the project's compile items include. SharpLensMcp's apply tools write only the files an edit changes, keep each file's encoding and line endings, and refuse with STALE_DOCUMENT when a target file changed on disk since it was read — run sync_documents, then retry. They also refuse with UNSUPPORTED_ENCODING to write a file whose bytes its encoding cannot reproduce (a BOM-less file that is not valid UTF-8 on a system whose fallback code page is UTF-8, such as Linux); save it as UTF-8 first.

Why this design?

This mirrors how LSP (Language Server Protocol) works - the client (editor) notifies the server of changes. This approach:

• Eliminates race conditions (agent controls timing)
• Avoids file watcher complexity and platform quirks
• Is faster than full solution reload
• Gives agents explicit control over workspace state

If you don't sync: Queries may return stale data (old method signatures, missing new files, etc.)

Features

• 92 Semantic Analysis Tools - Navigation, refactoring, code generation, diagnostics, discovery, audit/quality
• AI-Optimized Descriptions - Clear USAGE/OUTPUT/WORKFLOW patterns
• Structured Responses - Consistent success/error/data format with suggestedNextTools
• Zero-Based Coordinates - Clear warnings to prevent off-by-one errors
• Preview Mode - Safe refactoring with preview before apply
• Batch Operations - Multiple lookups in one call to reduce context usage

Tool Categories

Navigation & Discovery (24 tools)

Analysis (17 tools)

Refactoring (16 tools)

Code Generation (3 tools)

Compound Tools (7 tools)

Audit & Quality (10 tools)

Discovery (3 tools)

Infrastructure (12 tools)

Other MCP Clients

For MCP clients other than Claude Code, add to your configuration:

{
  "mcpServers": {
    "sharplens": {
      "command": "sharplens",
      "args": [],
      "env": {
        "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)"
      }
    }
  }
}

Usage

1. Load a solution: Call load_solution with path to .sln or .slnx file (or set DOTNET_SOLUTION_PATH)
2. Analyze code: Use any of the 92 tools for navigation, analysis, refactoring, audit
3. Refactor safely: Preview changes before applying with preview: true

Architecture

MCP Client (AI Agent)
        | stdin/stdout (JSON-RPC 2.0)
        v
   SharpLensMcp
   - Protocol handling
   - 92 AI-optimized tools
        |
        v
Microsoft.CodeAnalysis (Roslyn)
  - MSBuildWorkspace
  - SemanticModel
  - SymbolFinder

Requirements

• .NET 8.0 SDK or later — works with .NET 8, 9, 10, and future versions. Analyzes any .NET 8+ project/solution.
• MCP-compatible AI agent

FAQ

Why does the tool target `net8.0` — can it analyze my .NET 9 / .NET 10 project?

Yes. net8.0 is the tool's own runtime floor — the Roslyn 5.x packages it builds on require it — not a ceiling on what it can analyze. RollForward lets the installed tool run on newer .NET runtimes, and MSBuildWorkspace loads each project's real target framework from its csproj, so one install analyzes solutions targeting .NET 8, 9, 10, and beyond.

Development

Adding New Tools

1. *Add the method to the matching `src/RoslynService..cs` partial** (Navigation, Analysis, Refactoring, CallAnalysis, …) and return through the shared response envelope:

public async Task<object> YourToolAsync(string param1, int? param2 = null,
    CancellationToken cancellationToken = default)
{
    EnsureSolutionLoaded();
    // Your logic...
    return CreateSuccessResponse(
        data: new { /* results */ },
        suggestedNextTools: new[] { "next_tool_hint" }
    );
}

1. Register one `ToolDefinition` in `src/ToolRegistry.cs` — its name, description, input schema, the ReadOnly flag (mutating tools pass ReadOnly: false and receive a destructiveHint annotation), and a handler that binds arguments through JsonRpcParameters and calls your method. The registry drives both tools/list and dispatch; there is no separate switch to edit. Two tests keep it honest: ToolsListGoldenTests locks the published schema byte-for-byte (re-capture the golden when a schema change is intentional), and ToolSchemaParityTests asserts every parameter the handler reads is declared in the schema.

1. Build and publish:

dotnet build -c Release
dotnet publish -c Release -o ./publish

1. Add both test levels — a unit test of the RoslynService method against a deterministic fixture, AND a wire test through the MCP dispatcher (in tests/SharpLensMcp.Tests/Mcp/) with exact value locks plus an error path. This is non-negotiable; see Testing.

Testing

Every test must satisfy the Testing Charter (C1–C9) in tests/SharpLensMcp.Tests/TESTING.md — the standing contract. The headline rules:

• Lock exact values (C1): assert a concrete name / count / substring / error code / (line, column) — never NotBeNull / > 0 / a type-only check as the sole assertion.
• Both levels per tool (C4): a unit test against a Fixtures/*.cs fixture and a dispatcher (wire) test that unwraps content[0].text, plus an error path.
• Right casing (C3): in-process Newtonsoft yields PascalCase error.Code / meta.TotalCount; the MCP wire yields camelCase. Read the casing your test's path actually produces.
• Deterministic (C7): the suite is serialized via xunit.runner.json; fixture mutators always restore; the timeout test uses a forced-cancellation seam, not a timing race.
• Out-of-process spine (C6): StdioIntegrationTests value-pins one tool per category over the real binary and runs the tools/list golden over the stdio pipe.
• Pre-commit gate (C9): build-clean + green is necessary but not sufficient — re-read each changed test and confirm it fails on a wrong answer.

Run the suite:

dotnet test -c Release

Key Files

License

MIT - See LICENSE for details. <!-- mcp-name: io.github.pzalutski-pixel/sharplens -->