dotnet-sherlock-mcp

# Sherlock MCP for .NET

**Sherlock MCP for .NET** is a comprehensive Model Context Protocol (MCP) server that provides deep introspection capabilities for .NET assemblies. It enables Language Learning Models (LLMs) to analyze and understand your .NET code with precision, delivering accurate and context-aware responses for complex development scenarios.

This tool is essential for developers who want to harness LLM capabilities for:

*   **Deep codebase analysis** - Understanding complex .NET architectures and dependencies
*   **Precise type information** - Getting detailed metadata about types, members, and their signatures
*   **Automated documentation** - Extracting and utilizing XML documentation and attributes
*   **Custom tooling** - Building sophisticated tools that interact with .NET assemblies
*   **Code generation** - Creating accurate code based on existing type structures

## Key Features

*   **Comprehensive MCP Server**: Provides 36 specialized tools for .NET assembly analysis
*   **Advanced Assembly Introspection**: Deep reflection-based analysis of types, members, and metadata
*   **Rich Member Analysis**: Detailed inspection of methods, properties, fields, events, and constructors
*   **Smart Filtering & Pagination**: Advanced filtering by name/attributes with efficient pagination for large datasets
*   **XML Documentation Integration**: Automatic extraction of summary, parameters, returns, and remarks
*   **Performance Optimized**: Caching, streaming, and memory-efficient processing
*   **Stable JSON API**: Consistent envelopes with versioning and structured error codes
*   **.NET 9.0 Native**: Built on the latest .NET platform with modern C# features
*   **Project Integration**: Solution and project file analysis with dependency resolution
*   **Current MCP SDK**: Built on `ModelContextProtocol` 1.4.0 (GA)

## What's New in 2.11.0

- **Built-in usage guidance**: the server now emits MCP usage instructions to connecting clients, so agents learn the token-efficient projections and discovery → type → member workflow without external docs.
- **Refreshed agent guidance**: `CLAUDE.md`, `GEMINI.md`, the README, and the runtime member-analysis docs now document the snake_case tool names, lean `projection` defaults, and recommended analysis workflow. See `CHANGELOG.md` for full details.

## Installation

Install the global tool from NuGet (adds `sherlock-mcp` to your PATH):

```bash
dotnet tool install -g Sherlock.MCP.Server
```

Alternatively, during development you can run the server locally:

```bash
dotnet run --project src/server/Sherlock.MCP.Server.csproj
```

## Configure Your MCP Client

Sherlock runs as a standard MCP server that communicates over stdio.

- Cursor: Settings → MCP / Custom tools → Add tool → Command: `sherlock-mcp`
- Claude Desktop / other MCP clients: Add a server entry pointing to the `sherlock-mcp` command. Example JSON entry (refer to your client’s docs for exact file location/format):

```jsonc
{
  "servers": {
    "sherlock": {
      "command": "sherlock-mcp"
    }
  }
}
```

No arguments are required. The server self-registers all tools when launched.

## Auto-Configure for .NET Projects

**You usually don't need to paste anything.** Sherlock ships its usage guidance in the MCP `instructions` field returned at initialize, and most MCP clients (including Claude Code) surface that to the agent automatically — so the guidance stays correct and versioned with the package, with no copy-paste to maintain.

The snippets below are **optional reinforcement**. Keep them short and principle-based rather than enumerating tool names and workflows: a static list pasted into your repo will drift as Sherlock's tools evolve, whereas the tools' own descriptions (and the server `instructions`) always match the version you're running.

> Tool names are exposed in `snake_case` (`get_type_methods`, `search_members`, …); argument names stay camelCase (`projection`, `nameContains`).

### Claude Code (CLAUDE.md)

Optional — a short pointer in your project's `CLAUDE.md`:

```markdown
## .NET Assembly Analysis

Use the Sherlock MCP tools (`get_type_methods`, `search_members`, …) for .NET type/assembly
questions instead of guessing. Locate DLLs with the `find_assembly_by_*` / `get_project_output_paths`
tools rather than hardcoding bin paths. Start lean — `search_members` or `get_types_from_assembly`,
then drill in — and pass `projection='full'` only when you need parameters/attributes/modifiers.
The tools' own descriptions cover the specifics.
```

### Cursor (.cursor/rules)

The single-file `.cursorrules` format is **deprecated** (and silently ignored in Cursor's Agent mode).
Add a Project Rule at `.cursor/rules/sherlock.mdc` instead:

```mdc
---
description: Use Sherlock MCP for .NET assembly/type analysis
alwaysApply: true
---

- Prefer the Sherlock MCP tools (snake_case, e.g. `get_type_methods`, `search_members`) over guessing about .NET APIs.
- Find DLLs with `find_assembly_by_*` / `get_project_output_paths`; don't hardcode `bin/Debug/<tfm>/*.dll`.
- Start lean (`search_members` / `get_types_from_assembly`); request `projection='full'` only when you need parameters/attributes/modifiers.
```

### Other agents (AGENTS.md)

For tools that follow the cross-editor `AGENTS.md` convention, the same short pointer works — drop the Claude Code snippet above into your `AGENTS.md`.

### Global configuration

For system-wide usage, add to your global agent settings:

```text
For .NET work, use the Sherlock MCP tools (snake_case) to analyze assemblies, types, and members instead of guessing. Start lean and opt into projection='full' only when you need detail.
```

## How To Prompt It

Below are compact prompt snippets you can paste into your chat to get productive fast. Adjust paths to your local DLLs.

General setup

```text
You have access to an MCP server named "sherlock" that can analyze .NET assemblies. Prefer these tools for .NET questions and include short reasoning for which tool you chose. Ask me for the assembly path if missing.
```

Enumerate members for a type

```text
Analyze: /absolute/path/to/MyLib/bin/Debug/net9.0/MyLib.dll
Type: MyNamespace.MyType
List methods, including non-public, filter name contains "Async", include attributes, return JSON.
```

Get XML docs for a member

```text
Use GetXmlDocsForMember on /abs/path/MyLib.dll, type MyNamespace.MyType, member TryParse. Summarize the summary + params.
```

Find types and drill in

```text
List types from /abs/path/MyLib.dll; then get type info for the first result and list its nested types.
```

Tune paging and filters

```text
Use GetTypeMethods on /abs/path/MyLib.dll, type MyNamespace.MyType, sortBy name, sortOrder asc, skip 0, take 25, hasAttributeContains Obsolete.
```

Browse lean, then get detail (projection)

```text
On /abs/path/MyLib.dll, run GetTypeMethods for MyNamespace.MyType with the default summary projection to see signatures. Then re-call GetTypeMethods with projection='full' only for the methods I name to get their parameters and attributes.
```

Trace relationships and call sites

```text
On /abs/path/MyLib.dll: FindImplementationsOf MyNamespace.IMyService. Then FindReferencesTo that interface with analysisDepth='il' to find callers, and GetMethodCalls on the most relevant method to see what it invokes.
```

## Tools Overview

> **Tool names:** MCP clients call these tools in `snake_case` — `GetTypeMethods` → `get_type_methods`, `SearchMembers` → `search_members`, and so on. The PascalCase names used throughout this README match the underlying C# methods and the tool descriptions your client displays.

### Assembly Discovery & Analysis
- **`AnalyzeAssembly`**: Complete assembly overview with public types and metadata
- **`GetAssemblyInfo`**: Assembly-level metadata — identity/version, target framework, and referenced assemblies (`projection=full` adds all assembly attributes)
- **`FindAssemblyByClassName`**: Locate assemblies containing specific class names
- **`FindAssemblyByFileName`**: Find assemblies by file name in common build paths
- **`FindAssemblyByNugetPackage`**: Resolve a DLL from the local NuGet cache by package id (optional `version`/`tfm`)

### Type Introspection
- **`GetTypesFromAssembly`**: List all public types with metadata (paginated)
- **`AnalyzeType`**: Comprehensive type analysis with all members
- **`GetTypeInfo`**: Detailed type metadata (accessibility, generics, nested types)
- **`GetTypeHierarchy`**: Inheritance chain and interface implementations
- **`GetGenericTypeInfo`**: Generic parameters, arguments, and variance information
- **`GetTypeAttributes`**: Custom attributes declared on types
- **`GetNestedTypes`**: Nested type declarations

### Member Analysis (Filterable & Paginated)
- **`GetAllTypeMembers`**: All members across all categories
- **`GetTypeMethods`**: Method signatures, overloads, and metadata
- **`GetTypeProperties`**: Property details including getters/setters and indexers
- **`GetTypeFields`**: Field information including constants and readonly fields
- **`GetTypeEvents`**: Event declarations with handler types
- **`GetTypeConstructors`**: Constructor signatures and parameters
- **`AnalyzeMethod`**: Deep method analysis with overloads and attributes

### Member Search
- **`SearchMembers`**: Search a whole assembly for members whose name contains a fragment — the entry point when you know a member name but not its declaring type. Filter by `memberKinds` (`method|property|field|event|type`).

### Reverse Lookup
- **`FindImplementationsOf`**: Types implementing an interface or deriving from a base class (open-generic match supported)
- **`FindMethodsReturning`**: Methods whose return type matches a given type (open-generic match supported)
- **`FindExtensionMethodsFor`**: Extension methods that extend a given type (scans static classes by `this`-parameter)
- **`FindReferencesTo`**: Broader sweep across parameters, fields, properties, events, and generic arguments; pass `ana