mcp-csharp-debug

C# MCP サーバーのデバッグ

C# MCP サーバーを実行、デバッグし、対話形式でテストします。ローカルでの実行、ブレークポイントを使用した IDE でのデバッグ、プロトコルレベルのテストに使う MCP Inspector、GitHub Copilot Agent Mode との統合を扱います。

使用するタイミング

• MCP サーバーを初めてローカルで実行するとき
• MCP サーバーをデバッグするために VS Code または Visual Studio を設定するとき
• MCP Inspector でツールを対話形式でテストするとき
• GitHub Copilot Agent Mode にツールが表示されることを確認するとき
• ツールが検出されない、プロトコルエラーが発生する、サーバーがクラッシュするなどの問題を診断するとき
• mcp.json または .mcp.json の設定を行うとき

中止条件

• まだプロジェクトがありませんか？ → 先に mcp-csharp-create を使用してください
• 自動テストが必要ですか？ → mcp-csharp-test を使用してください
• 本番環境へのデプロイに関する問題ですか？ → mcp-csharp-publish を使用してください

入力

入力	必須	説明
プロジェクトのパス	はい	.csproj ファイルまたはプロジェクトディレクトリへのパス
トランスポートの種類	推奨	stdio または http。指定されていない場合は .csproj から判定します
IDE	推奨	VS Code または Visual Studio。指定されていない場合は環境から判定します

エージェントの動作： .csproj に ModelContextProtocol.AspNetCore の PackageReference があるか確認して、トランスポートの種類を判定します。ある場合は HTTP、ない場合は stdio です。

ワークフロー

ステップ 1：サーバーをローカルで実行する

stdio トランスポート：

cd <ProjectDir>
dotnet run

プロセスが起動し、標準入力で JSON-RPC メッセージを待ちます。標準出力に何も表示されなければ、正常に動作しています。

HTTP トランスポート：

cd <ProjectDir>
dotnet run
# Server listens on http://localhost:3001 (or configured port)

ステップ 2：MCP 設定を生成する

IDE とトランスポートを判定し、適切な設定ファイルを作成します。

VS Code の場合 — .vscode/mcp.json を作成します。

stdio：

{
  "servers": {
    "<ProjectName>": {
      "type": "stdio",
      "command": "dotnet",
      "args": ["run", "--project", "<path/to/ProjectFile.csproj>"]
    }
  }
}

HTTP：

{
  "servers": {
    "<ProjectName>": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

Visual Studio の場合 — ソリューションのルートに .mcp.json を作成します（JSON の構造は同じです）。

IDE 固有の詳細な設定（launch.json、環境変数、シークレット）については、references/ide-config.md を参照してください。

ステップ 3：MCP Inspector でテストする

MCP Inspector は、ツールのテスト、スキーマの確認、プロトコルメッセージの検査に使う UI を提供します。

stdio サーバー：

npx @modelcontextprotocol/inspector dotnet run --project <path/to/ProjectFile.csproj>

HTTP サーバー：

1. サーバーを起動します：dotnet run
2. Inspector を実行します：npx @modelcontextprotocol/inspector
3. http://localhost:3001 に接続します

Inspector の機能、使用方法、トラブルシューティングの詳細については、references/mcp-inspector.md を参照してください。

ステップ 4：GitHub Copilot Agent Mode でテストする

1. GitHub Copilot Chat を開き、Agent モードに切り替えます
2. Select Tools（レンチアイコン）をクリックし、サーバーとツールが一覧に表示されることを確認します
3. ツールが呼び出されるはずのプロンプトでテストします
4. 求められたらツールの実行を承認します

ツールが表示されない場合 — ツールの検出をトラブルシューティングします：

1. 最初に再ビルドします — 古いビルドが最もよくある原因です：

   dotnet build
   

   次に MCP サーバーを再起動します（VS Code で Stop → Start をクリックするか、dotnet run を再起動します）。

2. 属性と登録を確認します：

   • クラスに [McpServerToolType] があり、各パブリックメソッドに [McpServerTool] があることを確認します
   • メソッドは static またはインスタンスメソッドにできます（インスタンス型には DI 登録が必要です）
   • Program.cs に .WithTools<T>() または .WithToolsFromAssembly() があることを確認します

3. mcp.json が正しいプロジェクトパスを指していることを確認します

4. それでも表示されない場合は、ツールを明示的に指定します：Using #tool_name, do X

ステップ 5：ブレークポイントを使ったデバッグを設定する

1. ツールメソッドにブレークポイントを設定します
2. デバッガーで起動します：
   • VS Code： F5（launch.json が必要です。references/ide-config.md を参照してください）
   • Visual Studio： F5 を押すか、プロジェクトを右クリックして → Debug → Start を選択します
3. ツールを呼び出します（Inspector、Copilot、またはテストクライアント経由）
4. ブレークポイントで実行が一時停止します

重要： Debug 構成でビルドしてください。Release ビルドではブレークポイントに到達しません。

ツールエラーの診断

ツールを単独で実行すると動作するのに、MCP 経由では失敗する場合は、次の項目を確認してください。

1. MCP の出力チャンネルを確認する — VS Code では、「表示」→「出力」→ MCP サーバー名を選択します。プロトコルエラーとサーバーの stderr が表示されます。Visual Studio では、出力ウィンドウで MCP 関連のメッセージを確認します。
2. デバッガーをアタッチする — 失敗するツールのメソッドにブレークポイントを設定し、実行をステップ実行します（ステップ 5 を参照）。例外が握りつぶされていないか、予期しないパラメーター値がないか確認してください。
3. MCP Inspector でテストする — Inspector からツールを直接呼び出し、問題がツールのコードにあるのか、クライアントとの統合にあるのかを切り分けます：npx @modelcontextprotocol/inspector dotnet run --project <path>
4. stdout の汚染を確認する（stdio のみ） — Console.WriteLine() や stdout へのログ出力は、JSON-RPC プロトコルを破損させます。すべての出力を stderr にリダイレクトしてください（ステップ 6 を参照）。
5. よくある原因を確認する：
   • シリアル化エラー — 戻り値の型は JSON にシリアル化できる必要があります。循環参照は避けてください。
   • DI の登録 — サービスの登録漏れは、実行時例外の原因になります。Program.cs を確認してください。
   • パラメーターのバインド — パラメーター名と型がツールのスキーマと一致していることを確認してください。
   • 未処理の例外 — ツールのロジックを try-catch で囲み、stderr またはファイルにログを記録してください。
6. ファイルログを有効にする — 事後分析のため、ファイルにログを記録します：

   builder.Logging.AddFile("mcp-debug.log"); // or use Serilog/NLog
   

ステップ 6：ログを設定する

stdio トランスポートでは重要です： stdout への出力（Console.WriteLine を含む）は、MCP JSON-RPC プロトコルを破損させ、応答の文字化けやクラッシュを引き起こします。すべてのログと診断出力は stderr に送る必要があります。

stdio トランスポート — stderr にのみログを記録します：

builder.Logging.AddConsole(options =>
    options.LogToStandardErrorThreshold = LogLevel.Trace);

HTTP トランスポート — HTTP トランスポートのログ設定については、references/ide-config.md を参照してください。

ツールのメソッド内 — コンストラクター経由で ILogger<T> を注入し、logger.LogDebug()／logger.LogError() を使用します。ILogger を通じたログ出力は、上記の stderr 設定に従います。

検証

• dotnet run でサーバーがエラーなく起動する
• MCP Inspector が接続し、想定されるすべてのツールを一覧表示する
• Inspector 経由のツール呼び出しで、想定される結果が返る
• IDE でデバッグするとブレークポイントに到達する
• GitHub Copilot Agent Mode のツール一覧にツールが表示される
• stdio：stdout にログ出力がない（stderr のみ）

よくある落とし穴

落とし穴	解決策
変更後にツールが表示されない、または古い状態のままになる	まず再ビルドします： dotnet build を実行してから、サーバーを再起動します。それでも表示されない場合は、クラスに [McpServerToolType] が、メソッドに [McpServerTool] が指定されていること、および Program.cs に WithTools<T>() または WithToolsFromAssembly() があることを確認してください
stdio サーバーの出力が文字化けする	Console.WriteLine() またはログが stdout に出力されています。すべての出力は stderr に送る必要があります。コンソールロガーで LogToStandardErrorThreshold = LogLevel.Trace を設定してください
HTTP サーバーが MCP エンドポイントで 404 を返す	Program.cs に app.MapMcp() がありません
ブレークポイントに到達しない	Release モードでビルドされています。Debug で再ビルドし、dotnet build -c Debug を実行してから再起動してください
環境変数がサーバーに渡されない	mcp.json に "env" セクションを追加します。VS Code でシークレットを使用する場合は、"${input:var_id}" 形式を使ってください
MCP Inspector が HTTP サーバーに接続できない	サーバーが起動していないか、ポートが間違っています。dotnet run の出力でリッスン中の URL を確認してください

関連スキル

• mcp-csharp-create — 新しい MCP サーバープロジェクトを作成する
• mcp-csharp-test — 自動テストと評価
• mcp-csharp-publish — NuGet、Docker、Azure へのデプロイ

参照ファイル

• references/mcp-inspector.md — MCP Inspector の詳細な使い方：インストール、サーバーへの接続、機能の解説、トラブルシューティング。読み込むタイミング： Inspector の詳しいガイダンスが必要な場合や、接続に問題がある場合。
• references/ide-config.md — VS Code および Visual Studio の完全な設定：mcp.json のテンプレート、launch.json、環境変数、条件付きブレークポイント。読み込むタイミング： IDE のデバッグをセットアップする場合や、環境固有の設定を行う場合。

詳細情報

• MCP Inspector — MCP サーバー向けのインタラクティブなデバッグツール
• VS Code MCP documentation — VS Code での MCP サーバーの設定