api-test-mcp

api-test-mcp

一个 MCP 服务，可让 Claude Code、Cursor、Windsurf 或任何兼容 MCP 的 AI Agent 实际调用你的 API，并根据 OpenAPI 规范承诺的内容检查响应——而不是只读文档后进行猜测。

无需 API 密钥、无需配置、无需费用。适用于任何 OpenAPI/Swagger 3.x 规范（URL 或本地文件）。

为什么开发这个项目

AI Agent 很擅长阅读 OpenAPI 规范并据此编写代码，但它们无法确定真实 API 的行为是否与规范一致。这个工具让 Agent（或你在普通聊天中）能够实际验证：调用在线端点，并检查响应是否符合文档中记录的架构。

安装

git clone <this repo>
cd api-test-mcp
npm install

将其添加到 MCP 客户端配置中，例如 Claude Code：

claude mcp add api-test -- node /absolute/path/to/api-test-mcp/src/index.js

或者在 claude_desktop_config.json / Cursor 的 MCP 设置中添加：

{
  "mcpServers": {
    "api-test": {
      "command": "node",
      "args": ["/absolute/path/to/api-test-mcp/src/index.js"]
    }
  }
}

工具

工具	功能
load_api_spec	从 URL 或本地路径加载并解析 OpenAPI/Swagger 规范。返回 API 标题、服务器以及所有已记录的端点。请先调用此工具。
list_endpoints	列出当前已加载的所有端点。
call_endpoint	对已记录的端点发起真实 HTTP 调用。返回真实的状态码、标头和响应正文。
validate_response	根据指定方法 + 路径 + 状态码对应的 JSON 架构检查响应正文。
test_endpoint	一步完成 call_endpoint + validate_response。主要工具——“这个端点的实际行为是否符合文档？”
run_all_tests	尽力对所有无需必填参数的 GET 端点执行契约测试。传入 includeMutating: true，还会根据架构自动生成示例参数/正文，并尝试 POST/PUT/PATCH（默认关闭，因为可能会写入真实数据）。仍需手动输入的端点会列为已跳过，并附上原因。
check_health	一次性对一组端点（或已加载规范中所有无需参数的 GET 端点）执行 ping，报告可达性和延迟。适用于演示前检查或作为 CI 步骤。
diff_api_specs	比较两个版本的规范（例如旧标签与 main），并标记可能导致破坏性变更的内容——已移除的端点、新增的必填字段、类型变更、已移除的枚举值——以及安全的增量变更。

以上所有工具都支持可选的 auth 预设（bearer、在标头或查询参数中传递的 apiKey，或 basic），因此使用经过身份验证的 API 时无需手动构建原始标头；也支持可选的 timeoutMs。

示例（Agent 对话示例）

你： 加载我的 API 规范 https://api.example.com/openapi.json，并检查 /users/{id} 是否确实返回了文档中记录的内容。

Agent： （调用 load_api_spec，然后使用真实用户 ID 调用 test_endpoint） → “已调用——返回了 200，但响应缺少规范标记为必填的 created_at 字段，而且文档将 role 定义为包含 3 个值的枚举，但 API 返回了 "superadmin"，它并不在枚举值中。”

对于需要身份验证的 API：

你： 使用这个 bearer 令牌，对我的预发布 API 执行完整的契约测试，并包含写入端点。

Agent： （使用 { auth: { type: "bearer", token: "..." }, includeMutating: true } 调用 run_all_tests） → “12 项通过，2 项失败，3 项跳过。POST /orders 未通过架构验证——total_cents 返回的是字符串，而不是规范中定义的整数。”

使用真实线上流量进行测试

npm test 会运行三项真实且未使用模拟数据的检查，不会用伪装成服务端的固定测试数据：

• test/smoke-test.js — 加载规范，对线上公共 API 发起真实 HTTPS 调用，验证真实响应，并故意输入错误响应，以确认验证确实能捕获不匹配（而不只是检查成功路径）。
• test/new-features-test.js — 将身份验证预设应用于真实的外发请求 URL，测试真实的网络超时和中止，进行真实的健康检查调用，并对规范差异逻辑进行确定性的离线测试。
• test/mcp-protocol-test.js — 将实际的 MCP 服务作为子进程启动，并通过真实的 MCP 协议与其通信，方式与 Claude Code 或 Cursor 相同。

CI 会在每次推送或 PR 时，针对 Node 18、20 和 22 运行完整测试套件。

路线图

v1.0 已提供契约测试、身份验证预设、为变更类端点自动生成示例数据、规范差异比较和健康检查。接下来的计划包括：

• YAML 输出模式 / 用于非 MCP 场景的小型 CLI 封装
• 为 run_all_tests 和 check_health 中不稳定的端点配置重试和退避
• 支持模式的示例生成（遵循 JSON Schema 的 pattern，而不是使用占位字符串）
• 持久化健康检查历史记录（目前仅支持单次检查）

欢迎贡献 — 请参阅 CONTRIBUTING.md。如果遇到此项目无法妥善处理的端点类型或规范问题，请提交 issue。

许可证

MIT