OpenAPI Contract Guard MCP

一个可自建、只读的 OpenAPI 契约守卫 MCP。它让 AI 客户端能够校验 OpenAPI 文档、比较两个版本、识别破坏性变更，并生成结构化变更日志。

底层差异分析使用 oasdiff，MCP 服务基于 官方 Python SDK 实现。

能力

工具	作用
validate_spec	校验允许目录内的 OpenAPI 3.x 文档
compare_specs	输出两个契约版本的完整结构差异
list_breaking_changes	定位可能破坏现有客户端的变更
generate_changelog	生成按严重级别分类的 API 变更日志

安全边界

• 全部工具只读，不修改接口文档。
• 本地文件只能来自 OPENAPI_GUARD_ALLOWED_ROOTS 配置的目录。
• 只接受本地文件，拒绝 URL 和其他 URI scheme。
• 校验和比较均拒绝外部 $ref，避免读取未授权文件或触发 SSRF。
• 使用参数数组启动子进程，固定 shell=False，不拼接 shell 命令。
• 单个契约文件上限为 20 MiB，单次标准输出和错误输出各上限约 1 MB。

环境要求

• Python 3.11+
• uv
• oasdiff（已使用 1.26.1 完成联调）

下载并解压 oasdiff 后，将可执行文件加入 PATH，或通过 OASDIFF_BIN 指定绝对路径。

本地运行

git clone https://github.com/xiaohuxi/openapi-contract-guard-mcp.git
cd openapi-contract-guard-mcp
uv sync
uv run openapi-contract-guard-mcp

默认使用 MCP stdio transport，适合 Codex、Claude Code、Cursor 等本地 AI 客户端。

MCP 配置

{
  "mcpServers": {
    "openapi-contract-guard": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/xiaohuxi/openapi-contract-guard-mcp.git",
        "openapi-contract-guard-mcp"
      ],
      "env": {
        "OPENAPI_GUARD_ALLOWED_ROOTS": "/absolute/path/to/your/api-project",
        "OASDIFF_BIN": "/absolute/path/to/oasdiff"
      }
    }
  }
}

Windows 可用分号配置多个允许目录，Linux 和 macOS 使用冒号：

OPENAPI_GUARD_ALLOWED_ROOTS=D:\project-a;D:\project-b

未配置时，允许目录默认为 MCP 进程的当前工作目录。

使用示例

可以直接向 AI 客户端提出：

• “校验 openapi.yaml 是否符合 OpenAPI 规范。”
• “比较 specs/v1.yaml 和 specs/v2.yaml，列出全部差异。”
• “检查新版本是否包含破坏性变更，并解释影响。”
• “根据两个契约版本生成发布变更日志。”

仓库内的 examples/base.yaml 和 examples/revision.yaml 可用于快速验证。

开发与测试

uv sync --group dev
uv run pytest

自动化测试覆盖本地路径边界、URL scheme、外部 $ref、OpenAPI 3.x 校验、三个差异工具、无 shell 子进程调用和 MCP 工具注册。真实联调示例 能够识别删除 GET /users 为破坏性变更。

配置项

环境变量	默认值	说明
OPENAPI_GUARD_ALLOWED_ROOTS	当前工作目录	允许读取的本地根目录列表
OASDIFF_BIN	oasdiff	oasdiff 可执行文件路径

License

MIT