MCP Failure Lab

Name: MCP Failure Lab
Author: cloudlabworks

本地服务

github.com开发工具01 周前更新

代码仓库访问官网

关于 MCP Failure Lab

MCP Failure Lab 是一个故意制造故障的 MCP 服务及有限重试的参考客户端测试框架，用于测试工具错误恢复和断连处理。它以确定性场景运行，不使用 LLM 或下游服务。

主要功能

01六种确定性故障模式
02带有限重试的参考客户端
03生成 JSON 结果和消息轨迹
04基于 Docker 的隔离测试
05可配置延迟和失败次数
06验证发布来源证明

适用场景

01测试客户端对工具错误的处理
02检查瞬时故障后的恢复
03观察超时和断连行为
04为 Agent Trace Clinic 生成轨迹

MCP 相关

该项目基于官方 TypeScript SDK 实现 MCP 服务，在注入故障的场景中提供 `lab_probe` 工具。它还包含有限重试的参考客户端；当前服务通过 stdio 传输。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudlabworks-mcp-failure-lab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "LAB_SCENARIO",
        "-e",
        "LAB_DELAY_MS",
        "-e",
        "LAB_FAILURES",
        "ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2"
      ],
      "env": {
        "LAB_SCENARIO": "<LAB_SCENARIO>",
        "LAB_DELAY_MS": "<LAB_DELAY_MS>",
        "LAB_FAILURES": "<LAB_FAILURES>"
      }
    }
  }
}

启动命令docker run -i --rm -e LAB_SCENARIO -e LAB_DELAY_MS -e LAB_FAILURES ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2

需要配置的环境变量

LAB_SCENARIOFault to inject: healthy, tool-error, transient-error, delay, malformed, or disconnect

LAB_DELAY_MSDelay in milliseconds for the delay scenario (0 to 10000)

LAB_FAILURESFailing calls before success for the transient-error scenario (0 to 10)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

ocighcr.io/cloudlabworks/mcp-failure-lab:0.1.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

MCP Failure Lab

一个经过刻意设置、带有故障的 MCP 服务，以及一个有界的参考客户端测试框架。 v0.1.0，MIT。基于官方 MCP TypeScript SDK 2.3.1 构建，并非替代协议实现。

试用

需要 Docker。镜像使用 Node 24 和锁定版本的 npm 依赖项。

docker build -t mcp-failure-lab:local .
docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges mcp-failure-lab:local npm test
docker run --rm --network none --read-only --cap-drop ALL --security-opt no-new-privileges mcp-failure-lab:local node runner.mjs

最后一条命令会输出 JSON 结果，以及来自七次确定性运行的 OpenAI 消息格式轨迹。整个过程不涉及大模型。计时数据是实际经过的毫秒数，并非基准测试结果。测试命令在回归时会以非零状态码退出；演示命令只会输出观察结果，不会给出评判结论。

本地开发：运行 npm ci --ignore-scripts，然后运行 npm test。

使用已发布的镜像（官方 MCP Registry：io.github.cloudlabworks/mcp-failure-lab）：

docker run -i --rm -e LAB_SCENARIO=tool-error ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2

验证发布版本

从 v0.1.2 开始，每个发布版本都会由 publish-mcp 工作流通过 Sigstore 签署构建来源证明。使用 GitHub CLI：

gh attestation verify oci://ghcr.io/cloudlabworks/mcp-failure-lab:0.1.2 --repo cloudlabworks/mcp-failure-lab
gh attestation verify mcp-failure-lab-0.1.2.tar.gz --repo cloudlabworks/mcp-failure-lab

第二条命令会检查 GitHub Release 中的源代码压缩包。若要离线验证，请添加 --bundle mcp-failure-lab-0.1.2.tar.gz.intoto.jsonl（附在同一发布版本中的来源证明文件）。

故障

LAB_SCENARIO	注入的行为	参考客户端预期
healthy	正常的工具响应	一次成功
tool-error	返回有效结果，且 isError=true	达到配置的尝试次数上限后停止
transient-error	前 LAB_FAILURES 次调用失败	若尝试次数上限允许，则恢复
delay	工具响应前等待 LAB_DELAY_MS	在截止时间内成功，或超时
malformed	JSON-RPC 信封有效，文本块值无效	拒绝该工具结果
disconnect	工具响应期间退出	报告连接已关闭，而非成功

只有公布的 lab_probe 工具会受到影响。初始化和发现使用官方 SDK。传输包装器会破坏结果结构，而非 JSON 帧；不实现截断帧、错误 ID、HTTP 故障和身份验证故障。

配置在进程启动时读取。场景按进程重置。 LAB_DELAY_MS：整数 0–10000（默认值为 1000）。 LAB_FAILURES：整数 0–10（默认值为 2）。值必须是纯十进制数字；未设置或为空的变量会使用默认值，其他任何值（0x10、1e3、 7）都会导致服务以退出码 2 停止。参考客户端只会重试明确的工具错误，最多尝试五次；协议错误、超时和断连都会立即停止。测试框架的工具调用截止时间为 10–10000 毫秒；SDK 连接和发现的截止时间则单独设置。重试有意不设置退避，以便生成的测试样例呈现重复调用；不建议在生产环境中采用这种重试策略。

接入你自己的 MCP 客户端

配置一个测试用 MCP 连接来运行此命令，并连接标准输入/标准输出：

docker run --rm -i --network none --read-only --cap-drop ALL --security-opt no-new-privileges -e LAB_SCENARIO=transient-error -e LAB_FAILURES=2 mcp-failure-lab:local

使用 {"message":"probe"} 调用 lab_probe。这里没有真实的下游服务、凭据、文件写入工具或监听网络端口。除内置参考客户端外，其他客户端集成均未经验证。

将故障输入 Agent Trace Clinic

在此仓库中，与 Clinic 并排检出：

mkdir -p artifacts
docker run --rm --network none --read-only mcp-failure-lab:local node runner.mjs > artifacts/run.json
node --input-type=module -e 'import fs from "node:fs"; const r=JSON.parse(fs.readFileSync("artifacts/run.json","utf8")); console.log(JSON.stringify(r.results.find(x=>x.scenario==="tool-error").trace));' > artifacts/tool-error.json
node ../agent-trace-clinic/cli.mjs artifacts/tool-error.json --html > artifacts/clinic-report.html

Clinic 应能在此测试样例中识别出 tool_loop、retry_storm 和 unhandled_tool_error。这些只是启发式线索：刻意设置的有界重试也可能触发它们。不会虚构令牌数量。

与上游的关系

MCP 一致性是协议测试的上游权威。本项目为恢复实验提供少量故障场景；不声称获得一致性认证。官方框架目前记录了基于 HTTP 的客户端/服务端场景运行器。首个版本仅支持 stdio；上游场景适配器和 Streamable HTTP 目标是后续计划，并非已发布功能。

核对来源的日期：2026-10-14：

维护约定

一种传输方式、一个工具、六种故障模式、一个参考客户端。锁定 SDK 升级版本，并重新运行每项故障测试。负责人：Cloud Lab Works / Waku。尚未分配或完成 Gherkin 审核。公开发布前：源代码/依赖项审核、独立测试，以及发布审批。云端执行前：设定有界的作业预算、拆除流程，并测量运行时间。本版本无需云账户。不收集遥测数据，也不进行远程报告。生成的报告保留在被忽略的 artifacts/ 中。

Agent Reliability Lab

打开公开演示，或阅读实验指南。四个受控的前后对比案例将官方 MCP 参考客户端连接到确定性的 Clinic 检查。公开样例是记录在本地的证据，并非实时云端执行。云适配器和运行手册已包含在内。

引用

如果您使用本项目，请引用随附的预印本： MCP Failure Lab: Reproducible Tool-Failure Fixtures and Cross-Platform Traces for Testing Agent Reliability。DOI：10.5281/zenodo.23720942。摘要和 PDF 请参阅论文页面。

@techreport{alvord2026mcp,
  author = {Alvord, Alex},
  title = {{MCP Failure Lab: Reproducible Tool-Failure Fixtures and Cross-Platform Traces for Testing Agent Reliability}},
  institution = {CloudLab Works},
  publisher = {Zenodo},
  year = {2026},
  month = oct,
  type = {Preprint},
  doi = {10.5281/zenodo.23720942},
  url = {https://doi.org/10.5281/zenodo.23720942}
}

支持 Markdown

登录后评论