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

通过 stdio 启动内置 MCP 服务器：

npx mcp-failure-lab serve

Related MCP server: mcp-chaos-rig

目的

MCP Failure Lab 帮助服务器作者以确定性的方式复现延迟、挂起工具、取消和传输丢失。

它提供受控的故障行为，用于测试超时处理、取消清理、传输丢失恢复、断言和 CI 结果。

当前范围

MCP Failure Lab 通过命令行针对其内置的 MCP 服务器运行确定性 JSON 场景。

当前可用：

• ping、delay、hang 和 disconnect 工具

• 通过 stdio 进行 MCP 通信

• 代码优先和 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 服务器使用 SDK v2 时代感知的 stdio 入口点，其内置场景客户端固定使用 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

命令行

# 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。

不要分享或提交 Inspector URL 中包含的临时认证令牌。

外部集成验证

MCP Failure Lab 已通过使用独立 Python MCP 客户端的 Future AGI 模拟进行了独立验证。该实验通过 stdio 调用了真实的 hang 工具，并在评估模拟代理响应之前应用了客户端超时。

这是一个外部验证示例，不是官方的 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

在提交拉取请求之前，运行：

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

有关贡献流程，请参阅 CONTRIBUTING.md。

路线图

计划中的工作跟踪在 GitHub Issues 中。

除非明确记录为可用，否则路线图项目不属于当前实现的一部分。

许可证

MIT