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

Примечание.

          Второй пилот SDK в настоящее время находится в public preview. Функциональность и доступность могут меняться.

Быстрая диагностика

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

Всегда сначала тестируйте ваш 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

# 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

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`
Отсутствующие зависимости	Проверьте на `ldd` (Linux) или запустите вручную
Проблемы с рабочими справочниками	Набор `cwd` в конфигурации

Отладка запускается вручную:

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

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

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

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

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

TypeScript

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

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

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

JSON-RPC ошибки

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

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

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

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

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

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

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

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

Для примеров конфигурации, специфичных для Windows, для консольных приложений и команд NPX, см. руководство по отладке MCP Server в 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

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

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

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

Bash

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

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
Есть ли сообщения об ошибках

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

В этой статье

Быстрая диагностика

Checklist

Включите логирование отладки MCP

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

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

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

Интерактивный скрипт тестирования

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

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

Сервер запускается, но инструменты не появляются

Инструменты указаны, но так и не позвонили

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

JSON-RPC ошибки

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

Виндоус

macOS

Линукс

Расширенная отладка

Захват всего MCP-трафика

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

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

Контрольный список отладки