mcptest

网站 · 文档 · 示例 · 示例服务器

[](https://github.com/soapbucket/mcptest/actions/workflows/ci.yml) [](https://crates.io/crates/mcptest) [](./LICENSE) [](https://www.rust-lang.org) [](https://github.com/soapbucket/mcptest/stargazers) [](https://mcptest.sh) **mcptest 是一个开源的 CLI 和 MCP server，用于测试 MCP server， 无论是在你的终端、CI 还是编程 agent 中均可使用。** 通用的 API 测试工具并不“懂” MCP，因此它们会忽略最关键的部分：你的 tool、resource 和 prompt 是否返回了应有的结果，以及 catalog 或 schema 是否发生了漂移。mcptest 端到端地使用 MCP 交流。你只需将检查写成 YAML， 就能得到确定性的通过或失败结果，以及结构化的失败报告，指出破坏了哪个 断言、server 发送的 payload 是什么，并提供一行用于复现的命令。 你可以测试的内容： - **Tool、resource、prompt：** 基于真实响应进行断言；捕获 catalog 和 input-schema 漂移。 - **Agent 行为：** 使用 rubric、LLM-judge 或 jury eval 对 agent loop 进行评分。 - **规范合规性与一致性：** 基于锁定的 MCP 协议版本进行测试。 - **安全：** red-team 探测、tool-poisoning 和 shadowing 检查。 - **离线：** 启动 mock server，无需真实后端或网络。 - **在 CI 中：** 一个可 diff 的 YAML 测试套件，带有退出码门禁。

通过三个命令试用它： ``` curl -fsSL https://download.mcptest.sh/install.sh | sh # or: brew install soapbucket/tap/mcptest mcptest init # writes the mcptest.yml suite plus a starter suite under tests/ mcptest run # deterministic verdicts, structured failures ``` 入门套件针对内置的 mock server (`mcptest mock`) 运行，其数据来源于 脚手架生成的 `tests/example-server.yml` catalog，因此首次运行 无需真实 server 和网络即可离线通过；你可以将 `command:` 替换为你自己的 server。如果你机器上的某个 MCP client 已经知道你的 server，`mcptest init --from-discovered ` 会转而根据它为你生成脚手架。 ### 在你的编程 agent 中使用 mcptest 这是其他工具做不到的部分。只需两个命令，就能赋予 Claude Code、 Cursor 或任何支持 MCP 的 agent 完整的测试循环： ``` mcptest mcp-server --install --enable-writes # the front door (verbs) mcptest skill --install # the packaged skill ``` 你的 agent 会发出“测试这个 MCP server”的请求，从 server 的真实 catalog 中 脚手架生成一个经过验证的入门测试套件 (`scaffold_suite`)，根据观察到的 响应优化通用检查 (`propose_assertions`)，运行该 测试套件，并读取返回的失败报告，其中已经包含了断言、 实际值以及一行用于复现的命令。Agent 提供 智能判断；mcptest 提供确定性的结论，它留下的 YAML 就是供人类审查的、可 diff 的审计记录。请查看 [agent 接口](./docs/agent-interface.md)获取完整的动词 参考、面向模型的 `--reporter agent` 输出，以及打包好的 [skill 和 subagent](./examples/agent-skill/)。 ### 或者自己运行，在 CI 中 同样的测试套件也是你每次提交时运行的、可 diff 的 YAML 文件。它能 捕获协议回退、延迟峰值、契约漂移、实时模型回退， 以及不安全的 tool 定义，防止它们进入生产环境，包括由 真实模型驱动的 agent loop (`prompt -> model -> tool selection -> MCP call -> result -> answer`)。 ``` $ mcptest run --config tests/smoke.yml mcptest 1.0.1+ run [PASS] search returns at least one result for a known query (41 ms) [PASS] tool catalog is well-formed (3 ms) ... Summary: 12 passed, 0 failed, 0 skipped in 3104 ms ``` 默认的 pretty reporter 会为每个测试打印一行并附带摘要，同时 在任何失败的测试下方内联显示失败详情。如果需要紧凑的单行计数 (`ran 12 tests: 12 passed, ...`)，请使用 `--reporter minimal`；如果输出 是为了让模型在循环中读取结果，请使用 `--reporter agent`。 **一行安装。** 选择与你的机器匹配的路径。 Homebrew (macOS, Linux)： ``` brew install soapbucket/tap/mcptest ``` curl 安装程序 (macOS, Linux，包括 Apple Silicon 和 arm64)： ``` curl -fsSL https://download.mcptest.sh/install.sh | sh ``` 安装程序会检测你的平台，从 `download.mcptest.sh` 下载已签名的发布版 tarball，根据校验和文件验证其 sha256，并将 `mcptest` 放到 `~/.local/bin` 中（如果使用 sudo 运行，则放到 `/usr/local/bin`）。在通过管道传递之前，请使用 `curl -fsSL https://download.mcptest.sh/install.sh | less` 检查脚本。 Docker： ``` docker run --rm -v "$PWD":/work -w /work soapbucket/mcptest:latest run ``` 验证已签名的发布版（cosign + SLSA provenance），请参见 [docs/release-verification.md](./docs/release-verification.md)。 **接下来请阅读** [入门指南](./docs/getting-started.md) 让你在五分钟内从安装走向第一个通过的测试。 ## 我能信任 mcptest 吗？ 不要信任我们，请亲自验证。mcptest 采用 Apache 2.0 许可，是一个单一静态 二进制文件，没有遥测，也没有自动更新，它直接将 CycloneDX 软件物料清单嵌入在二进制文件中，因此你可以从你已有的副本中读取完整的 依赖列表： ``` mcptest sbom # the embedded CycloneDX SBOM mcptest sbom --verify # re-hash the embedded BOM to catch tampering ``` 每个发布版也都经过 Sigstore 签名，并带有 SLSA L3 构建 来源。完整的演练过程（包括如何验证已发布的 版本）位于 [mcptest.sh/trust](https://mcptest.sh/trust)（另请参见 [docs/sbom.md](./docs/sbom.md) 和 [docs/release-verification.md](./docs/release-verification.md))。 ## 为什么选择 mcptest mcptest 具备三大特性。每一个特性都能为你节省原本必须 花在定制测试脚本上的时间。 ### 规范驱动 测试以 YAML 形式存在，在加载时由 JSON Schema 进行验证。一次编写， 即可在 mcptest 运行的任何地方运行。无需为每个仓库维护特定的测试框架。 ``` # mcptest.yml # yaml-language-server: $schema=https://mcptest.sh/schema/v1.json servers: local: command: ["node", "./dist/server.js"] tools: - name: "search returns at least one result for a known query" server: local tool: search args: { query: "anthropic" } expect: assertions: - target: "result.content" matcher: { schema: { type: array, minItems: 1 } } max_duration_ms: 2000 ``` ### CI 优先 无头执行。精美的 reporter。富有意义的退出码。在所有 CI 平台上表现出一致的行为。 ``` # .github/workflows/mcptest.yml - name: Install mcptest run: curl -fsSL https://download.mcptest.sh/install.sh | MCPTEST_VERSION=v1.0.0 sh - name: Run mcptest run: mcptest run --reporter junit --output mcptest.junit.xml ``` ### 合理的默认设置，按需进阶 针对全新安装的 server 运行 `mcptest run`，无需任何配置， 你就能在大约 30 秒内看到通过测试的结果。其背后蕴含着生产 团队所需的深度：cassette、OAuth 2.1 + PKCE、内容寻址 缓存、多种 reporter，以及带有 预期失败基准的合规语料库。 ## 功能 在首次测试通过后，你会用到的六项核心能力。 ### 1. Agent 端到端测试 编写一个 YAML 测试，将其指向一个或一组模型，然后 运行它。驱动程序会列出你指定的每个 MCP server 上的 tool， 将附带合并 catalog 的 prompt 发送给模型，分派 模型发起的 tool 调用，并记录整个对话过程。你的 断言会针对追踪记录进行解析，因此同一个测试套件可以检查 `tool_calls[0].name == get_weather` 和 `conversation.tokens.total <= 8000`。 目前支持的 Provider：Anthropic、OpenAI（包括 o 系列）、 Google Gemini、Mistral，以及任何兼容 OpenAI-API 的 endpoint （Azure、OpenRouter、vLLM、llama.cpp、LiteLLM、Together、Groq、 Anyscale、Fireworks、由 Bedrock 前端代理的 Anthropic），只需通过指定的 `providers:` 块进行配置。 ``` agents: - name: weather query routes to get_weather models: - claude-sonnet-4-5 - gpt-5 - gemini-2.5-pro servers: [weather] prompt: What is the weather in Sacramento? expect: - target: tool_calls[0].name matcher: { exact: get_weather } - target: tool_calls[0].args.city matcher: { regex: "(?i)sacramento" } - target: conversation.tokens.total matcher: { regex: "^[0-9]+$" } ``` 在你的环境中配置好 provider 密钥后，记录运行过程，然后重新渲染 保存的 envelope 以获取按模型划分的明细： ``` $ mcptest run --record --reporter json --output run.json ran 3 tests: 2 passed, 1 failed, 0 skipped (2355ms) $ mcptest report run.json --format pretty mcptest 1.0.1+ run [PASS] weather query routes to get_weather [claude-sonnet-4-5] (842 ms) [FAIL] weather query routes to get_weather [gpt-5] (901 ms) tool_calls[0].name: expected get_weather, got search [PASS] weather query routes to get_weather [gemini-2.5-pro] (612 ms) Summary: 2 passed, 1 failed, 0 skipped in 2355 ms ``` 每个 `(test, model)` 对都会获得自己的 cassette，因此普通的 `mcptest run` 可以在 CI 中确定性地重放它们，而无需花费一分钱。 当有新模型问世时，你只需将其标识符添加到 `models:` 中，重新记录， 报告就会立刻告诉你哪个断言对哪个模型失效了。 无需修改 YAML，即可从命令行将整个测试套件在多个模型间进行全面扫掠， 并得到一个并排比较的网格图（测试用例 x 模型， 每个单元格的通过/失败状态，可深入查看失败的断言），格式可以是 独立的 HTML 或 Markdown 文件： ``` mcptest run --models claude-sonnet-4-5,gpt-5,gemini-2.5-pro # 默认使用 `matrix` reporter：按模型对比的测试网格 ``` 具体示例：[agent-weather.yml](./examples/agent-weather.yml)、 [agent-matrix.yml](./examples/agent-matrix.yml)、 [agent-custom-providers.yml](./examples/agent-custom-providers.yml)、 [agent-llm-judge.yml](./examples/agent-llm-judge.yml)、 [agent-issues-and-notifications.yml](./examples/agent-issues-and-notifications.yml)。 相关背景请见 [`docs/models.md`](./docs/models.md)。 ### 2. Cassette 记录与重放 将真实的协议交互记录到 cassette 中，然后在 CI 中离线 重放。快照和 agent cassette 共享相同的标准化处理流程， 因此今天的录制和下周的录制能够清晰地进行 diff 对比。默认 使用重放模式；`--record` 标志用于捕获新的录制。 ``` mcptest run --record # captures cassettes alongside the YAML mcptest run # replays them, no API key needed in CI ``` ### 3. 多种 reporter `mcptest run` 一次输出一种 reporter，通过 `--reporter` 选择： `pretty`、`minimal`、`json`、`junit`、`md`、`html`、`sarif`、`gitlab`、 `ndjson`、`tap`、`matrix`、`matrix-md` 或 `quiet`。默认的 `pretty` 会列出 每个测试及摘要；`minimal` 是紧凑的单行计数。只需捕获一次 JSON 运行 envelope，然后使用 `mcptest report --format` 将其重新渲染为以下任何格式：pretty CLI、JSON、JUnit、Markdown、HTML、SARIF、 GitLab Code Quality JSON、NDJSON、TAP 和 comparison-matrix 网格。无需 二次运行，无需二次 API 调用。 ``` # 运行一次，捕获 JSON envelope。 mcptest run --reporter json --output run.json # 将该 envelope 重新渲染为任何给定消费者所需的格式。 mcptest report run.json --format sarif --output run.sarif mcptest report run.json --format html --output run.html mcptest report run.json --format matrix --output matrix.html ``` ### 4. 从 Claude Desktop、Cursor 和 Claude Code 自动发现 如果你已经在编辑器中使用过 MCP server，`mcptest doctor` 会列出在你的本地 MCP client 配置中找到的 server，并且 `mcptest init --from-discovered ` 会为你选择的对象生成一个入门 测试套件，复制其命令和参数，省去了你重新输入 路径的麻烦。（而普通的 `mcptest init` 会生成固定的 filesystem-server 模板。） ``` mcptest doctor # lists discovered servers by name mcptest init --from-discovered github # scaffold against one of them ``` ### 5. 用于 HTTP server 的 OAuth 2.1 + PKCE 支持 OAuth 2.1 和 PKCE 的 server 是一等公民。Token 会 从你的环境中发现，在运行期间过期时会自动刷新，并且会在所有的 reporter 中被掩码处理。 ``` servers: saas: url: "https://api.example.com/mcp" auth: oauth: client_id_env: "MCPTEST_SAAS_CLIENT_ID" authorization_url: "https://auth.example.com/oauth/authorize" token_url: "https://auth.example.com/oauth/token" ``` ### 6. 预期失败基准（合规语料库） 在一个已知存在缺陷的 server 上采用合规语料库，而不会阻塞 PR 队列。基准文件记录了当前 预期会失败的检查项；`mcptest compliance run --baseline` 仅在 通过的检查变为失败时（即新的回退），或基准中记录的检查项 重新开始通过时（即需要移除的过期记录）才会判定失败。 ``` # 在 baseline 上设置 CI 门禁，以便已知的失败保持 green。 mcptest compliance run \ --results-from artifacts/compliance.json \ --baseline compliance-baseline.yml # 在 deliberate cleanup 后重新生成 baseline。 mcptest compliance run \ --results-from artifacts/compliance.json \ --baseline compliance-baseline.yml \ --update-baseline --yes ``` ## 概览 上述六项能力是核心亮点；这里一次性列出 其他所有功能。 - **测试类型：** tool、resource 和 prompt 调用；快照；延迟 预算；合规语料库（PROTO、SCHEMA、SEQ、TOOL、RES、EDGE）； schema-drift diff (`mcptest diff`)；生成的 output-schema 一致性测试 (`mcptest generate`)；对 tool 定义进行确定性安全扫描 (`mcptest security`)；agent 端到端测试；以及 渲染为测试与模型网格图的模型比较扫掠 (`--models`)。 - **断言：** 确定性匹配器（`exact`、`contains`、`regex`、 `schema`、`subset`、`is-json`、`is-xml`、`is-sql`、`levenshtein`、 `starts-with`、`contains-*` 家族、`not`/`oneOf`/`anyOf`/`allOf`）； 用于自定义逻辑的 `cel` 谓词；embedding `similar`；带 校准的 `llm-judge` / `llm_jury`；以及命名的模型评分检查 （`factuality`、`answer-relevance`、`context-faithfulness`）。 - **安全：** 针对 tool 表面的确定性 red-team catalog， 审阅者级别的漏洞报告（`security --format html|md`），以及 OW LLM Top 10 覆盖范围视图。 - **传输：** stdio、streamable HTTP、旧版 SSE。 - **认证：** OAuth 2.1 + PKCE、bearer token、自定义 headers、自动 密钥掩码处理。 - **SDK：** 从你自己的测试运行程序中驱动 mcptest。支持 Python (pytest)、 TypeScript (vitest、jest、mocha、`node:test`)、Go、Rust (proc-macro)、 .NET (xUnit) 和 JVM (JUnit 5)。 - **CI：** GitHub Actions、GitLab CI 和 CircleCI 集成路径。 - **分发：** Apache-2.0、签名发布版、适用于 macOS、Linux 和 Windows 的预构建二进制文件。 路线图项目及功能需求位于 [GitHub Issues](https://github.com/soapbucket/mcptest/issues)。 ## 示例 涵盖各个层面的可运行套件展示，而不仅限于 agent loop。 每个示例都可通过 `mcptest run --config `（或 `mcptest `）运行；包含每个示例说明的 完整目录位于 [`examples/README.md`](./examples/README.md)。 - **Tool / 协议测试：** [`server-stdio.yml`](./examples/server-stdio.yml) （stdio 目标）， [`server-url.yml`](./examples/server-url.yml) ， [`named-errors-stdio.yml`](./examples/named-errors-stdio.yml)（断言 命名的 MCP 错误代码）。 - **合规性：** [`compliance-baseline.yml`](./examples/compliance-baseline.yml) （预期失败基准）， [`official-conformance.yml`](./examples/official-conformance.yml)， [`spec-version-pinning.yml`](./examples/spec-version-pinning.yml)。 - **安全：** [`security/`](./examples/security)（tool-description 注入、 tool shadowing、rug-pull、data-exfiltration、authz 系列）。 - **覆盖范围：** [`coverage/`](./examples/coverage)（针对内置的 `mcptest mock` server 执行每个匹配器和顶级 块，无需密钥）。 - **无 Oracle 鲁棒性：** [`robustness-walkthrough/`](./examples/robustness-walkthrough) 将元 metamorphic 关系、输入 fuzzing、负面路径 合规性以及三值断言连接到一个 tool 上。在 [docs/oracle-free-robustness.md](./docs/oracle-free-robustness.md) 中有端到端的详细叙述。按功能查看 示例：[`metamorphic/`](./examples/metamorphic)、[`fuzz/`](./examples/fuzz)、 [`negative-path.yml`](./examples/negative-path.yml)、 [`tool-schema-lint/`](./examples/tool-schema-lint)、 [`coverage/tool-edges.yml`](./examples/coverage/tool-edges.yml)、 [`inconclusive.yml`](./examples/inconclusive.yml)。 - **组合（tool DAG）：** [`composition-full.yml`](./examples/composition-full.yml)（transform、`when`、 `for_each`、assembly、budget、cases）和 [`pipe-search-then-update.yml`](./examples/pipe-search-then-update.yml)。 - **Eval 匹配器：** [`rubric-eval.yml`](./examples/rubric-eval.yml)（加权 rubric 评分，离线）和 [`sota-matchers.yml`](./examples/sota-matchers.yml) （`cel` 谓词和命名的模型评分匹配器）。 - **Transform 和 hooks：** [`transform.yml`](./examples/transform.yml)、 [`hooks-context.yml`](./examples/hooks-context.yml)。 - **漂移与发现：** 用于 `mcptest diff` 的 [`diff-tools-baseline.json`](./examples/diff-tools-baseline.json)，以及用于 `mcptest discover` 的 [`discovery/`](./examples/discovery)。 - **Agent（LLM 参与循环）：** [`agent-weather.yml`](./examples/agent-weather.yml)、 [`agent-matrix.yml`](./examples/agent-matrix.yml)。 - **SDK 集成：** [`python-sdk/`](./examples/python-sdk) (pytest)、 [`typescript-sdk/`](./examples/typescript-sdk) (vitest)。 ## 项目布局 代码位于 `crates/` 目录下，语言 SDK 位于 `sdks/` 目录下。 [项目布局参考](./docs/project-layout.md) 是关于哪个 crate 拥有什么、依赖图以及 SDK 矩阵的权威指南。请查阅 [`AGENTS.md`](./AGENTS.md) 了解贡献者规则手册。 YAML 配置的 JSON Schema 位于 `schemas/v1.json`，并在 每次发布时发布到 `https://mcptest.sh/schema/v1.json`。Agent cassette schema 与它相邻，位于 `schemas/agent-cassette-v1.json`。 ## 从源码构建 ``` cargo build --release ./target/release/mcptest --help # 像 CI 那样运行完整的检查门禁（fmt + clippy + doc + build + test）： ./scripts/check.sh # 在本地构建文档站点（配置位于 docs-site/）： cd docs-site && mdbook serve # if mdbook is installed; otherwise read raw Markdown under docs/ ``` 完整的构建与架构细节位于 [`docs/project-layout.md`](./docs/project-layout.md)。 ## 文档 完整文档位于 [`docs/`](./docs/index.md) 下。重点内容： - [入门指南](./docs/getting-started.md)：从安装到第一个 通过的测试。 - [概念](./docs/concepts.md)：mcptest 的工作原理。 - [YAML 参考](./docs/yaml-reference.md)：每个字段、每个 匹配器。 - [CLI 参考](./docs/cli-reference.md)：每个子命令、每个 标志。 - [故障排除](./docs/troubleshooting.md)：你最常遇到的 失败模式。 ## 许可证 Apache-2.0。请参见 [LICENSE](./LICENSE) 和 [NOTICE](./NOTICE)。 版权所有 2026 Soap Bucket LLC 及 mcptest 贡献者。Soap Bucket LLC 网址为 [soapbucket.com](https://soapbucket.com)。 ## 链接 - 文档：[`docs/index.md`](./docs/index.md) - 示例：[`examples/`](./examples/) - 发布版： [github.com/soapbucket/mcptest/releases](https://github.com/soapbucket/mcptest/releases) - 问题追踪器： [github.com/soapbucket/mcptest/issues](https://github.com/soapbucket/mcptest/issues) - X (Twitter)：[@soapbucket](https://x.com/soapbucket)

标签：AI代理, LLM评估, MCP, Ollama, Rust, 可视化界面, 安全测试, 开源框架, 持续集成, 攻击性安全, 测试工具, 网络流量审计, 请求拦截, 通知系统