MCP Failure Lab

Набор инструментов для хаос-инжиниринга и тестирования отказоустойчивости серверов Model Context Protocol.

Документация · Страница проекта

Быстрый старт

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

npx mcp-failure-lab demo

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

MCP Failure Lab — Demo
Running a real 500ms delay scenario...

Scenario: Deterministic delay demo
Outcome: success
Duration: ~500 ms
Assertions: passed

Точная длительность может незначительно отличаться между запусками. API-ключ или внешний MCP-сервер не требуются.

Покажите доступные команды:

npx mcp-failure-lab --help

Запустите встроенный MCP-сервер через stdio:

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

Назначение

MCP Failure Lab помогает авторам серверов воспроизводить задержки, зависающие инструменты, отмену и потерю транспорта детерминированным образом.

Он обеспечивает контролируемое поведение при сбоях для тестирования обработки тайм-аутов, очистки при отмене, восстановления после потери транспорта, утверждений и результатов CI.

Текущая область применения

MCP Failure Lab выполняет детерминированные JSON-сценарии против собственного встроенного MCP-сервера из командной строки.

Доступно сейчас:

• инструменты ping, delay, hang и disconnect

• MCP-взаимодействие через stdio

• определения сценариев в виде кода и JSON

• утверждения о результате и максимальной длительности

• утверждения о результатах MCP

• последовательные вызовы наблюдателя для проверки постусловий

• вывод в консоль и JSON

• машиночитаемые ошибки команд

• коды выхода, удобные для CI

• модульные, интеграционные и сквозные тесты

Не реализовано:

• оркестрация внешних MCP-клиентов

• адаптеры целевых клиентов

• Streamable HTTP

• отчёты JUnit

• сбои из-за некорректных сообщений, дублирующихся ответов и потери сеанса

MCP Failure Lab в настоящее время не является универсальным прокси или оркестратором тестов внешних MCP-клиентов.

Как это работает

MCP Failure Lab выполняет детерминированные сценарии через встроенные MCP-клиент и сервер. Сценарий вызывает ping, delay, hang или disconnect, записывает наблюдаемый результат и длительность и оценивает объявленные ожидания.

Необязательные вызовы наблюдателя выполняются последовательно через то же соединение MCP-клиента для проверки постусловий через отдельный путь инструмента.

См. документацию по архитектуре для диаграмм, обязанностей и границ реализации.

Документация

Полные руководства и справочники доступны на mcplab.dev/docs.

• Начало работы

• Сценарии

• Инструменты сбоев

• Справочник CLI

• Отчётность

• Архитектура

• Примеры

• Устранение неполадок

Требования

• Node.js 22.19.0 или новее

• npm

Совместимость протоколов

MCP Failure Lab по умолчанию нацелен на MCP 2026-07-28. Его CLI-сервер использует точку входа stdio с учётом эпохи из SDK v2, а встроенный клиент сценариев закрепляет 2026-07-28, чтобы современное поведение проверялось явно.

Сервер также принимает поток инициализации 2025-11-25 для совместимости. Этот устаревший путь по-прежнему покрыт интеграционными тестами, но новая разработка нацелена на 2026-07-28. Существующие инструменты сбоев ping, delay, hang и disconnect имеют одинаковое пользовательское поведение в обеих эпохах; функции протокола, которые полагаются на запросы, инициируемые сервером, различаются между эпохами и выходят за рамки этих инструментов сбоев.

Установка

Запустите пакет напрямую с помощью npx:

npx mcp-failure-lab demo

Глобальная установка не требуется.

Чтобы установить команду глобально:

npm install -g mcp-failure-lab

CLI

# Run the built-in demonstration
npx mcp-failure-lab demo

# Display command help
npx mcp-failure-lab --help

# Display the installed version
npx mcp-failure-lab --version

# Start the MCP server over stdio
npx mcp-failure-lab serve

Процесс serve ожидает MCP-клиента. Нажмите Ctrl+C для корректного завершения.

Запуск сценария

Файлы сценариев используют JSON:

{
  "name": "bounded delay succeeds",
  "call": {
    "tool": "delay",
    "args": {
      "delayMs": 250
    }
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "success",
    "maxDurationMs": 500
  }
}

Из клона репозитория запустите включённый сценарий:

npm run dev -- run examples/scenarios/delay-success.json

Сгенерируйте машиночитаемый вывод:

npm run dev -- run examples/scenarios/delay-success.json --report json

Команда завершается с кодом:

Для утверждений о результатах, вызовов наблюдателя, форматов отчётов и поведения тайм-аутов см. документацию по сценариям и отчётности.

Инструменты сбоев

См. справочник по инструментам сбоев для аргументов и поведения.

Инспектирование сервера

Запустите MCP Inspector для опубликованного пакета:

npx @modelcontextprotocol/inspector npx mcp-failure-lab serve

Подключитесь через stdio, перечислите доступные инструменты и вызовите ping, delay, hang или disconnect.

Не делитесь и не фиксируйте временные токены аутентификации, включённые в URL-адреса Inspector.

Внешняя проверка интеграции

MCP Failure Lab был независимо проверен с помощью симуляции Future AGI с использованием независимого Python MCP-клиента. Эксперимент вызывал реальный инструмент hang через stdio и применял тайм-аут на стороне клиента перед оценкой смоделированных ответов агента.

Это пример внешней проверки, а не официальная интеграция или одобрение Future AGI.

См. пример Future AGI для результатов и шагов воспроизведения.

Разработка

Клонируйте репозиторий и установите зависимости:

git clone https://github.com/anilloutombam/mcp-failure-lab.git
cd mcp-failure-lab
npm install

Запустите CLI для разработки:

npm run dev -- --help

Перед открытием pull request выполните:

npm run format:check
npm run typecheck
npm test
npm run build

См. CONTRIBUTING.md для описания процесса внесения вклада.

Дорожная карта

Планируемые работы отслеживаются в GitHub Issues.

Элементы дорожной карты не являются частью текущей реализации, если явно не задокументированы как доступные.

Лицензия

MIT