# Руководство по отладке серверов MCP В этом руководстве рассматриваются методы отладки, специфичные для серверов MCP (Model Context Protocol) при использовании Copilot SDK. ## Оглавление * [Быстрая диагностика](#quick-diagnostics) * [Независимое тестирование серверов MCP](#testing-mcp-servers-independently) * [Распространённые проблемы](#common-issues) * [Platform-Specific Проблемы](#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 Всегда сначала тестируйте ваш 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 # 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) или запустите вручную | | Проблемы с рабочими справочниками | Набор `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-схема действительно действительна * Обязательные поля должны быть расположены в `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 #### Приложения и инструменты консолей .NET ```csharp using GitHub.Copilot; public static class McpDotnetConfigExample { public static void Main() { var servers = new Dictionary { ["my-dotnet-server"] = new McpStdioServerConfig { Command = @"C:\Tools\MyServer\MyServer.exe", Args = new List(), WorkingDirectory = @"C:\Tools\MyServer", Tools = new List { "*" }, }, ["my-dotnet-tool"] = new McpStdioServerConfig { Command = "dotnet", Args = new List { @"C:\Tools\MyTool\MyTool.dll" }, WorkingDirectory = @"C:\Tools\MyTool", Tools = new List { "*" }, } }; } } ``` ```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 using GitHub.Copilot; public static class McpNpxConfigExample { public static void Main() { var servers = new Dictionary { ["filesystem"] = new McpStdioServerConfig { Command = "cmd", Args = new List { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" }, Tools = new List { "*" }, } }; } } ``` ```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 { "*" }, } ``` #### Проблемы с путями * Используйте необработанные струны (`@"C:\path"`) или прямые слэши (`"C:/path"`) * По возможности избегайте пробелов в путях * Если нужны места, убедитесь, что правильно оформляете цены #### Антивирус/файрвол Windows Defender или другой антивирус могут блокировать: * Новые исполняемые файлы * Процессы, взаимодействующие через stdin/stdout **Решение:** Добавьте исключения для вашего исполняемого файла сервера MCP. ### macOS #### Блокировка хранителя врат ```bash # If the server is blocked xattr -d com.apple.quarantine /path/to/mcp-server ``` #### Самодельные пути ```typescript import { MCPStdioServerConfig } from "@github/copilot-sdk"; const mcpServers: Record = { "my-server": { command: "/opt/homebrew/bin/node", args: ["/path/to/server.js"], tools: ["*"], }, }; ``` ```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 Inspector: ```bash npx @modelcontextprotocol/inspector /path/to/your/mcp-server ``` Это обеспечивает веб-интерфейс для: * Отправка тестовых запросов * Просмотреть ответы * Инспективные схемы инструментов ### Несоответствия версий протокола Проверьте, поддерживает ли ваш сервер версию протокола, которую использует 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 * [ ] Есть ли сообщения об ошибках ## См. также * [Using MCP servers with the GitHub Copilot SDK](/ru/copilot/how-tos/copilot-sdk/features/mcp) — Настройка и настройка * [Руководство по отладке](/ru/copilot/how-tos/copilot-sdk/troubleshooting/debugging) — отладка по всему SDK * [Спецификация MCP](https://modelcontextprotocol.io/) — официальная документация протокола