SharpLens

SharpLensMcp

Microsoft Roslyn を使用して、.NET/C# のセマンティックなコード分析、ナビゲーション、リファクタリング、コード生成を行う、92 個の AI 最適化ツールを提供する Model Context Protocol（MCP）サーバーです。

AI コーディングエージェント向けに構築されており、ソースファイルを読むだけでは AI が推測できない、コンパイラーに忠実なコード理解を提供します。

インストール

NuGet 経由（推奨）

dotnet tool install -g SharpLensMcp

次のコマンドで実行します：

sharplens

npm 経由

npx -y sharplens-mcp

ソースからビルド

dotnet build -c Release
dotnet publish -c Release -o ./publish

Claude Code のセットアップ

1. ツールをインストールします（いずれかを選択）：

dotnet tool install -g SharpLensMcp
# or
npx -y sharplens-mcp

2. プロジェクトのルートに .mcp.json を作成します：

{
  "mcpServers": {
    "sharplens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "sharplens-mcp"],
      "env": {
        "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)"
      }
    }
  }
}

3. Claude Code を再起動して MCP サーバーを読み込みます

4. 確認：Claude に Roslyn サーバーのヘルスチェックを実行するよう依頼します

Claude Code と組み合わせて使う理由

Claude Code は、基本的なナビゲーション（定義へ移動、参照の検索）をネイティブで LSP サポートしています。SharpLensMcp は、より深いセマンティック分析を追加します：

機能	ネイティブ LSP	SharpLensMcp
定義へ移動	✅	✅
参照の検索	✅	✅
CancellationToken が不足している async メソッドの検索	❌	✅
影響分析（何が壊れるか？）	❌	✅
デッドコードの検出	❌	✅
複雑度メトリクス	❌	✅
プレビュー付きの安全なリファクタリング	❌	✅
一括操作	❌	✅

設定

環境変数	説明	デフォルト
DOTNET_SOLUTION_PATH	起動時に自動読み込みする .sln、.slnx、.slnf ファイル（または、そのうち 1 つだけを含むディレクトリ）へのパスです。読み込みはリクエストループと並行して実行されるため、initialize はすぐに応答します	なし（load_solution の呼び出しが必要です）
SHARPLENS_ABSOLUTE_PATHS	相対パスではなく絶対パスを使用します	false（相対パスを使うとトークンを節約できます）
SHARPLENS_LOG_LEVEL	ログの詳細度：Trace、Debug、Information、Warning、Error	Information
SHARPLENS_TIMEOUT_SECONDS	長時間実行される操作のタイムアウト	30
SHARPLENS_MAX_DIAGNOSTICS	返す診断の最大数	100
SHARPLENS_ENABLE_SEMANTIC_CACHE	ファイルパスからドキュメントへの検索結果をキャッシュします	true（無効にするには false を設定）

1.6.0 より前の ROSLYN_* 形式の変数名も、フォールバックとして引き続き読み込まれます。両方が設定されている場合は、SHARPLENS_* 形式が優先されます。ブール値では大文字と小文字が区別されません。数値を解析できない場合、または最小値を下回る場合はデフォルト値に戻り、最大値を上回る場合は最大値に制限されます。いずれの場合も、標準エラー出力に警告が記録されます。

マルチターゲットプロジェクト

複数のターゲットフレームワーク向けにビルドされたプロジェクトも、すべてのツールからは 1 つのプロジェクトとして扱われます。各結果は一度だけ報告され、一部のフレームワークにしか存在しない場合は targetFrameworks リストが含まれます。projectName には、すべてのフレームワークを対象とする通常の名前（MyLib）、または 1 つのフレームワークを対象とするフレームワーク修飾名（MyLib(net8.0)）を指定できます。

DOTNET_SOLUTION_PATH が設定されていない場合は、他のツールを使う前に load_solution ツールを呼び出す必要があります。

1.5.x のツール名からの移行

ツール名に roslyn: プレフィックスが付かなくなりました。このコロンは MCP のツール名パターン（^[a-zA-Z0-9_-]{1,64}$）に適合せず、一部のクライアントで拒否されるためです。すべてのツール名からプレフィックスが取り除かれます：

1.5.x の名前	1.6.0 の名前
roslyn:load_solution	load_solution
roslyn:get_diagnostics	get_diagnostics
roslyn:rename_symbol	rename_symbol
...すべてのツールに同じルールを適用...	roslyn: プレフィックスを削除

tools/list が公開するのは新しい名前のみです。旧プレフィックス付きの名前による呼び出しは、1 回のリリースに限りエイリアスとして引き続き受け付けられ、その次のリリースで削除されます。

AI エージェントの設定に関するヒント

AI モデルは、SharpLensMcp がより優れた機能を提供している場合でも、MCP サーバーのツールではなく、ネイティブツール（Grep、Read、LSP）を使用するように学習されている可能性があります。

ツールを最適に使用するには：

1. Claude Code：プロジェクトの CLAUDE.md に追加します：

   For C# code analysis, prefer SharpLensMcp tools over native tools:
   - Use `search_symbols` instead of Grep for finding symbols
   - Use `get_method_source` instead of Read for viewing methods
   - Use `find_references` for semantic (not text) references
   

2. その他の MCP クライアント：エージェントのシステムプロンプトでツールの優先順位を設定します

Roslyn によるセマンティック分析は、特にオーバーロードされたメソッド、部分クラス、継承階層において、テキストベースの検索よりも正確です。

エージェントの責任：ドキュメントの同期

重要： SharpLensMcp は、高速なクエリのためにソリューションをメモリ内に保持します。ファイルが（Edit/Write ツール経由で）外部から変更された場合、変更を同期する責任はエージェントにあります。

sync_documents を呼び出すタイミング：

操作	sync_documents を呼び出しますか？
Edit ツールを使用して .cs ファイルを変更した	✅ はい
Write ツールを使用して新しい .cs ファイルを作成した	✅ はい
.cs ファイルを削除した	✅ はい
SharpLensMcp のリファクタリングツール（rename、extract など）を使用した	❌ いいえ（自動更新されます）
.csproj ファイルを変更した	❌ いいえ（代わりに load_solution を使用します）

使用方法：

# After editing specific files
sync_documents(filePaths: ["src/MyClass.cs", "src/MyService.cs"])

# After bulk changes - sync all documents
sync_documents()

完全同期では、プロジェクトのコンパイル項目に含まれる新しい .cs ファイルも取り込みます。SharpLensMcp の適用ツールは、編集によって変更されたファイルのみを書き込み、各ファイルのエンコーディングと改行コードを維持します。また、読み取り後に対象ファイルがディスク上で変更されている場合は STALE_DOCUMENT で処理を拒否します。その場合は sync_documents を実行してから再試行してください。さらに、エンコーディングで元のバイト列を再現できないファイル（Linux など、フォールバックのコードページが UTF-8 であるシステム上で、UTF-8 として有効ではない BOM なしのファイル）への書き込みは UNSUPPORTED_ENCODING で拒否します。その場合は、まず UTF-8 として保存してください。

この設計の理由

これは、クライアント（エディター）が変更をサーバーに通知する LSP（Language Server Protocol）の仕組みを踏襲しています。この方法には、次の利点があります。

• 競合状態を解消できます（エージェントがタイミングを制御します）
• ファイル監視の複雑さやプラットフォーム固有の問題を回避できます
• ソリューション全体の再読み込みよりも高速です
• エージェントがワークスペースの状態を明示的に制御できます

同期しない場合： クエリで古いデータ（古いメソッドシグネチャ、新しいファイルの欠落など）が返される可能性があります。

機能

• 92 個のセマンティック分析ツール - ナビゲーション、リファクタリング、コード生成、診断、探索、監査／品質
• AI 向けに最適化された説明 - 明確な USAGE／OUTPUT／WORKFLOW パターン
• 構造化された応答 - suggestedNextTools を備えた一貫性のある success/error/data 形式
• ゼロベースの座標 - 1 つずれるエラーを防ぐ明確な警告
• プレビューモード - 適用前のプレビューで安全にリファクタリング
• 一括操作 - 1 回の呼び出しで複数の検索を行い、コンテキストの使用量を削減

ツールのカテゴリ

ナビゲーションと検索（24 個のツール）

ツール	説明
get_symbol_info	指定位置のセマンティック情報
go_to_definition	シンボルの定義に移動
find_references	すべての参照。各参照は読み取り／書き込み／呼び出し／キャスト／typeof／nameof／属性に分類されます。任意の kind フィルターを指定できます
find_implementations	インターフェイス／抽象クラスの実装
find_callers	影響分析 — これを呼び出しているのは何か？
get_call_graph	深度制限とサイクル検出を備えた、複数ホップの呼び出し元／呼び出し先グラフ
find_path_between	2 つのメソッド間の到達可能性と、それらをつなぐ呼び出し経路。ディスパッチを追跡し、バリアとチェックポイントを使用します
get_type_hierarchy	継承チェーン
search_symbols	Glob パターン検索（*Handler、Get*）
semantic_query	複数条件による検索（async、public など）
get_type_members	型名で指定した型のすべてのメンバー
get_type_members_batch	1 回の呼び出しで複数の型を指定
get_method_signature	名前で指定したメソッドの詳細なシグネチャ
get_derived_types	すべての派生クラスを検索
get_base_types	継承チェーン全体
get_attributes	シンボルの属性を一覧表示
get_containing_member	指定位置を囲むシンボル
get_method_overloads	メソッドのすべてのオーバーロード
find_attribute_usages	属性が使用されている型／メンバーを検索
get_external_type_info	NuGet／BCL／外部アセンブリの型を調査 — メンバーと XML ドキュメント
resolve_stack_trace	貼り付けたスタックトレースをファイル／行／シンボルに対応付けます。マングリングも解除されます
get_extension_methods	型に適用される拡張メソッド — 従来形式と C# 14 のブロック
get_documentation	<inheritdoc> を展開した、シンボルの完全な XML ドキュメント
get_super_method	メンバーが実装する基底メンバー／インターフェイスメンバーに移動

分析（17 個のツール）

ツール	説明
get_diagnostics	コンパイラーのエラー／警告と、設定済みのアナライザーによる検出結果（StyleCop、Roslynator、NetAnalyzers）。CI と一致します
diff_api_surface	git の参照先と比較した、公開 API の破壊的変更レポート
get_exception_flow	メソッドから送出される可能性のある例外と、その捕捉箇所
find_similar_code	構造的類似性検索（トークンシャイングル指紋）
remove_unused_code	削除するデッドコードと新たに未使用となる using を算出します（生成のみ）
find_dead_branches	メソッドごとの到達不能な基本ブロック（ヒューリスティックではなく、実際の CFG を使用）
add_missing_imports	CS0246／CS0103 を解消する using を算出します（生成のみ）
analyze_data_flow	変数の代入と使用状況
analyze_control_flow	分岐／到達可能性
analyze_change_impact	変更すると何が壊れるかを分析
check_type_compatibility	A を B に代入できるかを確認
get_outgoing_calls	このメソッドが呼び出すもの
find_unused_code	デッドコードを検出
validate_code	書き込みを行わずにコンパイルを確認
get_complexity_metrics	循環的複雑度、ネスト、行数、認知的複雑度
find_circular_dependencies	プロジェクトと名前空間の循環依存を検出
get_missing_members	未実装のインターフェイス／抽象メンバー

リファクタリング（16 ツール）

ツール	説明
rename_symbol	ソリューション全体で安全に名前を変更
change_signature	パラメーターの追加・削除・並べ替え
extract_method	データフロー分析を使用して抽出
extract_interface	クラスからインターフェイスを生成
generate_constructor	フィールド／プロパティから生成
move_type_to_file	型を独自のファイルに移動するための内容を計算（生成のみ）
split_type	選択したメンバーを部分クラスに分割するための内容を計算（生成のみ）
organize_usings	整理し、未使用のものを削除
organize_usings_batch	複数のファイルを一括で整理
format_document_batch	プロジェクト内のファイルを一括でフォーマット
get_code_actions_at_position	指定位置にあるすべての Roslyn リファクタリング
apply_code_action_by_title	タイトルを指定して任意のリファクタリングを適用
implement_missing_members	インターフェイスのスタブを生成
encapsulate_field	フィールドをプロパティに変換
inline_variable	一時変数をインライン化
extract_variable	式を変数に抽出

コード生成（3 ツール）

ツール	説明
add_null_checks	ArgumentNullException のガードを生成
generate_equality_members	Equals／GetHashCode／演算子
generate_test_stub	メソッドのコンパイル可能なテストスケルトンを生成（フレームワークを自動検出）

複合ツール（7 ツール）

ツール	説明
get_type_overview	1 回の呼び出しで型の全情報を取得
analyze_method	シグネチャ＋呼び出し元＋呼び出し先＋位置
get_file_overview	診断情報付きのファイル概要
get_method_source	名前を指定してソースコードを取得
get_method_source_batch	1 回の呼び出しで複数のメソッドソースを取得
get_instantiation_options	型の作成方法
get_project_health	複合監査ダッシュボード：プロジェクトごとの診断情報＋未使用項目＋結合度＋カバレッジ

監査と品質（10 ツール）

ツール	説明
find_god_objects	外部結合度＋内部結合度＋メンバー数のしきい値を用いて、過度に結合された型を検出
find_untested_code	どのテストからも到達されない公開範囲を検索 — xUnit、NUnit、MSTest、TUnit、Reqnroll、SpecFlow のテストを検出し、セットアップ、フィクスチャ、ステップバインディングも考慮
find_tests	シンボルをカバーするテストを検索 — find_untested_code の逆
find_type_instantiations	型が構築される箇所（new T）を検索
find_pattern_usages	型が is/as／パターンマッチに登場する箇所を検索
find_throw_sites	例外型がスローされる箇所を検索（派生型も任意で対象）
find_catch_blocks	例外型がキャッチされる箇所を検索（基底句経由も任意で対象）
find_async_issues	async void／async のブロッキング呼び出し／転送されない CancellationToken
check_architecture	型グラフ全体で名前空間／プロジェクトの依存関係ルールを適用
find_naming_violations	.editorconfig のルールに従い、慣例的なデフォルト値も使用して命名を監査

検出（3 ツール）

ツール	説明
get_di_registrations	DI サービス登録をスキャン
find_reflection_usage	リフレクション／動的な使用を検出
find_interceptors	[InterceptsLocation] による呼び出しの再ルーティングを提示（生成コードも対象）

インフラストラクチャ（12 個のツール）

ツール	説明
health_check	サーバーの状態と読み込み状況の整合性（partial フラグ、宣言済みプロジェクトと読み込み済みプロジェクト、loadFailures、loadWarnings、lastLoadFailure）を確認します。再読み込みは行いません
find_unused_dependencies	コンパイラーが必要としない PackageReferences／ProjectReferences
fix_all	診断 ID のすべての発生箇所に対する修正を計算します（生成のみ）
load_solution	.sln／.slnx／.slnf を読み込みます。一部のみ読み込まれた場合（partial と loadFailures：除外されたプロジェクト、復元の失敗、参照なしで読み込まれたプロジェクト）と、MSBuild の警告（loadWarnings）を個別に報告します
sync_documents	ファイルの変更を読み込み済みのソリューションに同期します
get_project_structure	ソリューションの構造
dependency_graph	プロジェクトの依存関係
get_code_fixes	診断に対して利用できる修正
apply_code_fix	指定したコード修正を適用します
get_nuget_dependencies	プロジェクトごとの NuGet パッケージ一覧
get_source_generators	アクティブなソースジェネレーターを一覧表示します
get_generated_code	生成されたソースコードを表示します

その他の MCP クライアント

Claude Code 以外の MCP クライアントでは、設定に次の内容を追加してください。

{
  "mcpServers": {
    "sharplens": {
      "command": "sharplens",
      "args": [],
      "env": {
        "DOTNET_SOLUTION_PATH": "/path/to/your/Solution.sln (or .slnx)"
      }
    }
  }
}

使用方法

1. ソリューションを読み込む：.sln または .slnx ファイルのパスを指定して load_solution を呼び出します（または DOTNET_SOLUTION_PATH を設定します）
2. コードを分析する：ナビゲーション、分析、リファクタリング、監査に 92 個のツールを使用します
3. 安全にリファクタリングする：preview: true を指定して、変更を適用する前にプレビューします

アーキテクチャ

MCP Client (AI Agent)
        | stdin/stdout (JSON-RPC 2.0)
        v
   SharpLensMcp
   - Protocol handling
   - 92 AI-optimized tools
        |
        v
Microsoft.CodeAnalysis (Roslyn)
  - MSBuildWorkspace
  - SemanticModel
  - SymbolFinder

要件

• .NET 8.0 SDK 以降 — .NET 8、9、10、および今後のバージョンで動作します。.NET 8 以降のプロジェクト／ソリューションを分析できます。
• MCP 互換の AI エージェント

FAQ

ツールが net8.0 を対象にしているのはなぜですか。私の .NET 9／.NET 10 プロジェクトも分析できますか？

はい。net8.0 はツール自体の実行環境の下限であり、ツールが基盤とする Roslyn 5.x パッケージに必要なものです。分析対象の上限ではありません。RollForward により、インストール済みのツールは新しい .NET ランタイムでも実行でき、MSBuildWorkspace は各プロジェクトの実際のターゲットフレームワークを csproj から読み込むため、1 回のインストールで .NET 8、9、10 以降を対象とするソリューションを分析できます。

開発

新しいツールの追加

1. 対応する src/RoslynService.*.cs の partial にメソッドを追加し、共通のレスポンスエンベロープを通じて返します（Navigation、Analysis、Refactoring、CallAnalysis など）。

public async Task<object> YourToolAsync(string param1, int? param2 = null,
    CancellationToken cancellationToken = default)
{
    EnsureSolutionLoaded();
    // Your logic...
    return CreateSuccessResponse(
        data: new { /* results */ },
        suggestedNextTools: new[] { "next_tool_hint" }
    );
}

2. src/ToolRegistry.cs に ToolDefinition を 1 つ登録します。登録するのは、名前、説明、入力スキーマ、ReadOnly フラグ（変更を行うツールは ReadOnly: false を渡し、destructiveHint アノテーションを受け取ります）、および JsonRpcParameters で引数をバインドしてメソッドを呼び出すハンドラーです。レジストリが tools/list とディスパッチの両方を担うため、別途編集する switch はありません。2 つのテストで整合性を維持します。ToolsListGoldenTests は公開スキーマをバイト単位で固定します（スキーマの変更が意図的な場合は、ゴールデンを再取得してください）。ToolSchemaParityTests は、ハンドラーが読み取るすべてのパラメーターがスキーマで宣言されていることを検証します。

3. ビルドして公開します：

dotnet build -c Release
dotnet publish -c Release -o ./publish

4. 両方のレベルのテストを追加します。決定論的なフィクスチャを使った RoslynService メソッドのユニットテストと、MCP ディスパッチャー経由のワイヤーテスト（tests/SharpLensMcp.Tests/Mcp/ 内）を追加します。後者では、正確な値を固定し、エラーパスもテストします。これは必須です。テストを参照してください。

テスト

すべてのテストは、基本契約である tests/SharpLensMcp.Tests/TESTING.md の Testing Charter（C1～C9） を満たす必要があります。主なルールは次のとおりです。

• 具体的な値を固定する（C1）：具体的な名前／件数／部分文字列／エラーコード／(line, column) をアサートします。唯一のアサーションとして NotBeNull／> 0／型だけのチェックを使ってはいけません。
• ツールごとに両方のレベルでテストする（C4）：Fixtures/*.cs のフィクスチャを使ったユニットテストに加え、content[0].text を取り出すディスパッチャー（ワイヤー）テストと、エラーパスのテストを実施します。
• 正しい大文字・小文字を使う（C3）：インプロセスの Newtonsoft では error.Code／meta.TotalCount のように PascalCase になり、MCP ワイヤー上では camelCase になります。テストの経路で実際に生成される大文字・小文字を読み取ってください。
• 決定性を保つ（C7）：テストスイートは xunit.runner.json によって直列化されます。フィクスチャのミューテーターは必ず状態を復元し、タイムアウトテストではタイミング競合ではなく強制キャンセル用のシームを使います。
• プロセス外テストの中核（C6）：StdioIntegrationTests は、実際のバイナリを使って各カテゴリから1つのツールの値を固定し、stdio パイプ上で tools/list のゴールデンテストを実行します。
• コミット前のゲート（C9）：ビルドがクリーンでテストがすべて成功していることは必要ですが、それだけでは不十分です。変更した各テストを読み直し、誤った結果に対して失敗することを確認してください。

テストスイートを実行します。

dotnet test -c Release

主要ファイル

ファイル	目的
src/RoslynService.cs + src/RoslynService.*.cs の部分クラス	関心ごとに約30の部分クラス（ナビゲーション、分析、リファクタリング、検査、検証、型の検出、検出、外部 API、品質、メトリクス、コードアクション、コード生成、複合処理、呼び出し分析、例外フロー、スタックトレース、API サーフェス、類似コードなど）に分割されたツール実装です。各ファイルの名前から内容を予測できます
src/McpServer.cs	MCP プロトコルの仕組みです。JSON-RPC 解析ループ、initialize ネゴシエーション、呼び出しごとのタイムアウト、インバンドエラーとプロトコルエラーのマッピングを扱います
src/ToolRegistry.cs + src/ToolDefinition.cs	ツールの一覧です。ツールごとに、名前、スキーマ、ReadOnly フラグ、ハンドラーを持つ ToolDefinition レコードが1つあります。tools/list の順序とディスパッチ検索を制御します
src/JsonRpcParameters.cs + JsonRpcInvalidParamsException.cs	型付きの JSON-RPC 引数アクセサーと、それらが発生させる -32602 Invalid params 例外です
src/*Data.cs / *Entry.cs のレコード、ConstructorMember.cs、SignatureChange.cs	監査コンポジット、コンストラクター生成器、シグネチャ変更パーサーで使用する型付きレコードです（1ファイルにつき1型）

ライセンス

MIT - 詳細は LICENSE をご覧ください。