pzalutski-pixel/sharplens-mcp

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)
Then run with:
Via npm
Build from Source
Claude Code Setup
1. **Install the tool** (pick one):
2. **Create .mcp.json in your project root**:
3. **Restart Claude Code** to load the MCP server
4. **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**:
| Capability | Native LSP | SharpLensMcp |
|------------|------------|--------------|
| Go to definition | ✅ | ✅ |
| Find references | ✅ | ✅ |
| Find async methods missing CancellationToken | ❌ | ✅ |
| Impact analysis (what breaks?) | ❌ | ✅ |
| Dead code detection | ❌ | ✅ |
| Complexity metrics | ❌ | ✅ |
| Safe refactoring with preview | ❌ | ✅ |
| Batch operations | ❌ | ✅ |
Configuration
| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| DOTNET_SOLUTION_PATH | Path to .sln or .slnx file to auto-load on startup | None (must call load_solution) |
| SHARPLENS_ABSOLUTE_PATHS | Use absolute paths instead of relative | false (relative paths save tokens) |
| SHARPLENS_LOG_LEVEL | Logging verbosity: Trace, Debug, Information, Warning, Error | Information |
| SHARPLENS_TIMEOUT_SECONDS | Timeout for long-running operations | 30 |
| SHARPLENS_MAX_DIAGNOSTICS | Maximum diagnostics to return | 100 |
| SHARPLENS_ENABLE_SEMANTIC_CACHE | Enable semantic model caching | true (set to false to disable) |
The pre-1.6.0 ROSLYN_* spellings of the last four variables are still read as a fallback for one release; the SHARPLENS_* spelling wins when both are set.
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:
| 1.5.x name | 1.6.0 name |
|------------|------------|
| roslyn:load_solution | load_solution |
| roslyn:get_diagnostics | get_diagnostics |
| roslyn:rename_symbol | rename_symbol |
| ...same rule for all tools... | drop the roslyn: 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:
2. **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:
| Action | Call sync_documents? |
|--------|---------------------|
| Used Edit tool to modify .cs files | ✅ **Yes** |
| Used Write tool to create new .cs files | ✅ **Yes** |
| Deleted .cs files | ✅ **Yes** |
| Used SharpLensMcp refactoring tools (rename, extract, etc.) | ❌ No (auto-updated) |
| Modified .csproj files | ❌ No (use load_solution instead) |
Usage:
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