Skip to main content
Glama

MCP Failure Lab

npm version CI

面向 Model Context Protocol 服务器的混沌工程与韧性测试工具包。

文档 · 项目页面

MCP Failure Lab 演示有界延迟和预期超时

快速开始

无需克隆仓库或全局安装包,即可运行一个真实的确定性延迟场景:

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 获取。

环境要求

  • 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

命令退出码:

代码

含义

0

所有预期均通过

1

场景无法加载或执行

2

一个或多个断言失败

有关结果断言、观察者调用、报告格式和超时行为,请参阅场景和报告文档。

故障工具

工具

行为

ping

返回确定性的健康响应

delay

在返回前等待有界时长

hang

保持挂起状态,直到客户端取消

disconnect

在请求进行中中断活动传输

有关参数和行为,请参阅故障工具参考。

检查服务器

针对已发布的包启动 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

Available Tools

10 tools
delayA

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

    B3.3/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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).

    Tool Count5/5

    Ten tools is well-scoped for a failure-injection lab. Each tool represents a distinct test scenario and none feels redundant or excessive.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive reference implementation demonstrating all features of the Model Context Protocol (MCP) specification, serving as documentation, learning resource, and testing tool for MCP implementations.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 npm
      10
      MIT