mcp-failure-lab

MCP Failure Lab

通过可重复的测试和 CI 报告，重现 MCP 超时、取消竞态、传输中断和无效响应。

文档 · 兼容性 · 项目页面

示例输出（时长会有所不同）：

$ 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

为什么要做这个项目

MCP 客户端在遇到故障时的表现各不相同。超时后，连接可能仍可用；响应中断则可能导致连接关闭。某个客户端可能会拒绝格式错误的回复，另一个客户端却可能接受。

Failure Lab 让这些情况可以重复复现，以便你检查失败的调用以及后续会发生什么。

实际案例

• Python SDK #3522：Python mcp 2.2.0 在 HTTP 响应中断后保持关闭状态，拒绝了下一个请求，并在清理时引发 ExceptionGroup。
• Rust SDK #1283：rmcp 3.4.0 通过 stdio 和 HTTP 接受了同时包含 result 和 error 的无效响应。
• Ruby SDK #589：在全部三次重复测试中，mcp 1.6.1 通过 stdio 和 HTTP 接受了缺少 jsonrpc 或声明 jsonrpc: "1.0" 的响应。Ruby 报告记录了全部 60 次执行；结果和上游发现已包含在 Observatory 导出中。
• Java SDK 2.0.1 通过两种传输方式接受了 jsonrpc: "1.0"（#1156）。通过 stdio 传输时，缺少 jsonrpc 或同时包含 result 和 error 的响应会导致后续 ping 超时（#1157）。请参阅 Java 报告。
• 重复响应对比：所有五个受测 SDK 都完成了后续 ping。TypeScript 通过错误回调报告了重复响应；其他测试框架均未在调用级别显示重复错误。

SDK 对比描述的是经过测试的特定版本，并不代表所有发行版。 有关复现步骤和限制，请参阅分版本报告。

快速开始

需要 Node.js 22.23.4 或更高版本以及 npm。

npx mcp-failure-lab demo

此演示无需 API 密钥、外部服务或全局安装。要测试自己的 MCP 客户端，请通过 stdio 或本地 Streamable HTTP 连接到 Failure Lab：

npx mcp-failure-lab serve
# Or:
npx mcp-failure-lab serve --transport http

stdio 进程会等待客户端连接；它不是交互式终端命令。请配置客户端以启动该进程，或参阅入门指南。 手动启动的服务可按 Ctrl+C 停止。

HTTP 默认地址为 http://127.0.0.1:3000/mcp。它既不提供身份验证，也不提供 TLS； 请勿将其暴露给不受信任的网络。

测试自己的 MCP 服务

外部目标支持 HTTP 和 stdio。完成仓库设置后， 安装官方 GitHub MCP 服务，并确保其可执行文件位于 PATH 中，然后在环境中设置 GITHUB_PERSONAL_ACCESS_TOKEN。接着运行：

npm run dev -- run examples/scenarios/github-get-me.json \
  --target examples/targets/github-stdio.json

此示例调用 GitHub 只读的 get_me 工具。其目标配置使用 envFrom 从环境中传递令牌，而不是将令牌存储在 JSON 中。 对于自己的场景和 目标配置，请使用：

npx mcp-failure-lab run scenario.json --target target.json

外部运行会检查工具结果、截止时间以及适配器的设置和清理。 它们不会向其他服务注入故障；Failure Lab 不是代理。

请参阅外部目标指南，了解先决条件、凭据处理和配置。

Failure Lab 可以破坏哪些行为

内置服务提供以下工具，用于测试客户端行为：

工具	行为
ping	返回确定性的健康状态响应
protocol_ping_liveness	在调用进行期间发送有界的协议 ping
delay	等待一段有界时长后再返回
hang	保持挂起，直到客户端取消
disconnect	在请求进行期间中断活动传输
malformed_message	恰好一次违反一条选定的 JSON-RPC 响应规则
duplicate_response	针对一个请求发送两次相同的 JSON-RPC 响应
response_after_cancellation	针对已取消的 stdio 请求发送一条迟到的响应
session_loss	使调用方的旧版 HTTP 会话失效
oversized_response	返回确定性的文本负载，最大为 256 KiB
invalid_progress	发送未知、递减或迟到的进度通知

协议 ping 与 ping 工具不同。内置场景默认使用 MCP 2026-07-28； 协议存活检测要求场景设置 protocolVersion: "2025-11-25"。 两个公共传输都接受旧版客户端。

有关时间限制、激活、取消、清理和传输限制，请参阅故障工具参考。

oversized_response 接受 0 到 262,144 之间的 sizeBytes。它只生成 ASCII x 字符，因此文本大小在 UTF-8 字节中是精确的，且不包含外部数据。stdio 和 HTTP 均适用此上限。选择一个低于客户端配置响应限制的大小以检查是否成功， 然后选择一个高于该限制（但不超过 262,144）的大小以检查客户端是否拒绝。 随附的 64 KiB 场景会检查返回文本的确切大小以及后续请求。 JSON-RPC 和传输封装会在文本周围增加字节，因此客户端的整条消息限制可能会在 sizeBytes 达到阈值之前触发。 集成测试确认，消息限制为 4 KiB 的 stdio 客户端会接受 1 KiB 负载并拒绝 8 KiB 负载。

invalid_progress 要求客户端提供进度令牌，并接受 unknown-token、 regressing-progress 或 after-completion。这些是与一次工具调用相关的协议通知，不是工具结果内容。未知令牌变体会发送一条带有不同令牌的通知。递减变体会先发送进度 2，再发送 1。迟到变体会在 stdio 上的匹配响应之后或 HTTP 响应流中发送一条通知。 这些变体分别违反了请求令牌关联、进度单调性和已完成请求生命周期规则。 每种变体都有次数限制，且只会被触发一次。请参阅 递减、 未知令牌和 完成后场景。 内置运行器可以使用 expect.progressValues 断言回调值； 外部目标适配器不会报告进度通知，因此无法使用此断言。

恢复测试的工作原理

触发故障并记录结果，然后在同一连接上发送第二个请求。 检测到故障并不能证明已恢复；后续请求也必须成功。

主要调用完成后（包括出错或超时的情况），都会运行场景中的 observe 调用。 例如，duplicate-response.json 会调用 duplicate_response，然后使用 ping 检查连接是否仍可用：

# From a repository checkout
npm run dev -- run examples/scenarios/duplicate-response.json

这检查的是故障发生后的行为，而非自动恢复策略。 stdio 断开会终止服务进程，因此需要启动新进程并建立新连接。

有关结果、持续时间、返回值和观察器断言，请参阅场景。

SDK / 传输证据

MCP Failure Observatory 收集 SDK 和传输证据。 仓库报告记录了经过测试的版本、方法和限制。

结果因 SDK、版本、传输方式和协议而异。一次通过的运行结果只能证明该组合可用， 并不能保证适用于所有客户端。

在 CI 中使用

保存一个包含明确预期和超时设置的场景文件， 然后生成 JUnit 报告：

npx mcp-failure-lab run scenario.json --report junit > junit.xml

在 CI 中固定 Failure Lab 软件包的版本，避免升级意外改变测试环境。

退出代码：0 表示符合预期，1 表示无法加载或执行场景， 2 表示断言失败。预期中的超时可以通过测试；意外成功则可能导致测试失败。

有关 JSON、JUnit 和生命周期诊断的信息，请参阅报告。

文档

详细指南请参阅 mcplab.dev： 快速入门 · CLI · 架构 · 故障排除。

贡献

有关设置、测试和贡献工作流，请参阅 CONTRIBUTING.md。 计划中的工作记录在 GitHub Issues 中。

如果 Failure Lab 能帮助你测试 MCP 集成，不妨为仓库点个星。

许可证

MIT