studiomeyer-io/mcp-gauntlet

# mcp-gauntlet **一个用于 [Model Context Protocol](https://modelcontextprotocol.io) 服务器的可靠性 + 安全性工具包。** 两个单二进制 CLI 共享一个快速异步 MCP 客户端核心： | 工具 | 功能 | |------|--------------| | 🔬 **[`mcp-fuzz`](crates/mcp-fuzz)** | 支持 schema 的模糊测试工具。读取每个工具的 `inputSchema` 并向其发送大量恶意/边界/畸形 payload —— 查找 **崩溃**、**挂起**、内部错误和隐式验证漏洞。为 GitHub code scanning 生成 **SARIF** 报告。 | | 🌩️ **[`mcp-storm`](crates/mcp-storm)** | 负载测试工具（“MCP 版 k6”）。驱动 N 个并发 worker 对您的服务器进行测试，报告每个工具的 **p50/p95/p99** 延迟 + 吞吐量，并根据延迟/错误率阈值为 **CI 设置门禁**。 | 两者均使用 Rust 编写：各自为一个静态二进制文件，无需 runtime，可直接放入任何 CI 中。它们通过 **stdio**（子进程）或 **Streamable HTTP** 进行 MCP 通信。 ## 为什么需要 MCP 服务器经常发生 [静默失败](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/2734) 并且迭代迅速。大多数服务器 **没有针对畸形输入进行测试**，也 **没有延迟预算**。`mcp-gauntlet` 让您只需两条命令即可同时实现这两点，并且今天就能接入 CI —— 无需手写任何测试，因为 payload 是根据服务器自身的 schema 生成的。 ## 安装 ``` # 从 crates.io（发布后） cargo install mcp-fuzz mcp-storm # 或从源码 git clone https://github.com/studiomeyer-io/mcp-gauntlet cd mcp-gauntlet && cargo build --release # target/release/{mcp-fuzz,mcp-storm} 中的二进制文件 ``` MSRV：Rust 1.82。 ## `mcp-fuzz` — 在用户之前发现崩溃 ``` # fuzz 一个 stdio server（-- 之后的所有内容为启动命令） mcp-fuzz run --stdio -- node my-server.js # fuzz 远程 HTTP endpoint，为 GitHub code scanning 写入 SARIF mcp-fuzz run --http https://example.com/mcp --sarif findings.sarif # 仅一个 tool，更多 payload，遇任何 HIGH 发现则 CI fail mcp-fuzz run --stdio --tool search --iterations 300 --fail-on high -- ./server ``` 它会建立连接，调用 `tools/list`，并根据 schema 为每个工具生成 payload： - **类型混淆**（在需要数字的地方传入字符串等） - **边界**（空字符串 / 10万字符的字符串，`i64::MAX`，负数，零，巨大的浮点数） - **注入**（路径遍历、SQLi、命令/模板/格式化字符串注入、prompt 注入、CRLF、NUL 字节、RTL/零宽 Unicode）—— 仅作为 *数据* 发送，绝不执行 - **缺少必填字段**，**`arguments` 类型错误**，**深层嵌套** 结果会被分类：连接断开 ⇒ **崩溃** (HIGH)，超时 ⇒ **挂起** (HIGH)，`-32603` ⇒ **内部错误** (MEDIUM)，在 schema 无效的输入上执行成功 ⇒ **接受无效输入** (LOW)。正常的 `-32602 invalid params` 会被视为服务器 *正确* 进行了验证 —— 不算作发现。 测试运行可复现（`--seed`）。发生崩溃后，模糊测试工具会重启服务器并继续测试；如果服务器无法恢复，它会记录一次该情况并干净地停止，而不是将后续的每个 payload 都归咎于最初的崩溃。 ``` mcp-fuzz report ─────────────── server my-server (protocol 2025-11-25) tools 7 payloads sent 412 findings 2 total — 1 high, 0 medium, 1 low, 0 info Findings (worst first): [HIGH ] crash search::server crashed on field 'query': null-byte stderr tail: thread 'main' panicked at 'invalid utf-8 ...' [LOW ] accepted-invalid search::schema-invalid input accepted without error: missing required field 'query' ``` ### 在 CI 中使用（GitHub code scanning） ``` - run: mcp-fuzz run --stdio --sarif mcp.sarif --fail-on high -- node server.js - uses: github/codeql-action/upload-sarif@v3 if: always() with: { sarif_file: mcp.sarif } ``` ## `mcp-storm` — 了解您的延迟预算 ``` # 使用 16 个 worker 对一个 stdio server 运行 30 秒 mcp-storm run --stdio --concurrency 16 --duration-secs 30 -- node my-server.js # 针对固定请求数量的 HTTP，基于 p95 + error rate 门控 CI mcp-storm run --http https://example.com/mcp --requests 5000 \ --threshold-p95-ms 250 --max-error-rate 1.0 ``` ``` mcp-storm report ──────────────── server my-server (protocol 2025-11-25) workers 16 duration 30.00s requests 48213 (3 errors, 0.01% error rate) throughput 1607 req/s tool calls err% p50ms p95ms p99ms maxms req/s ────────────────────────────────────────────────────────────────────────────────────── search 31044 0.01% 6.20 14.80 31.10 102.40 1035 fetch 17169 0.00% 9.10 22.30 58.70 210.00 572 ``` 在 stdio 模式下，并发是真实的：请求通过单个管道进行多路复用，并由 JSON-RPC id 进行解复用，因此 N 个 worker 是真正重叠执行的。`--threshold-p95-ms` / `--max-error-rate` 参数使其在超出预算时以非零状态码退出 —— 可以直接将其放入 CI 门禁中。使用 `--warmup-secs` 来排除冷启动的影响。 ## 工作区结构 ``` mcp-gauntlet/ ├── crates/mcp-gauntlet-core # shared async MCP client (stdio + HTTP), schema gen, mock server ├── crates/mcp-fuzz # the fuzzer CLI └── crates/mcp-storm # the load tester CLI ``` `mcp-gauntlet-core` 也已发布 —— 它是一个小巧且支持并发的 MCP 客户端，您可以独立使用，它包含一个基于 schema 的值/突变生成器以及一个进程内的 [`mock`](crates/mcp-gauntlet-core/src/mock.rs) 服务器（`mcp-fuzz mock` / `mcp-storm mock`），您可以将这两个工具指向它，从而在零配置的情况下进行试用： ``` mcp-fuzz run --stdio -- mcp-fuzz mock # fuzz the bundled demo server ``` ## 开发 ``` cargo fmt --all cargo clippy --all-targets --all-features -- -D warnings cargo test --all-features ``` ## StudioMeyer MCP 工具包的一部分 这是一个专注于构建和运维 MCP 服务器的生产级小型工具家族 —— 您可以自由搭配使用： - [mcp-armor](https://github.com/studiomeyer-io/mcp-armor) —— 运行时防御 sidecar：扫描工具调用，验证已签名的 manifest，拦截已知的恶意 CVE - **mcp-gauntlet** *（本工具）** —— 部署前使用的 `mcp-fuzz`（基于 schema 的模糊测试工具）+ `mcp-storm`（负载测试工具） - [mcp-otel](https://github.com/studiomeyer-io/mcp-otel) —— W3C Trace Context → OpenTelemetry 桥接器 - [mcp-cache-kit](https://github.com/studiomeyer-io/mcp-cache-kit) —— 防泄漏的 SEP-2549 缓存（`ttlMs` + `cacheScope`） - [skilldoctor](https://github.com/studiomeyer-io/skilldoctor) —— 针对 agent skill 文件的 linter + 安全扫描器 ## 许可证 MIT © StudioMeyer。参见 [LICENSE](LICENSE)。

标签：AI基础设施, ASM汇编, Rust, 压力测试, 可视化界面, 开发与测试工具, 模型上下文协议(MCP), 网络流量审计