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