{ "markdown": "# MCP Failure Lab\n\n

\n \n \n \n \"MCP\n \n

\n\n[![npm version](https://img.shields.io/npm/v/mcp-failure-lab)](https://www.npmjs.com/package/mcp-failure-lab)\n[![CI](https://github.com/anilloutombam/mcp-failure-lab/actions/workflows/ci.yml/badge.svg)](https://github.com/anilloutombam/mcp-failure-lab/actions/workflows/ci.yml)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-Official-blue)](https://registry.modelcontextprotocol.io/)\n[![GitHub MCP Registry](https://img.shields.io/badge/GitHub_MCP_Registry-Listed-181717?logo=github)](https://github.com/mcp/anilloutombam/mcp-failure-lab)\n\nA chaos-engineering and resilience-testing toolkit for Model Context Protocol servers.\n\n[Documentation](https://mcplab.dev/docs/) ·\n[Project page](https://mcplab.dev/failure)\n\n![MCP Failure Lab demonstrating a bounded delay and an expected timeout](docs/demo.gif)\n\n## Quick start\n\nRun a real deterministic delay scenario without cloning the repository or installing the package globally:\n\n```bash\nnpx mcp-failure-lab demo\n```\n\nExample output:\n\n```text\nMCP Failure Lab — Demo\nRunning a real 500ms delay scenario...\n\nScenario: Deterministic delay demo\nOutcome: success\nDuration: ~500 ms\nAssertions: passed\n```\n\nThe exact duration may vary slightly between runs. No API key or external MCP server is required.\n\nDisplay the available commands:\n\n```bash\nnpx mcp-failure-lab --help\n```\n\nStart the built-in MCP server over stdio:\n\n```bash\nnpx mcp-failure-lab serve\n```\n\nOr start a local Streamable HTTP endpoint:\n\n```bash\nnpx mcp-failure-lab serve --transport http\n```\n\n## Purpose\n\nMCP Failure Lab helps server authors reproduce delays, hanging tools, cancellation, and transport loss in a deterministic way.\n\nIt provides controlled failure behavior for testing timeout handling, cancellation cleanup, transport-loss recovery, assertions, and CI outcomes.\n\n## Current scope\n\nMCP Failure Lab runs deterministic JSON scenarios against its built-in server or a configured\nexternal HTTP or stdio MCP target from the command line.\n\nAvailable now:\n\n- `ping`, `delay`, `hang`, and `disconnect` tools\n- MCP communication over stdio and Streamable HTTP\n- Code-first and JSON scenario definitions\n- Outcome and maximum-duration assertions\n- MCP result assertions\n- Sequential observer calls for post-condition verification\n- External MCP target orchestration through a validated adapter registry\n- Streamable HTTP and stdio target configurations\n- Bounded adapter setup, execution, observation, cancellation, and cleanup\n- Separate scenario-assertion and adapter-lifecycle diagnostics\n- Console and JSON reporting\n- Machine-readable command errors\n- CI-friendly exit codes\n- Unit, integration, and end-to-end tests\n\nNot implemented:\n\n- Provider-specific adapters and recovery policies\n- JUnit reporting\n- Malformed-message, duplicate-response, and session-loss faults\n\nMCP Failure Lab is not a general-purpose proxy. External targets are exercised through the same\nscenario calls and expectations as the built-in server.\n\n## Run against another MCP server\n\nPass a target configuration to execute the same scenario against a Streamable HTTP or stdio MCP\nserver:\n\n```bash\n# From a repository checkout\nnpm run dev -- run path/to/scenario.json --target path/to/target.json\n\n# With the published package and your own scenario and target files\nnpx mcp-failure-lab run path/to/scenario.json --target path/to/target.json\n```\n\nSee the [external MCP targets guide](https://mcplab.dev/docs/external-targets/) for complete HTTP\nand stdio configuration, verified GitHub and GitLab workflows, browser-based MCP Inspector\nvalidation, lifecycle diagnostics, credential handling, and troubleshooting.\n\nThe repository also includes a safe, read-only GitHub MCP example using the official remote server:\n\n```bash\nexport GITHUB_MCP_AUTHORIZATION=\"Bearer your-token\"\nnpm run dev -- run examples/scenarios/github-get-me.json \\\n --target examples/targets/github-http.json\n```\n\nGitLab is available through its OAuth-capable stdio bridge:\n\n```bash\nnpm run dev -- run examples/scenarios/gitlab-search-projects.json \\\n --target examples/targets/gitlab-stdio.json\n```\n\nThe first connection can open a browser for GitLab authorization. See the external-target guide\nfor GitLab prerequisites and the difference between GitLab OAuth and GitHub token authentication.\n\n## Target-client adapter contract\n\nThe generic adapter contract drives external-target orchestration, and the deterministic test\nadapter verifies its lifecycle without external I/O. See the\n[architecture documentation](https://mcplab.dev/docs/architecture/#target-client-adapter-boundary)\nfor lifecycle, ownership, timeout, and observation details.\n\n## How it works\n\nMCP Failure Lab runs deterministic scenarios through its built-in MCP client and server or through\na configured external HTTP or stdio target. A scenario invokes a tool, records the observed outcome\nand duration, and evaluates the declared expectations. Built-in scenarios use `ping`, `delay`,\n`hang`, or `disconnect`; external scenarios use tools exposed by their target server.\n\nOptional observer calls run sequentially on the same MCP client connection to verify post-conditions through a separate tool path.\n\nSee the [architecture documentation](https://mcplab.dev/docs/architecture/) for diagrams, responsibilities, and implementation boundaries.\n\n## Documentation\n\nFull guides and references are available at [mcplab.dev/docs](https://mcplab.dev/docs/).\n\n- [Getting started](https://mcplab.dev/docs/getting-started/)\n- [Scenarios](https://mcplab.dev/docs/scenarios/)\n- [External MCP targets](https://mcplab.dev/docs/external-targets/)\n- [Fault tools](https://mcplab.dev/docs/fault-tools/)\n- [CLI reference](https://mcplab.dev/docs/cli/)\n- [Reporting](https://mcplab.dev/docs/reporting/)\n- [Architecture](https://mcplab.dev/docs/architecture/)\n- [Examples](https://mcplab.dev/docs/examples/)\n- [Troubleshooting](https://mcplab.dev/docs/troubleshooting/)\n\n## Requirements\n\n- Node.js 22.19.0 or newer\n- npm\n\n## Protocol compatibility\n\nMCP Failure Lab targets MCP `2026-07-28` and accepts the `2025-11-25` initialization flow for\ncompatibility. See [Streamable HTTP](https://mcplab.dev/docs/streamable-http/) for protocol and\nsession details.\n\n## Installation\n\nRun the package directly with `npx`:\n\n```bash\nnpx mcp-failure-lab demo\n```\n\nNo global installation is required.\n\nTo install the command globally:\n\n```bash\nnpm install -g mcp-failure-lab\n```\n\n## CLI\n\n```bash\n# Run the built-in demonstration\nnpx mcp-failure-lab demo\n\n# Display command help\nnpx mcp-failure-lab --help\n\n# Display the installed version\nnpx mcp-failure-lab --version\n\n# Start the MCP server over stdio\nnpx mcp-failure-lab serve\n\n# Start Streamable HTTP with local-safe defaults\nnpx mcp-failure-lab serve --transport http\n\n# Override the HTTP endpoint explicitly\nnpx mcp-failure-lab serve --transport http --host localhost --port 4000 --path /mcp\n```\n\nThe `serve` process waits for an MCP client. Press `Ctrl+C` to shut it down gracefully.\n\nStreamable HTTP listens on `http://127.0.0.1:3000/mcp` by default. The server validates\nthe request path plus `Host` and `Origin` headers. Binding another host is an explicit\nchoice; this mode does not provide authentication or TLS, so do not expose it to an\nuntrusted network. Put authentication and TLS termination in a trusted front end if\nremote access is required.\n\n## Run a scenario\n\nScenario files use JSON:\n\n```json\n{\n \"name\": \"bounded delay succeeds\",\n \"call\": {\n \"tool\": \"delay\",\n \"args\": {\n \"delayMs\": 250\n }\n },\n \"timeoutMs\": 1000,\n \"expect\": {\n \"outcome\": \"success\",\n \"maxDurationMs\": 500\n }\n}\n```\n\nFrom a repository checkout, run the included scenario:\n\n```bash\nnpm run dev -- run examples/scenarios/delay-success.json\n```\n\nGenerate machine-readable output:\n\n```bash\nnpm run dev -- run examples/scenarios/delay-success.json --report json\n```\n\nThe command exits with:\n\n| Code | Meaning |\n| ---: | -------------------------------------------- |\n| `0` | All expectations passed |\n| `1` | The scenario could not be loaded or executed |\n| `2` | One or more assertions failed |\n\nFor result assertions, observer calls, reporting formats, and timeout behavior, see the [scenario](https://mcplab.dev/docs/scenarios/) and [reporting](https://mcplab.dev/docs/reporting/) documentation.\n\n## Fault tools\n\n| Tool | Behavior |\n| ------------ | ------------------------------------------------------------ |\n| `ping` | Returns a deterministic health response |\n| `delay` | Waits for a bounded duration before returning |\n| `hang` | Remains pending until the client cancels |\n| `disconnect` | Interrupts the active transport while a request is in flight |\n\nSee the [fault tools reference](https://mcplab.dev/docs/fault-tools/) for arguments and behavior.\n\n## Inspect the server\n\nLaunch the official MCP Inspector web UI against the published package:\n\n```bash\nnpx @modelcontextprotocol/inspector npx mcp-failure-lab serve\n```\n\nSee [External MCP targets](https://mcplab.dev/docs/external-targets/#validate-the-connection-in-a-browser)\nfor the complete browser-testing workflow and credential guidance.\n\n## External integration validation\n\nSee the [Future AGI example](https://mcplab.dev/docs/examples/#future-agi-experiment) for an\nindependent Python-client validation of the `hang` fault. It is an external validation example,\nnot an official integration or endorsement.\n\n## Development\n\nClone the repository and install its dependencies:\n\n```bash\ngit clone https://github.com/anilloutombam/mcp-failure-lab.git\ncd mcp-failure-lab\nnpm install\n```\n\nRun the development CLI:\n\n```bash\nnpm run dev -- --help\n```\n\nBefore opening a pull request, run:\n\n```bash\nnpm run format:check\nnpm run typecheck\nnpm test\nnpm run build\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.\n\n## Roadmap\n\nPlanned work is tracked in [GitHub Issues](https://github.com/anilloutombam/mcp-failure-lab/issues).\n\nRoadmap items are not part of the current implementation unless explicitly documented as available.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 10663, "sha": "961a5bdb49f9249c6ac5ff6cfc7b124c45d085fe710ced5f1f27034f1139b5a4", "repo_slug": "anilloutombam/mcp-failure-lab", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_anilloutombam_mcp_failure_lab_c32f297a/readme" }