RoslynLens

A token-efficient MCP (Model Context Protocol) server for .NET codebase
navigation, powered by Roslyn semantic analysis. Designed for use with
Claude Code.

Instead of reading entire .cs files (500-2000+ tokens each), Claude Code
queries this MCP server and receives focused, semantic results (30-150
tokens). This dramatically reduces token consumption when working with
large .NET solutions.

Features

34 Navigation & Analysis Tools

18 Anti-Pattern Detectors

General .NET detectors:

Domain-specific detectors:

Optional Roslynator analyzers

Beyond the curated detectors above, get_diagnostics can optionally run the
bundled Roslynator analyzers (500+
rules) by passing includeAnalyzers: true. They ship with the tool and load on
demand, so the default path stays compiler-only and fast. See
docs/tools/project.md for details.

Requirements

• .NET 10 SDK or later (to run the tool itself)
• A .NET solution (.sln or .slnx)

RoslynLens runs on .NET 10, but analyzes any C# project regardless of its
target framework (.NET Framework 4.x, .NET Core, .NET 5–10). If your
solution's global.json pins a specific SDK, that SDK must also be
installed so MSBuild can restore and load it.

Installation

dotnet tool install --global RoslynLens

Claude Desktop (one-click bundle)

RoslynLens ships an MCP Bundle manifest in
mcpb/. Pack it and drag the .mcpb into Claude
Desktop → Settings → Extensions — no manual config editing. The bundle picks
your solution path and tuning through a settings UI and launches the server via
dnx (so the .NET 10 SDK is still required):

npx @anthropic-ai/mcpb pack mcpb roslyn-lens.mcpb

See docs/getting-started/installation.md.

Docker

A container image bundles the .NET SDK (required because MSBuildWorkspace
evaluates MSBuild at runtime). Mount the repository to analyse at /workspace
and keep stdin open (-i) so the server can speak MCP over stdio:

docker build -t roslyn-lens .
docker run --rm -i -v "$PWD":/workspace roslyn-lens

Usage

With Claude Code (recommended)

Add to your Claude Code MCP configuration:

# User-scoped (available in all projects)
claude mcp add --scope user --transport stdio roslyn-lens -- roslyn-lens

# Project-scoped
claude mcp add --transport stdio roslyn-lens -- roslyn-lens

Or via .mcp.json in your project root:

{
  "mcpServers": {
    "roslyn-lens": {
      "type": "stdio",
      "command": "roslyn-lens",
      "args": []
    }
  }
}

Solution Discovery

The server automatically finds the nearest .sln or .slnx file
using BFS from the current directory (max 3 levels up). You can
also specify a solution explicitly:

roslyn-lens --solution /path/to/MySolution.slnx

When multiple solutions are discovered, the server auto-selects
the shallowest one and logs a warning. Use list_solutions and
switch_solution to change at runtime without restarting.

Standalone

roslyn-lens

The server communicates over stdio using the MCP protocol.

Building from Source

git clone https://github.com/jfmeyers/roslyn-lens.git
cd roslyn-lens
dotnet build
dotnet test

Pack and install locally

dotnet pack -c Release -o ./nupkgs
dotnet tool install --global --add-source ./nupkgs RoslynLens

Token efficiency

RoslynLens exists to let an agent navigate a codebase by structure instead of
re-reading source. A reproducible benchmark quantifies the saving: for every
single-type source file it compares the full file against the real
get_public_api response, counting both with the GPT-4o (o200k_base)
tokenizer whose vocabulary ships embedded in the package — so the run is fully
offline.

dotnet run --project benchmarks/RoslynLens.TokenBenchmark -c Release

Self-hosted on this repository it reports a 77% pooled / 73% median token
reduction. Results and a per-type table are written to
docs/BENCHMARKS.md.

Configuration

Environment variables for runtime tuning:

Architecture

src/RoslynLens/
├── Program.cs                  # Host + MCP stdio transport
├── SolutionDiscovery.cs        # BFS .sln/.slnx auto-discovery
├── WorkspaceManager.cs         # MSBuildWorkspace, LRU compilation cache
├── WorkspaceInitializer.cs     # Background solution loading
├── SymbolResolver.cs           # Cross-project symbol resolution + fuzzy FQN
├── RoslynLensConfig.cs          # Environment variable configuration
├── WorkspaceState.cs           # Workspace loading state enum
├── ComplexityAnalyzer.cs       # Cyclomatic/cognitive complexity metrics
├── DuplicateCodeDetector.cs    # AST fingerprinting for duplicate detection
├── ExternalSourceResolver.cs   # SourceLink + decompilation for NuGet deps
├── Tools/                      # 34 MCP tool implementations
├── Analyzers/                  # 18 anti-pattern detectors
└── Responses/                  # Token-optimized DTOs

Key design decisions:

• Lazy compilation: Solutions with 50+ projects only compile
  on-demand (LRU cache of 50 compilations)
• File watcher: .cs changes trigger incremental text updates;
  .csproj changes trigger full reload
• Background loading: Solution loads asynchronously; tools return
  "loading" status until ready
• Logs to stderr: All logging goes to stderr to keep stdout clean
  for JSON-RPC

Acknowledgments

Inspired by
CWM.RoslynNavigator
by Mukesh Murugan (MIT License). Adapted with additional detectors,
auto-discovery, and global tool distribution.

Documentation

Full documentation is available in the docs/ directory and
online at https://jfmeyers.github.io/roslyn-lens/ — an Astro site
(docs-website/) generated from those same markdown files and
deployed to GitHub Pages.

Author

JF Meyers — GitHub

License

Apache License 2.0