Copilot SDK での MCP サーバーのデバッグ

メモ

          Copilot SDK は現在 パブリック プレビューです。 機能と可用性は変更される場合があります。

クイック診断

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
    },
  },
}

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

# 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

          **予想される応答:**

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

Windows PowerShell の例については、リポジトリの github/copilot-sdk参照してください。

テストツールの一覧

初期化後、ツールの一覧を要求します。

Bash

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

          **予想される応答:**

{"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

#!/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

./test-mcp.sh | /path/to/mcp-server

一般的な問題

サーバーが起動しない

          **症状：** ツールは表示されません。ログにエラーはありません。

原因	ソリューション
コマンドパスが正しくありません	絶対パスを使用します。 `/usr/local/bin/server`
実行可能なアクセス許可がありません

          `chmod +x /path/to/server` を実行します。 |

手動で実行してデバッグする:

Bash

# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2

# 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
  },
}

mcpServers: {
  "server": {
    // ...
    tools: ["*"],  // Must be "*" or list of tool names
  },
}

       **サーバーはツールを公開しません。**`tools/list`要求を使用して手動でテストします。 サーバーが `tools/list` メソッドを実装していることを確認します。

       **初期化ハンドシェイクが失敗する:** サーバーは、 `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"
});

// 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"
});

       **ツールの説明が不明:**

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." }

// 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." }

       **ツール スキーマの問題:**`inputSchema`が有効な JSON スキーマであることを確認します。 必須フィールドは、 `required` 配列に一覧表示する必要があります。

タイムアウトエラー

          **現象:**`MCP tool call timed out` エラー。

タイムアウトを増やす:

TypeScript

mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

mcpServers: {
  "slow-server": {
    // ...
    timeout: 300000,  // 5 minutes
  },
}

進行状況ログを追加してボトルネックを特定し、非同期操作を検討し、I/O をブロックするかどうかを確認することで、サーバーのパフォーマンスを最適化します。
実行時間の長いツールの場合は、サポートされている場合はストリーミング応答を検討してください。

JSON-RPC エラー

          **症状：** 解析エラー、無効な要求エラー。

一般的な原因:

       **サーバーが stdout に誤って書き込む:** stderr の代わりに stdout に出力されるデバッグ出力、または余分な改行または空白:

TypeScript

// Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

// Wrong—pollutes stdout
console.log("Debug info");

// Correct—use stderr for debug
console.error("Debug info");

       **エンコードの問題:** BOM を使用しない UTF-8 エンコード (バイトオーダー マーク) を確認します。

       **メッセージ フレーミング:** 各メッセージは、完全な JSON オブジェクトである必要があります。改行区切り (1 行に 1 つのメッセージ)。

プラットフォーム固有の問題

ウィンドウズ

Windows では、ウイルス対策ソフトウェアまたはファイアウォールソフトウェアによって、stdin/stdout 経由で通信する新しい実行可能ファイルまたはプロセスがブロックされる場合があります。必要に応じて、MCP サーバー実行ファイルの除外を追加します。

.NET コンソールアプリと NPX コマンドの Windows 固有の構成例については、リポジトリの github/copilot-sdk参照してください。

          **パスの問題:**

生の文字列 (@"C:\path") またはフォワードスラッシュ ("C:/path") を使用します。
可能な場合は、パスにスペースを入れないでください。
スペースが必要な場合は、適切な引用符を使用してください。

macOS

       **ゲートキーパー のブロック:** サーバーがブロックされている場合:

Bash

xattr -d com.apple.quarantine /path/to/mcp-server

xattr -d com.apple.quarantine /path/to/mcp-server

       **Homebrew パス:** GUI アプリに PATH に `/opt/homebrew` がない可能性があります。 完全なパスを使用します。

TypeScript

mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

リナックス

       **アクセス許可の問題:**

Bash

chmod +x /path/to/mcp-server

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

# 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="/tmp/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"

#!/bin/bash
# mcp-debug-wrapper.sh

LOG="/tmp/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"],
  },
}

mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

MCP Inspector を使用して検査する

公式の MCP インスペクターツールを使用します。

Bash

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

npx @modelcontextprotocol/inspector /path/to/your/mcp-server

これにより、テスト要求の送信、応答の表示、ツールスキーマの検査を行う Web UI が提供されます。

プロトコルバージョンの不一致

SDK で使用されているプロトコルバージョンがサーバーでサポートされているかどうかを確認します。

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

バージョンが一致しない場合は、MCP サーバーライブラリを更新します。

デバッグチェックリスト

問題を開くか、 GitHub の問題に関するヘルプを求める場合は、次の情報を収集します。

SDK の言語とバージョン
CLI バージョン (copilot --version)
MCP サーバーの種類 (Node.js、Python、.NET、Go など)
MCP サーバーの完全な構成 (シークレットの編集)
手動 initialize テストの結果
手動 tools/list テストの結果
SDK からログをデバッグする
いずれかのエラーメッセージ

Copilot SDK での MCP サーバーのデバッグ

この機能を使用できるユーザーについて

この記事で

クイック診断

Checklist

MCP デバッグログを有効にする

MCP サーバーを個別にテストする

手動プロトコルテスト

テストツールの一覧

対話型テストスクリプト

一般的な問題

サーバーが起動しない

サーバーは起動しますが、ツールは表示されません

一覧表示されているが呼び出されないツール

タイムアウトエラー

JSON-RPC エラー

プラットフォーム固有の問題

ウィンドウズ

macOS

リナックス

高度なデバッグ

すべての MCP トラフィックをキャプチャする

MCP Inspector を使用して検査する

プロトコルバージョンの不一致

デバッグチェックリスト