Руководство по отладке серверов MCP

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

Checklist

Прежде чем погружаться в глубину, проверьте следующие основы:

исполняемый файл сервера MCP существует и может быть запущен
Путь команды верен (используйте абсолютные пути при сомнении)
Инструменты включены (tools: ["*"] или имена конкретных инструментов)
Сервер правильно реализует протокол MCP (отвечает на initialize)
Нет брандмауэра/антивируса, блокирующего процесс (Windows)

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

Добавьте переменные среды в конфигурацию вашего MCP-сервера:

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:

# 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

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

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

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

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

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-сервера:

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

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

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

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

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

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

Причины и решения:

Причина	Решение
Неправильный путь команд	Используйте абсолютный путь: `/usr/local/bin/server`
Отсутствие разрешения на исполняемые файлы	Запуск `chmod +x /path/to/server`
Отсутствующие зависимости	Проверьте на `ldd` (Linux) или запустите вручную
Проблемы с рабочими справочниками	Набор `cwd` в конфигурации

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

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

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

Симптомы: Серверный процесс работает, но инструментов нет.

Причины и решения:

Инструменты, не включённые в конфигурации:

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

Сервер не раскрывает инструменты:
- Тестируйте по tools/list запросу вручную
- Проверьте метод реализации tools/list сервера
Инициализация рукопожатия не удаётся:
- Сервер должен правильно ответить на initialize
- Сервер должен обрабатывать notifications/initialized

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

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

Причины и решения:

Prompt явно не нуждается в этом инструменте:

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

Описание инструмента неясно:

// 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 ошибки.

Решения:

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

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

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

JSON-RPC ошибки

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

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

Сервер неправильно записывает в stdout:
- Вывод отладки идёт в stdout вместо stderr
- Дополнительные новые строки или пробелы
```
// Wrong - pollutes stdout
console.log("Debug info");

// Correct - use stderr for debug
console.error("Debug info");
```
Проблемы с кодированием:
- Обеспечьте кодирование UTF-8
- Нет BOM (метка порядка байтов)
Формулировка сообщения:
- Каждое сообщение должно быть полным JSON-объектом
- Разграничение по новой линии (одно сообщение на строку)

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

Windows

Приложения и инструменты консолей .NET

using GitHub.Copilot;

public static class McpDotnetConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["my-dotnet-server"] = new McpStdioServerConfig
            {
                Command = @"C:\Tools\MyServer\MyServer.exe",
                Args = new List<string>(),
                WorkingDirectory = @"C:\Tools\MyServer",
                Tools = new List<string> { "*" },
            },
            ["my-dotnet-tool"] = new McpStdioServerConfig
            {
                Command = "dotnet",
                Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
                WorkingDirectory = @"C:\Tools\MyTool",
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
    Command = @"C:\Tools\MyServer\MyServer.exe",  // Full path with .exe
    Args = new List<string>(),
    WorkingDirectory = @"C:\Tools\MyServer",  // Set working directory
    Tools = new List<string> { "*" },
}

// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
    Command = "dotnet",
    Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
    WorkingDirectory = @"C:\Tools\MyTool",
    Tools = new List<string> { "*" },
}

Команды NPX

using GitHub.Copilot;

public static class McpNpxConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["filesystem"] = new McpStdioServerConfig
            {
                Command = "cmd",
                Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
    Command = "cmd",
    Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
    Tools = new List<string> { "*" },
}

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

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

Антивирус/файрвол

Windows Defender или другой антивирус могут блокировать:

Новые исполняемые файлы
Процессы, взаимодействующие через stdin/stdout

Решение: Добавьте исключения для вашего исполняемого файла сервера MCP.

macOS

Блокировка хранителя врат

# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server

Самодельные пути

import { MCPStdioServerConfig } from "@github/copilot-sdk";

const mcpServers: Record<string, MCPStdioServerConfig> = {
  "my-server": {
    command: "/opt/homebrew/bin/node",
    args: ["/path/to/server.js"],
    tools: ["*"],
  },
};

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

Проблемы с разрешениями

chmod +x /path/to/mcp-server

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

# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS

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

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

Создайте скрипт-обёртку для логирования всей коммуникации:

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

Используйте его:

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

Осмотрите с инспектором MCP

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

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

Это обеспечивает веб-интерфейс для:

Отправка тестовых запросов
Просмотреть ответы
Инспективные схемы инструментов

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

Проверьте, поддерживает ли ваш сервер версию протокола, которую использует SDK:

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

См. также

Using MCP servers with the GitHub Copilot SDK — Настройка и настройка
Руководство по отладке — отладка по всему SDK
Спецификация MCP — официальная документация протокола

Руководство по отладке серверов MCP

В этой статье

Оглавление

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

Checklist

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

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

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

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

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

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

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

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

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

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

JSON-RPC ошибки

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

Windows

Приложения и инструменты консолей .NET

Команды NPX

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

Антивирус/файрвол

macOS

Блокировка хранителя врат

Самодельные пути

Linux

Проблемы с разрешениями

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

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

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

Осмотрите с инспектором MCP

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

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

См. также