RoselineMCP

![RoselineMCP banner](.github/banner.png)

# RoselineMCP

<!-- mcp-name: io.github.Atypical-Consulting/roseline-mcp -->

> **Roslyn code intelligence for AI coding agents, over MCP.** Give Claude, Cursor, and Copilot a semantic view of your C# solution — symbols, references, call graphs, surgical edits — so they navigate by *structure* instead of re-reading source. **[Measured 85% fewer tokens (median) →](https://atypical-consulting.github.io/RoselineMCP/benchmark)**

<!-- Badges: Row 1 — Identity -->
[![Atypical-Consulting - RoselineMCP](https://img.shields.io/static/v1?label=Atypical-Consulting&message=RoselineMCP&color=blue&logo=github)](https://github.com/Atypical-Consulting/RoselineMCP)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![.NET 10](https://img.shields.io/badge/.NET-10.0-purple?logo=dotnet)](https://dotnet.microsoft.com/)
[![stars - RoselineMCP](https://img.shields.io/github/stars/Atypical-Consulting/RoselineMCP?style=social)](https://github.com/Atypical-Consulting/RoselineMCP)
[![forks - RoselineMCP](https://img.shields.io/github/forks/Atypical-Consulting/RoselineMCP?style=social)](https://github.com/Atypical-Consulting/RoselineMCP)

<!-- Badges: Row 2 — Activity -->
[![GitHub tag](https://img.shields.io/github/tag/Atypical-Consulting/RoselineMCP?include_prereleases=&sort=semver&color=blue)](https://github.com/Atypical-Consulting/RoselineMCP/releases/)
[![issues - RoselineMCP](https://img.shields.io/github/issues/Atypical-Consulting/RoselineMCP)](https://github.com/Atypical-Consulting/RoselineMCP/issues)
[![GitHub pull requests](https://img.shields.io/github/issues-pr/Atypical-Consulting/RoselineMCP)](https://github.com/Atypical-Consulting/RoselineMCP/pulls)
[![GitHub last commit](https://img.shields.io/github/last-commit/Atypical-Consulting/RoselineMCP)](https://github.com/Atypical-Consulting/RoselineMCP/commits/main)

<!-- Badges: Row 3 — Quality -->
[![CI](https://github.com/Atypical-Consulting/RoselineMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/Atypical-Consulting/RoselineMCP/actions/workflows/ci.yml)

<!-- Badges: Row 4 — Distribution -->
[![NuGet](https://img.shields.io/nuget/v/RoselineMCP.svg)](https://www.nuget.org/packages/RoselineMCP/)
[![Docker](https://img.shields.io/docker/v/phmatray/roseline-mcp?label=docker)](https://hub.docker.com/r/phmatray/roseline-mcp)

<!-- Badges: Row 5 — Docs & result -->
[![Docs & Benchmark](https://img.shields.io/badge/docs-site-e01e5a)](https://atypical-consulting.github.io/RoselineMCP/)
[![Tokens saved](https://img.shields.io/badge/tokens-85%25_fewer_(median)-1baf7a)](https://atypical-consulting.github.io/RoselineMCP/benchmark)

**📖 [Documentation, tool reference & the honest benchmark →](https://atypical-consulting.github.io/RoselineMCP/)**

---

## Table of Contents

- [Why RoselineMCP](#why-roselinemcp)
- [Quick Start](#quick-start)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Getting Started](#getting-started)
- [MCP Client Compatibility](#mcp-client-compatibility)
- [Available Tools](#available-tools)
- [Tool Annotations](#tool-annotations)
- [Tool Compatibility Policy](#tool-compatibility-policy)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Compile guard](#compile-guard)
- [Security](#security)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)

## Why RoselineMCP

Your coding agent shouldn't read a 700-line file to change one method. Source code dominates an
agent's token budget, so the cheapest win is to stop feeding it whole files.

RoselineMCP wraps the [Roslyn](https://github.com/dotnet/roslyn) compiler platform as an MCP server.
Instead of dumping source into the model, it answers *structural* questions precisely — where is
this symbol used, what implements this interface, who calls this method, what's the shape of this
file — and it edits **surgically**: a member-level diff, not a whole-file rewrite.

On RoselineMCP's own source, the read-only navigation tools returned a **median 85% fewer tokens
per task** (pooled, size-weighted: 93%) than reading the corresponding files —
[measured honestly, weak cases included](https://atypical-consulting.github.io/RoselineMCP/benchmark).

> `search_symbols` on `Program.cs`: **1,638 tokens → 71** (−96%). The agent gets the shape of the
> file; you skip the wall.

## Quick Start

Any MCP client that speaks `dnx` (the .NET equivalent of `npx`) runs it on demand — no install step.
Requires the .NET 10 SDK.

```jsonc
// claude_desktop_config.json  ·  .vscode/mcp.json  ·  ~/.cursor/mcp.json
{
  "mcpServers": {
    "roseline": { "command": "dnx", "args": ["RoselineMCP", "--yes"] }
  }
}
```

Then ask your agent to *"find every caller of `OrderService.Checkout`"* or *"rename `Foo` to `Bar`
across the solution."* Prefer a pinned NuGet install or Docker? See
[Getting Started](#getting-started).

## Features

- [x] **Token-efficient code navigation** -- symbols, references, call graphs, type hierarchies, and file outlines via Roslyn instead of whole files. A measured **85% median** token reduction per task (93% pooled, size-weighted) -- [see the benchmark](https://atypical-consulting.github.io/RoselineMCP/benchmark).
- [x] **Surgical code edits** -- replace/add/delete a member or rename a symbol solution-wide, emitting a unified diff instead of a whole-file rewrite. Preview by default.
- [x] **Comprehensive analysis & auto-fix** -- diagnostics across a solution (Roslyn + Roslynator) with automated fixes and reviewable patches.
- [x] **Read-only by default** -- the seven navigation tools and the diagnostics/patch tools never touch disk; the three write tools require an explicit `previewOnly: false`.
- [x] **Compile guard (opt-in)** -- a `PostToolUse` hook that puts the compiler's verdict behind **every** file write, not just RoselineMCP's own -- see [Compile guard](#compile-guard) below.
- [x] **Works with your client** -- Claude Desktop, VS Code (Copilot / MCP), Cursor. Install via `dnx`, NuGet global tool, or Docker.
- [x] **Honest, reproducible benchmark** -- run it against your own solution: `dotnet run --project RoselineMCP.TokenBenchmark -c Release`.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Runtime | .NET 10.0 |
| Compiler Platform | Roslyn (Microsoft.CodeAnalysis) 5.6.0 |
| Analyzers | Roslynator 4.15.0 |
| MCP SDK | ModelContextProtocol 2.2.0 |
| Diff Engine | DiffPlex 1.9.0 |
| Build System | MSBuild 18.8.2 |
| Hosting | Microsoft.Extensions.Hosting 10.0.10 |

> Versions above are kept in sync with [`RoselineMCP/RoselineMCP.csproj`](RoselineMCP/RoselineMCP.csproj) — that file is the source of truth if this table ever drifts.

## Getting Started

### Prerequisites

- **NuGet global tool**: .NET 10.0 SDK or later
- **Docker**: Docker Desktop or Docker Engine
- **Build from source**: .NET 10.0 SDK + MSBuild (included with Visual Studio or .NET SDK)
- **MCP client**: Claude Desktop or any MCP-compatible client

### Installation

> **Claude Desktop, one click:** download **`RoselineMCP.mcpb`** from the
> [latest release](https://github.com/Atypical-Consulting/RoselineMCP/releases/latest) and open it —
> Claude Desktop shows an install dialog, no config editing. (It launches via `dnx` under the hood,
> so the .NET 10 SDK is still required.) Prefer to edit config yourself, or using another client?
> Use one of the options below.

**Option 1 -- `dnx` (no install step)** *(recommended)*

RoselineMCP ships an [MCP server registry manifest](.mcp/server.json), so any MCP client that
understands the `dnx` launcher (the .NET equivalent of `npx` — resolves and runs a NuGet-packaged
tool on demand, without a separate `dotnet tool install` step) can start it directly. Requires the
.NET 10.0 SDK.

```json
{
  "mcpServers": {
    "roseline": {
      "command": "dnx",
      "args": ["RoselineMCP", "--yes"]
    }
  }
}
```

Add this to your Claude Desktop or VS Code MCP configuration (see
[MCP Client Compatibility](#mcp-client-compatibility) below for exact file locations per client).
`dnx` downloads and caches the tool on first use, so there's nothing to pre-install globally.

---

**Option 2 -- NuGet Global Tool** *(offline / pinned-version installs)*

Requires .NET 10.0 SDK or later.

```bash
dotnet tool install -g RoselineMCP
```

After installation, the `roseline-mcp` command is available globally.

#### Claude Desktop configuration (NuGet global tool)

Add to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "roseline": {
      "command": "roseline-mcp"
    }
  }
}
```

> **Config file location:**
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

---

**Option 3 -- Docker**

No SDK required. Works on any platform with Docker installed.

```bash
docker run -i --rm phmatray/roseline-mcp:latest
```

#### Claude Desktop configuration (Docker)

```json
{
  "mcpServers": {
    "roseline": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "phmatray/roseline-mcp:latest"
      ]
    }
  }
}
```

> **Note:** The `-i` flag is required for stdio transport. The `--rm` flag removes the container after the session ends.

---

**Option 4 -- Build from Source**

```bash
git clone https://github.com/Atypical-Consulting/RoselineMCP.git
cd RoselineMCP
dotnet build
dotnet test
```

#### Claude Desktop configuration (build from source)

```json
{
  "mcpServers": {
    "roseline": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/RoselineMCP/RoselineMCP.csproj"]
    }
  }
}
```

## MCP Client Compatibility

RoselineMCP speaks plain stdio MCP, so it should work with any MCP-compatible client. The
snippets below are **documented, not independently verified in every case** — we've confirmed the
prot