SharpLensMcp

A Model Context Protocol (MCP) server providing 91 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

2. 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)"
      }
    }
  }
}

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 91 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:

   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
   

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:

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

# After bulk changes - sync all documents
sync_documents()

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

• 91 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 (23 tools)

Tool	Description
get_symbol_info	Semantic info at position
go_to_definition	Jump to symbol definition
find_references	All references; each classified read/write/invocation/cast/typeof/nameof/attribute; optional kind filter
find_implementations	Interface/abstract implementations
find_callers	Impact analysis - who calls this?
get_call_graph	Multi-hop callers/callees graph with depth bound + cycle detection
get_type_hierarchy	Inheritance chain
search_symbols	Glob pattern search (*Handler, Get*)
semantic_query	Multi-filter search (async, public, etc.)
get_type_members	All members by type name
get_type_members_batch	Multiple types in one call
get_method_signature	Detailed signature by name
get_derived_types	Find all subclasses
get_base_types	Full inheritance chain
get_attributes	List attributes on a symbol
get_containing_member	Enclosing symbol at position
get_method_overloads	All overloads of a method
find_attribute_usages	Find types/members by attribute
get_external_type_info	Inspect NuGet/BCL/external assembly types — members + XML docs
resolve_stack_trace	Map a pasted stack trace to file/line/symbol, mangling undone
get_extension_methods	Extensions applying to a type — classic and C# 14 blocks
get_documentation	Full XML docs for a symbol with <inheritdoc> expanded
get_super_method	Navigate to the base member / interface members a member implements

Analysis (17 tools)

Tool	Description
get_diagnostics	Compiler errors/warnings + configured analyzer findings (StyleCop, Roslynator, NetAnalyzers); matches CI
diff_api_surface	Public-API breaking-change report vs a git ref
get_exception_flow	Which exceptions can escape a method, and where they're caught
find_similar_code	Structural similarity search (token-shingle fingerprints)
remove_unused_code	Compute dead-code removals + newly unused usings (generation-only)
find_dead_branches	Unreachable basic blocks per method (real CFG, not heuristics)
add_missing_imports	Compute the usings that fix CS0246/CS0103 (generation-only)
analyze_data_flow	Variable assignments and usage
analyze_control_flow	Branching/reachability
analyze_change_impact	What breaks if changed?
check_type_compatibility	Can A assign to B?
get_outgoing_calls	What does this method call?
find_unused_code	Dead code detection
validate_code	Compile check without writing
get_complexity_metrics	Cyclomatic, nesting, LOC, cognitive
find_circular_dependencies	Project and namespace cycle detection
get_missing_members	Unimplemented interface/abstract members

Refactoring (16 tools)

Tool	Description
rename_symbol	Safe rename across solution
change_signature	Add/remove/reorder parameters
extract_method	Extract with data flow analysis
extract_interface	Generate interface from class
generate_constructor	From fields/properties
move_type_to_file	Compute the contents to move a type into its own file (generation-only)
split_type	Compute a partial-class split for selected members (generation-only)
organize_usings	Sort and remove unused
organize_usings_batch	Batch organize multiple files
format_document_batch	Batch format files in project
get_code_actions_at_position	All Roslyn refactorings at position
apply_code_action_by_title	Apply any refactoring by title
implement_missing_members	Generate interface stubs
encapsulate_field	Field to property
inline_variable	Inline temp variable
extract_variable	Extract expression to variable

Code Generation (3 tools)

Tool	Description
add_null_checks	Generate ArgumentNullException guards
generate_equality_members	Equals/GetHashCode/operators
generate_test_stub	Compilable test skeleton for a method (framework auto-detected)

Compound Tools (7 tools)

Tool	Description
get_type_overview	Full type info in one call
analyze_method	Signature + callers + outgoing calls + location
get_file_overview	File summary with diagnostics
get_method_source	Source code by name
get_method_source_batch	Multiple method sources in one call
get_instantiation_options	How to create a type
get_project_health	Composite audit dashboard: diagnostics + unused + coupling + coverage per project

Audit & Quality (10 tools)

Tool	Description
find_god_objects	Detect over-coupled types via efferent + afferent coupling + member-count thresholds
find_untested_code	Find public surface not reached by any [Fact]/[Theory]/[Test]/[TestMethod]
find_tests	Which tests cover a symbol — the inverse of find_untested_code
find_type_instantiations	Where a type is constructed (new T)
find_pattern_usages	Where a type appears in is/as/pattern matches
find_throw_sites	Where an exception type is thrown (optionally derived)
find_catch_blocks	Where an exception type is caught (optionally via a base clause)
find_async_issues	async void / blocking-on-async / unforwarded CancellationToken
check_architecture	Enforce namespace/project dependency rules over the type graph
find_naming_violations	Naming audit honoring .editorconfig rules, with conventional defaults

Discovery (3 tools)

Tool	Description
get_di_registrations	Scan DI service registrations
find_reflection_usage	Detect reflection/dynamic usage
find_interceptors	Surface [InterceptsLocation] call rerouting, generated code included

Infrastructure (12 tools)

Tool	Description
health_check	Server status
find_unused_dependencies	PackageReferences/ProjectReferences the compiler never needs
fix_all	Compute the fix for every instance of a diagnostic id (generation-only)
load_solution	Load .sln/.slnx for analysis
sync_documents	Sync file changes into loaded solution
get_project_structure	Solution structure
dependency_graph	Project dependencies
get_code_fixes	Available fixes for a diagnostic
apply_code_fix	Apply a specific code fix
get_nuget_dependencies	NuGet package listing per project
get_source_generators	List active source generators
get_generated_code	View generated source code

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 91 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
   - 91 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" }
    );
}

2. 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.

3. Build and publish:

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

4. 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

File	Purpose
src/RoslynService.cs + the src/RoslynService.*.cs partials	Tool implementations split by concern across ~30 partials (Navigation, Analysis, Refactoring, Inspection, Validation, TypeDiscovery, Discovery, ExternalApi, Quality, Metrics, CodeActions, CodeGeneration, Compound, CallAnalysis, ExceptionFlow, StackTrace, ApiSurface, SimilarCode, …) — each file's name predicts its contents
src/McpServer.cs	MCP protocol mechanics: JSON-RPC parse loop, initialize negotiation, per-call timeout, in-band vs protocol error mapping
src/ToolRegistry.cs + src/ToolDefinition.cs	The tool surface: one ToolDefinition record per tool (name, schema, ReadOnly flag, handler). Drives tools/list order and dispatch lookup
src/JsonRpcParameters.cs + JsonRpcInvalidParamsException.cs	Typed JSON-RPC argument accessors and the -32602 Invalid params exception they raise
src/*Data.cs / *Entry.cs records, ConstructorMember.cs, SignatureChange.cs	Typed records used by the audit composite, constructor generator, and signature-change parser (one type per file)

License

MIT - See LICENSE for details.