MCP Failure Lab

A chaos-engineering and resilience-testing toolkit for Model Context Protocol servers.

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

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

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

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

Или запустите локальный потоковый HTTP-эндпоинт:

npx mcp-failure-lab serve --transport http

Назначение

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

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

Текущий охват

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

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

• Инструменты ping, delay, hang и disconnect
• Обмен MCP через stdio и Streamable HTTP
• Определения сценариев в коде и JSON
• Проверки исхода и максимальной продолжительности
• Проверки результатов MCP
• Последовательные вызовы наблюдателей для проверки постусловий
• Оркестрация внешних MCP-целей через валидированный реестр адаптеров
• Конфигурации целей Streamable HTTP и stdio
• Ограниченная настройка адаптера, выполнение, наблюдение, отмена и очистка
• Отдельная диагностика сценариев и жизненного цикла адаптера
• Отчеты в консоли, JSON и JUnit XML
• Машиночитаемые ошибки команд
• Совместимость с CI
• Единичные, интеграционные и сквозные тесты

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

• Адаптеры и политики восстановления, специфичные для провайдера
• ОшибкиMalformed-message, duplicate-response и session-loss

MCP Failure Lab не является универсальным прокси. Внешние цели тестируются через те же вызовы сценариев и ожидания, что и встроенный сервер.

ЗапускAgainst другой MCP server

Передайте конфигурацию цели, чтобы выполнить тот же сценарий против Streamable HTTP или stdio MCP-сервера:

# Из репозитория
npm run dev -- run path/to/scenario.json --target path/to/target.json

# С опубликованным пакетом и вашими сценарием и целями
npx mcp-failure-lab run path/to/scenario.json --target path/to/target.json

См. руководство по внешним MCP-целям для полного HTTP и stdio-конфигураций, проверенных workflow GitHub и GitLab, валидации MCP Inspector в браузере, диагностики жизненного цикла, обработки учетных данных и устранения неполадок.

В репозитории также приведён безопасный, только для чтения пример MCP для GitHub с использованием официального удалённого сервера:

export GITHUB_MCP_AUTHORIZATION="Bearer your-token"
npm run dev -- run examples/scenarios/github-get-me.json \
  --target examples/targets/github-http.json

GitLab доступен через его stdio-мост с поддержкой OAuth:

npm run dev -- run examples/scenarios/gitlab-search-projects.json \
  --target examples/targets/gitlab-stdio.json

Первое соединение может открыть браузер для авторизации в GitLab. См. руководство по внешним целям для GitLab и различия между OAuth GitLab и аутентификацией GitHub-токена.

Контракт адаптера целевого клиента

Общий контракт адаптера управляет оркестрацией внешних целей, а детерминированный тестовый адаптер проверяет его жизненный цикл без внешнего ввода/вывода. См. архитектурную документацию для деталей жизненного цикла, владения, тайм-аутов и наблюдений.

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

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

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

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

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

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

• Начало работы
• Сценарии
• Внешние MCP-цели
• Инструменты отказов
• Справка по CLI
• Отчеты
• Архитектура
• Примеры
• Устранение неполадок

Требования

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

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

MCP Failure Lab поддерживает MCP 2026-07-28 и принимает инициализационный поток 2025-11-25 для совместимости. См. Streamable HTTP для деталей протокола и сессий.

Установка

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

npx mcp-failure-lab demo

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

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

npm install -g mcp-failure-lab

CLI

# Запуск встроенной демонстрации
npx mcp-failure-lab demo

# Показать помощь по командам
npx mcp-failure-lab --help

# Показать установленную версию
npx mcp-failure-lab --version

# Запуск MCP-сервера через stdio
npx mcp-failure-lab serve

# Запуск Streamable HTTP со значениями по умолчанию для локальной безопасности
npx mcp-failure-lab serve --transport http

# Явно переопределить HTTP-эндпоинт
npx mcp-failure-lab serve --transport http --host localhost --port 4000 --path /mcp

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

Streamable HTTP по умолчанию слушает на http://127.0.0.1:3000/mcp. Сервер валидирует путь запроса, а также заголовки Host и Origin. Привязка к другому хосту — явный выбор; этот режим не обеспечивает аутентификацию или TLS, поэтому не рекомендуется открывать его в ненадёжной сети. При необходимости удалённого доступа поместите аутентификацию и TLS-терминацию в надёжную фронтенд-стойку.

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

Файлы сценариев используют 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

Сгенерировать JUnit XML для CI-систем:

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

Код выполнения возвращает:

Код	Значение
0	Все ожидания выполнены успешно
1	Не удалось загрузить или выполнить сценарий
2	Одно или несколько утверждений не выполнены

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

Инструменты отказов

Инструмент	Поведение
ping	Возвращает детерминированный ответ о состоянии здоровья
delay	Ожидание ограниченного времени перед возвратом
hang	Остаётся зависшим до отмены со стороны клиента
disconnect	Прерывает активный транспорт во время выполнения запроса

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

Осмотр сервера

Запустите официальный MCP Inspector веб-интерфейс против опубликованного пакета:

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

См. руководство по внешним MCP-целям для полного рабочего процесса тестирования в браузере и руководства по учетным данным.

Валидация внешних интеграций

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

Разработка

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

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