incident-assistant — MCP «Hello World»

Тестовый MCP-сервер (Model Context Protocol), созданный в рамках упражнения «реагирование на инциденты» из книги/курса по MCP — с тем отличием, что здесь он подключён к Claude Code в качестве клиента вместо Gemini CLI.

Сервер имитирует панель оповещений для продакшн-системы и предоставляет:

• Ресурс (resource://incidents/active) со списком активных оповещений (мок-данные).

• Инструмент (resolve_incident), который «перезапускает» сервис для устранения оповещения, с симулированным уровнем успеха 80% (чтобы можно было увидеть и сценарий сбоя).

Исходный код: src/index.ts

Стек

• @modelcontextprotocol/sdk — официальный MCP SDK для TypeScript/Node.

• Транспорт stdio (клиент запускает сервер как подпроцесс, и они общаются через stdin/stdout).

• TypeScript компилируется в dist/ (см. tsconfig.json).

Related MCP server: mcp-live-telemetry

1. Установка и сборка

npm install
npx tsc

Это компилирует src/index.ts → dist/index.js (точка входа, которая запускает сервер).

Примечание: console.error намеренно используется для логирования внутри сервера — stdout зарезервирован для протокола MCP JSON-RPC, поэтому любой console.log там нарушил бы связь с клиентом.

2. Регистрация сервера в Claude Code

В отличие от книги (где используется settings.json от Gemini CLI), в Claude Code локальный MCP-сервер регистрируется командой claude mcp add:

cd /absolute/path/to/incident-assistant
claude mcp add --scope project incident-assistant -- node /absolute/path/to/incident-assistant/dist/index.js

Ключевые моменты:

• -- отделяет собственные флаги claude mcp add от фактической команды, которая запускает сервер.

• Используется абсолютный путь к dist/index.js (относительный путь разрешался бы относительно каталога, из которого был запущен claude, а не относительно расположения .mcp.json).

• --scope project сохраняет конфигурацию в .mcp.json в корне репозитория (контролируется в git). Альтернативы: --scope local (приватно для меня, не публикуется) или --scope user (доступно во всех моих проектах, хранится в ~/.claude.json).

Это создаёт локальный .mcp.json с встроенным абсолютным путём вашей машины. Поскольку этот путь специфичен для вашего окружения, сам .mcp.json находится в gitignore — вместо него репозиторий содержит .mcp.json.example, показывающий ожидаемую структуру с путём-заглушкой:

{
  "mcpServers": {
    "incident-assistant": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/incident-assistant/dist/index.js"]
    }
  }
}

3. Подтверждение сервера

Поскольку .mcp.json — это файл проекта (он может прийти из общего репозитория), Claude Code запрашивает явное подтверждение при первом запуске:

claude

При запуске появляется запрос на доверие для incident-assistant — примите его один раз для проекта (если только команда/аргументы сервера не изменятся позже).

4. Проверка

claude mcp list
claude mcp get incident-assistant

Ожидаемый вывод после подтверждения:

incident-assistant: node /absolute/path/to/incident-assistant/dist/index.js - ✔ Connected

Внутри сессии claude команда /mcp показывает доступные инструменты/ресурсы сервера.

5. Демонстрация — реальный результат

Запрос агенту: «есть ли критические оповещения? Если да, попробуй исправить их и сообщи мне результат»

Агент:

1. Перечислил доступные MCP-ресурсы (listMcpResources) и нашёл resource://incidents/active.

2. Прочитал этот ресурс (readMcpResource) и получил мок-оповещения:

   ID	Service	Status	Message
   ALRT-001	auth-api	🔴 CRITICAL	Memory leak detected
   ALRT-002	payment-gateway	🟡 WARNING (not critical)	Latency > 500ms

3. Определил, что критическим является только ALRT-001, и вызвал инструмент resolve_incident с serviceName: "auth-api".

4. Результат:

   ✅ Исправлено: auth-api был корректно перезапущен для устранения утечки памяти (ALRT-001, CRITICAL). Перезапуск прошёл успешно.

   ⚠️ Не тронуто: payment-gateway всё ещё показывает WARNING (latency > 500ms), но это не критично, поэтому его оставили как есть.

   Примечание агента: перезапуск устраняет симптом, но не обязательно первопричину — стоит следить за памятью auth-api, чтобы убедиться, что утечка не повторится.

5. Когда агента явно просят «перезапусти также payment-gateway», он снова вызывает resolve_incident с serviceName: "payment-gateway" (точный результат здесь не зафиксирован, поскольку он зависит от 80% симулированного уровня успеха — может вернуться ✅ или ❌ FAILURE).

Это подтверждает полный цикл: MCP-клиент (Claude Code) → обнаружение ресурсов/инструментов → чтение ресурса → принятие решения → вызов инструмента → результат.

Благодарности

Это упражнение основано на / изучено из maliksahil/mcp-incident-assistant. В оригинальном руководстве в качестве MCP-клиента используется Gemini CLI; этот репозиторий адаптирует тот же сервер для использования с Claude Code.

Заметки / подводные камни

• Сервер работает под WSL; поскольку в этой конфигурации Claude Code также запускается из WSL-терминала, пути в .mcp.json являются нативными Linux-путями (например, /home/<user>/...), а не Windows UNC-путями (\\wsl.localhost\...).

• Если src/index.ts изменён, его нужно пересобрать (npx tsc), чтобы изменение вступило в силу — сервер запускается из dist/index.js, а не напрямую из .ts-файла.

• resolve_incident имеет намеренно симулированный уровень успеха 80% (Math.random() > 0.2), поэтому можно наблюдать, как агент обрабатывает как успешный случай, так и случай сбоя (isError: true).