**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 properties). Explicit interface implementations (`IFoo.Bar`) are matched too.
- Parameter types parsed from the declaration line are compared case-insensitively and whitespace-insensitively, without namespace prefixes; C# aliases are mapped to their metadata names (`int` → `Int32`, `string` → `String`, …). The comparison is relaxed step by step: exact → ignoring generic arguments → allowing a prefix of the parameter list.
- When nothing matches, `(no match)` is printed followed by `candidates :` and candidate declaration lines (same-named methods of that type first, otherwise every method of that type).

The result is a text block per overload: `path` / `desc` (raw XML docs, 2000-char cap) / `namespace` / `class` / `signature` / `body` (source with the outermost braces and the common indentation removed); overloads are separated by a line containing `---`.

### `find_inheritance`

```json
{ "typeDeclaration": "public abstract class BuffEntity", "namespaceName": "Duel" }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `typeDeclaration` | string, required | — | Declaration line of the class / interface / struct / record. |
| `namespaceName` | string | any namespace | Namespace of the type; empty or `global` means the global namespace. |

The first line is the queried type itself (no indentation, no prefix); every derived type follows on its own line, indented by one tab and prefixed with `-` per hierarchy level. A class root reports the classes / records deriving from it; an interface root reports sub-interfaces plus the classes / structs / records implementing it directly. Generic base types are matched by `OriginalDefinition` (`Base<T>` and `Base<int>` count as the same base). Each type appears once, at its shallowest depth; a miss prints `(no match)` followed by `candidates :` and candidate declaration lines.

### `find_method_overrides`

```json
{ "methodDeclaration": "public abstract void Apply(BuffEntity buff)", "typeDeclaration": "public abstract class BuffEntity", "namespaceName": "Duel" }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `methodDeclaration` | string, required | — | Declaration line of the method. |
| `typeDeclaration` | string, required | — | Declaration line of the declaring class / interface / struct. |
| `namespaceName` | string | any namespace | Namespace of the declaring type; empty or `global` means the global namespace. |

The first line is the method itself; implementations / overrides follow on their own lines, indented by one tab and prefixed with `-` per hierarchy level. An interface member root reports the implementing methods in every implementing type (including explicit `IFoo.Bar` implementations); a class method root reports the `override`s in derived classes. Only the downward direction is reported — base declarations are not walked upwards. A miss prints `(no match)` followed by `candidates :` and candidate declaration lines.

### `reload_solution`

No parameters. Discards the cached snapshot and re-opens the solution, so later queries see the current files on disk. Prints `solution` / `resolveBaseDirectory` / `projects` / `reloaded : true ({ms} ms)`.

### `set_resolve_base_path`

```json
{ "basePath": "src" }
```

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `basePath` | string | solution directory | Absolute path, or a path relative to the current base directory. Empty/omitted restores the default (the directory of the solution file). |

## Type kinds and `kinds`

`kind` is lowercase and mutually exclusive: `class`, `static class`, `record`, `struct`, `record struct`, `interface`, `enum`, `delegate`. Only classes can be `static`, so `class` and `static class` are distinct; structs, enums, interfaces and delegates have no static form.

The `kinds` filter is case-insensitive and accepts multiple values (an omitted `kinds` behaves like `["class"]`):

| `kinds` value | Matches |
| --- | --- |
| *(omitted)* / `class` | every class, including static classes and records |
| `static` / `static class` | static classes only |
| `record` | records and record structs |
| `struct` | structs and record structs |
| `record struct` | record structs only |
| `enum` / `interface` / `delegate` | that kind |
| `all` | every type |

The same table, the **declaration-line protocol** (strict matching of `typeDeclaration` / `methodDeclaration` plus `candidates` recovery) and the **text output shapes** are all sent to the client as server-level instructions during the `initialize` handshake (see `Tools/ServerInstructions.cs`), so the model does not have to guess the accepted values or the output format.

## Output format

Every tool returns plain text (MCP text content) and never `structuredContent`. Paths are shown relative to the resolve base directory (default: the solution's directory), using `/` as separator.

### Listing (`list_classes_in_folder` / `list_classes_in_namespace`)

One line per type:

```
{relativePath} L{start}-{end} {namespace}: {signature}
```

The namespace segment is omitted for the global namespace (only the `:` remains); a `partial` type shows the location of its first declaration plus a trailing `...(partial xN)`; no match prints `(no match)`.

```
script/config/ItemConfig.cs L14-163: public static class ItemConfig
src/Services/UserService.cs L12-88 MyApp.Services: public class UserService : BaseService
```

### Type detail (`get_class_documentation`)

One block per same-named type, blocks separated by a line containing `---`:

```
path : {relativePath} L{start}-{end}
desc :
{raw XML documentation, truncated to maxXmlChars; the whole section is omitted when there is none}
namespace : {namespace; the global namespace prints as global}
signature : {modifiers + kind + name + type/primary-constructor parameters + constraints + base list}
body :
{member signatures, one per line: enum members / fields / properties / methods / events / nested types; omitted when there are none}
```

### Method detail (`get_method`)

One block per overload, blocks separated by a line containing `---`:

```
path : {relativePath} L{start}-{end}
desc :
{raw XML documentation, 2000-char cap}
namespace : {namespace}
class : {type name}
signature : {modifiers + return type + name + parameters (including this / ref / out / in / params)}
body :
{method source: block bodies lose their outermost braces and common indentation, expression bodies lose "=>"}
```

No match prints `(no match)` followed by `candidates :` and candidate declaration lines (brief-line format, ready to copy into the declaration parameter):

```
(no match)
candidates :
script/config/ItemConfig.cs L16-39: public static string TextName(this ItemInfo.ItemType itemType)
script/config/ItemConfig.cs L40-120: public static void RegisterItem(ItemModel model)
```

### Hierarchy (`find_inheritance` / `find_method_overrides`)

The first line is the queried type / method itself (no indentation, no `-`); derived types / implementations follow, indented by one tab and prefixed with `-` per hierarchy level:

```
script/config/BuffEntity.cs L12-40 Duel: public abstract class BuffEntity
	-script/config/DamageBuff.cs L8-25 Duel: public class DamageBuff : BuffEntity
		-script/config/BurnBuff.cs L6-18 Duel: public class BurnBuff : DamageBuff
	-script/config/HealBuff.cs L9-20 Duel: public class HealBuff : BuffEntity
```

No match prints `(no match)`; multiple roots (several equally good candidates or several matching overloads) are separated by a line containing `---`.

### Workspace (`reload_solution` / `set_resolve_base_path`)

```
solution : {absolute path of the solution file}
resolveBaseDirectory : {resolve base directory}
projects : {project count}
reloaded : true ({ms} ms)
```

## Output limits

Long payloads are truncated to keep tool results small; the appended marker reads `... [truncated: showing {n} of {m} chars]`. All thresholds live in `Services/TextTruncator.cs`.

| Payload | Default limit | How to lift it |
| --- | --- | --- |
| `desc` (XML documentation) | 2000 chars | `maxXmlChars` on `get_class_documentation` (`get_method` is fixed at 2000) |
| Method `body` | 8000 chars | `maxBodyChars` on `get_method` |

Passing `0` to `maxXmlChars` / `maxBodyChars` disables truncation for that call.

## Typical workflow

1. Start the server once with `--workspace` pointing at your solution (an MCP client does this for you).
2. Discover types: `list_classes_in_namespace { "namespaceName": "MyApp.Services" }` or `list_classes_in_folder { "folderPath": "src/Services", "kinds": ["all"] }`.
3. Read a type's contract by copying its declaration line from the listing: `get_class_documentation { "typeDeclaration": "public class UserService : BaseService" }`.
4. Read the exact implementation: `get_method { "methodDeclaration": "public User GetById(int id)", "typeDeclaration": "public class UserService : BaseService" }`.
5. Walk the hierarchy: `find_inheritance { "typeDeclaration": "public abstract class UserServiceBase" }` or `find_method_overrides { "methodDeclaration": "public abstract User GetById(int id)", "typeDeclaration": "public abstract class UserServiceBase" }`.
5. After the source files change, call `reload_solution` before the next query — otherwise queries keep answering from the stale snapshot.

## Troubleshooting

- The server exits immediately with `Solution file not found` (or another MSBuild error) on stderr → the `--workspace` path is wrong; it must point at the solution file, not at a folder.
- `The command "dnx" was not found` in the client's MCP log → `dnx` ships with the .NET SDK 10 and newer. Install .NET SDK 10, or use an installed tool or the published executable instead.
- `dotnet tool install` reports that the package is not a .NET tool → the version you asked for was packed before `PackAsTool` was enabled; install the current version instead (`dotnet tool list --global` shows what is installed).
- `spawn csharp-analyser-mcp ENOENT` or `MCP error -32000: Connection closed` in the client log → the client could not resolve the command it was told to run. Use the absolute path to `%USERPROFILE%\.dotnet\tools\csharp-analyser-mcp.exe` (a `--local` install has no shim there at all) and restart the client.
- `Cannot find package CSharpAnalyserMcp with version x.y.z` right after a release → NuGet's index can lag behind the release. Retry later, or install from the downloaded `.nupkg`: `dotnet tool install -g --add-source <folder> CSharpAnalyserMcp --version x.y.z`.

## Behavior notes and limitations

- **Snapshot semantics.** The solution is read once from disk; file edits become visible only after `reload_solution`. Unsaved editor buffers are never visible.
- **Source-only view.** Syntax trees under `bin`/`obj` are skipped, so types without source declarations are not reported.
- **Declared members only.** `get_method` does not walk base types, interfaces or the other parts of a `partial` type.
- **Exact names.** Type and method names must match exactly; namespaces are compared as full display strings. Use `namespaceName` (or a qualified `className`) to disambiguate.
- **Cost.** Every query asks each project for its compilation, so response time grows with solution size.
- **Diagnostics.** Workspace load problems are written to stderr as `[WorkspaceFailed] {Kind}: {Message}`; nothing but JSON-RPC ever reaches stdout.
- **One solution per process.** The workspace path is fixed at startup; start another instance to analyse another solution.

## License

MIT — see [LICENSE](LICENSE).

---

Building, publishing and the release process: [docs/DEVELOPMENT.zh-CN.md](docs/DEVELOPMENT.zh-CN.md) (中文).


<!-- mcp-name: io.github.undy-mosq/CSharpAnalyserMcp -->