wehub-resource-sync
17 KiB
Налагодження з 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: Початок роботи! Продовжуйте навчання:
Додаткові ресурси
- MCP Inspector GitHub Репозиторій
- Специфікація MCP - Повідомлення протоколу
- Специфікація JSON-RPC 2.0
Відмова від відповідальності: Цей документ було перекладено за допомогою сервісу автоматичного перекладу Co-op Translator. Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматизовані переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для важливої інформації рекомендується звертатися до професійного людського перекладу. Ми не несемо відповідальності за будь-які непорозуміння чи неправильні тлумачення, що виникли внаслідок використання цього перекладу.