dotnet-sherlock-mcp

Sherlock MCP for .NET

Sherlock MCP for .NET 是一款功能全面的模型上下文协议（MCP）服务，可对 .NET 程序集进行深入分析。它支持大语言模型（LLM）精准分析和理解你的 .NET 代码，为复杂开发场景提供准确且结合上下文的响应。

对于希望利用大模型能力的开发者来说，这款工具必不可少，可用于：

• 深入分析代码库 - 理解复杂的 .NET 架构及其依赖关系
• 精准获取类型信息 - 获取类型、成员及其签名的详细元数据
• 自动生成文档 - 提取和利用 XML 文档及特性
• 自定义工具 - 构建与 .NET 程序集交互的高级工具
• 代码生成 - 根据现有类型结构创建准确的代码

主要功能

• 全面的 MCP 服务：提供 47 个专用于 .NET 程序集分析的工具；可选的 24 工具 core 配置还支持按需分组加载其他工具
• 高级程序集分析：基于反射深入分析类型、成员及元数据
• 丰富的成员分析：详细检查方法、属性、字段、事件和构造函数
• 智能筛选与分页：按名称／特性进行高级筛选，并针对大型数据集高效分页
• XML 文档集成：自动提取摘要、参数、返回值和备注
• 性能优化：采用缓存、分页和高效内存处理
• 稳定的 JSON API：提供包含版本信息和结构化错误代码的一致封装
• 现代 .NET：面向 .NET 8、9 和 10
• 项目集成：分析解决方案和项目文件，并解析依赖项
• 工作流提示词：explore_package、explain_type 和 who_calls 提示词可一键启动常见分析工作流
• 当前 MCP SDK：基于 ModelContextProtocol 2.1.0（GA）构建
• 当前 MCP 规范：支持协议修订版 2026-07-28，并自动协商以兼容使用更早修订版的客户端

2.15.0 版本更新

• 读取和比较代码：get_member_source 通过 PDB 或 Source Link 返回成员的原始源代码；decompile_member／decompile_type 可将代码反编译为 C#；compare_api_surface 可比较两个程序集或包版本的差异并标记破坏性变更。
• 框架模式：find_endpoints、find_service_registrations、find_ef_entities 和 find_handlers 可列出 ASP.NET Core 端点、DI 注册、EF Core 实体和 MediatR 处理程序。
• 精准解析：框架类型根据目标框架的引用包解析，依赖项从项目的 project.assets.json 中解析（get_package_graph 可显示还原后的依赖关系图），项目工具则通过 MSBuild 评估项目。
• 提升 Agent 使用体验：open_assembly 句柄、工作流提示词（explore_package、explain_type、who_calls）、层次结构和调用图的 Mermaid 图表，以及 core 配置下带发现提示的按需工具组。
• 更适配 Windows：检查的程序集不再被锁定，因此服务运行期间也能成功重新生成。完整详情请参阅 CHANGELOG.md。

安装

使用 dnx 运行（.NET 10 SDK）

使用 .NET 10 SDK 时，dnx 会从 NuGet 下载程序包并直接运行，无需安装：

dnx -v q --yes [email protected]

--yes 会跳过交互式确认提示，因为通过标准输入/输出启动服务的 MCP 客户端无法响应此提示。首次下载某个版本时，-v q 会阻止 dnx 向标准输出打印“Skipping NuGet package signature verification.”通知，否则会导致 MCP 数据流损坏，并使首次连接失败。这两项都是 dnx 选项，因此必须放在程序包 ID 前面；其后的任何内容都会传递给服务。固定版本可确保启动过程可复现；要升级时再更新版本。该程序包以 McpServer 程序包类型发布，因此也会作为 MCP 服务列在 NuGet.org 上。

安装为全局工具

在任何受支持的 SDK（.NET 8 或更高版本）上，都可以从 NuGet 安装全局工具（将 sherlock-mcp 添加到 PATH）：

dotnet tool install -g Sherlock.MCP.Server

或者，在开发过程中，你可以在本地运行服务：

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

配置 MCP 客户端

Sherlock 作为标准 MCP 服务运行，通过标准输入/输出进行通信。

Claude Code 插件

此仓库也是 Claude Code 插件市场。sherlock 插件包含该服务（通过 dnx 启动，因此需要 .NET 10 SDK）以及一项技能，用于指导 Agent 按照定位 → 了解概况 → 深入探查 → 梳理关系的工作流进行操作：

/plugin marketplace add jcucci/dotnet-sherlock-mcp
/plugin install sherlock@dotnet-sherlock-mcp

插件使用 core 工具配置启动服务，与该技能涵盖的工具相匹配。需要时，Agent 可以通过 load_tools 按组添加其他工具（参见工具组）。若要从一开始就启用所有工具，请在启动 Claude Code 的环境中设置 SHERLOCK_TOOL_PROFILE=full。

每位用户只需运行这些命令一次；之后重启 Claude Code（或运行 /reload-plugins）。要获取新版本，请运行 /plugin marketplace update dotnet-sherlock-mcp。如果你之前使用 claude mcp add 注册过 Sherlock，请移除该条目（claude mcp remove sherlock），以免重复加载工具。

团队设置

若要让仓库中的所有成员都能使用此插件，请将以下内容提交到该仓库的 .claude/settings.json。每位队友信任此文件夹时，Claude Code 都会提示他们安装插件，因此无需手动输入上述命令：

{
  "extraKnownMarketplaces": {
    "dotnet-sherlock-mcp": {
      "source": {
        "source": "github",
        "repo": "jcucci/dotnet-sherlock-mcp"
      }
    }
  },
  "enabledPlugins": {
    "sherlock@dotnet-sherlock-mcp": true
  }
}

队友仍需将 .NET 10 SDK 添加到其 PATH 中，才能使用 dnx。

使用 dnx

• Claude Code：

claude mcp add sherlock -- dnx -v q --yes [email protected]

• VS Code（.vscode/mcp.json）：

{
  "servers": {
    "sherlock": {
      "type": "stdio",
      "command": "dnx",
      "args": ["-v", "q", "--yes", "[email protected]"]
    }
  }
}

使用全局工具

• Cursor：设置 → MCP / 自定义工具 → 添加工具 → 命令：sherlock-mcp
• Claude Desktop / 其他 MCP 客户端：添加指向 sherlock-mcp 命令的服务条目。JSON 条目示例（确切的文件位置和格式请参阅客户端文档）：

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

无需提供参数。服务启动时会自动注册所有工具。

工具配置

大量工具会占用 Agent 的上下文并降低工具的可发现性（当工具描述超过上下文窗口的大约 10% 后，Claude Code 会切换到延迟工具搜索）。Sherlock 可以从较小的工具集开始：

配置	工具数	内容
full（默认）	47	所有工具，包括已弃用的各类型成员工具
core	24	load_tools 和 invoke_tool（参见工具组）、发现工具（find_assembly_by_class_name、find_assembly_by_file_name、find_assembly_by_nuget_package、get_project_output_paths、open_assembly）、概览工具（get_assembly_info、get_types_from_assembly、get_type_info、get_type_hierarchy）、成员和文档工具（get_type_members、search_members、analyze_method、get_xml_docs_for_type、get_xml_docs_for_member）以及关系工具（find_implementations_of、find_methods_returning、find_extension_methods_for、find_references_to、get_method_calls）、源码工具（get_member_source、decompile_member）和 API 差异工具（compare_api_surface）

使用 --profile 参数或 SHERLOCK_TOOL_PROFILE 环境变量选择配置（参数优先）。如果配置名称无效，服务将报错并停止。

{
  "servers": {
    "sherlock": {
      "command": "sherlock-mcp",
      "args": ["--profile", "core"]
      // or: "env": { "SHERLOCK_TOOL_PROFILE": "core" }
    }
  }
}

工具组

使用 core 配置时，其他工具都属于某个工具组，Agent 可在需要时加载：

工具组	工具
frameworks	find_endpoints、find_service_registrations、find_ef_entities、find_handlers
project	analyze_solution、analyze_project、resolve_package_references、get_package_graph、find_deps_json_dependencies
metadata	analyze_assembly、get_generic_type_info、get_nested_types、get_type_attributes、get_member_attributes、get_parameter_attributes
decompile	decompile_type
config	get_runtime_options、update_runtime_options
legacy	已弃用的 analyze_type、get_all_type_members 和 get_type_{methods,properties,fields,events,constructors}

• load_tools：不带参数时，会列出所有工具组、各组中的工具以及工具组是否已加载。传入 groups=['frameworks', …] 时，会将这些工具添加到服务的工具列表，并返回每个已加载工具的名称、描述和输入架构。随后，服务会发送 notifications/tools/list_changed。在协议修订版 2026-07-28 下，只有通过 subscriptions/listen 请求接收此通知的客户端才能收到。

• invoke_tool：通过 name 和 arguments 对象调用已加载的工具，并返回该工具自身的结果。即使客户端从未刷新工具列表，也仍可通过这种方式使用已加载的工具组。如果调用的工具所属工具组尚未加载，则会失败并返回 ToolNotLoaded，同时指出该工具组。

• 发现提示：核心工具的结果可能包含 hints[]，其中每项为 { tool, reason, group }，用于指向相关工具。例如：

  • 对具有嵌套类型或泛型参数的类型，或属于 DbContext、控制器或 MediatR 处理程序的类型调用 get_type_info；
  • 对这些框架类型或 IServiceCollection 调用 find_implementations_of / find_references_to / find_extension_methods_for；
  • decompile_member → decompile_type；
  • get_project_output_paths → analyze_project 和 get_package_graph。

  依赖项错误会建议使用 get_package_graph。对于核心工具，group 为 null。

• 工具列表缓存：使用 core 配置时，tools/list 会标记为 cacheScope: private，因为会话的工具列表会随工具组的加载而扩展。使用 full 配置时，它仍标记为 public。

full 配置会列出所有工具，并省略 load_tools 和 invoke_tool。

为 .NET 项目自动配置

通常无需粘贴任何内容。 Sherlock 会在初始化时返回的 MCP instructions 字段中提供使用指南，大多数 MCP 客户端（包括 Claude Code）都会自动将其呈现给 Agent。这样一来，指南就能随软件包保持正确并同步更新，无需维护复制粘贴的内容。

以下代码片段是可选的补充说明。请尽量简短并以原则为主，不要罗列工具名称和工作流：粘贴到仓库中的静态列表会随着 Sherlock 工具的演进而过时，而工具自身的描述（以及服务端的 instructions）始终与当前运行的版本一致。

工具名称以 snake_case 形式公开（get_type_members、search_members 等）；参数名称仍为 camelCase（projection、nameContains）。

Claude Code（CLAUDE.md）

如果你安装了 Claude Code 插件，其技能已包含这些内容。否则，你可以在项目的 CLAUDE.md 中添加一个简短的可选指引：

## .NET Assembly Analysis

Use the Sherlock MCP tools (`get_type_members`, `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）

单文件 .cursorrules 格式已弃用（并且在 Cursor 的 Agent 模式下会被静默忽略）。 请改为在 .cursor/rules/sherlock.mdc 添加项目规则：

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

- Prefer the Sherlock MCP tools (snake_case, e.g. `get_type_members`, `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.

其他 Agent（AGENTS.md）

对于遵循跨编辑器 AGENTS.md 约定的工具，同样可以使用这一简短指引——将上面的 Claude Code 代码片段放入你的 AGENTS.md 即可。

全局配置

如需在系统范围内使用，请添加到全局 Agent 设置中：

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.

如何编写提示词

以下是简短的提示词片段，可粘贴到聊天中，帮助你快速开始使用。请根据本地 DLL 的路径进行调整。

常规设置

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.

枚举类型的成员

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.

获取成员的 XML 文档

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

查找类型并深入查看

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

调整分页和筛选条件

Use GetTypeMembers on /abs/path/MyLib.dll, type MyNamespace.MyType, kinds method, sortBy name, sortOrder asc, skip 0, take 25, hasAttributeContains Obsolete.

先精简浏览，再获取详细信息（投影）

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

追踪关系和调用位置

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.

工具概览

工具名称： MCP 客户端以 snake_case 调用这些工具——GetTypeMembers → get_type_members、SearchMembers → search_members 等。本 README 中使用的 PascalCase 名称与底层 C# 方法以及客户端显示的工具描述一致。

程序集发现与分析

• OpenAssembly：返回一个简短的 asm_… 句柄，可在任何接受程序集的工具中作为 assemblyHandle 传入，以替代 assemblyPath。该句柄还会携带 additionalAssemblies，在服务端重启后仍会保留（保存在 SHERLOCK_STATE_DIR 下的 handles.json 中；默认位置为用户本地应用数据目录下的 sherlock 文件夹），并与当前构建版本绑定：重新构建后，调用会失败并返回 StaleAssemblyHandle，直到重新打开程序集
• AnalyzeAssembly：完整的程序集概览，包含公共类型和元数据
• GetAssemblyInfo：程序集级元数据——标识和版本、目标框架以及引用的程序集（projection=full 会添加所有程序集特性）；frameworkResolution 会报告类型所依据的框架：目标框架的引用包（referencePack，例如 Microsoft.NETCore.App.Ref/8.0.x/ref/net8.0，以及 Microsoft.AspNetCore.App.Ref 和项目 FrameworkReference 或应用的 runtimeconfig.json 指定的其他包）、独立部署输出目录中的程序集自身目录（appLocal），或者未安装匹配的引用包或目标为 .NET Framework 时的服务端运行时（hostRuntime，并在 missingFrameworks 中列出未匹配的框架）
• FindAssemblyByClassName：按简单名称、完整名称或嵌套名称查找声明了公共类型的程序集；跳过 obj/、ref/、refint/、node_modules/、packages/、TestResults/ 和点开头的目录，并优先匹配 bin/ 目录
• FindAssemblyByFileName：在根目录下按文件名查找程序集，排除目录并排序规则与上方相同
• FindAssemblyByNugetPackage：根据软件包 ID 从本地 NuGet 缓存解析 DLL（可选的 version/tfm）

类型内省

• GetTypesFromAssembly：列出所有公共类型及其元数据（分页）
• AnalyzeType (已弃用)：类型元数据及其所有成员；请使用 GetTypeInfo + GetTypeMembers projection=full
• GetTypeInfo：详细类型元数据（可访问性、泛型、嵌套类型）
• GetTypeHierarchy：继承链和接口实现；format='mermaid' 会返回 Mermaid classDiagram
• GetGenericTypeInfo：泛型参数、实参和变体信息
• GetTypeAttributes：类型上声明的自定义特性
• GetNestedTypes：嵌套类型声明

成员分析（可筛选和分页）

• GetTypeMembers：在一个分页列表中列出类型的方法、属性、字段、事件和构造函数。可使用 kinds（method|property|field|event|constructor）、nameContains 和 hasAttributeContains 缩小范围；summary 项为 { kind, name, signature }，projection=full 会为每种成员类型添加结构化字段
• AnalyzeMethod：深入分析方法，包括重载和特性
• 已弃用，将保留一两个版本： GetTypeMethods、GetTypeProperties、GetTypeFields、GetTypeEvents、GetTypeConstructors（请使用带 kinds 的 GetTypeMembers）和 GetAllTypeMembers（请使用 GetTypeMembers projection=full）

成员搜索

• SearchMembers：在整个程序集内搜索名称包含某个片段的成员——当你知道成员名称但不知道其声明类型时，可从此入口开始。可使用 memberKinds（method|property|field|event|type）筛选。

反向查找

• FindImplementationsOf：查找实现某个接口或派生自某个基类的类型（支持开放泛型匹配）
• FindMethodsReturning：查找返回类型与给定类型匹配的方法（支持开放泛型匹配）
• FindExtensionMethodsFor：查找扩展给定类型的扩展方法（通过 this 参数扫描静态类）
• FindReferencesTo：更广泛地扫描参数、字段、属性、事件和泛型实参；传入 analysisDepth='il' 还可从方法体中解析调用当前方法的方法

框架模式

位于 frameworks 工具组中（始终列在 full 下）。每个工具都会扫描一个或多个程序集（additionalAssemblies），并通过 maxItems / continuationToken 分页。默认的 summary 投影内容精简，projection='full' 则会添加程序集路径和详细字段。

• FindEndpoints：查找 ASP.NET Core 端点。控制器操作从 [Route] / [Http*] / [AcceptVerbs] 特性路由中读取，并将 [controller] / [action] 替换为对应名称。Minimal API 来自从 IL 中读取的 Map{Get,Post,Put,Delete,Patch,Methods,Group,Fallback} 调用。可使用 routeContains 和 httpMethod 筛选。Minimal API 路由和处理程序取自每个调用旁边的字符串字面量和方法引用，因此，存放在变量或字段中的路由会返回 null；MapGroup 前缀则作为单独的 minimalApiGroup 条目列出，而不会合并
• FindServiceRegistrations：查找 Microsoft.Extensions.DependencyInjection 注册，从 IL 中读取对 Add{Singleton,Scoped,Transient}、TryAdd*、AddKeyed*、AddHostedService 的调用以及 ServiceDescriptor 工厂。生命周期、服务和实现类型取自泛型实参或 typeof(...) 操作数；工厂注册和实例注册会返回 implementation: null。可使用 serviceType、implementationType 和 lifetime 筛选
• FindEfEntities：查找每个 DbContext 子类声明或继承的 DbSet<T> 属性。可使用 contextType 和 entityType 筛选
• FindHandlers：查找 MediatR 风格的处理程序：来自 MediatR 或 Mediator 命名空间的 IRequestHandler<,> / IRequestHandler<>、INotificationHandler<>、IStreamRequestHandler<,> 和 IPipelineBehavior<,> 的具体实现。可使用 messageType 和 kind 筛选

IL 分析

• GetMethodCalls：读取方法的 IL 主体，列出它调用的方法以及访问的字段——回答签名级工具无法回答的“这个方法做了什么？”问题（汇总所有重载；构造函数使用 .ctor/.cctor）。format='mermaid' 会返回 Mermaid 流程图调用图，depth（最多为 5）会继续追踪同一程序集内定义的被调方法

API 差异

• CompareApiSurface：比较程序集两个版本的公共 API。left（旧版本）和 right（新版本）均可指定程序集路径、asm_… 句柄，或从本地缓存解析的 NuGet 包 [email protected]（省略版本时使用缓存中版本最高的包；tfm 用于选择目标框架；默认情况下，两侧使用两个包都支持的一个目标框架；若没有共同支持的目标框架，则会发出警告）。比较公共类型和成员，以及可继承类型上的受保护成员。会标出具有原因的破坏性变更：移除类型或成员、更改返回类型／字段类型／属性类型、降低可访问性、类变为密封、抽象或静态、移除基类型或接口、新增泛型约束、向接口或可继承类添加抽象成员、成员在静态与实例之间转换、成员变为抽象或非虚拟、字段变为只读、移除属性访问器或降低其可访问性、设置器变为 init、更改参数修饰符、参数不再是可选参数或 params，以及更改枚举值。新增内容和兼容性变更（参数重命名、新增默认值、更改常量、新增 params、成员移至基类型）会列出，但不标记为破坏性变更。默认的 summary 返回 counts 和破坏性变更；projection='full' 会列出所有变更，并包含 leftSignature、rightSignature 和 reasons[]（可通过 breakingOnly 和 namespaceFilter 缩小范围）。支持使用 maxItems / continuationToken 分页

原始源码与反编译

• GetMemberSource：成员的原始源码，包含注释和真实名称，通过程序集的可移植 PDB（嵌入 DLL 中或位于 DLL 旁）读取。它会依次使用 PDB 中嵌入的源码、构建该程序集时所用的本地文件，以及 PDB 的 Source Link URL 所指向的文件。每个候选文件（包括嵌入的源码）都必须与 PDB 记录的 SHA-1/SHA-256 校验和匹配（允许 CRLF/LF 差异）；否则该重载会回退到反编译的 C#。本地文件仅从绝对非 UNC 路径读取，且大小不超过 5 MB。结果中的 origin 为 embedded、local、sourcelink、decompiled 或 mixed，每个重载都会报告其 document、url 和 lines，而 note 会说明任何回退情况。截取内容涵盖成员的 /// 文档、特性、签名和主体
• DecompileMember：使用 ICSharpCode.Decompiler 将一个成员（方法、属性、字段、事件或构造函数）反编译为 C#。返回该名称的所有重载；若提供 parameterTypes，则返回其中一个重载（例如 string,int；空字符串会选择无参数重载）。构造函数使用 .ctor/.cctor
• DecompileType：将整个类型反编译为 C#。位于 decompile 工具组中；优先使用 DecompileMember

以上三个工具都按行对源码分页：maxLines（默认值为 400，最大值为 5000）限制每页大小；每页也会在达到约 90,000 个字符时提前结束，以确保内容始终符合响应限制；每页都会报告 startLine、lineCount、totalLines、truncated 和用于获取下一页的 continuationToken。超过 2,000 个字符的行会被截断，并附上 /* … more characters clipped */ 标记；此类行的数量会计入 clippedLines。如果依赖项位于程序集文件夹之外，请传入 additionalAssemblies（或使用以这些依赖项打开的 assemblyHandle）；解析引用类型时会搜索这些依赖项所在的文件夹，其文件时间戳也会纳入缓存键。完整的反编译结果会按文件时间戳缓存，因此后续分页开销很小。如果程序集仅转发某个类型（例如 System.Runtime.dll 外观程序集中转发的 System.String），则会返回 TypeForwarded，并在 recommendedParams 中提供定义该类型的程序集

特性与元数据

• GetMemberAttributes：获取指定成员的特性
• GetParameterAttributes：获取参数级别的特性信息

XML 文档

• GetXmlDocsForType：提取类型级别的 XML 文档
• GetXmlDocsForMember：获取成员专属文档（摘要／参数／返回值／备注）

项目与解决方案分析

• AnalyzeSolution：解析 .sln 文件并枚举项目
• AnalyzeProject：获取项目元数据、引用和构建配置
• GetProjectOutputPaths：解析不同配置的输出目录
• ResolvePackageReferences：将 NuGet 包映射到缓存的程序集
• GetPackageGraph：从 obj/project.assets.json 获取还原后的 NuGet 依赖关系图（按目标框架和 RID 列出精确的直接与传递依赖版本）
• FindDepsJsonDependencies：解析 deps.json 中的运行时依赖项

项目工具会使用已安装的 .NET SDK 评估项目（执行 dotnet msbuild -getProperty/-getItem，仅进行评估，不构建），因此会遵循 Directory.Build.props/targets、集中式包管理、条件、导入项和计算得出的输出路径。SDK 由项目的 global.json 选择。如果没有可用的 SDK（例如在容器映像中），或评估失败，则会回退到解析项目文件的 XML；evaluation.mode / evaluation.reason 会说明回退情况。评估过程会运行仓库的 .props/.targets 和 SDK 解析器；设置 SHERLOCK_PROJECT_EVALUATION=off 或调用 update_runtime_options projectEvaluation=off，即可仅使用 XML 解析器。

配置与运行时

• GetRuntimeOptions：当前服务配置和默认值
• UpdateRuntimeOptions：修改分页、缓存、搜索、Source Link 获取和项目评估行为

默认情况下，get_member_source 仅通过 HTTPS 从已知源主机获取 Source Link 文件（raw.githubusercontent.com、gitlab.com、bitbucket.org、api.bitbucket.org、dev.azure.com、*.visualstudio.com），因为 URL 来自 PDB，否则可能指向任意位置。将 SHERLOCK_SOURCE_FETCH 设置为 off、known-hosts（默认值）或 any，也可以在运行时通过 update_runtime_options sourceFetch=… 和 addSourceFetchHosts / removeSourceFetchHosts 进行更改。主机有 5 秒时间响应，并有 30 秒时间传输文件；超过 5 MB 的文件将被拒绝；重定向由手动跟随（最多 3 次），且每一跳都必须通过相同的 HTTPS 和主机检查；无法连接的主机在本次会话剩余时间内不会重试；网络故障导致的回退结果不会缓存；经过验证的文件会缓存在 SHERLOCK_STATE_DIR/sources 下。

资源

三个资源模板让客户端无需再次调用工具即可获取单个类型、文档条目或缓存的软件包。所有变量都会进行百分号编码。

• sherlock://assembly/{path}/type/{fullName}：类型元数据，与 get_type_info 返回的内容相同
• sherlock://assembly/{path}/docs/{memberId}：文档 ID 对应的 XML 文档，例如 T:Ns.Type 或 M:Ns.Type.Method(System.String)
• sherlock://nuget/{packageId}/{version}：缓存的 NuGet 软件包版本所解析到的程序集，与 find_assembly_by_nuget_package 返回的内容相同

search_members、get_types_from_assembly 和 find_* 反向查找工具会在 JSON 文本块之后，为页面上的每个不同类型返回一个指向类型资源的 resource_link。resources/read 会携带私有缓存提示；如果 URI 中的程序集、类型、文档 ID 或软件包不存在，则会失败并返回 -32602。

模板变量支持 completion/complete，最多返回 100 个值：

• path：最近加载的程序集，然后是正在输入的文件夹中的 .dll / .exe 文件和子文件夹
• fullName：来自 path 上下文参数所指定程序集的类型名称（元数据格式，例如 List`1）
• memberId：与 path 程序集位于同一目录的 XML 文件中的文档 ID
• packageId / version：本地 NuGet 缓存中的软件包文件夹及其版本（按从新到旧排序）

提示词

三个提示词将常用工具调用序列编排为一键入口（Claude Code 会将其列为 /mcp__sherlock__<name> 斜杠命令）。每个提示词都会返回一条用户消息，引导 Agent 使用这些工具；它们只会调用 core 配置中的工具，因此在任一配置下均可使用。

• explore_package（packageId、version?）：从本地 NuGet 缓存解析软件包（省略 version 时使用缓存中版本最高的软件包），了解程序集概况，并总结其主要类型和入口点
• explain_type（assemblyPath、typeName）：一个类型的层次结构、成员、XML 文档和用法
• who_calls（assemblyPath、typeName、memberName、additionalAssemblies?）：通过 IL 查找某成员的调用方，可选择跨逗号分隔的其他程序集进行查找

assemblyPath、typeName（在补全上下文中包含 assemblyPath）、packageId 和 version（上下文中包含 packageId）支持 completion/complete，方式与资源模板变量相同。prompts/list 携带与 tools/list 相同的公共缓存提示。

高级筛选与分页

所有成员分析工具都支持全面的筛选和分页：

筛选选项：

• caseSensitive (bool)：区分大小写的类型/成员匹配
• nameContains (string)：按成员名称子字符串筛选
• hasAttributeContains (string)：按属性类型子字符串筛选
• includePublic / includeNonPublic (bool)：可见性筛选
• includeStatic / includeInstance (bool)：成员类型筛选

分页：

• skip / take (int)：标准偏移分页
• maxItems (int)：每次请求的最大结果数（默认为 50；FindReferencesTo 默认为 25）
• continuationToken (string)：用于大型数据集的基于令牌的分页
• sortBy / sortOrder (string)：按名称/访问权限以升序/降序排序

响应形状（节省 token）

大多数枚举工具默认使用精简的 summary 投影，仅在需要时才让你选择内容更丰富的 full 负载。请有目的地使用 full——通常 summary 就足以决定下一次调用。

• projection（summary | full）：GetTypesFromAssembly、GetTypeMembers、GetTypeMethods、GetAssemblyInfo、GetMethodCalls、FindImplementationsOf、FindMethodsReturning、FindExtensionMethodsFor、FindReferencesTo、FindEndpoints、FindServiceRegistrations、FindEfEntities 和 FindHandlers 支持此参数。summary 仅返回足以供浏览的信息（例如，成员的 { kind, name, signature }）；full 会添加结构化字段（参数、特性、返回类型、修饰符等）。注意：已弃用的 GetTypeProperties/Fields/Events/Constructors 只有一种固定形状，不接受 projection。
• analysisDepth（signatures | il）：仅适用于 FindReferencesTo。signatures（默认值）会扫描成员声明；il 还会扫描方法体以查找调用方（速度较慢）。
• format（json | mermaid）：GetTypeHierarchy（classDiagram）和 GetMethodCalls（flowchart，可通过 depth 查找传递调用）支持此参数。Mermaid 结果返回 { diagram, nodeCount, edgeCount, truncated, note }，受 maxNodes 限制（默认值为 50，最大值为 200）。
• additionalAssemblies（string[]）：扩大 GetTypeHierarchy 和反向查找工具的搜索范围。GetTypeHierarchy.derivedTypes 在传入此参数之前会保持为 null。
• noCache（bool）：当怀疑结果已过期时，绕过响应缓存执行单次调用。每个读取程序集或项目的工具都会缓存其响应，缓存键由输入文件的时间戳组成（程序集及任何 additionalAssemblies、包含该程序集 bin 输出的项目的 project.assets.json、应用的 runtimeconfig.json、程序集旁的 XML 文档文件，或项目文件、obj/project.assets.json 及其上级目录中的任何 Directory.Build.props、Directory.Build.targets、Directory.Packages.props 或 global.json），因此重新生成或还原会自动使缓存失效。find_assembly_by_* 查找、resolve_package_references（读取共享 NuGet 包缓存）、配置工具和句柄工具不会缓存。以下两种情况无法通过时间戳检测，此时可使用 noCache=true：在之前仅部分解析成功的程序集旁放入依赖 DLL（缓存键记录程序集的时间戳，不记录其同目录文件）；项目的还原文件 project.assets.json 位于 obj/ 或 artifacts/obj/<project>/ 之外（例如使用了自定义的 BaseIntermediateOutputPath）；以及在首次针对主机运行时解析程序集之后安装了目标框架包（使用 noCache 调用会检测到新包，并重新构建程序集的检查上下文）。
• assemblyHandle（string）：每个接受 assemblyPath 的工具都可接受此参数作为替代项（传入其中一个，不要同时传入两个）。通过 open_assembly 获取；它还会提供打开时使用的 additionalAssemblies，你显式传入的程序集会追加到其中。

类型解析：

• 支持完整名称（Namespace.Type）、简单名称（Type）和嵌套类型（Outer+Inner）
• 区分大小写由 caseSensitive 参数控制
• 对有歧义的类型名称会自动回退解析

响应架构

所有工具都会返回稳定的 JSON 封装：

{ "kind": "type.list|member.methods|...", "version": "1.0.0", "data": { /* result */ }, "hints": [ /* optional */ ] }

封装以紧凑（无缩进）JSON 的形式序列化到工具的文本内容块中。核心浏览工具还会公布 MCP outputSchema，并将相同的封装作为 structuredContent 返回，因此客户端无需解析文本即可验证和使用结果：open_assembly、search_members、get_types_from_assembly、get_type_info、get_type_members、get_type_methods、get_assembly_info、get_method_calls、decompile_member、get_member_source、compare_api_surface、find_implementations_of、find_methods_returning、find_extension_methods_for 和 find_references_to。这些架构描述的是默认的 summary 投影；projection='full' 项目会在此基础上添加字段。错误结果不会携带 structuredContent。

错误结果会标记 MCP 的 isError: true，因此客户端无需解析文本即可区分失败与正常结果。错误使用统一的结构。每个错误都包含 kind、version、code 和 message；部分错误还会包含 details，引导型错误则会添加 suggestion、alternativeTools 或 recommendedParams，为 Agent 指明后续步骤：

{
  "kind": "error",
  "version": "1.0.0",
  "code": "MethodNotFound",
  "message": "No method named 'Parse' was found on type 'MyApp.Config' in MyApp.dll.",
  "suggestion": "Verify the type and method names. Use get_type_members with kinds=method to list available methods, or set includeNonPublic=true for private methods.",
  "alternativeTools": ["get_type_members", "analyze_method"]
}

错误代码：

• 未找到： AssemblyNotFound（recommendedParams.similarFiles 会列出同一文件夹中名称相近的程序集）、TypeNotFound / MemberNotFound（recommendedParams.candidates 会列出最接近的名称）、MethodNotFound、PackageNotFound、VersionNotFound、XmlNotFound、ProjectNotFound、FileNotFound、OverloadNotFound、TypeForwarded（recommendedParams 会指出定义该类型的程序集）、AssetsFileNotFound、TargetFrameworkNotFound、ToolNotFound
• 输入错误： AmbiguousTypeName（仅适用于无法主动询问的客户端；recommendedParams.candidates 会列出匹配的完整名称）、AmbiguousTargetFramework、InvalidArgument、InvalidProjection、InvalidAnalysisDepth、InvalidFormat、InvalidContinuationToken
• 句柄和工具组： StaleAssemblyHandle、UnknownAssemblyHandle、ToolNotLoaded（错误会指出需要加载的工具组）
• 加载： InvalidAssembly（不是托管程序集）、DependencyNotFound（无法加载引用的程序集）、DependencyResolutionFailed、InvalidAssetsFile、AccessDenied
• 限制和内部错误： ResponseTooLarge、InternalError

路线图

已发布的功能和计划中的工作总结在 src/docs/roadmap.md 中；实时清单通过 #87 跟踪。

贡献

欢迎贡献。本仓库包含一个 .editorconfig，其中采用了现代 C# 编码偏好（文件范围的命名空间、表达式主体成员、4 空格缩进）。

提交消息格式

本项目使用 Conventional Commits 自动生成变更日志。所有提交都必须遵循以下格式：

type(scope): description

有效类型：

• feat - 新功能
• fix - 修复错误
• docs - 仅修改文档
• style - 代码风格修改（格式、分号等）
• refactor - 既不修复错误也不添加功能的代码修改
• perf - 性能改进
• test - 添加或修正测试
• build - 修改构建系统或依赖项
• ci - 修改 CI 配置
• chore - 不修改 src 或 test 文件的其他变更
• revert - 撤销之前的提交

示例：

git commit -m "feat(tools): add new assembly analysis tool"
git commit -m "fix: resolve null reference in type loader"
git commit -m "docs(readme): update installation instructions"

开发环境设置

# Restore .NET tools (versionize, husky)
dotnet tool restore

# Install git hooks for commit validation
dotnet husky install

指南

• 保持修改小而集中；为新增行为添加单元测试。
• 添加工具时遵循响应封装和错误代码约定。
• 在打开 PR 前，在本地运行 dotnet build 和 dotnet test。

创建发布版本

发布版本基于一个拉取请求创建，该请求会将所有版本固定值更新为新版本：src/server/Sherlock.MCP.Server.csproj 中的 <Version>、server.json 中的两个 version 字段、Claude Code 插件在 plugins/sherlock/.claude-plugin/plugin.json 和 .claude-plugin/marketplace.json 中的 version、plugins/sherlock/.mcp.json 和本 README 中固定的 dnx 版本，以及 CHANGELOG.md 标题（[Unreleased] → [x.y.z] - date）。server.json 会作为 .mcp/server.json 打包到 NuGet 包中。不要在此基础上运行 dotnet versionize；它会再次提升版本号。

PR 合并后，为 main 上的合并提交创建标签并推送该标签：

git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin vX.Y.Z

发布工作流会自动：

1. 验证标签、server.json、项目版本和 Claude Code 插件版本是否一致
2. 构建并测试项目
3. 创建包含更新日志说明的 GitHub Release
4. 发布 NuGet 包和 MCP Registry 条目

MCP Registry

mcp-name: io.github.jcucci/dotnet-sherlock-mcp

许可证

Sherlock MCP for .NET 根据 MIT License 授权。