Отладка MCP-серверов в Copilot SDK

Диагностировать и исправлять проблемы с MCP-серверами, интегрированными с Второй пилот SDK, включая сбои при запуске сервера, проблемы с обнаружением инструментов и ошибки протокола.

Кто может использовать эту функцию?

GitHub Copilot SDK Доступна со всеми 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
    },
  },
}

Независимое тестирование серверов MCP

Всегда сначала тестируйте ваш MCP-сервер вне SDK.

Ручной протокольный тест

Отправьте initialize запрос через stdin:

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

Ожидаемый ответ:

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

Для примера Windows PowerShell см. руководство по отладке MCP Server в github/copilot-sdk репозитории.

Список тестовых инструментов

После инициализации запросите список инструментов:

Bash
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

Использование:

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

Распространенные проблемы

Сервер не запускается

Симптомы: Инструменты не появляются, нет ошибок в логах.

ПричинаРешение
Неправильный путь командИспользуйте абсолютный путь: /usr/local/bin/server
Отсутствие разрешения на исполняемые файлыЗапуск chmod +x /path/to/server
Отсутствующие зависимостиПроверьте на ldd (Linux) или запустите вручную
Проблемы с рабочими справочникамиНабор 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. Prompt явно не нуждается в этом инструменте:

    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 Schema действительна. Обязательные поля должны быть указаны в массиве required .

Ошибки, связанные с истечением времени ожидания

Симптомы:MCP tool call timed out ошибки.

  1. Увеличьте тайм-аут:

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

  2. Оптимизируйте производительность сервера, добавляя лог прогресса для выявления узкого места, учитывая асинхронные операции и проверяя блокировку ввода-вывода.

  3. Для долгосрочных инструментов рассмотрите возможность потоковых ответов, если они поддерживаются.

JSON-RPC ошибки

Симптомы: Ошибки разбора, некорректные ошибки запроса.

Распространенные причины:

  1. Сервер неправильно записывает в stdout: Вывод отладки идёт в stdout вместо stderr, или добавляют новые строки или пробелы:

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

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

  2. Проблемы с кодированием: Обеспечьте кодирование UTF-8 без BOM (метки порядка байтов).

  3. Формулировка сообщения: Каждое сообщение должно быть полным JSON-объектом, разделённым по новой строке (одно сообщение на строку).

Проблемы, связанные с платформой

Виндоус

В Windows антивирусное или файрволное программное обеспечение может блокировать новые исполняемые файлы или процессы, взаимодействующие через stdin/stdout. Добавьте исключения для вашего исполняемого файла MCP сервера, если это необходимо.

Для примеров конфигурации, специфичных для Windows, для консольных приложений и команд NPX, см. руководство по отладке MCP Server в github/copilot-sdk репозитории.

Проблемы с путями:

  • Используйте необработанные струны (@"C:\path") или прямые косые черты ("C:/path").
  • По возможности избегайте пробелов в дорожках.
  • Если нужны места, убедитесь, что стоит правильно оформить цены.

macOS

  1. Блокировка вратаря: Если сервер заблокирован:

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

  2. Домашние пути: GUI-приложения могут не иметь /opt/homebrew в PATH. Используйте полный путь:

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

Линукс

  1. Проблемы с разрешением:

    Bash
    chmod +x /path/to/mcp-server

  2. Отсутствуют общие библиотеки:

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

Проверьте с инспектором MCP

Используйте официальный инструмент MCP Inspector:

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

Это обеспечивает веб-интерфейс для отправки тестовых запросов, просмотра ответов и проверки схем инструментов.

Несоответствия версий протокола

Проверьте, поддерживает ли ваш сервер версию протокола, которую использует 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
  • Есть ли сообщения об ошибках