Files

T

wehub-resource-sync c275ba2868 chore: import upstream snapshot with attribution

2026-07-13 13:31:35 +08:00

18 KiB

Raw Permalink Blame History

Отладка с помощью MCP Inspector

MCP Inspector — это важный инструмент для отладки, который позволяет интерактивно тестировать и устранять неполадки на ваших MCP серверах без необходимости использовать полнофункциональное приложение AI хоста. Можно считать его «Postman для MCP» — он предоставляет визуальный интерфейс для отправки запросов, просмотра ответов и понимания поведения вашего сервера.

Почему стоит использовать MCP Inspector?

При разработке MCP серверов вы часто столкнетесь с этими задачами:

«Мой сервер вообще запущен?» — Inspector отображает статус подключения
«Правильно ли зарегистрированы мои инструменты?» — Inspector показывает все доступные инструменты
«Каков формат ответа?» — Inspector демонстрирует полный JSON ответ
«Почему этот инструмент не работает?» — Inspector показывает подробные сообщения об ошибках

Требования

Установлен Node.js версии 18 и выше
npm (устанавливается вместе с Node.js)
MCP сервер для тестирования (см. Модуль 3.1 — Первый сервер)

Установка

Вариант 1: Запуск через npx (рекомендуется для быстрого теста)

npx @modelcontextprotocol/inspector

Вариант 2: Глобальная установка

npm install -g @modelcontextprotocol/inspector
mcp-inspector

Вариант 3: Добавление в ваш проект

cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector

Добавьте в package.json:

{
  "scripts": {
    "inspector": "mcp-inspector"
  }
}

Подключение к вашему серверу

Серверы stdio (локальный процесс)

Для серверов, обменивающихся данными через стандартный ввод/вывод:

# Сервер на Python
npx @modelcontextprotocol/inspector python -m your_server_module

# Сервер на Node.js
npx @modelcontextprotocol/inspector node ./build/index.js

# С переменными окружения
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py

Серверы SSE/HTTP (сетевая работа)

Для серверов, работающих как HTTP сервисы:

Сначала запустите ваш сервер:

python server.py  # Сервер запущен на http://localhost:8080

Запустите Inspector и подключитесь:

npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse

Обзор интерфейса Inspector

При запуске Inspector вы увидите веб-интерфейс (обычно по адресу http://localhost:5173):

┌─────────────────────────────────────────────────────────────┐
│  MCP Inspector                              [Connected ✅]   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   🔧 Tools  │  │ 📄 Resources│  │ 💬 Prompts  │         │
│  │    (3)      │  │    (2)      │  │    (1)      │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐ │
│  │  📋 Message Log                                       │ │
│  │  ─────────────────────────────────────────────────── │ │
│  │  → initialize                                         │ │
│  │  ← initialized (server info)                          │ │
│  │  → tools/list                                         │ │
│  │  ← tools (3 tools)                                    │ │
│  └───────────────────────────────────────────────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Тестирование инструментов

Просмотр доступных инструментов

Перейдите на вкладку Tools
Inspector автоматически вызывает tools/list
Вы увидите все зарегистрированные инструменты с:
- Названием инструмента
- Описанием
- Схемой входных параметров

Вызов инструмента

Выберите инструмент из списка
Заполните необходимые параметры в форме
Нажмите Run Tool
Просмотрите ответ в панели результатов

Пример: тестирование калькулятора

Tool: add
Parameters:
  a: 25
  b: 17

Response:
{
  "content": [
    {
      "type": "text",
      "text": "42"
    }
  ]
}

Отладка ошибок инструментов

Когда инструмент завершился с ошибкой, Inspector показывает:

Error Response:
{
  "error": {
    "code": -32602,
    "message": "Invalid params: 'b' is required"
  }
}

Распространённые коды ошибок:

Код	Значение
-32700	Ошибка парсинга (некорректный JSON)
-32600	Некорректный запрос
-32601	Метод не найден
-32602	Неверные параметры
-32603	Внутренняя ошибка

Тестирование ресурсов

Просмотр ресурсов

Перейдите на вкладку Resources
Inspector вызывает resources/list
Вы увидите:
- URI ресурсов
- Названия и описания
- MIME типы

Чтение ресурса

Выберите ресурс
Нажмите Read Resource
Просмотрите возвращённое содержимое

Пример вывода:

Resource: file:///config/settings.json
Content-Type: application/json

{
  "config": {
    "debug": true,
    "maxConnections": 10
  }
}

Тестирование подсказок

Просмотр подсказок

Перейдите на вкладку Prompts
Inspector вызывает prompts/list
Просмотрите доступные шаблоны подсказок

Получение подсказки

Выберите подсказку
Заполните необходимые аргументы
Нажмите Get Prompt
Посмотрите отрендеренные сообщения подсказки

Анализ журнала сообщений

Журнал сообщений отображает все сообщения протокола MCP:

14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}

На что обратить внимание

Пары запросов/ответов: каждому → должен соответствовать ←
Сообщения об ошибках: ищите "error" в ответах
Временные задержки: большие паузы могут говорить о проблемах с производительностью
Версия протокола: убедитесь, что сервер и клиент используют одинаковую версию

Интеграция с VS Code

Inspector можно запускать прямо из VS Code:

С помощью launch.json

Добавьте в .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug with MCP Inspector",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npx",
      "runtimeArgs": [
        "@modelcontextprotocol/inspector",
        "python",
        "${workspaceFolder}/server.py"
      ],
      "console": "integratedTerminal"
    },
    {
      "name": "Debug SSE Server with Inspector",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",
      "preLaunchTask": "Start MCP Inspector"
    }
  ]
}

С помощью задач (tasks)

Добавьте в .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start MCP Inspector",
      "type": "shell",
      "command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Inspector",
          "endsPattern": "listening"
        }
      }
    }
  ]
}

Типичные сценарии отладки

Сценарий 1: Сервер не подключается

Симптомы: Inspector показывает «Disconnected» или зависает на «Connecting...»

Проверочный список:

✅ Правильная команда запуска сервера?
✅ Установлены все зависимости?
✅ Путь к серверу абсолютный или относительно текущей директории?
✅ Установлены необходимые переменные окружения?

Шаги отладки:

# Сначала вручную протестируйте сервер
python -c "import your_server_module; print('OK')"

# Проверьте наличие ошибок импорта
python -m your_server_module 2>&1 | head -20

# Убедитесь, что MCP SDK установлен
pip show mcp

Сценарий 2: Инструменты не отображаются

Симптомы: Вкладка Tools пуста

Возможные причины:

Инструменты не зарегистрированы при инициализации сервера
Сервер упал после запуска
Обработчик tools/list возвращает пустой массив

Шаги отладки:

Проверьте журнал сообщений на ответ tools/list
Добавьте логирование при регистрации инструментов
Убедитесь, что декораторы @mcp.tool() присутствуют (Python)

Сценарий 3: Инструмент возвращает ошибку

Симптомы: Вызов инструмента возвращает ошибку

Подход к отладке:

Внимательно прочитайте сообщение об ошибке
Проверьте соответствие типов параметров схеме
Добавьте try/catch с подробными сообщениями об ошибках
Проверьте логи сервера на наличие трассировок стека

Пример улучшенной обработки ошибок:

@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
    try:
        # Логика инструмента здесь
        result = process(param1, param2)
        return str(result)
    except ValueError as e:
        raise McpError(f"Invalid parameter: {e}")
    except Exception as e:
        raise McpError(f"Tool failed: {type(e).__name__}: {e}")

Сценарий 4: Содержимое ресурса пустое

Симптомы: Ресурс возвращается, но содержимое пустое или null

Проверочный список:

✅ Путь к файлу или URI корректен
✅ Сервер имеет разрешения на чтение ресурса
✅ Содержимое ресурса возвращается правильно

Расширенные возможности Inspector

Пользовательские заголовки (SSE)

npx @modelcontextprotocol/inspector \
  --sse http://localhost:8080/sse \
  --header "Authorization: Bearer your-token"

Подробное логирование

DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py

Запись сессий

Inspector может экспортировать журналы сообщений для последующего анализа:

Нажмите Export Log в панели сообщений
Сохраните JSON файл
Поделитесь им с коллегами для отладки

Лучшие практики

Тестируйте часто и как можно раньше — используйте Inspector на протяжении всей разработки, а не только при ошибках
Начинайте с простого — проверьте базовое соединение перед сложными вызовами инструментов
Проверяйте схему — многие ошибки связаны с несовпадением типов параметров
Читайте сообщения об ошибках — ошибки MCP обычно описательные
Держите Inspector открытым — это помогает своевременно выявлять проблемы во время разработки

Что дальше

Вы успешно завершили Модуль 3: Начало работы! Продолжайте обучение:

Модуль 4: Практическая реализация

Дополнительные ресурсы

Отказ от ответственности:
Этот документ был переведен с помощью сервиса машинного перевода Co-op Translator. Несмотря на наши усилия обеспечить точность, пожалуйста, учитывайте, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения важной информации рекомендуется воспользоваться профессиональным переводом, выполненным человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода.

18 KiB Raw Permalink Blame History Unescape Escape

Отладка с помощью MCP Inspector

Почему стоит использовать MCP Inspector?

Требования

Установка

Вариант 1: Запуск через npx (рекомендуется для быстрого теста)

Вариант 2: Глобальная установка

Вариант 3: Добавление в ваш проект

Подключение к вашему серверу

Серверы stdio (локальный процесс)

Серверы SSE/HTTP (сетевая работа)

Обзор интерфейса Inspector

Тестирование инструментов

Просмотр доступных инструментов

Вызов инструмента

Отладка ошибок инструментов

Тестирование ресурсов

Просмотр ресурсов

Чтение ресурса

Тестирование подсказок

Просмотр подсказок

Получение подсказки

Анализ журнала сообщений

На что обратить внимание

Интеграция с VS Code

С помощью launch.json

С помощью задач (tasks)

Типичные сценарии отладки

Сценарий 1: Сервер не подключается

Сценарий 2: Инструменты не отображаются

Сценарий 3: Инструмент возвращает ошибку

Сценарий 4: Содержимое ресурса пустое

Расширенные возможности Inspector

Пользовательские заголовки (SSE)

Подробное логирование

Запись сессий

Лучшие практики

Что дальше

Дополнительные ресурсы

18 KiB

Raw Permalink Blame History