MCP API Guardian

io.github.petrovicistefanv0.1.1更新于 Oct 9, 2026

Local OpenAPI contract and breaking-change checks for AI agents.

已验证STDIO仅桌面Developer ToolsSecurity & Monitoring

概览

AI 生成的概览

让 AI 编程助手在本地审计 OpenAPI 3.0.x/3.1.x 规范，并比较两个版本之间的破坏性契约变更。

功能
通过 stdio 提供两个工具：audit_openapi 检查已解析的 OpenAPI 文档中的选定契约错误、引用、operation ID、必需的路径参数、公开操作以及有风险的身份验证声明；compare_openapi 对比前后两个文档，检测被删除的操作、变更的 operation ID、新增的内联必需参数、新变为必需的请求体、被删除的响应码以及变更的身份验证要求。它是针对性的 linter，而不是完整的 OpenAPI 校验器，报告会说明其覆盖范围。
适用场景
适合在助手编辑或审查 API 规范时，快速做一次契约检查，或对比两个版本之间的破坏性变更。适用于规范已解析为 JSON 对象的本地开发流程。
运行要求
作为 Node.js 22+ 本地进程通过 stdio 运行，通常用 npx mcp-api-guardian 启动；本地服务器不需要账号、API 密钥或网络访问。规范必须以已解析的 JSON OpenAPI 3.0.x 或 3.1.x 对象传入；未实现 YAML 解析、文件系统访问、外部引用获取和实时 HTTP 探测。
安装前请注意
本地服务器不需要凭据，文档不会离开进程。另有一条可选托管路径：它在托管主机上处理 OpenAPI 文档，需要 Authorization Bearer 密钥，会执行配额限制，超额时返回 429；其控制平面请求只携带 product、requestId 和 units。该托管路径被描述为参考集成，而非已发布的多租户部署，且成功消耗不予退款。警告并不等于存在漏洞的证明。

安装

在 SourceWeft 中

  1. 打开 控制台中的 MCP API Guardian，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

MCP API Guardian

Local OpenAPI contract checks for AI coding agents. MVP 0.1.0, no runtime dependencies, Node.js 22+.

Transport: newline-delimited JSON-RPC over stdio, with the initialize-based MCP protocol family through 2025-11-25. The newer 2026-07-28 stateless protocol is not implemented. Test with your target client before deployment. Protocol reference: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports

Install in your AI client

Works with any MCP client over stdio; no account or API key needed for the local server.

Claude Code

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

Codex CLI

sh
codex mcp add api-guardian -- npx -y mcp-api-guardian

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — add to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Cline MCP settings, ~/.gemini/settings.json):

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

VS Code / GitHub Copilot — .vscode/mcp.json:

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

Zed — settings.json:

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

Run from source

sh
npm testnpm start

Add to an MCP client's configuration, replacing the absolute path:

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

Tools

  • audit_openapi({spec}): checks selected contract errors, references, operation IDs, required path parameters, public operations and risky authentication declarations.
  • compare_openapi({before, after}): detects removed operations, changed operation IDs, added inline required parameters, newly required request bodies, removed response codes and changed authentication requirements.

Pass parsed JSON OpenAPI 3.0.x or 3.1.x documents as objects. YAML parsing, filesystem access, external reference fetching and live HTTP probes are not implemented. No credentials or source documents leave the process.

This is a targeted linter, not a complete OpenAPI validator. Schema compatibility (including request versus response variance), composed schemas and referenced parameter comparisons require a later release. Public endpoints may be intentional; warnings are not proof of a vulnerability. Reports explicitly state coverage.

Packaging

sh
npm run checknpm testnpm pack

Clients can use npx -y mcp-api-guardian.

Hosted path (quotas via control plane)

The local stdio MCP server above stays fully useful without an account or network. Quotas are enforced only by a separate hosted HTTP process that reserves units on mcp-control-plane before running the same analysis core.

sh
# 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-guardiancp .env.example .env                 # set CONTROL_PLANE_URLnpm run start:hosted

Bootstrap a customer key with the control-plane admin API (POST /v1/admin/accounts, POST /v1/admin/keys). Then:

MethodPathBody
GET/healthLiveness
POST/v1/audit{ "requestId": "scan-1", "units": 1, "spec": { … } }
POST/v1/compare{ "requestId": "diff-1", "before": { … }, "after": { … } }

Customer routes require Authorization: Bearer mcp_…. On success the response includes report and usage. Over quota returns 429 with { "error": "quota_exceeded" } and does not run analysis. Default bind: 127.0.0.1:3100. Production needs an HTTPS reverse proxy.

Privacy: OpenAPI documents are processed on the hosted host only. Control-plane requests carry solely product (api-guardian), requestId, and units — never specs, reports, or credentials. Successful consume has no refund in the control-plane MVP.

This hosted path is a reference integration, not a published multi-tenant deploy. README prices remain hypotheses until billing is live.

Roadmap and commercial model

  1. Add full schema compatibility tests and local reference resolution.
  2. Add explicit opt-in live response validation, target allowlists, limits and secret redaction.
  3. Validate demand with API teams using real release diffs.
  4. Offer managed history, CI integration, shared policies and team reporting as Pro (hosted path above is the quota hook).

A local MIT package cannot reliably enforce paid quotas; those belong to an authenticated hosted service. Keep the useful local tool free.

来源：README.md，提交 93e0bb2

工具

0
工具元数据尚未被收录。

版本历史

1
  1. v0.1.1最新Oct 9, 2026