dotnet-mcp-builder

.NET で MCP サーバーを構築する

このスキルは、Microsoft と MCP プロジェクトがメンテナンスする公式の ModelContextProtocol NuGet パッケージを使用して、C#/.NET で本番品質の MCP サーバーと基本的なクライアントを作成するのに役立ちます。安定版 2.x 系列と、現行仕様（2026-07-28）を対象としています。

このスキルが役立つ場面

.NET MCP SDK は 1.0 に到達するまで何年もプレビュー版パッケージ（0.x-preview）が提供されており、v2 では複数のデフォルト設定が変更されました。支援なしでは、モデルは次のような間違いをしがちです。

• 現行のサンプルではコンパイルできない古いプレビュー版を固定する。
• v2 で逆になった 1.x 時代のデフォルト設定を適用する（HTTP はステートフルがデフォルトでしたが、2.x では Stateless のデフォルトが true です）。
• 2026-07-28 仕様で非推奨となった機能（roots、sampling、MCP チャネルのロギング。現在は [Obsolete] となり、警告 MCP9005 が出ます）を推奨する。
• 最近の仕様機能を見落とす（複数回のやり取りに対応する input_required、発見優先のネゴシエーション、MCP Apps/Tasks 拡張パッケージ、elicitation の URL モード、構造化コンテンツブロック）。
• HTTP トランスポートの詳細を誤る（ステートフル／ステートレス、プロキシのバッファリング、OAuth の接続）。
• STDIO の標準出力／標準エラーの落とし穴を忘れる。

タスクがこれらのいずれかに当てはまる場合は、該当するリファレンスを読み込み、その指示に従ってください。本当に単純な作業（例：「このツールメソッドの名前を変更する」）であれば、すべてを読む必要はありません。以下の基本ルールだけは必ず確認してください。

30 秒でわかる基本モデル

.NET MCP サーバーは、DI を通じて MCP サーバーを構成する通常の Microsoft.Extensions.Hosting（または WebApplication）アプリです。

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()      // OR .WithHttpTransport(...)
    .WithToolsFromAssembly()         // discover [McpServerToolType] classes
    .WithPrompts<MyPrompts>()        // optional
    .WithResources<MyResources>();   // optional

プリミティブは、属性（[McpServerToolType] と [McpServerTool]、[McpServerPromptType] と [McpServerPrompt]、[McpServerResourceType] と [McpServerResource]）を付けたクラス上の通常の C# メソッドです。パラメーターは JSON-RPC からバインドされ、SDK はシグネチャと [Description] 属性から JSON Schema を構築します。

エリシテーション、進行状況通知、そして現在は非推奨となったサンプリング／roots／ログ通知といった、サーバーからクライアントへの機能は、注入された IMcpServer のメソッドとして提供されます。

判断ツリー → 読み込むリファレンス

新しいプロジェクトを作成する場合、または現在のパッケージバージョンが不明な場合は、必ず references/packages.md を読み込んでください。

タスク	読み込むもの
新しい STDIO サーバー	references/transport-stdio.md
新しい HTTP（Streamable）サーバー	references/transport-http.md
ツールの追加／変更	references/tool-primitive.md
プロンプトの追加／変更	references/prompt-primitive.md
リソースの追加／変更	references/resource-primitive.md
ツールの実行中にユーザーへ質問する	references/elicitation.md
ツールからクライアントの LLM を呼び出す（2026-07-28 に非推奨）	references/sampling.md
ユーザーのプロジェクトルートを読み取る（2026-07-28 に非推奨）	references/roots.md
インタラクティブ UI を返す	references/mcp-apps.md
引数の補完、ログ／進行状況通知、フィルター、サーバー指示	references/server-features.md
MCP サーバーを利用する .NET プログラムの作成	references/client.md
MCP Inspector、インメモリテスト、モック、CI	references/testing.md

複数のプリミティブに関わるタスクでは、複数のリファレンスをまとめて読み込んでください。既存ファイルへの単純な変更であれば、通常はどれも必要ありません。

最優先のルール（常に適用してください。最も頻繁に起きる問題を防ぎます）

1. プレビュー版ではなく、現在の安定版パッケージを固定してください。 ModelContextProtocol／ModelContextProtocol.AspNetCore／ModelContextProtocol.Core の最新の 2.x を使用してください。0.3-preview または 0.4-preview と書こうとしている場合は、いったん止めて NuGet を確認してください。プレビュー API には破壊的変更が含まれています。1.x も引き続き動作しますが、2026-07-28 の仕様より前のものです。
2. STDIO サーバーは stdout に書き込んではいけません。 stdout は JSON-RPC チャネルです。まず何よりも先に LogToStandardErrorThreshold = LogLevel.Trace を設定し、ツールから Console.WriteLine を呼び出さないでください。
3. 2.x では HTTP はデフォルトでステートレスです（v1.x のデフォルトはステートフルでした。v2 における最も影響の大きい破壊的変更です）。2026-07-28 の改訂版では HTTP セッションがなくなりました。Stateless = false を設定すると、サーバーはその改訂版を拒否し、レガシーの initialize フォールバックを介してクライアントにサービスを提供します。現在のプロトコルの HTTP で「ツールの実行中にユーザーに何かを尋ねる」場合は、複数回の往復を行う InputRequiredException パターンを使用してください。ステートフル HTTP（または STDIO）は、レガシーの ElicitAsync／サンプリング／ルートの経路や、プッシュ通知のために確保してください。
4. SSE のみの方式は非推奨です。 Streamable HTTP を使用してください。レガシー SSE（EnableLegacySse = true）は、サポートが必須の古いクライアントがある場合にのみ有効にし、その旨を明記してください。
5. 非推奨の機能を中心に新しいサーバーを設計しないでください。 2026-07-28 の仕様では、ルート、サンプリング、MCP チャネルのロギングが非推奨になり、SDK では [Obsolete]（警告 MCP9005）としてマークされています。古いクライアントとの互換性は引き続きありますが、新しい設計では複数回の往復を行う input_required パターンと ILogger ロギングを優先してください。MCP9005 の抑制は、移行期間中の措置として文書化する場合に限ってください。
6. ツールとパラメーターには必ず [Description] を付けてください。 LLM はこれを見て、呼び出すツールと呼び出し内容を決定します。説明が曖昧なのは、ツールが使われない最大の理由です。
7. プリミティブを追加するたびに、登録行を必ず示してください。 .WithPrompts<...>()（または .WithPromptsFromAssembly()）を追加していない [McpServerPromptType] クラスは認識されません。
8. 存在しない API を作り出さないでください。 メソッドが存在するか確信が持てない場合は、その旨を伝えて API リファレンス を確認してください。メソッド名を間違えると、エラーが表面化しないまま失敗する原因になります。新しい v2 拡張パッケージ（ModelContextProtocol.Extensions.Tasks、ModelContextProtocol.Extensions.Apps）では、特に注意が必要です。これらを使ったコードを書く前にドキュメントを確認してください。

作業スタイル

• 最小限の追加変更にとどめてください。 プロジェクトを再構成するのではなく、既存のツールクラスにメソッドを追加してください。
• 複雑なセットアップでは dotnet build を実行してください。 ユーザーが問題に気付く前に、using の不足、属性の誤記、TFM の不一致を検出できます。
• コンテキストから明らかでない場合は、ひな形を作成する前にトランスポート、.NET のバージョン、プリミティブを確認してください。 新しいプロジェクトでは、デフォルトで .NET 10 を使用してください。

ユーザーが行き詰まった場合

推測する前に、次のチェックリストを確認してください。

1. STDIO： stdout に何かが書き込まれています（ロガーの出力先、Console.WriteLine、ライブラリのバナー）。
2. HTTP 404： パスが一致していません。app.MapMcp() はルートにマッピングし、app.MapMcp("/mcp") は /mcp 配下に配置します。
3. ツールが表示されない： クラスに [McpServerToolType] がないか、.WithToolsFromAssembly() / .WithTools<T>() が登録されていません。
4. 引数がバインドされない： パラメーター名は JSON-RPC の arguments キーと一致する必要があります。複合型は System.Text.Json を介してバインドされます。
5. サンプリング／エリシテーション／ルートが機能しない： これらのレガシーなサーバーからクライアントへの呼び出しは、現行プロトコルの HTTP では実行できません。複数回の往復を行う InputRequiredException パターンに移行するか、（レガシーなパスに限り）Stateless = false を設定してください。ただし、その場合、HTTP クライアントは旧バージョンの initialize リビジョンに固定されます。また、クライアントが実際にその機能を通知していることも確認してください。
6. 2.x へのアップグレード後に MCP9005 のビルド警告が表示される： コードで非推奨のルート／サンプリング／ログ記録 API が使用されています。移行を計画し、抑制は一時的なものにとどめてください。

それでも解決しない場合は、ユーザーに EverythingServer のサンプルを案内してください。すべての機能を試せます。