{"meta":{"title":"MCP サーバー デバッグ ガイド","intro":"このガイドでは、Copilot SDK を使用する場合の MCP (モデル コンテキスト プロトコル) サーバーに固有のデバッグ手法について説明します。","product":"GitHub Copilot","breadcrumbs":[{"href":"/ja/copilot","title":"GitHub Copilot"},{"href":"/ja/copilot/how-tos","title":"方法"},{"href":"/ja/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/ja/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/ja/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"MCP デバッグ"}],"documentType":"article"},"body":"# MCP サーバー デバッグ ガイド\n\nこのガイドでは、Copilot SDK を使用する場合の MCP (モデル コンテキスト プロトコル) サーバーに固有のデバッグ手法について説明します。\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## 目次\n\n* [クイック診断](#quick-diagnostics)\n* [MCP サーバーを個別にテストする](#testing-mcp-servers-independently)\n* [一般的な問題](#common-issues)\n* [プラットフォーム固有の問題](#platform-specific-issues)\n* [高度なデバッグ](#advanced-debugging)\n\n## クイック診断\n\n### Checklist\n\n詳細を確認する前に、次の基本事項を確認してください。\n\n* [ ] MCP サーバー実行可能ファイルが存在し、実行可能である\n* [ ] コマンド パスが正しい (不明な場合は絶対パスを使用する)\n* [ ] ツールが有効になっている (`tools: [\"*\"]` または特定のツール名)\n* [ ] サーバーが MCP プロトコルを正しく実装する ( `initialize`に応答)\n* [ ] ファイアウォール/ウイルス対策がプロセスをブロックしていない (Windows)\n\n### MCP デバッグ ログを有効にする\n\nMCP サーバー構成に環境変数を追加します。\n\n```typescript\nmcpServers: {\n  \"my-server\": {\n    type: \"local\",\n    command: \"/path/to/server\",\n    args: [],\n    env: {\n      MCP_DEBUG: \"1\",\n      DEBUG: \"*\",\n      NODE_DEBUG: \"mcp\",  // For Node.js MCP servers\n    },\n  },\n}\n```\n\n## MCP サーバーを個別にテストする\n\n最初に、必ず SDK の外部で MCP サーバーをテストします。\n\n### 手動プロトコル テスト\n\nstdin を使用して `initialize` 要求を送信します。\n\n```bash\n# Unix/macOS\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n\n# Windows (PowerShell)\n'{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | C:\\path\\to\\your\\mcp-server.exe\n```\n\n**予想される応答:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"your-server\",\"version\":\"1.0\"}}}\n```\n\n### テスト ツールの一覧\n\n初期化後、ツールの一覧を要求します。\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**予想される応答:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### 対話型テスト スクリプト\n\nMCP サーバーを対話形式でデバッグするテスト スクリプトを作成します。\n\n```bash\n#!/bin/bash\n# test-mcp.sh\n\nSERVER=\"$1\"\n\n# Initialize\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n\n# Send initialized notification\necho '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}'\n\n# List tools\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'\n\n# Keep stdin open\ncat\n```\n\n使用法:\n\n```bash\n./test-mcp.sh | /path/to/mcp-server\n```\n\n## 一般的な問題\n\n### サーバーが起動しない\n\n**症状：** ツールは表示されません。ログにエラーはありません。\n\n**原因と解決策:**\n\n| 原因                                 | ソリューション                             |\n| ---------------------------------- | ----------------------------------- |\n| コマンド パスが正しくありません                   | 絶対パスを使用します。 `/usr/local/bin/server` |\n| 実行可能なアクセス許可がありません                  |                                     |\n| `chmod +x /path/to/server` を実行します。 |                                     |\n| 不足している依存関係                         |                                     |\n| `ldd` (Linux) で確認するか、手動で実行する       |                                     |\n| 作業ディレクトリの問題                        | config で `cwd` を設定する                |\n\n**手動で実行してデバッグする:**\n\n```bash\n# Run exactly what the SDK would run\ncd /expected/working/dir\n/path/to/command arg1 arg2\n```\n\n### サーバーは起動しますが、ツールは表示されません\n\n**症状：** サーバー プロセスは実行されますが、使用できるツールはありません。\n\n**原因と解決策:**\n\n1. **構成でツールが有効になっていない:**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **サーバーはツールを公開しません。**\n   * `tools/list`要求を手動でテストする\n   * サーバーが`tools/list`メソッドを実装しているか確認\n\n3. **初期化ハンドシェイクが失敗する:**\n   * サーバーが `initialize` に正しく応答する必要がある\n   * サーバーが処理する必要がある `notifications/initialized`\n\n### 一覧表示されているが呼び出されないツール\n\n**症状：** ツールはデバッグ ログに表示されますが、モデルでは使用されません。\n\n**原因と解決策:**\n\n1. **プロンプトにツールは必要ありません。**\n\n   ```typescript\n   // Too vague\n   await session.sendAndWait({ prompt: \"What's the weather?\" });\n\n   // Better - explicitly mentions capability\n   await session.sendAndWait({ \n     prompt: \"Use the weather tool to get the current temperature in Seattle\" \n   });\n   ```\n\n2. **ツールの説明が不明:**\n\n   ```typescript\n   // Bad - model doesn't know when to use it\n   { name: \"do_thing\", description: \"Does a thing\" }\n\n   // Good - clear purpose\n   { name: \"get_weather\", description: \"Get current weather conditions for a city. Returns temperature, humidity, and conditions.\" }\n   ```\n\n3. **ツール スキーマの問題:**\n   * `inputSchema`が有効な JSON スキーマであることを確認する\n   * 必須フィールドは配列内 `required` 必要があります\n\n### タイムアウトエラー\n\n**現象:**`MCP tool call timed out` エラー。\n\n**ソリューション:**\n\n1. **タイムアウトの増加:**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **サーバーのパフォーマンスを最適化する:**\n   * 進行状況ログを追加してボトルネックを特定する\n   * 非同期操作を検討する\n   * ブロッキングI/Oを確認する\n\n3. **実行時間の長いツールの場合**は、サポートされている場合はストリーミング応答を検討してください。\n\n### JSON-RPC エラー\n\n**症状：** 解析エラー、無効な要求エラー。\n\n**一般的な原因:**\n\n1. **サーバーが stdout に誤って書き込む:**\n   * stderr ではなく stdout への出力をデバッグする\n   * 余分な改行または空白\n   ```typescript\n   // Wrong - pollutes stdout\n   console.log(\"Debug info\");\n\n   // Correct - use stderr for debug\n   console.error(\"Debug info\");\n   ```\n\n2. **エンコードの問題:**\n   * UTF-8 エンコードを確認する\n   * BOM なし (バイトオーダー マーク)\n\n3. **メッセージ フレーミング:**\n   * 各メッセージは完全な JSON オブジェクトである必要があります\n   * 改行区切り (1 行に 1 つのメッセージ)\n\n## プラットフォーム固有の問題\n\n### Windows\n\n#### .NET コンソール アプリ/ツール\n\n```csharp\n// Correct configuration for .NET exe\n[\"my-dotnet-server\"] = new McpStdioServerConfig\n{\n    Command = @\"C:\\Tools\\MyServer\\MyServer.exe\",  // Full path with .exe\n    Args = new List<string>(),\n    WorkingDirectory = @\"C:\\Tools\\MyServer\",  // Set working directory\n    Tools = new List<string> { \"*\" },\n}\n\n// For dotnet tool (DLL)\n[\"my-dotnet-tool\"] = new McpStdioServerConfig\n{\n    Command = \"dotnet\",\n    Args = new List<string> { @\"C:\\Tools\\MyTool\\MyTool.dll\" },\n    WorkingDirectory = @\"C:\\Tools\\MyTool\",\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### npx コマンド\n\n```csharp\n// Windows needs cmd /c for npx\n[\"filesystem\"] = new McpStdioServerConfig\n{\n    Command = \"cmd\",\n    Args = new List<string> { \"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\allowed\\\\path\" },\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### パスに関する問題\n\n* raw 文字列 (`@\"C:\\path\"`) またはフォワード スラッシュ (`\"C:/path\"`) を使用します\n* 可能な場合はパス内のスペースを避ける\n* スペースが必要な場合は、適切な引用符を使用してください。\n\n#### ウイルス対策/ファイアウォール\n\nWindows Defenderまたはその他の AV がブロックされる場合があります。\n\n* 新しい実行可能ファイル\n* stdin/stdout 経由で通信するプロセス\n\n**ソリューション：** MCP サーバー実行可能ファイルの除外を追加します。\n\n### macOS\n\n#### ゲートキーパーのブロック\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Homebrew のパス\n\n```typescript\n// GUI apps may not have /opt/homebrew in PATH\nmcpServers: {\n  \"my-server\": {\n    command: \"/opt/homebrew/bin/node\",  // Full path\n    args: [\"/path/to/server.js\"],\n  },\n}\n```\n\n### Linux\n\n#### アクセス許可の問題\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### 共有ライブラリがありません\n\n```bash\n# Check dependencies\nldd /path/to/mcp-server\n\n# Install missing libraries\napt install libfoo  # Debian/Ubuntu\nyum install libfoo  # RHEL/CentOS\n```\n\n## 高度なデバッグ\n\n### すべての MCP トラフィックをキャプチャする\n\nすべての通信をログに記録するラッパー スクリプトを作成します。\n\n```bash\n#!/bin/bash\n# mcp-debug-wrapper.sh\n\nLOG=\"./mcp-debug-$(date +%s).log\"\nACTUAL_SERVER=\"$1\"\nshift\n\necho \"=== MCP Debug Session ===\" >> \"$LOG\"\necho \"Server: $ACTUAL_SERVER\" >> \"$LOG\"\necho \"Args: $@\" >> \"$LOG\"\necho \"=========================\" >> \"$LOG\"\n\n# Tee stdin/stdout to log file\ntee -a \"$LOG\" | \"$ACTUAL_SERVER\" \"$@\" 2>> \"$LOG\" | tee -a \"$LOG\"\n```\n\nこれを使用します。\n\n```typescript\nmcpServers: {\n  \"debug-server\": {\n    command: \"/path/to/mcp-debug-wrapper.sh\",\n    args: [\"/actual/server/path\", \"arg1\", \"arg2\"],\n  },\n}\n```\n\n### MCP インスペクターを使用して検査する\n\n公式の MCP インスペクター ツールを使用します。\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nこれにより、次の Web UI が提供されます。\n\n* テスト要求を送信する\n* 応答を表示する\n* ツール スキーマを検査する\n\n### プロトコル バージョンの不一致\n\nSDK で使用されているプロトコル バージョンがサーバーでサポートされているかどうかを確認します。\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nバージョンが一致しない場合は、MCP サーバー ライブラリを更新します。\n\n## デバッグ チェックリスト\n\n問題を開いたり、ヘルプを求めたりする場合は、次の情報を収集します。\n\n* [ ] SDK の言語とバージョン\n* [ ] CLI バージョン (`copilot --version`)\n* [ ] MCP サーバーの種類 (Node.js、Python、.NET、Go、Rust など)\n* [ ] MCP サーバーの完全な構成 (シークレットの編集)\n* [ ] 手動 `initialize` テストの結果\n* [ ] 手動 `tools/list` テストの結果\n* [ ] SDK からログをデバッグする\n* [ ] いずれかのエラーメッセージ\n\n## こちらも参照ください\n\n* [GitHub Copilot SDK での MCP サーバーの使用](/ja/copilot/how-tos/copilot-sdk/features/mcp) - 構成とセットアップ\n* [デバッグ ガイド](/ja/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - SDK 全体のデバッグ\n* [MCP 仕様](https://modelcontextprotocol.io/) - 公式プロトコル ドキュメント"}