# OpenAPI Contract Guard MCP

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

底层差异分析使用 [oasdiff](https://github.com/oasdiff/oasdiff)，MCP 服务基于
官方 [Python SDK](https://github.com/modelcontextprotocol/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](https://docs.astral.sh/uv/)
- [oasdiff](https://github.com/oasdiff/oasdiff/releases)（已使用 1.26.1
  完成联调）

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

## 本地运行

```bash
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 配置

```json
{
  "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 使用冒号：

```text
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` 可用于快速验证。

## 开发与测试

```bash
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](LICENSE)