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