{"meta":{"title":"Руководство по отладке серверов MCP","intro":"В этом руководстве рассматриваются методы отладки, специфичные для серверов MCP (Model Context Protocol) при использовании Copilot SDK.","product":"GitHub Copilot","breadcrumbs":[{"href":"/ru/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos","title":"Инструкции"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Второй пилот SDK"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting","title":"Troubleshooting"},{"href":"/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"Отладка MCP"}],"documentType":"article"},"body":"# Руководство по отладке серверов MCP\n\nВ этом руководстве рассматриваются методы отладки, специфичные для серверов MCP (Model Context Protocol) при использовании Copilot SDK.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Оглавление\n\n* [Быстрая диагностика](#quick-diagnostics)\n* [Независимое тестирование серверов MCP](#testing-mcp-servers-independently)\n* [Распространённые проблемы](#common-issues)\n* [Platform-Specific Проблемы](#platform-specific-issues)\n* [Продвинутая отладка](#advanced-debugging)\n\n## Быстрая диагностика\n\n### Checklist\n\nПрежде чем погружаться в глубину, проверьте следующие основы:\n\n* [ ] исполняемый файл сервера MCP существует и может быть запущен\n* [ ] Путь команды верен (используйте абсолютные пути при сомнении)\n* [ ] Инструменты включены (`tools: [\"*\"]` или имена конкретных инструментов)\n* [ ] Сервер правильно реализует протокол MCP (отвечает на `initialize`)\n* [ ] Нет брандмауэра/антивируса, блокирующего процесс (Windows)\n\n### Включите логирование отладки MCP\n\nДобавьте переменные среды в конфигурацию вашего MCP-сервера:\n\n```typescript\nmcpServers: {\n  \"my-server\": {\n    type: \"local\",\n    command: \"/path/to/server\",\n    args: [],\n    env: {\n      MCP_DEBUG: \"1\",\n      DEBUG: \"*\",\n      NODE_DEBUG: \"mcp\",  // For Node.js MCP servers\n    },\n  },\n}\n```\n\n## Независимое тестирование серверов MCP\n\nВсегда сначала тестируйте ваш MCP-сервер вне SDK.\n\n### Ручной протокольный тест\n\nОтправьте `initialize` запрос через stdin:\n\n```bash\n# Unix/macOS\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n\n# Windows (PowerShell)\n'{\"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\n```\n\n**Ожидаемый ответ:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"your-server\",\"version\":\"1.0\"}}}\n```\n\n### Список тестовых инструментов\n\nПосле инициализации запросите список инструментов:\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**Ожидаемый ответ:**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### Интерактивный скрипт тестирования\n\nСоздайте тестовый скрипт для интерактивной отладки вашего MCP-сервера:\n\n```bash\n#!/bin/bash\n# test-mcp.sh\n\nSERVER=\"$1\"\n\n# Initialize\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n\n# Send initialized notification\necho '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}'\n\n# List tools\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'\n\n# Keep stdin open\ncat\n```\n\nИспользование:\n\n```bash\n./test-mcp.sh | /path/to/mcp-server\n```\n\n## Распространенные проблемы\n\n### Сервер не запускается\n\n**Симптомы:** Инструменты не появляются, нет ошибок в логах.\n\n**Причины и решения:**\n\n| Причина                                    | Решение                                              |\n| ------------------------------------------ | ---------------------------------------------------- |\n| Неправильный путь команд                   | Используйте абсолютный путь: `/usr/local/bin/server` |\n| Отсутствие разрешения на исполняемые файлы | Запуск `chmod +x /path/to/server`                    |\n| Отсутствующие зависимости                  | Проверьте на `ldd` (Linux) или запустите вручную     |\n| Проблемы с рабочими справочниками          | Набор `cwd` в конфигурации                           |\n\n**Отладка запускается вручную:**\n\n```bash\n# Run exactly what the SDK would run\ncd /expected/working/dir\n/path/to/command arg1 arg2\n```\n\n### Сервер запускается, но инструменты не появляются\n\n**Симптомы:** Серверный процесс работает, но инструментов нет.\n\n**Причины и решения:**\n\n1. **Инструменты, не включённые в конфигурации:**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **Сервер не раскрывает инструменты:**\n   * Тестируйте по `tools/list` запросу вручную\n   * Проверьте метод реализации `tools/list` сервера\n\n3. **Инициализация рукопожатия не удаётся:**\n   * Сервер должен правильно ответить на `initialize`\n   * Сервер должен обрабатывать `notifications/initialized`\n\n### Инструменты указаны, но так и не позвонили\n\n**Симптомы:** Инструменты появляются в логах отладки, но модель их не использует.\n\n**Причины и решения:**\n\n1. **Prompt явно не нуждается в этом инструменте:**\n\n   ```typescript\n   // Too vague\n   await session.sendAndWait({ prompt: \"What's the weather?\" });\n\n   // Better - explicitly mentions capability\n   await session.sendAndWait({ \n     prompt: \"Use the weather tool to get the current temperature in Seattle\" \n   });\n   ```\n\n2. **Описание инструмента неясно:**\n\n   ```typescript\n   // Bad - model doesn't know when to use it\n   { name: \"do_thing\", description: \"Does a thing\" }\n\n   // Good - clear purpose\n   { name: \"get_weather\", description: \"Get current weather conditions for a city. Returns temperature, humidity, and conditions.\" }\n   ```\n\n3. **Проблемы со схемой инструментов:**\n   * Убедитесь `inputSchema` , что JSON-схема действительно действительна\n   * Обязательные поля должны быть расположены в `required` массиве\n\n### Ошибки, связанные с истечением времени ожидания\n\n**Симптомы:**`MCP tool call timed out` ошибки.\n\n**Решения:**\n\n1. **Увеличение тайм-аута:**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **Оптимизировать производительность сервера:**\n   * Добавьте логирование прогресса для выявления узких мест\n   * Рассмотрим асинхронные операции\n   * Проверьте наличие блокировки ввода/вывода\n\n3. **Для долгосрочных инструментов** рассмотрите возможность потоковых ответов, если они поддерживаются.\n\n### JSON-RPC ошибки\n\n**Симптомы:** Ошибки разбора, некорректные ошибки запроса.\n\n**Распространенные причины:**\n\n1. **Сервер неправильно записывает в stdout:**\n   * Вывод отладки идёт в stdout вместо stderr\n   * Дополнительные новые строки или пробелы\n   ```typescript\n   // Wrong - pollutes stdout\n   console.log(\"Debug info\");\n\n   // Correct - use stderr for debug\n   console.error(\"Debug info\");\n   ```\n\n2. **Проблемы с кодированием:**\n   * Обеспечьте кодирование UTF-8\n   * Нет BOM (метка порядка байтов)\n\n3. **Формулировка сообщения:**\n   * Каждое сообщение должно быть полным JSON-объектом\n   * Разграничение по новой линии (одно сообщение на строку)\n\n## Проблемы, связанные с платформой\n\n### Windows\n\n#### Приложения и инструменты консолей .NET\n\n```csharp\n// Correct configuration for .NET exe\n[\"my-dotnet-server\"] = new McpStdioServerConfig\n{\n    Command = @\"C:\\Tools\\MyServer\\MyServer.exe\",  // Full path with .exe\n    Args = new List<string>(),\n    WorkingDirectory = @\"C:\\Tools\\MyServer\",  // Set working directory\n    Tools = new List<string> { \"*\" },\n}\n\n// For dotnet tool (DLL)\n[\"my-dotnet-tool\"] = new McpStdioServerConfig\n{\n    Command = \"dotnet\",\n    Args = new List<string> { @\"C:\\Tools\\MyTool\\MyTool.dll\" },\n    WorkingDirectory = @\"C:\\Tools\\MyTool\",\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### Команды NPX\n\n```csharp\n// Windows needs cmd /c for npx\n[\"filesystem\"] = new McpStdioServerConfig\n{\n    Command = \"cmd\",\n    Args = new List<string> { \"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\allowed\\\\path\" },\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### Проблемы с путями\n\n* Используйте необработанные струны (`@\"C:\\path\"`) или прямые слэши (`\"C:/path\"`)\n* По возможности избегайте пробелов в путях\n* Если нужны места, убедитесь, что правильно оформляете цены\n\n#### Антивирус/файрвол\n\nWindows Defender или другой антивирус могут блокировать:\n\n* Новые исполняемые файлы\n* Процессы, взаимодействующие через stdin/stdout\n\n**Решение:** Добавьте исключения для вашего исполняемого файла сервера MCP.\n\n### macOS\n\n#### Блокировка хранителя врат\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Самодельные пути\n\n```typescript\n// GUI apps may not have /opt/homebrew in PATH\nmcpServers: {\n  \"my-server\": {\n    command: \"/opt/homebrew/bin/node\",  // Full path\n    args: [\"/path/to/server.js\"],\n  },\n}\n```\n\n### Linux\n\n#### Проблемы с разрешениями\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### Отсутствующие общие библиотеки\n\n```bash\n# Check dependencies\nldd /path/to/mcp-server\n\n# Install missing libraries\napt install libfoo  # Debian/Ubuntu\nyum install libfoo  # RHEL/CentOS\n```\n\n## Расширенная отладка\n\n### Захват всего MCP-трафика\n\nСоздайте скрипт-обёртку для логирования всей коммуникации:\n\n```bash\n#!/bin/bash\n# mcp-debug-wrapper.sh\n\nLOG=\"./mcp-debug-$(date +%s).log\"\nACTUAL_SERVER=\"$1\"\nshift\n\necho \"=== MCP Debug Session ===\" >> \"$LOG\"\necho \"Server: $ACTUAL_SERVER\" >> \"$LOG\"\necho \"Args: $@\" >> \"$LOG\"\necho \"=========================\" >> \"$LOG\"\n\n# Tee stdin/stdout to log file\ntee -a \"$LOG\" | \"$ACTUAL_SERVER\" \"$@\" 2>> \"$LOG\" | tee -a \"$LOG\"\n```\n\nИспользуйте его:\n\n```typescript\nmcpServers: {\n  \"debug-server\": {\n    command: \"/path/to/mcp-debug-wrapper.sh\",\n    args: [\"/actual/server/path\", \"arg1\", \"arg2\"],\n  },\n}\n```\n\n### Осмотрите с инспектором MCP\n\nИспользуйте официальный инструмент MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nЭто обеспечивает веб-интерфейс для:\n\n* Отправка тестовых запросов\n* Просмотреть ответы\n* Инспективные схемы инструментов\n\n### Несоответствия версий протокола\n\nПроверьте, поддерживает ли ваш сервер версию протокола, которую использует SDK:\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nЕсли версии не совпадают, обновите библиотеку сервера MCP.\n\n## Контрольный список отладки\n\nПри открытии выпуска или просьбе о помощи собирайте:\n\n* [ ] Язык и версия SDK\n* [ ] CLI-версия (`copilot --version`)\n* [ ] Тип сервера MCP (Node.js, Python, .NET, Go, Rust и многое другое)\n* [ ] Полная конфигурация сервера MCP (скрыть секреты)\n* [ ] Результат ручного `initialize` теста\n* [ ] Результат ручного `tools/list` теста\n* [ ] Логи отладки из SDK\n* [ ] Есть ли сообщения об ошибках\n\n## См. также\n\n* [Использование MCP-серверов с SDK GitHub Copilot](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/mcp) — Настройка и настройка\n* [Руководство по отладке](/ru/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/troubleshooting/debugging) — отладка по всему SDK\n* [Спецификация MCP](https://modelcontextprotocol.io/) — официальная документация протокола"}