MCP API Guardian

MCP API Guardian

阻止 AI Agent 破坏你的 API：通过 MCP 检查 OpenAPI 契约并对比破坏性变更，完全在本地运行。

为使用 OpenAPI 规范的 AI 编码 Agent 提供本地优先的防护措施：捕获契约错误（缺少操作 ID、未解析的引用、公开认证）、检测破坏性变更（删除操作、新增必需参数、更改认证方式），并在发布前确保 API 使用者正常工作。

零配置。无需 API 密钥。无需联网。通过 Model Context Protocol 完全在你的机器上运行。

---

目录

• 快速安装
• 为什么选择 API Guardian
• 工具
• 使用场景
• 与替代方案比较
• 限制
• 从源码运行
• 路线图
• 托管路径（控制平面）
• 贡献
• 许可证
• 作者的其他 MCP 服务

---

快速安装

一键安装

Cursor：

也可以使用直接协议链接：cursor://anysphere.cursor-deeplink/mcp/install?name=api-guardian&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1hcGktZ3VhcmRpYW4iXX0=

Claude Code：

claude mcp add api-guardian -- npx -y mcp-api-guardian

如果已安装 petrovicistefan/mcp-marketplace，也可以使用：

/plugin marketplace add petrovicistefan/mcp-marketplace

手动安装

Claude Desktop：

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Cursor：

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

VS Code / GitHub Copilot：

或者手动创建/编辑 .vscode/mcp.json：

{
  "servers": {
    "api-guardian": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Windsurf：

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

Zed：

添加到 Zed 的 settings.json：

{
  "context_servers": {
    "api-guardian": {
      "command": "npx",
      "args": ["-y", "mcp-api-guardian"]
    }
  }
}

直接使用 npx（单行测试）：

npx -y mcp-api-guardian

---

⭐ 如果觉得有帮助，请为本仓库点星

觉得这个 MCP 有用？为本仓库点星！

GitHub 星标有助于其他开发者发现此项目，也方便你稍后再次访问。感谢你支持开源！

---

为什么选择 API Guardian

AI 编码 Agent 在开发 API 功能、编写文档和进行集成时，越来越常常会修改 OpenAPI 规范。一次 Agent 迭代就可能：

• 删除客户端所依赖的操作
• 添加没有默认值的必需请求参数
• 更改生成的 SDK 所依赖的 operationId
• 意外发布没有认证的公开端点
• 破坏外部引用或引入重复 ID

**API Guardian 能在这些问题影响生产环境之前将其捕获。**它提供两个 MCP 工具供 AI Agent 调用：

1. audit_openapi — 检查单个 OpenAPI 规范，找出契约错误、缺失的元数据和认证风险
2. compare_openapi — 对比两个规范版本并检测破坏性变更

完全在本地运行，只读，零依赖。无遥测、无 API 密钥、不发起网络请求。

---

工具

API Guardian 提供 2 个 MCP 工具，用于验证 OpenAPI 3.0.x 和 3.1.x 文档：

工具	描述	输入
audit_openapi	对 OpenAPI 3.0/3.1 进行静态检查，并审查身份验证声明。不会调用端点。	spec（对象）：以 JSON 格式表示的 OpenAPI 文档
compare_openapi	查找两个 OpenAPI 文档之间选定的破坏性变更；不全面检查架构兼容性。	before（对象）：原始 OpenAPI 文档 after（对象）：更新后的 OpenAPI 文档

audit_openapi({spec})

对单个 OpenAPI 规范进行静态契约检查：

• 契约错误：未解析的 $ref 引用、缺少 info.title/info.version、无效路径
• 操作元数据：缺少或重复的 operationId、缺少响应定义
• 路径参数：所有 {param} 占位符都必须声明为必需的路径参数
• 安全警告：公开操作（不要求身份验证）、通过 HTTP 使用基本身份验证、在查询字符串中使用 API 密钥
• 外部引用：标记未经检查的外部 $ref URL（不会获取）

报告错误和警告，并提供严重程度、位置及可执行的说明。明确说明覆盖范围的限制。

compare_openapi({before, after})

检测两个 OpenAPI 规范版本之间的破坏性变更：

• 已移除的操作：删除了先前可用的端点
• 已更改的操作 ID：生成的客户端和 Agent 可能依赖稳定的 ID
• 新增的必需参数：添加了内联必需参数（客户端无法提供这些参数）
• 请求体要求：可选请求体变为必需
• 已移除的响应代码：客户端可能处理的状态代码已被移除
• 安全变更：身份验证要求已修改（警告级别）

报告确定的破坏性变更（error）和潜在的兼容性问题（warning）。尚未分析架构差异和组合架构（参见限制）。

---

使用场景

个人开发者

提示词：“在提交之前，审查 api/openapi.json 中的 OpenAPI 规范”

你的 AI Agent 会调用 audit_openapi，发现缺少操作 ID，并建议修复方法——在 PR 之前。

---

CI / PR 检查

提示词：“将此分支上的 OpenAPI 规范与 main 进行比较，如果存在破坏性变更则失败”

你的 Agent 会运行 compare_openapi，检测到已移除的端点，并通过提供可执行报告来阻止合并。

---

团队和企业

提示词：“检查 api/ 中的所有 OpenAPI 规范，找出未启用身份验证的公开端点”

你的 Agent 会审查每个规范，标记公开操作，并生成安全审查清单。

---

与其他方案的比较

特性	MCP API Guardian	oasdiff	pb33f/openapi-changes	optic（已归档）
MCP 集成	✅ 原生 MCP 服务	❌ 仅 CLI	❌ 仅 CLI	❌ 仅 CLI
适用于 AI Agent	✅ JSON-RPC stdio，专为 Agent 设计	⚠️ CLI 输出解析	⚠️ CLI 输出解析	⚠️ 已归档
完全本地运行（无需网络）	✅ 不进行任何网络调用	✅ 离线	✅ 离线	⚠️ 曾提供云服务
破坏性变更检测	✅ 核心功能	✅ 全面（773 项检查）	✅ 全面	✅（旧版）
静态契约检查	✅ 核心功能	⚠️ 仅验证	⚠️ 侧重变更	⚠️ 侧重流量
Git 修订版本比较	❌ 计划中	✅ 内置	✅ 内置	✅（旧版）
Schema 兼容性	❌ 计划中	✅ 完整支持	✅ 完整支持	✅（旧版）
HTML/Markdown 报告	❌ 仅 JSON	✅ 多种格式	✅ 多种格式	✅（旧版）
许可证	MIT	Apache 2.0	GPL-3.0 / 商业版	MIT（已归档）

适合使用 API Guardian 的情况：

• ✅ 你希望 AI Agent（Claude、Cursor 等）原生检查 OpenAPI 契约，无需 CLI 包装器
• ✅ 你需要本地优先、零网络验证（无外部依赖）
• ✅ 你希望在一个 MCP 服务中实现针对性 lint 检查 + 破坏性变更检测

适合使用其他方案的情况：

• 如果你需要最全面的破坏性变更规则集（773 项检查）和原生支持 CI 的工作流，请使用 oasdiff
• 如果你需要美观的 HTML/Markdown 差异报告供人工审查，请使用 pb33f/openapi-changes
• oasdiff 和 openapi-changes 均支持完整的 Schema 兼容性检查和原生支持 Git 的比较；API Guardian 将在未来版本中添加这些功能

---

局限性

API Guardian 是针对性 lint 工具，而非完整的 OpenAPI 验证器。目前的局限性：

• ❌ 不支持 YAML 规范：仅接受 JSON OpenAPI 文档。请将解析后的 JSON 对象传递给 MCP 工具。YAML 支持已列入路线图（见下文）。
• ❌ 不会获取外部 $ref：外部 HTTP/HTTPS 引用会被标记为警告，但不会解析或验证
• ❌ 不会检查 Schema 兼容性：请求与响应的差异、oneOf/anyOf/allOf 组合 Schema，以及属性级破坏性变更需在后续版本中支持
• ❌ 不会比较被引用的参数：compare_openapi 仅检查内联参数
• ❌ 不进行实时 HTTP 探测：不会测试实际 API 行为，也不会验证运行时响应
• ❌ 不访问文件系统：必须将规范作为已解析的 JSON 对象传递（不接受文件路径）

公开端点可能是有意设置的；警告并不代表存在漏洞。报告会明确说明覆盖范围的限制。

---

从源码运行

git clone https://github.com/petrovicistefan/mcp-api-guardian.git
cd mcp-api-guardian
npm test
npm start

添加到 MCP 客户端的配置中，并替换为绝对路径：

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

**要求：**Node.js 22+

---

路线图

未来版本将添加：

1. YAML 支持：解析并验证 YAML OpenAPI 规范（目前仅支持 JSON）
2. 完整的 Schema 兼容性：检测属性级破坏性变更、组合 Schema（oneOf/anyOf/allOf），以及请求与响应的差异
3. 本地引用解析：通过可配置的允许列表获取并验证外部 $ref 引用
4. 原生支持 Git 的比较：无需手动提取文件，即可跨分支/提交比较规范
5. 实时响应验证：可选的 HTTP 探测，支持目标允许列表、大小限制和密钥脱敏

---

托管路径（控制平面）

上述本地 stdio MCP 服务即使没有账户或网络连接，也能完整使用。配额仅由独立的托管 HTTP 进程强制执行；该进程会先在 mcp-control-plane 上预留用量，然后运行相同的分析核心。

# Terminal 1 — control plane (see its README for ADMIN_TOKEN)
node --env-file=.env src/server.js   # in mcp-control-plane

# Terminal 2 — hosted api-guardian
cp .env.example .env                 # set CONTROL_PLANE_URL
npm run start:hosted

使用控制平面管理 API（POST /v1/admin/accounts、POST /v1/admin/keys）创建客户密钥。然后：

方法	路径	请求体
GET	/health	存活状态
POST	/v1/audit	{ "requestId": "scan-1", "units": 1, "spec": { … } }
POST	/v1/compare	{ "requestId": "diff-1", "before": { … }, "after": { … } }

客户路由需要 Authorization: Bearer mcp_…。成功时，响应包含 report 和 usage。超出配额时会返回 429 和 { "error": "quota_exceeded" }，且不会运行分析。默认绑定地址：127.0.0.1:3100。生产环境需要 HTTPS 反向代理。

隐私： OpenAPI 文档仅在托管主机上处理。控制平面请求只携带 product（api-guardian）、requestId 和 units，绝不包含规格、报告或凭据。控制平面 MVP 中，成功扣减的用量不可退款。

此托管路径是面向未来商业产品的参考集成，并非已发布的多租户部署方案。在计费功能上线前，README 中的价格仍是假设。本地 MIT 软件包无法可靠地强制执行付费配额；配额应由经过身份验证的托管服务负责。

---

参与贡献

欢迎贡献！请：

1. 开始工作前先提交 issue，讨论变更内容
2. 遵循现有代码风格（ESM、node:test、零依赖）
3. 为新功能添加测试
4. 让提交内容聚焦且描述清晰

如果 CONTRIBUTING.md 存在，请参阅；如果你想参与贡献，也可以提交 issue。

---

许可证

MIT — 可免费用于个人和商业用途。完整条款请参阅 LICENSE。

---

作者的更多 MCP 服务

属于 petrovicistefan MCP 套件 — 为 AI 编码 Agent 提供本地优先的防护措施。

服务	描述
mcp-security-guard	审计 MCP 服务，检查工具投毒、恶意接管、名称遮蔽和密钥泄露。符合 OWASP MCP Top 10。
mcp-dependency-doctor	检测项目中的依赖漏洞、许可证风险和供应链问题。
mcp-database-doctor	SQL 架构 lint、迁移安全检查和查询性能分析。
mcp-cost-optimizer	在基础设施配置中发现云成本优化机会。
mcp-seo-auditor	Web 项目的技术 SEO 审计：元标签、schema.org、Core Web Vitals、无障碍性。
mcp-dealfinder	面向电子商务和 SaaS 的价格比较与优惠发现。
mcp-marketplace	所有可用 MCP 服务和插件的目录。

所有服务均采用 MIT 许可证、完全在本地运行，且无需 API 密钥。

---

⭐ 如果此项目对你有帮助，请在 GitHub 上为其点星，帮助更多人发现它！