Claude Desktop

\n\nEdit `claude_desktop_config.json` (see file locations under [Installation](#getting-started)\nabove) and add a `roseline` entry under `mcpServers`, using any of the four install options shown\nabove (`dnx`, global tool, Docker, or build-from-source).\n\n

\n\n

VS Code (GitHub Copilot / MCP extension)

\n\nAdd an entry to your workspace or user `mcp.json` (Command Palette → \"MCP: Open User\nConfiguration\", or `.vscode/mcp.json` in the workspace):\n\n```json\n{\n \"servers\": {\n \"roseline\": {\n \"command\": \"dnx\",\n \"args\": [\"RoselineMCP\", \"--yes\"]\n }\n }\n}\n```\n\nSubstitute `\"command\": \"roseline-mcp\"` (no `args`) if you installed via the NuGet global tool\ninstead.\n\n

\n\n

Cursor

\n\nAdd a `roseline` entry to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local),\nusing the same `command`/`args` shape as the VS Code snippet above.\n\n

\n\n## Available Tools\n\nEvery tool's description — the text an MCP client shows the model at tool-selection time — states\nits own `Limitations:` and shows one `Example:` call, within a test-enforced word ceiling; the\ntwelve tools with an optional `project` share one wording for the worktree caveat below, and\n`resolvedPath` is how you confirm which checkout actually answered. See\n[docs/API.md § Tool description contract](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md#tool-description-contract).\n\n### 1. AnalyzeSolution\n\nAnalyzes an entire C# solution for diagnostics. Read-only — never modifies files on disk.\n`pathOrGit` also accepts an `http(s)://` Git URL, which is shallow-cloned to a temp directory,\nanalyzed, and deleted afterward.\n\n```typescript\nanalyzeSolution({\n pathOrGit: \"/path/to/solution.sln\",\n include: \"Core\", // Optional: only project names containing this substring\n exclude: \"Test\", // Optional: skip project names containing this substring\n severity: \"warning\", // Optional: minimum severity (Error|Warning|Info|Hidden)\n maxDiagnostics: 100 // Optional: Maximum diagnostics to return (default: 100)\n})\n```\n\n**Returns:** solution file name, project count, a `diagnosticSummary` (counts by severity), a\n`topDiagnostics` array with project/file/line/column/id/severity/message per diagnostic, and\n`analyzerLoad` — present only when an analyzer reference contributed nothing (merged across the\nanalyzed projects), naming it and why.\n\n### 2. ListDiagnostics\n\nGets detailed diagnostics for a specific project. Read-only — never modifies files on disk.\n`project` is **optional** and accepts the same references as the navigation tools (name,\ndirectory, `.csproj`, or `.sln` path); when omitted, the solution/project is auto-discovered from\nthe working directory.\n\n```typescript\nlistDiagnostics({\n project: \"MyProject.csproj\", // Optional: name, directory, .csproj, or .sln; auto-discovered if omitted\n ids: [\"CS0168\", \"CS0219\"], // Optional: Filter by diagnostic IDs\n files: [\"Controller.cs\"], // Optional: substring match against each diagnostic's file path (case-insensitive; NOT a glob pattern)\n max: 50 // Optional: Maximum results\n})\n```\n\n**Returns:** project name, `resolvedPath` (the absolute `.sln`/`.csproj` actually loaded),\n`totalDiagnostics` count, the filtered `diagnostics` list, `stats` (counts grouped by ID and by\nseverity), `suggestedFixableIds` — diagnostic IDs a code fix provider is actually registered for,\nwhether it ships with Roslyn, in the bundled Roslynator catalog, or **inside one of the project's\nown analyzer references** — and `analyzerLoad`, which names every analyzer reference that\ncontributed nothing (and why), present only when there is something to say.\n\n### 3. ApplyFixes\n\nApplies automated code fixes for specified diagnostics. **Defaults to preview mode**:\n`previewOnly` defaults to `true`, so calling this tool without setting it never writes to disk —\nyou must pass `previewOnly: false` explicitly to apply changes. `project` is **optional** and\naccepts the same references as the navigation tools (name, directory, `.csproj`, or `.sln` path);\nwhen omitted, the solution/project is auto-discovered from the working directory.\n\n```typescript\napplyFixes({\n ids: [\"CS0168\", \"RCS1001\"], // Diagnostic IDs to fix\n project: \"MyProject.csproj\", // Optional: name, directory, .csproj, or .sln; auto-discovered if omitted\n previewOnly: false // Optional (default: true). Set false to write changes to disk.\n})\n```\n\n**Returns:** project name, `resolvedPath` (the absolute `.sln`/`.csproj` actually loaded),\n`fixedCount`, `fixersApplied` (diagnostic IDs actually fixed), `changedFiles`\n(relative to `resolvedPath`'s directory, forward slashes — the same path base as the navigation\ntools), a unified\ndiff `patch`, `notes` (the scope — which project was fixed and which of the solution's projects were\nnot analyzed, plus any linked file whose write reaches a sibling — and skipped/failed IDs and status\nmessages), `previewOnly` echoing back what the caller asked for, `applied` (whether anything\nactually reached disk), `verification` — the compiler's verdict on the fixed code — and\n`analyzerLoad` (present only when an analyzer reference contributed nothing, so \"no diagnostics\nfound for X\" can be told apart from \"the analyzer that reports X never loaded\"). Fixers are looked\nup in the Roslyn built-ins, then the bundled Roslynator catalog, then the project's own analyzer\nreferences; the bundled provider wins for an ID both carry.\n\nA `.sln` target fixes **one** project — its primary project — and that scope is enforced on the\nwrite path, not only announced by the confirmation prompt: only the anchor project's documents are\nverified and written, and a caller who never sees a prompt (preview, a non-eliciting client, an\nunattended host) still reads which projects were skipped in `notes`. Pass a `.csproj` to fix a\nspecific project — then nothing is reported as skipped, since that is what was asked for.\n\n### 14. CheckCompilation\n\nAnswers **\"does this compile right now, and what broke\"** against on-disk state — the replacement\nfor a `dotnet build` round trip in an agent's edit loop. Read-only, and compiler diagnostics only:\nanalyzers cost several times a bare compile, which is the whole reason this tool is fast enough to\nrun after every edit.\n\nIt reports on whatever is on disk, whoever wrote it, so it works just as well for edits made by\nother tools. The speed comes from the warm `MSBuildWorkspace` the server already holds: the first\ncall of a session pays a cold load, every call after it reuses an incremental Roslyn compilation.\n\n```typescript\ncheckCompilation({\n project: \"MyApp.sln\", // Optional: name, directory, .csproj, or .sln; auto-discovered if omitted\n max: 20 // Optional (default: 20). The rest are counted in `omitted`.\n})\n```\n\n**Returns:** `resolvedPath`, `compiles`, `errors` (omitted when it compiles), `omitted`, `scope`\n(the projects compiled), `scopeComplete` and `notes`.\n\n> **`check_compilation` vs `list_diagnostics`:** `check_compilation` answers *\"is it still\n> building?\"* — compiler errors, fast, for the edit loop. `list_diagnostics` answers *\"what should I\n> clean up?\"* — analyzer diagnostics, statistics, and which IDs are auto-fixable. Reach for the\n> first after an edit and the second when exploring.\n\n### 4. CreatePatch\n\nGenerates a unified diff between two text versions. Read-only — operates purely on the provided\nstrings, never touches the filesystem.\n\n```typescript\ncreatePatch({\n before: \"original code\",\n after: \"modified code\",\n fileName: \"Example.cs\", // Optional: For display in diff\n ignoreWhitespace: false, // Optional: ignore whitespace-only differences\n ignoreCase: false // Optional: ignore case differences\n})\n```\n\n**Returns:** the unified diff `patch`, `hasChanges`, `linesAdded`, `linesRemoved`, and the\n`fileName`/`summary` used in the diff header.\n\n### Code Navigation Tools (read-only)\n\nThese tools return **precise structure instead of whole files**, so an AI agent can orient itself\nin a codebase while spending far fewer tokens than reading source directly. All are read-only and\ntake an **optional** `project` (name, directory, `.csproj` path, or `.sln` path) — when omitted,\nRoselineMCP auto-discovers the solution/project from its working directory. When the project belongs\nto a solution, the whole solution is loaded and symbol search/resolution spans every project in it\n(including sibling projects the requested project doesn't reference), so references/renames span\nprojects. Full request/response shapes are in [docs/API.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md).\n\n> **Working in a git worktree?** Auto-discovery is anchored to **the server's** working directory —\n> the one the MCP client launched RoselineMCP in — not yours. They differ whenever work happens in a\n> git worktree (e.g. `.claude/worktrees/`), which sits below the discovery walk's reach, so an\n> omitted `project` resolves the **main checkout** instead. Every tool that takes an optional\n> `project` — the seven navigation tools, both edit tools, `listDiagnostics` and `applyFixes` —\n> reports `resolvedPath`, the absolute `.sln`/`.csproj` that actually answered — the `.sln` when the\n> solution was loaded and contains the project, otherwise the `.csproj` that was opened directly\n> (e.g. a project not listed in its nearest ancestor `.sln`). Check it, and pass\n> an absolute path as `project` to target a specific checkout. (`analyzeSolution` is the exception:\n> its `pathOrGit` is required, so it auto-discovers nothing.)\n>\n> **Failures report it too**, which is where you will usually meet this: the wrong checkout answers\n> `NotFoundError: Symbol not found: 'X'` rather than a plausible-looking success. The failure\n> envelope's `error.resolvedPath` names the checkout that was searched, and is omitted entirely when\n> the call failed before resolving anything. See [docs/API.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md#which-checkout-answered).\n>\n> **Relative file paths hang off `resolvedPath`.** The navigation tools' `file`/`definitionFile`,\n> `applyFixes`/`editMember`/`renameSymbol`'s `changedFiles` **and patch headers**, and\n> `verification.errors[]`/`checkCompilation`'s `errors[]` `file`, are relative\n> to the directory containing `resolvedPath` — so `dirname(resolvedPath) + ` is the\n> real file, and a returned `patch` applies (`git apply -p1`) from that directory. That is the\n> solution root in the usual case, and the project's own directory whenever a `.csproj` answered\n> directly — including a project not listed in its nearest ancestor `.sln`. One exception:\n> `listDiagnostics`/`analyzeSolution` report `file` **absolute**, so there is nothing to join. See\n> [docs/API.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md#code-navigation-tools).\n\n> **Tool names on the wire are `snake_case`.** The section headings below use friendly\n> PascalCase/`camelCase` for readability, but the actual MCP tool names returned by `tools/list`\n> (and expected by `tools/call`) are: `search_symbols`, `get_symbol_info`, `find_references`,\n> `find_implementations`, `get_call_graph`, `get_type_hierarchy`, `get_symbol_at_position`,\n> `edit_member`, `rename_symbol`\n> (matching the existing `analyze_solution` / `list_diagnostics` / `apply_fixes` /\n> `check_compilation` / `create_patch`).\n\n#### 5. SearchSymbols\n\nFind symbols by wildcard/substring name pattern, or outline a single file.\n\n```typescript\nsearchSymbols({\n project: \"MyApp.Core\",\n query: \"*Service\", // Substring, or wildcard with * and ? — omit to outline a file\n file: \"UserService.cs\", // Optional: restrict to one file, or outline it when query omitted\n kinds: [\"class\", \"method\"], // Optional: filter by kind (also accepts \"type\" / \"member\")\n max: 50 // Optional (default: 50)\n})\n```\n\n**Returns:** `symbols` (name, fullName, kind, signature, file, line — `file` is relative to `resolvedPath`'s directory; the single-file outline instead returns name, kind, signature, line, containingType), `totalFound`, `truncated` (omitted when not capped).\n\n#### 6. GetSymbolInfo\n\nThe compact \"go to definition\": a symbol's declaration metadata and (optionally) its source.\n\n```typescript\ngetSymbolInfo({\n project: \"MyApp.Core\",\n symbol: \"Acme.Users.UserService.GetUser\", // Simple or fully-qualified name\n includeSource: true // Optional (default: true)\n})\n```\n\n**Returns:** name, fullName, kind, signature, and (each omitted when empty/absent) modifiers, baseTypes, interfaces, documentation, definitionFile/Line, and source. Accessibility is already part of `signature`; `definitionFile` is relative to `resolvedPath`'s directory.\n\n#### 7. FindReferences\n\nEvery use site of a symbol across the solution, as location + one-line snippet.\n\n```typescript\nfindReferences({ project: \"MyApp.Core\", symbol: \"GetUser\", includeDefinition: false, max: 100 })\n```\n\n**Returns:** `references` (file — relative to `resolvedPath`'s directory, line, snippet), `totalReferences`, `truncated` (omitted when not capped).\n\n#### 8. FindImplementations\n\nImplementations of an interface/member, overrides of a virtual/abstract member, or derived types of a class.\n\n```typescript\nfindImplementations({ project: \"MyApp.Core\", symbol: \"IRepository\", max: 100 })\n```\n\n**Returns:** `implementations` (symbol summaries), `totalFound`, `truncated`.\n\n#### 9. GetCallGraph\n\nA depth-bounded caller and/or callee graph for a method, with cycle detection.\n\n```typescript\ngetCallGraph({\n project: \"MyApp.Core\",\n method: \"Handle\",\n direction: \"callers\", // \"callers\" (default) | \"callees\" | \"both\"\n depth: 1, // 1-3 (default: 1)\n max: 50 // Optional: nodes expanded per direction\n})\n```\n\n**Returns:** `callers`/`callees` trees of nodes (fullName with simple parameter-type names, file — relative to `resolvedPath`'s directory, line, truncated, children). Call GetSymbolInfo for a node's full signature.\n\n#### 10. GetTypeHierarchy\n\nA type's base-class chain, implemented interfaces, and/or derived types.\n\n```typescript\ngetTypeHierarchy({\n project: \"MyApp.Core\",\n type: \"SqlRepository\",\n direction: \"both\", // \"base\" | \"derived\" | \"both\" (default)\n max: 100 // Optional: maximum derived types returned (default: 100)\n})\n```\n\n**Returns:** `baseTypes`, `interfaces`, `derivedTypes` (as symbol summaries).\n\n#### 13. GetSymbolAtPosition\n\nThe symbol living at a `file:line(:column)` position — turn a diagnostic, stack trace, or grep hit\ninto a symbol name without reading the file.\n\n```typescript\ngetSymbolAtPosition({\n project: \"MyApp.Core\",\n file: \"UserService.cs\", // File name or path suffix (same matching as SearchSymbols)\n line: 42, // 1-based\n column: 17 // Optional (1-based) — omit to resolve the most relevant symbol on the line\n})\n```\n\n**Returns:** name, fullName, kind, signature, `isDeclaration` (whether the position sits on the symbol's own declaration), and (each omitted when empty/absent) containingType, documentation, definitionFile/Line (relative to `resolvedPath`'s directory). Line-only queries prefer declarations on the line over referenced symbols.\n\n### Code Editing Tools (preview by default)\n\nSurgical edits that emit a member-level change rather than a whole-file rewrite. Like `ApplyFixes`,\nboth **default to preview mode** (`previewOnly: true`) — nothing is written to disk unless you pass\n`previewOnly: false` explicitly.\n\n#### 11. EditMember\n\nReplace, add, or delete a single type member; returns a unified diff.\n\n```typescript\neditMember({\n project: \"MyApp.Core\",\n symbol: \"Acme.UserService.GetUser\", // The member (replace/delete), or the container type (add)\n operation: \"replace\", // \"replace\" | \"add\" | \"delete\"\n newSource: \"public User GetUser(int id) => _repo.Find(id);\", // Required for replace/add\n previewOnly: false // Optional (default: true). Set false to write to disk.\n})\n```\n\n**Returns:** operation, target, `changedFiles`, `patch`, `previewOnly`, `applied`, `notes`.\n\n#### 12. RenameSymbol\n\nRename a symbol and update every reference across the solution (Roslyn rename); returns a unified diff.\n\n```typescript\nrenameSymbol({ project: \"MyApp.Core\", symbol: \"GetUser\", newName: \"GetUserById\", previewOnly: false })\n```\n\n**Returns:** symbol, newName, `changedFiles`, `patch`, `previewOnly`, `applied`, `verification`, `notes`.\n\n> **Every write is compile-verified.** Before `edit_member`, `rename_symbol` or `apply_fixes`\n> touches disk, the candidate change is compiled in memory. If it *introduces* compiler errors —\n> including in a downstream project you never named — the write is **refused**: the call still\n> succeeds, `applied` comes back `false`, nothing is written, and you get the diff *and* the\n> errors. Pass `allowIntroducedErrors: true` to write anyway. A repository that was already\n> broken stays editable: the gate is what the change *introduces*, never whether the tree\n> compiles. See [Compile Verification](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md#compile-verification) for the scope rule and\n> the guarantee boundary.\n\n## Tool Annotations\n\nRoselineMCP's SDK (`ModelContextProtocol` 2.2.0) supports the standard MCP tool\n[annotation hints](https://modelcontextprotocol.io/) (`readOnlyHint`, `destructiveHint`,\n`idempotentHint`), and every tool declares them via `[McpServerTool(ReadOnly = ..., Destructive =\n..., Idempotent = ...)]`:\n\n| Tool | readOnlyHint | destructiveHint | idempotentHint | Notes |\n|------|:---:|:---:|:---:|-------|\n| `AnalyzeSolution` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `ListDiagnostics` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `ApplyFixes` | ❌ false | ⚠️ true | ❌ false | `destructiveHint` is a static, worst-case annotation: it's `true` because the tool *can* write files when `previewOnly: false` is passed, even though the default call (`previewOnly` unset, i.e. `true`) writes nothing. The SDK's annotation model has no way to express \"destructive only for a specific parameter value\" — see the doc comment on `ApplyFixesTool.ApplyFixes` in source. |\n| `CheckCompilation` | ✅ true | ❌ false | ✅ true | Never writes to disk. Compiles the loaded solution and reports the compiler's verdict. |\n| `CreatePatch` | ✅ true | ❌ false | ✅ true | Operates purely on the two provided strings; never touches the filesystem. |\n| `SearchSymbols` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `GetSymbolInfo` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `FindReferences` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `FindImplementations` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `GetCallGraph` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `GetTypeHierarchy` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `GetSymbolAtPosition` | ✅ true | ❌ false | ✅ true | Never writes to disk. |\n| `EditMember` | ❌ false | ⚠️ true | ❌ false | Same worst-case `destructiveHint` rationale as `ApplyFixes`: writes a file only when `previewOnly: false` is passed; the default call writes nothing. |\n| `RenameSymbol` | ❌ false | ⚠️ true | ❌ false | Same worst-case `destructiveHint` rationale as `ApplyFixes`: writes files only when `previewOnly: false` is passed; the default call writes nothing. |\n\nThese hints are static per-tool metadata for MCP clients that surface them (e.g. to warn a user\nbefore an agent invokes a destructive tool) — they describe the tool's worst-case behavior, not\nthe outcome of any specific call. See [Tool Compatibility Policy](#tool-compatibility-policy)\nbelow for the stability guarantees around tool names and parameters that these annotations sit on\ntop of.\n\n## Tool Compatibility Policy\n\n- **Tool names and required parameters are stable within a major version.** An MCP client\n integration written against `AnalyzeSolution(pathOrGit, ...)` on `1.x` will keep working across\n all `1.x` releases.\n- **Optional parameters may be added in minor versions** (e.g. `CreatePatch` gained\n `ignoreWhitespace`/`ignoreCase` as optional, defaulted parameters without breaking existing\n callers).\n- **Renaming or removing a parameter, changing a parameter's required/optional status, or\n changing a tool's name is a breaking change.** Breaking changes are called out under a\n dedicated \"Breaking Changes\" heading in [`CHANGELOG.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/CHANGELOG.md) and only ship in a major\n version bump.\n- Response *shapes* (JSON field names/types) are documented in [`docs/API.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md) and\n follow the same policy: additive fields are non-breaking, renamed/removed fields are breaking.\n\n## Supported Analyzers\n\nThe diagnostics tools (`analyze_solution`, `list_diagnostics`, `apply_fixes`) report compiler\ndiagnostics plus analyzer diagnostics, executed via Roslyn's `CompilationWithAnalyzers`\n(`check_compilation` is deliberately **not** in this list — it is compiler-only, which is what makes\nit fast enough for an edit loop):\n\n- **Roslyn Analyzers** -- Built-in C# compiler diagnostics\n- **Roslynator** -- 500+ analyzers and fixes for C#, **bundled with RoselineMCP** (shipped as an\n `analyzers/` folder next to `RoselineMCP.dll`) and executed by default, so RCS* diagnostics\n surface and are fixable out of the box\n- **Custom Analyzers** -- Any Roslyn-based analyzer referenced by your analyzed solution is\n loaded from the project's analyzer references and run alongside the bundled ones (there is no\n built-in StyleCop.Analyzers reference — add it to your analyzed solution if you want SA*\n diagnostics). **Their code fixers are loaded too**: an analyzer-reported rule is auto-fixable\n when a matching fixer ships with Roslyn, in the bundled catalog, or inside one of the project's\n own analyzer references (the bundled one wins for an ID both carry).\n\n**What could not be loaded is named.** Roslyn reports an analyzer reference it cannot load — one\nbuilt against a newer `Microsoft.CodeAnalysis` than RoselineMCP's, a corrupt file — by\ncontributing *zero* analyzers, not by failing. The three diagnostics responses carry an\n`analyzerLoad` block (`analyzersRan`, `referencesConsulted`, `referencesContributing`, `analyzersLoaded`, and a\n`notes[]` entry per reference that contributed nothing: its name, the reason — `load-failure`\nwith Roslyn's `errorCode` and message, `no C# analyzers`, or `exception`). The block is omitted\nwhen every reference contributed, so a present one always says something; see\n[`docs/API.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md#analyzerloadreport).\n\nSet `RoselineMCP:RunAnalyzers` to `false` for compiler-only diagnostics (faster on big\nsolutions; see [Configuration](#configuration) and the analyzer-execution note in\n[`SECURITY.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md)). The block is then present with `analyzersRan: false`, so \"off\"\nstays distinguishable from \"all fine\".\n\n## Examples\n\n### Analyzing a Solution\n\n```bash\n# Using with an MCP client\nmcp call analyzeSolution '{\n \"pathOrGit\": \"/Users/dev/MyProject/MyProject.sln\",\n \"severity\": \"warning\",\n \"maxDiagnostics\": 50\n}'\n```\n\nResponse:\n```json\n{\n \"solution\": \"MyProject.sln\",\n \"projects\": 5,\n \"diagnosticSummary\": {\n \"error\": 2,\n \"warning\": 15,\n \"info\": 28\n },\n \"topDiagnostics\": [\n {\n \"id\": \"CS0168\",\n \"severity\": \"warning\",\n \"message\": \"The variable 'ex' is declared but never used\",\n \"file\": \"Program.cs\",\n \"line\": 42\n }\n ]\n}\n```\n\n### Applying Fixes\n\n```bash\nmcp call applyFixes '{\n \"project\": \"MyProject.Core.csproj\",\n \"ids\": [\"CS0168\", \"RCS1001\"],\n \"previewOnly\": true\n}'\n```\n\nResponse includes a unified diff patch showing all changes that would be applied.\n\n## Configuration\n\nRoselineMCP reads `appsettings.json` and `appsettings.{Environment}.json` from the directory the\nserver binary is installed in (`AppContext.BaseDirectory`) — **not** from the process working\ndirectory. Launching the server from inside a target repository never picks up that repository's\nown `appsettings.json`, and the settings packaged with the `dotnet tool` install are always found.\nConfiguration is read once at startup; there is no reload-on-change file watching.\n\n### Environment Variables\n\nEnvironment variables prefixed with `ROSELINE_` override the JSON files, using `__` as the section\nseparator. Settings under the `RoselineMCP` section therefore take a double prefix:\n\n```bash\n# RoselineMCP:EnableDiagnosticLogging\nROSELINE_RoselineMCP__EnableDiagnosticLogging=true\n\n# RoselineMCP:DefaultTimeout (ms)\nROSELINE_RoselineMCP__DefaultTimeout=300000\n\n# RoselineMCP:RunAnalyzers (compiler-only diagnostics when false)\nROSELINE_RoselineMCP__RunAnalyzers=false\n\n# RoselineMCP:ConfirmDestructiveWrites (no elicitation before writes; unattended hosts)\nROSELINE_RoselineMCP__ConfirmDestructiveWrites=false\n\n# RoselineMCP:ConfirmDestructiveWritesTimeout (ms to wait for that confirmation; 0 = forever)\nROSELINE_RoselineMCP__ConfirmDestructiveWritesTimeout=300000\n\n# Logging:LogLevel:RoselineMCP\nROSELINE_Logging__LogLevel__RoselineMCP=Debug\n```\n\n- `DOTNET_ENVIRONMENT`: Set environment (Development, Production)\n\n### appsettings.json\n\nConfigure logging and other settings:\n\n```json\n{\n \"Logging\": {\n \"LogLevel\": {\n \"Default\": \"Information\",\n \"RoselineMCP\": \"Debug\"\n }\n },\n \"RoselineMCP\": {\n \"DefaultTimeout\": 120000,\n \"EnableDiagnosticLogging\": false,\n \"WorkspaceCache\": true,\n \"RunAnalyzers\": true,\n \"ConfirmDestructiveWrites\": true,\n \"ConfirmDestructiveWritesTimeout\": 300000\n }\n}\n```\n\n- `RoselineMCP:DefaultTimeout`: Wall-clock **analysis** budget (ms) applied to each tool call, in addition to the caller's own cancellation. `0` disables it. On the three write tools it does not cover the whole invocation: when a write confirmation is elicited, this clock starts only *after* the human answers, so think-time is charged to `ConfirmDestructiveWritesTimeout` instead. Size it for the analysis, not for the span a caller observes.\n- `RoselineMCP:EnableDiagnosticLogging`: Opt-in, local-only tracing of tool invocations — see [Debug Logging](#debug-logging). Disabled by default; enabled in `appsettings.Development.json`.\n- `RoselineMCP:WorkspaceCache`: Reuse the loaded MSBuild workspace across navigation/edit tool calls (enabled by default) — see [Performance](#performance). Set to `false` to load a fresh workspace on every call. **This is an isolation/debugging switch, not a memory-saving one** — measured, disabling it costs ~26% more resident memory and ~45× second-call latency; see [Memory Management](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/ARCHITECTURE.md#memory-management).\n- `RoselineMCP:RunAnalyzers`: Run Roslyn analyzers (bundled Roslynator + the target project's own analyzer references) in the diagnostics tools (enabled by default) — see [Supported Analyzers](#supported-analyzers). Set to `false` for compiler-only diagnostics.\n- `RoselineMCP:ConfirmDestructiveWrites`: Ask the client to confirm (via MCP elicitation) before a write tool actually writes, when the caller passed `previewOnly: false` (enabled by default). Set to `false` for unattended hosts — CI, headless agents, or any client that cannot answer an elicitation — in which case the explicit `previewOnly: false` opt-in is the only guard before a write.\n- `RoselineMCP:ConfirmDestructiveWritesTimeout`: How long (ms) to wait for that confirmation before treating the silence as \"no\" and returning a preview (default `300000`, 5 minutes). It is deliberately **not** `DefaultTimeout` — that is an analysis budget, and a human reading a real diff may legitimately exceed it. A client that accepts the prompt and never answers used to block the tool call forever; set this to `0` or less to restore that unbounded wait.\n\n## Architecture\n\nRoselineMCP uses **stdio transport** — this is an intentional design decision. The server runs as a local process launched by the MCP client (Claude Desktop, AI agents), communicates over stdin/stdout, and exits when the client disconnects. This makes it perfectly suited for distribution as a NuGet global tool (`dotnet tool install -g RoselineMCP`) or Docker image — no port binding, no HTTP server, no infrastructure to manage.\n\n```\n┌─────────────────────┐\n│ MCP Client │\n│ (Claude Desktop, │\n│ AI Assistants) │\n└────────┬────────────┘\n │ MCP Protocol (stdio)\n ▼\n┌─────────────────────┐\n│ RoselineMCP │\n│ MCP Server │\n│ │\n│ ┌───────────────┐ │\n│ │ Tool Layer │ │\n│ │ (Analyze, │ │\n│ │ Fix, Patch) │ │\n│ └───────┬───────┘ │\n│ ▼ │\n│ ┌───────────────┐ │\n│ │ Service Layer │ │\n│ │ (Workspace, │ │\n│ │ Diagnostics) │ │\n│ └───────┬───────┘ │\n│ ▼ │\n│ ┌───────────────┐ │\n│ │ Roslyn + │ │\n│ │ Roslynator │ │\n│ │ Analyzers │ │\n│ └───────────────┘ │\n└─────────────────────┘\n │\n ▼\n┌─────────────────────┐\n│ C# Source Code │\n│ (.sln / .csproj) │\n└─────────────────────┘\n```\n\n## Project Structure\n\n```\nRoselineMCP/\n├── RoselineMCP/\n│ ├── Interfaces/ # Service interfaces\n│ ├── Services/ # Core business logic\n│ ├── Tools/ # MCP tool implementations\n│ ├── Models/ # Data transfer objects\n│ └── Program.cs # Application entry point\n├── RoselineMCP.Tests/ # Unit tests\n├── .github/workflows/ # CI/CD pipelines\n├── Dockerfile # Container build\n└── RoselineMCP.sln # Solution file\n```\n\n## Performance\n\n- **Workspace Cache** -- The navigation, edit, and diagnostics/fix tools (`ListDiagnostics`,\n `ApplyFixes`, and everything backed by `IProjectLoader`) reuse the loaded `MSBuildWorkspace`\n across calls, cutting hundreds of milliseconds of reload off every call after the first. Cached\n entries are fingerprinted (last-write-time + size of the `.sln`, every `.csproj`, and every\n source file, plus their directories) and re-checked on each call, so any change on disk —\n including RoselineMCP's own edits — triggers a fresh reload. A file/directory whose own last\n write was still fresh when its stamp was captured also gets a content signature (a hash, or a\n directory listing) recorded alongside it, so a same-length write landing in the same\n filesystem-timestamp bucket is still caught by comparing that signature rather than trusted on a\n bare stat match — cheaply, without forcing a reload on every call while the file stays fresh.\n Disable with\n `RoselineMCP:WorkspaceCache = false` — but note that this is an isolation/debugging switch, **not**\n a way to reduce memory: a disposed workspace's memory is not returned to the OS, so disabling the\n cache measures ~26% *worse* on resident memory as well as ~45× slower. The measured profile — and\n why an idle-release was evaluated and rejected — is in\n [Memory Management](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/ARCHITECTURE.md#memory-management)\n- **Workspace Isolation (AnalyzeSolution)** -- `AnalyzeSolution` still creates a fresh\n `MSBuildWorkspace` per operation (see [Architecture](#architecture))\n- **Sequential Project Analysis** -- Projects within a solution are analyzed one at a time, not\n concurrently, to keep MSBuild workspace state consistent\n- **Result Capping** -- `maxDiagnostics`/`max` bound how many diagnostics are returned per call,\n independent of how many were found\n\n## Compile guard\n\nThe compile gate behind `EditMember`/`RenameSymbol`/`ApplyFixes` only fires on writes made **through\nthose tools**. The compile guard puts the same verdict behind every file write in a C# solution —\n`Edit`, `Write`, `MultiEdit`, whatever your agent reached for — by running as a `PostToolUse` hook\nthat asks the already-running server for a verdict over a local socket.\n\n**It reports; it cannot block.** `PostToolUse` fires *after* the tool has written, and the hook\ncontract carries no blocking decision. What the guard does is surface the introduced compiler errors\nto the agent inside the same turn, so the next thing it does is repair them instead of building on\ntop of them. Preventing the write is not on offer — see\n[the issue](https://github.com/Atypical-Consulting/RoselineMCP/issues/168) for why the alternative\nthat *can* block was rejected.\n\nTurn it on (it is **off** by default), then install the hook:\n\n```bash\n# 1. the server opens the local guard endpoint\nexport ROSELINE_RoselineMCP__Guard=true\n\n# 2. print the settings.json block and paste it into .claude/settings.json\nroseline-mcp guard --print-hook\n```\n\nWhat it does on each write:\n\n| Situation | Result |\n|---|---|\n| The edit introduced compiler errors | the errors, in the agent's turn (exit `2`, stderr) |\n| The edit introduced nothing | **silence** — exit `0`, no output, no tokens |\n| The branch was already red | **silence** — pre-existing errors are not the agent's doing |\n| Not a `.cs` file, or no owning project | **silence** |\n| Server not running, or slow to answer | **silence** — a guard that cannot inform must not interrupt |\n\nCompiler diagnostics only, and scoped to the changed project plus its dependents, so it is fast\nenough to sit in an inner loop. It adds a local IPC endpoint: read\n[SECURITY.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md#known-risk-the-compile-guard-endpoint) before enabling it on a shared\nmachine.\n\n## Security\n\n- **Read-Only by Default** -- `AnalyzeSolution`, `ListDiagnostics`, `CreatePatch`, and all six code\n navigation tools (`SearchSymbols`, `GetSymbolInfo`, `FindReferences`, `FindImplementations`,\n `GetCallGraph`, `GetTypeHierarchy`) never write to disk. The three write-capable tools —\n `ApplyFixes`, `EditMember`, and `RenameSymbol` — each default to `previewOnly: true`; writing\n requires the caller to pass `previewOnly: false` explicitly. Behind that opt-in sits a second,\n best-effort guard: the write tools ask the client to confirm via MCP elicitation before writing,\n and a decline downgrades the call to a preview. So does an unanswered prompt — the round-trip is\n bounded by `RoselineMCP:ConfirmDestructiveWritesTimeout` (default 5 minutes), after which the call\n returns a preview rather than writing or hanging. That confirmation is skipped when the client\n cannot elicit, and an operator can disable it outright with\n `RoselineMCP:ConfirmDestructiveWrites=false` — after which `previewOnly: false` is the only guard\n left. See [SECURITY.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md).\n- **Real, Read-Only Git Cloning** -- `pathOrGit` accepts `http(s)://` Git URLs, which are\n shallow-cloned (`git clone --depth 1`) into a temp directory that's deleted after the operation.\n No other URL scheme is treated as a Git remote.\n- **MSBuild Is Not a Sandbox** -- loading a `.sln`/`.csproj` via `MSBuildWorkspace` is a\n design-time MSBuild evaluation and can execute build logic embedded in the project (``\n tasks, custom `UsingTask` assemblies, imported `.targets`/`.props`). Analyzing a fully untrusted\n repository or URL carries a real code-execution risk on the host. **See\n [`SECURITY.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md)** for the full write-up and operator recommendations before\n pointing RoselineMCP at untrusted input.\n- **Analyzer Execution Is Code Execution** -- the diagnostics tools also run the target project's\n own referenced Roslyn analyzers in-process (see\n [Supported Analyzers](#supported-analyzers)); an analyzer from an untrusted repository is\n arbitrary code. `RoselineMCP:RunAnalyzers = false` disables the **diagnostic analyzer** pass\n (bundled Roslynator included). See [`SECURITY.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md).\n- **Code-Fix Providers Come From Those Same References** -- `list_diagnostics` and `apply_fixes`\n also load the `CodeFixProvider` types a project's own analyzer references carry. That adds no\n assembly the analyzer pass does not already load (each is obtained through the reference's own\n assembly loader), but it is a decision rather than an accident, and `RunAnalyzers = false` does\n not govern it. Recorded in [`SECURITY.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md).\n- **Source Generators Run Regardless Of That Switch** -- generators ship through the same\n `AnalyzerReferences`, but run as part of building *any* compilation rather than as part of the\n diagnostics pass, so every semantic path executes them -- all navigation tools included. They\n cannot be suppressed without breaking semantic analysis. `RunAnalyzers = false` narrows the\n code-execution surface of an untrusted repository; it does not close it. Isolate instead --\n see [`SECURITY.md`](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md).\n- **No Dedicated Path-Traversal Sandbox** -- paths are resolved with plain existence checks, not\n canonicalized against an allowed root; treat `pathOrGit`/`project`/`branch` as trusted operator\n input.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **MSBuild not found**: Ensure .NET SDK is installed and in PATH\n2. **Solution won't load**: Check for missing NuGet packages, run `dotnet restore`\n3. **No analyzer (RCS*/SA*) diagnostics found**: Verify `RoselineMCP:RunAnalyzers` isn't set to `false`; for non-bundled rule sets (e.g. StyleCop), verify the analyzer is installed in the target project\n4. **Permission denied**: Ensure read access to solution files\n\n### Debug Logging\n\nEnable detailed logging:\n\n```bash\nROSELINE_Logging__LogLevel__RoselineMCP=Debug dotnet run --project RoselineMCP/RoselineMCP.csproj\n```\n\n### Tracing Individual Tool Calls\n\nEvery tool call gets a per-invocation correlation ID (a GUID). It's cheap to generate so it's\nalways created, but it's only surfaced when you need it: it's included in every JSON error\nresponse (`correlationId`) and attached to that call's log lines via `ILogger.BeginScope`, so a\nuser reporting a failure can hand you one ID that ties back to the full server-side log entry —\nwithout needing to grep timestamps.\n\nFor deeper, opt-in tracing of each tool invocation (start/stop, duration, success/failure) as a\n`System.Diagnostics.Activity` span, set `RoselineMCP:EnableDiagnosticLogging` to `true` (it's\nalready `true` in `appsettings.Development.json`):\n\n```bash\nROSELINE_RoselineMCP__EnableDiagnosticLogging=true dotnet run --project RoselineMCP/RoselineMCP.csproj\n```\n\nThis uses the built-in `ActivitySource`/`Activity` APIs rather than the OpenTelemetry SDK, so it\nadds no extra dependency. Spans are logged exclusively through the existing `ILogger` pipeline,\nwhich is already routed to stderr — never to stdout (the MCP JSON-RPC channel) — and nothing is\never sent over the network; when the flag is off (the default), no listener is registered and the\nspans cost essentially nothing.\n\n## Roadmap\n\n- [ ] Additional analyzer rule sets (SonarAnalyzer, FxCop)\n- [ ] Auto-fix suggestions with confidence scoring\n- [ ] CI/CD integration for automated analysis pipelines\n- [ ] Multi-solution support in a single session\n- [ ] Incremental analysis (only changed files)\n- [ ] Custom analyzer rule configuration via MCP\n\n> Want to contribute? Pick any roadmap item and open a PR!\n\n## Documentation\n\n- **[Documentation site](https://atypical-consulting.github.io/RoselineMCP/)** -- overview, tool\n reference, and the [token-savings benchmark](https://atypical-consulting.github.io/RoselineMCP/benchmark)\n (built from `website/`, deployed to GitHub Pages)\n- [docs/API.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/API.md) -- Full request/response reference for every MCP tool, service\n interfaces, models, and the error-response contract\n- [docs/AGENT-BENCHMARK.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/AGENT-BENCHMARK.md) -- End-to-end A/B: does an AI agent actually\n spend fewer tokens with RoselineMCP? (honest answer — a large-codebase win, break-even on small)\n- [docs/ARCHITECTURE.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/docs/ARCHITECTURE.md) -- Layered architecture, data flow, and design\n patterns\n- [PROMPTS.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/PROMPTS.md) -- Example prompts and end-to-end workflows for each tool\n- [CHANGELOG.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/CHANGELOG.md) -- Release history and breaking changes\n- [SECURITY.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/SECURITY.md) -- Vulnerability reporting and the MSBuild code-execution caveat\n- [CONTRIBUTING.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/CONTRIBUTING.md) -- Development setup and PR process\n\n## Atypical MCP servers\n\nPart of a suite of Model Context Protocol servers by Atypical Consulting:\n\n- [RoselineMCP](https://github.com/Atypical-Consulting/RoselineMCP) — Roslyn code intelligence for AI agents\n- [ASTral](https://github.com/Atypical-Consulting/ASTral) — structured code retrieval (tree-sitter)\n- [AdrMcp](https://github.com/Atypical-Consulting/AdrMcp) — Architecture Decision Records over MCP\n- [MarkdownInk](https://github.com/Atypical-Consulting/MarkdownInk) — Markdown rendering for the terminal\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/CONTRIBUTING.md) first.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit using [conventional commits](https://www.conventionalcommits.org/) (`git commit -m 'feat: add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\n[MIT](https://github.com/Atypical-Consulting/RoselineMCP/blob/dev/LICENSE) © 2026 [Atypical Consulting SRL](https://atypical.garry-ai.cloud)\n\n## Acknowledgments\n\n- Built on [Roslyn](https://github.com/dotnet/roslyn) -- The .NET Compiler Platform\n- Powered by [Roslynator](https://github.com/JosefPihrt/Roslynator) -- C# analyzers and refactorings\n- Uses [DiffPlex](https://github.com/mmanela/diffplex) -- Diff generation library\n- Implements [Model Context Protocol](https://modelcontextprotocol.io) -- AI assistant integration protocol\n\n---\n\nBuilt with care by [Atypical Consulting](https://atypical.garry-ai.cloud) -- opinionated, production-grade open source.\n\n[![Contributors](https://contrib.rocks/image?repo=Atypical-Consulting/RoselineMCP)](https://github.com/Atypical-Consulting/RoselineMCP/graphs/contributors)\n\n\n---\nBuilt by [Atypical Consulting](https://www.atypical.consulting). We also make\n[NuGetKeep](https://nugetkeep.com/?utm_source=github-readme&utm_medium=readme&utm_campaign=launch-2026-07),\na self-hosted NuGet server with supply-chain quarantine.\n\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ai","ai-agents","claude","claude-code","code-analysis","code-intelligence","code-navigation","copilot","csharp","cursor","developer-tools","dotnet","llm","roslyn","token-efficiency","topics",[94,95,96,97,98,99,100,101,102,103,104,105,106,125,126,127,107,108],"license","MIT","language","C#","registryName","io.github.Atypical-Consulting/roseline-mcp","homepage","https://atypical-consulting.github.io/RoselineMCP/","packages",[121],{"_122":123,"_124":24,"_71":72},"registryType","nuget","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_130":131,"_132":133,"_134":135},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]