CSharpAnalyserMcp

**English** | [简体中文](README.zh-CN.md)

# CSharpAnalyserMcp

A read-only [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets an AI assistant browse any C# solution through Roslyn.

The server loads a solution with `MSBuildWorkspace` into a cached Roslyn snapshot and then answers structured queries about it: where each type is declared, its XML documentation, and a method's signature, documentation, source location and body. An agent can therefore pull in the exact slice of source it needs instead of reading whole files into its context window.

- Transport: stdio (`StdioServerTransport`), protocol traffic on stdout only; all logs go to stderr.
- Solution path is passed on the command line (`--workspace <path to .sln>`); the solution is loaded **before** the MCP handshake, so a bad path fails fast with a message on stderr and a non-zero exit code.
- Every tool returns plain text (MCP text content) instead of `structuredContent`: listing tools emit one line per type, detail tools emit `path / desc / namespace / signature / body` blocks separated by a line containing `---`.
- Distribution: published to NuGet as the .NET tool **CSharpAnalyserMcp** (command `csharp-analyser-mcp`) and listed in the official [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.undy-mosq/CSharpAnalyserMcp`.

## Installation

### NuGet .NET tool (recommended)

```powershell
dotnet tool install --global CSharpAnalyserMcp
csharp-analyser-mcp --workspace D:\MyProject\MySolution.sln

# upgrade / remove
dotnet tool update --global CSharpAnalyserMcp
dotnet tool uninstall --global CSharpAnalyserMcp
```

Install it **globally**: a `--local` install only writes a manifest entry, so `csharp-analyser-mcp` never lands on `PATH` and MCP clients cannot start it.

### On demand with `dnx` (nothing to install, .NET SDK 10+)

```powershell
# "--" separates dnx options from the arguments forwarded to the server
dnx CSharpAnalyserMcp --yes -- --workspace D:\MyProject\MySolution.sln
```

### From source

```powershell
git clone https://github.com/undy-mosq/CSharpAnalyserMcp
dotnet build CSharpAnalyserMcp\CSharpAnalyserMcp.csproj
dotnet run --project CSharpAnalyserMcp -- --workspace D:\MyProject\MySolution.sln
```

## Requirements

| Purpose | Requirement |
| --- | --- |
| Run the published tool (`dotnet tool install --global`) | .NET SDK 8.0 or newer on `PATH` (the package targets `net8.0`) |
| Run it on demand with `dnx` | .NET SDK 10.0 or newer — `dnx` ships with the SDK |
| Build / run from source | .NET SDK 8.0 or newer (the project targets `net8.0`) |
| Load the analyzed solution | An MSBuild toolchain that can open it — Visual Studio 2022 or VS Build Tools (`Microsoft.Build.Locator` registers the newest installed instance), or the .NET SDK itself for SDK-style projects |

## Client configuration

The server is started with a single argument, `--workspace`, pointing at the solution file.

### Installed .NET tool

The global tool shim lives in `%USERPROFILE%\.dotnet\tools`. MCP clients spawn the process themselves and only see the `PATH` they inherited, so point the configuration at the shim **by absolute path** (expand `%USERPROFILE%`, e.g. `C:\Users\you\.dotnet\tools\csharp-analyser-mcp.exe`):

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "csharp-analyser": {
      "command": "C:\\Users\\you\\.dotnet\\tools\\csharp-analyser-mcp.exe",
      "args": ["--workspace", "D:\\MyProject\\MySolution.sln"]
    }
  }
}
```

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "csharp-analyser": {
      "type": "stdio",
      "command": "C:\\Users\\you\\.dotnet\\tools\\csharp-analyser-mcp.exe",
      "args": ["--workspace", "D:\\MyProject\\MySolution.sln"]
    }
  }
}
```

The bare command name (`"command": "csharp-analyser-mcp"`) works only when that directory is already on the client's `PATH`; a client started before the tool was installed keeps the old environment, so restart it after changing `PATH`.

### On demand with `dnx` (nothing installed)

```json
{
  "servers": {
    "csharp-analyser": {
      "type": "stdio",
      "command": "dnx",
      "args": ["CSharpAnalyserMcp", "--yes", "--", "--workspace", "D:\\MyProject\\MySolution.sln"]
    }
  }
}
```

Append `@<version>` to the package id to pin a version. The **MCP Server** tab of the [NuGet package page](https://www.nuget.org/packages/CSharpAnalyserMcp) offers the same JSON for copying. `dnx` is a `.cmd` shim; if the client cannot spawn it, use the equivalent `dotnet` form instead: `"command": "dotnet"` with `"args": ["tool", "exec", "CSharpAnalyserMcp", "--yes", "--", "--workspace", "D:\\MyProject\\MySolution.sln"]`.

### Published executable

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "csharp-analyser": {
      "type": "stdio",
      "command": "C:\\Tools\\csharp-analyser\\CSharpAnalyserMcp.exe",
      "args": ["--workspace", "D:\\MyProject\\MySolution.sln"]
    }
  }
}
```

### Running the project from source

```json
{
  "servers": {
    "csharp-analyser": {
      "type": "stdio",
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "D:\\MyProject\\CSharpAnalyserMcp\\CSharpAnalyserMcp\\CSharpAnalyserMcp.csproj",
        "--",
        "--workspace",
        "D:\\MyProject\\MySolution.sln"
      ]
    }
  }
}
```

Press `F5` in VS Code to debug the server itself; `.vscode/launch.json` already passes a `--workspace` argument — point it at your own solution.

## Tools

| Tool | MCP annotations | Purpose |
| --- | --- | --- |
| `list_classes_in_folder` | read-only | List type declarations in a folder and its subfolders (one line each) |
| `list_classes_in_namespace` | read-only | List type declarations in a namespace (sub-namespaces optional; one line each) |
| `get_class_documentation` | read-only | Return the XML documentation and member signatures of a type located by its declaration line |
| `get_method` | read-only | Return a method's signature, XML docs, location and body, located by its declaration line plus its declaring type's declaration line |
| `find_inheritance` | read-only | List the derived-type tree of a type (first line: the type itself) |
| `find_method_overrides` | read-only | List the overrides / implementations of a method (first line: the method itself) |
| `reload_solution` | idempotent | Rebuild the Roslyn snapshot after source files changed |
| `set_resolve_base_path` | idempotent | Change the directory used to resolve relative paths |

### `list_classes_in_folder`

```json
{ "folderPath": "src/Services", "kinds": ["class", "interface"] }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `folderPath` | string, required | — | Absolute path, or a path relative to the resolve base directory (default: the solution's directory). |
| `kinds` | string[] | `["class"]` | Type kinds to include (see [Type kinds and `kinds`](#type-kinds-and-kinds)). |

Files under `bin`/`obj` are skipped. Each type is printed as `{relativePath} L{start}-{end} {namespace}: {signature}`; the namespace segment is omitted for the global namespace, and a `partial` type reports the location of its first declaration plus a trailing `...(partial xN)`.

### `list_classes_in_namespace`

```json
{ "namespaceName": "MyApp.Services", "includeSubNamespaces": true, "kinds": ["all"] }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `namespaceName` | string | global namespace | Namespace name, e.g. `MyApp.Services`. Empty, `global`, `global namespace` or `<global namespace>` all mean the global namespace. |
| `includeSubNamespaces` | bool | `true` | Also include types declared in child namespaces. |
| `kinds` | string[] | `["class"]` | Type kinds to include. |

### `get_class_documentation`

```json
{ "typeDeclaration": "public static class ItemConfig", "maxXmlChars": 2000 }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `typeDeclaration` | string, required | — | Declaration line of the type (the `signature` segment printed by the listing tools), e.g. `public static class ItemConfig`. Whitespace is stripped, then it must match the canonical signature or the first source line of the declaration **exactly**. |
| `namespaceName` | string | any namespace | Namespace of the type; empty or `global` means the global namespace. |
| `maxXmlChars` | int | `2000` | Maximum characters of the raw XML documentation per type (the `desc` field); `0` = no limit. |

On a match the result is a text block: `path` / `desc` / `namespace` (the global namespace prints as `global`) / `signature` / `body` (member signatures, one per line); multiple matches are separated by a line containing `---`. A miss prints `(no match)` followed by `candidates :` and candidate declaration lines.

### `get_method`

```json
{ "methodDeclaration": "public static void SetEffect(RoleAttributes owner, int stack)", "typeDeclaration": "public class RoleAttributes", "namespaceName": "DuelModel" }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `methodDeclaration` | string, required | — | Declaration line of the method, e.g. `public static string TextName(this ItemInfo.ItemType itemType)`. The method name and its parameter types are parsed from this text. |
| `typeDeclaration` | string, required | — | Declaration line of the declaring class / interface / struct, e.g. `public static class ItemConfig`. |
| `namespaceName` | string | any namespace | Namespace of the declaring type; empty or `global` means the global namespace. |
| `maxBodyChars` | int | `8000` | Maximum characters of the method body; `0` = no limit. |

Matching rules:

- Both declaration lines must match the canonical signature or the first source line of the declaration **exactly** after whitespace is stripped (no substring matching).
- Only members declared by the type itself are searched (ordinary methods; no inherited members, constructors or propert