MCP Failure Lab
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 serveRelated 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 获取。
环境要求
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 serveserve 进程等待 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 中。
除非明确记录为可用,否则路线图项目不属于当前实现的一部分。
许可证
Available Tools
10 toolsdelayA
Delay a successful MCP response to test client timeout behavior.
Inputs: delayMs (required).
disconnectA
Close the MCP transport before this request can receive a response.
Inputs: no named parameters.
duplicate_responseB
Return the same JSON-RPC response twice for this request.
Inputs: no named parameters.
hangB
Never respond unless the MCP request is cancelled.
Inputs: no named parameters.
invalid_progressA
Send one bounded progress-notification fault for this request; requires a client progress token.
Inputs: variant (required).
malformed_messageC
Return one deterministic response that violates a selected JSON-RPC rule.
Inputs: variant (required).
oversized_responseA
Return a deterministic text payload of exactly sizeBytes UTF-8 bytes (maximum 256 KiB).
Inputs: sizeBytes (required).
pingB
Check whether the MCP server is responsive.
Inputs: no named parameters.
protocol_ping_livenessC
Send an MCP protocol ping during this in-flight call and apply a bounded liveness policy.
Inputs: pingAfterMs (required), livenessTimeoutMs (required), closeOnFailure, completionDelayMs.
response_after_cancellationA
Send a response after this call is cancelled (stdio only).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools target clearly distinct failure modes such as delay, disconnect, hang, malformed_message, and duplicate_response. However, ping and protocol_ping_liveness both concern liveness checking and could be confused, keeping this from a perfect score.
All tool names use consistent snake_case and are descriptive. The main deviation is grammatical style: some are bare verbs (delay, disconnect, hang, ping) while others are noun phrases (oversized_response, malformed_message).
Ten tools is well-scoped for a failure-injection lab. Each tool represents a distinct test scenario and none feels redundant or excessive.
The set covers core transport, protocol, timing, and cancellation failure modes, including oversized responses, malformed messages, duplicates, and post-cancellation responses. It lacks explicit injection of JSON-RPC error responses or invalid request IDs, which are common client-handling tests.
Maintenance
Related MCP Connectors
MEOK MCP Test MCP — golden-file + schema-drift + tool-failure tests for any MCP server. Drop-in
MCP server for building and testing AI agents with multi-model experimentation and insights.
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA comprehensive reference implementation demonstrating all features of the Model Context Protocol (MCP) specification, serving as documentation, learning resource, and testing tool for MCP implementations.1MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that breaks on demand, allowing you to test your client against auth failures, disappearing tools, flaky responses, and token expiry from a web UI.10 npm10MIT
- AlicenseBqualityBmaintenanceConformance test harness for Model Context Protocol servers, validating JSON-RPC, transport, capability, schema, and more across multiple spec versions.1269 npmMIT
- FlicenseNot gradedqualityBmaintenanceEnables distributed multi-agent chaos latency injection and fault fuzzing, allowing MCP-compatible clients to inject network faults and retrieve structured execution telemetry.8-