MCP Failure Lab

Un kit de herramientas de ingeniería del caos y pruebas de resiliencia para servidores de Model Context Protocol.

Documentación · Página del proyecto

Inicio rápido

Ejecuta un escenario de retraso determinista real sin clonar el repositorio ni instalar el paquete globalmente:

npx mcp-failure-lab demo

Salida de ejemplo:

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

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

La duración exacta puede variar ligeramente entre ejecuciones. No se requiere clave API ni servidor MCP externo.

Muestra los comandos disponibles:

npx mcp-failure-lab --help

Inicia el servidor MCP integrado a través de stdio:

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

Propósito

MCP Failure Lab ayuda a los autores de servidores a reproducir retrasos, herramientas colgadas, cancelaciones y pérdida de transporte de forma determinista.

Proporciona un comportamiento de fallo controlado para probar el manejo de tiempos de espera, la limpieza de cancelaciones, la recuperación de pérdida de transporte, las aserciones y los resultados de CI.

Alcance actual

MCP Failure Lab ejecuta escenarios JSON deterministas contra su propio servidor MCP integrado desde la línea de comandos.

Disponible ahora:

• Herramientas ping, delay, hang y disconnect

• Comunicación MCP a través de stdio

• Definiciones de escenarios code-first y JSON

• Aserciones de resultado y duración máxima

• Aserciones de resultados MCP

• Llamadas secuenciales de observador para verificación de postcondiciones

• Informes en consola y JSON

• Errores de comando legibles por máquina

• Códigos de salida compatibles con CI

• Pruebas unitarias, de integración y de extremo a extremo

No implementado:

• Orquestación de clientes MCP externos

• Adaptadores de cliente objetivo

• Streamable HTTP

• Informes JUnit

• Faltas de mensajes malformados, respuestas duplicadas y pérdida de sesión

MCP Failure Lab no es actualmente un proxy de propósito general ni un orquestador de pruebas de clientes MCP externos.

Cómo funciona

MCP Failure Lab ejecuta escenarios deterministas a través de su cliente y servidor MCP integrados. Un escenario invoca ping, delay, hang o disconnect, registra el resultado y la duración observados, y evalúa las expectativas declaradas.

Las llamadas opcionales de observador se ejecutan secuencialmente en la misma conexión de cliente MCP para verificar las postcondiciones a través de una ruta de herramienta separada.

Consulta la documentación de arquitectura para ver diagramas, responsabilidades y límites de implementación.

Documentación

Guías completas y referencias disponibles en mcplab.dev/docs.

• Primeros pasos

• Escenarios

• Herramientas de fallo

• Referencia de CLI

• Informes

• Arquitectura

• Ejemplos

• Solución de problemas

Requisitos

• Node.js 22.19.0 o superior

• npm

Compatibilidad de protocolo

MCP Failure Lab apunta a MCP 2026-07-28 por defecto. Su servidor CLI utiliza el punto de entrada stdio consciente de la era del SDK v2, y su cliente de escenarios integrado fija 2026-07-28 para que el comportamiento moderno se ejercite explícitamente.

El servidor también acepta el flujo de inicialización 2025-11-25 por compatibilidad. Esa ruta heredada sigue cubierta por pruebas de integración, pero el nuevo desarrollo apunta a 2026-07-28. Las herramientas de fallo existentes ping, delay, hang y disconnect tienen el mismo comportamiento visible para el usuario en ambas eras; las características del protocolo que dependen de solicitudes iniciadas por el servidor difieren entre eras y quedan fuera de estas herramientas de fallo.

Instalación

Ejecuta el paquete directamente con npx:

npx mcp-failure-lab demo

No se requiere instalación global.

Para instalar el comando globalmente:

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

El proceso serve espera a un cliente MCP. Pulsa Ctrl+C para cerrarlo correctamente.

Ejecutar un escenario

Los archivos de escenario usan JSON:

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

Desde una copia del repositorio, ejecuta el escenario incluido:

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

Genera una salida legible por máquina:

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

El comando sale con:

Para aserciones de resultados, llamadas de observador, formatos de informes y comportamiento de tiempo de espera, consulta la documentación de escenarios y informes.

Herramientas de fallo

Consulta la referencia de herramientas de fallo para ver argumentos y comportamiento.

Inspeccionar el servidor

Lanza MCP Inspector contra el paquete publicado:

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

Conéctate a través de stdio, lista las herramientas disponibles e invoca ping, delay, hang o disconnect.

No compartas ni confirmes tokens de autenticación temporales incluidos en las URL de Inspector.

Validación de integración externa

MCP Failure Lab fue validado de forma independiente con una simulación de Future AGI utilizando un cliente MCP Python independiente. El experimento invocó la herramienta real hang a través de stdio y aplicó un tiempo de espera del lado del cliente antes de evaluar las respuestas simuladas del agente.

Este es un ejemplo de validación externa, no una integración o respaldo oficial de Future AGI.

Consulta el ejemplo de Future AGI para ver resultados y pasos de reproducción.

Desarrollo

Clona el repositorio e instala sus dependencias:

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

Ejecuta la CLI de desarrollo:

npm run dev -- --help

Antes de abrir una solicitud de extracción, ejecuta:

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

Consulta CONTRIBUTING.md para el flujo de trabajo de contribución.

Hoja de ruta

El trabajo planificado se rastrea en GitHub Issues.

Los elementos de la hoja de ruta no forman parte de la implementación actual a menos que se documenten explícitamente como disponibles.

Licencia

MIT