dotnet-sherlock-mcp

Sherlock MCP for .NET

Sherlock MCP for .NET は、.NET アセンブリを詳細に解析する機能を提供する、包括的な Model Context Protocol（MCP）サーバーです。LLM が .NET コードを正確に分析・理解できるようにし、複雑な開発シナリオに対して、正確でコンテキストを踏まえた回答を提供します。

このツールは、次のような目的で LLM の機能を活用したい開発者に欠かせません。

• コードベースの詳細な分析 - 複雑な .NET アーキテクチャと依存関係の把握
• 正確な型情報 - 型、メンバー、シグネチャに関する詳細なメタデータの取得
• ドキュメントの自動化 - XML ドキュメントと属性の抽出および活用
• カスタムツールの作成 - .NET アセンブリと連携する高度なツールの構築
• コード生成 - 既存の型構造に基づく正確なコードの作成

主な機能

• 包括的な MCP サーバー：.NET アセンブリを分析する47個の専用ツールを提供します。オプションの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 はアセンブリまたはパッケージの2つのバージョンを比較して、破壊的変更を検出します。
• フレームワークのパターン：find_endpoints、find_service_registrations、find_ef_entities、find_handlers を使って、ASP.NET Core のエンドポイント、DI 登録、EF Core エンティティ、MediatR ハンドラーを一覧表示できます。
• 正確な解決：フレームワークの型は対象フレームワークの参照パックを基に解決され、依存関係はプロジェクトの project.assets.json から解決されます（復元されたグラフは get_package_graph で確認できます）。また、プロジェクトツールは MSBuild を使ってプロジェクトを評価します。
• エージェントの使いやすさ：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 は対話形式の確認プロンプトを省略します。stdio 経由でサーバーを起動する MCP クライアントは、このプロンプトに応答できません。-v q は、あるバージョンを初めてダウンロードする際に dnx が標準出力へ「Skipping NuGet package signature verification.」という通知を出力するのを防ぎます。この通知は MCP ストリームを破損させ、最初の接続を失敗させてしまいます。どちらも dnx のオプションなので、パッケージ ID より前に指定する必要があります。パッケージ ID より後に指定したものは、すべてサーバーに渡されます。バージョンを固定すると、実行を再現可能にできます。アップグレードする場合は、バージョンを更新してください。このパッケージは McpServer パッケージタイプで公開されているため、NuGet.org では MCP サーバーとしても掲載されています。

グローバルツールとしてインストールする

サポートされている 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 は、stdio 経由で通信する標準的な MCP サーバーとして動作します。

Claude Code プラグイン

このリポジトリは Claude Code プラグインのマーケットプレイスでもあります。sherlock プラグインには、サーバー（dnx で起動するため、.NET 10 SDK が必要です）と、エージェントに「検索 → 状況把握 → 詳細調査 → 関連性の確認」というワークフローを教えるスキルが含まれています。

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

このプラグインは、スキルが対象とするツールに対応する core ツールプロファイルでサーバーを起動します。必要に応じて、エージェントは 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
  }
}

チームメンバーも dnx を使えるよう、.NET 10 SDK を PATH に含める必要があります。

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：Settings → MCP / Custom tools → Add tool → Command：sherlock-mcp
• Claude Desktop／その他の MCP クライアント：sherlock-mcp コマンドを指定するサーバーエントリを追加します。JSON エントリの例（ファイルの正確な場所や形式については、使用するクライアントのドキュメントを参照してください）：

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

引数は不要です。サーバーは起動時にすべてのツールを自動登録します。

ツールプロファイル

ツールの一覧が大きいと、エージェントのコンテキストを消費し、見つけにくくなります（Claude Code は、ツールの説明がコンテキストウィンドウのおよそ 10％を超えると、遅延ツール検索に切り替わります）。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 プロファイルでは、その他のツールはすべてグループに属しており、エージェントは必要に応じて読み込めます。

グループ	ツール
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 で失敗し、グループ名が示されます。

• 検出のヒント：core の結果には、関連ツールを示す { tool, reason, group } 形式の hints[] が含まれることがあります。例：

  • ネストされた型やジェネリックパラメーターを持つ型、または 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 が提案されます。core ツールの場合、group は null です。

• ツール一覧のキャッシュ：core では、グループの読み込みに応じてセッションのツール一覧が増えるため、tools/list は cacheScope: private に設定されます。full では public のままです。

full プロファイルでは、すべてのツールが一覧表示され、load_tools と invoke_tool は含まれません。

.NET プロジェクト向けの自動設定

通常、何かを貼り付ける必要はありません。 Sherlock は、初期化時に返される MCP の instructions フィールドに使用方法のガイダンスを含めています。また、Claude Code を含むほとんどの MCP クライアントは、そのガイダンスをエージェントに自動的に提示します。そのため、コピー＆ペーストした内容を保守しなくても、ガイダンスはパッケージのバージョンに合わせて正確に保たれます。

以下のスニペットは、任意の補足情報です。ツール名やワークフローを列挙するのではなく、短く、原則に基づいた内容にしてください。リポジトリに貼り付けた静的なリストは 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.

その他のエージェント（AGENTS.md）

エディター間で共通の AGENTS.md 規約に従うツールでは、同じ短い案内を利用できます。上記の Claude Code 用スニペットを AGENTS.md に貼り付けてください。

グローバル設定

システム全体で使用する場合は、グローバルエージェント設定に追加してください。

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.

概要を確認してから詳細を取得する（projection）

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_… ハンドルを返します。アセンブリを指定するツールでは、assemblyPath の代わりに assemblyHandle として渡せます。このハンドルには additionalAssemblies も含まれ、サーバーの再起動後も保持されます（SHERLOCK_STATE_DIR の handles.json 内。デフォルトでは、ユーザーのローカルアプリデータにある sherlock フォルダー）。また、現在のビルドに固定されます。再ビルド後は、再度開くまで呼び出しが StaleAssemblyHandle で失敗します
• AnalyzeAssembly：パブリック型とメタデータを含む、アセンブリの完全な概要
• GetAssemblyInfo：アセンブリレベルのメタデータ（ID／バージョン、ターゲットフレームワーク、参照アセンブリ）。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（任意の version／tfm）を指定して、ローカルの NuGet キャッシュから DLL を解決します

型のイントロスペクション

• 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：オーバーロードと属性を含む、メソッドの詳細な分析を行います。
• 非推奨。あと1〜2回のリリースでは維持されます： 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 に表示されます）。各ツールは1つ以上のアセンブリ（additionalAssemblies）をスキャンし、maxItems / continuationToken を使ってページ分割します。デフォルトの summary 投影は簡潔で、projection='full' を指定するとアセンブリパスと詳細フィールドが追加されます。

• FindEndpoints：ASP.NET Core のエンドポイントを検索します。コントローラーのアクションは、[Route] / [Http*] / [AcceptVerbs] 属性ルートから読み取られ、[controller] / [action] は置き換えられます。最小 API は、IL から読み取られた Map{Get,Post,Put,Delete,Patch,Methods,Group,Fallback} 呼び出しに基づきます。routeContains と httpMethod で絞り込めます。最小 API のルートとハンドラーは、各呼び出しの隣にある文字列リテラルとメソッド参照から取得されるため、変数またはフィールドに保持されたルートは null となり、MapGroup のプレフィックスは結合されず、個別の minimalApiGroup エントリーとして一覧表示されます。
• FindServiceRegistrations：Microsoft.Extensions.DependencyInjection の登録を、Add{Singleton,Scoped,Transient}、TryAdd*、AddKeyed*、AddHostedService への IL 呼び出しと 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：2 つのアセンブリバージョンの公開 API を比較します。left（旧バージョン）と right（新バージョン）には、それぞれアセンブリのパス、asm_… ハンドル、またはローカルキャッシュから解決される [email protected] 形式の NuGet パッケージを指定します（バージョンを省略すると、キャッシュ内で最も新しいバージョンが選ばれます。tfm で対象フレームワークを指定できます。デフォルトでは、両方のパッケージが提供する対象フレームワークのうち 1 つが両側に使用され、共通するものがない場合は警告が表示されます）。公開型とメンバーに加え、継承可能な型の protected メンバーも比較されます。破壊的変更には理由が示されます。対象となるのは、型またはメンバーの削除、戻り値／フィールド／プロパティの型の変更、アクセシビリティの縮小、クラスの sealed 化・abstract 化・static 化、基底型またはインターフェイスの削除、ジェネリック制約の追加、インターフェイスまたは継承可能なクラスへの abstract メンバーの追加、メンバーの static／インスタンス、abstract／非 virtual への変更、フィールドの readonly 化、プロパティアクセサーの削除またはアクセシビリティの縮小、セッターの init への変更、パラメーター修飾子の変更、パラメーターが省略可能または params ではなくなる変更、列挙値の変更です。追加や互換性のある変更（パラメーター名の変更、新しいデフォルト値、定数の変更、新しい params、メンバーの基底型への移動）は、フラグなしで一覧表示されます。デフォルトの summary は counts と破壊的変更を返します。projection='full' を指定すると、すべての変更が leftSignature、rightSignature、reasons[] とともに一覧表示されます（breakingOnly と namespaceFilter で絞り込めます）。maxItems／continuationToken を使ってページ分割できます

ソースの取得と逆コンパイル

• GetMemberSource：コメントと実際の名前を含むメンバーの元のソースです。アセンブリのポータブル PDB（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 を使い、1 つのメンバー（メソッド、プロパティ、フィールド、イベント、コンストラクター）を C# に逆コンパイルします。指定した名前のすべてのオーバーロードを返します。parameterTypes を指定すると、そのうち 1 つのオーバーロードを返します（例：string,int。空文字列は引数なしのオーバーロードを選択します）。コンストラクターには .ctor/.cctor を使用してください
• DecompileType：型全体を C# に逆コンパイルします。ツールグループの decompile にあります。DecompileMember の使用を推奨します

3 つのツールはいずれも、ソースを行単位でページ分割します。maxLines（デフォルトは 400、最大 5000）でページサイズを制限します。また、レスポンス上限を必ず超えないよう、ページの文字数が約 90,000 文字に達すると途中で停止します。各ページは次のページ用の continuationToken とともに、startLine、lineCount、totalLines、truncated を返します。2,000 文字を超える行は /* … more characters clipped */ マーカーで切り詰められ、clippedLines に計上されます。依存関係がアセンブリのフォルダー外にある場合は、additionalAssemblies を渡すか、それらを指定して開いた assemblyHandle を使用してください。参照型の解決時には依存関係のフォルダーも検索され、それらのファイルスタンプはキャッシュキーの一部になります。逆コンパイル結果全体はファイルスタンプを基準にキャッシュされるため、以降のページ取得は高速です。アセンブリが転送のみを行う型（例：System.Runtime.dll ファサード内の System.String）の場合、recommendedParams に定義元アセンブリを含む TypeForwarded を返します

属性とメタデータ

• GetMemberAttributes：特定のメンバーの属性
• GetParameterAttributes：パラメーター単位の属性情報

XML ドキュメント

• GetXmlDocsForType：型レベルの XML ドキュメントを抽出します
• GetXmlDocsForMember：メンバー固有のドキュメント（summary/params/returns/remarks）

プロジェクトとソリューションの分析

• 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 リゾルバーが実行されます。XML パーサーのみを使用するには、SHERLOCK_PROJECT_EVALUATION=off を設定するか、update_runtime_options projectEvaluation=off を呼び出してください。

設定とランタイム

• GetRuntimeOptions：現在のサーバー設定とデフォルト値
• UpdateRuntimeOptions：ページネーション、キャッシュ、検索、Source Link の取得、プロジェクト評価の動作を変更します

get_member_source は、デフォルトでは既知のソースホスト（raw.githubusercontent.com、gitlab.com、bitbucket.org、api.bitbucket.org、dev.azure.com、*.visualstudio.com）からのみ HTTPS 経由で Source Link ファイルを取得します。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 にキャッシュされます。

リソース

3 つのリソーステンプレートを使うと、クライアントは別のツール呼び出しをせずに、単一の型、ドキュメント項目、またはキャッシュ済みパッケージを取得できます。すべての変数はパーセントエンコードされます。

• sherlock://assembly/{path}/type/{fullName}：型のメタデータ。get_type_info と同じペイロードです
• sherlock://assembly/{path}/docs/{memberId}：T:Ns.Type や M:Ns.Type.Method(System.String) のようなドキュメント ID に対応する XML ドキュメント
• sherlock://nuget/{packageId}/{version}：キャッシュ済みの NuGet パッケージのバージョンが解決するアセンブリ。find_assembly_by_nuget_package と同じペイロードです

search_members、get_types_from_assembly、および find_* の逆引きツールは、JSON テキストブロックの後に、ページ内の各一意な型について型リソースへの resource_link を返します。resources/read には非公開のキャッシュヒントが含まれます。アセンブリ、型、ドキュメント ID、またはパッケージが存在しない URI は -32602 エラーになります。

テンプレート変数は completion/complete に対応し、最大 100 件の値を返します。

• path：最近読み込まれたアセンブリ、その後に入力中のフォルダー内の .dll ／ .exe ファイルとサブフォルダー
• fullName：path コンテキスト引数で指定されたアセンブリ内の型名（メタデータ形式。例：List`1）
• memberId：path のアセンブリと同じフォルダーにある XML ファイル内のドキュメント ID
• packageId ／ version：ローカル NuGet キャッシュ内のパッケージフォルダーとそのバージョン（新しい順）

プロンプト

3 つのプロンプトは、よく使われるツールの呼び出し順序をワンクリックで実行できるエントリーポイントとして定義しています（Claude Code では /mcp__sherlock__<name> スラッシュコマンドとして表示されます）。それぞれ、エージェントにツールの使い方を順に示す単一のユーザーメッセージを返します。core プロファイルのツールのみを呼び出すため、どちらのプロファイルでも使用できます。

• explore_package（packageId、version?）：ローカル NuGet キャッシュからパッケージを解決し（version が省略された場合は、キャッシュ内で最も高いバージョンを使用）、アセンブリの概要を確認して、主な型とエントリーポイントをまとめます
• explain_type（assemblyPath、typeName）：1 つの型の階層、メンバー、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)：名前／アクセスレベルで昇順／降順にソート

レスポンス形式（トークン効率）

列挙するツールの多くは、デフォルトで簡潔な 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 で解決できるケースが 2 つあります。1 つ目は、以前は部分的にしか解決できなかったアセンブリの隣に依存 DLL を配置した場合です（キーはアセンブリのタイムスタンプを使いますが、その兄弟ファイルは対象外です）。2 つ目は、プロジェクトの 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 が追加されます。

{
  "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 で管理されています。

コントリビューション

コントリビューションを歓迎します。このリポジトリには、最新の C# のスタイル設定（ファイルスコープの名前空間、式形式のメンバー、4 スペースのインデント）を含む .editorconfig があります。

コミットメッセージの形式

このプロジェクトでは、自動 changelog 生成に 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 は NuGet パッケージの .mcp/server.json としてパッケージに含まれます。これに重ねて dotnet versionize を実行しないでください。バージョンが再度更新されてしまいます。

プルリクエストのマージ後、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 リリースを作成します
4. NuGet パッケージと MCP Registry エントリを公開します

MCP Registry

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

ライセンス

Sherlock MCP for .NET は MIT License の下でライセンスされています。