Skip to main content
Glama
xiaohuxi

OpenAPI Contract Guard MCP

by xiaohuxi
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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 变更日志

Related MCP server: swagger-mcp

安全边界

  • 全部工具只读，不修改接口文档。

  • 本地文件只能来自 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

Available Tools

4 tools
compare_specsC

Compare two OpenAPI documents and return the complete structural diff.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseYes
revisionYes
output_formatNotext

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the action but omits details about authentication, rate limits, side effects, or the nature of the diff (e.g., read-only). The minimal transparency leaves critical behavioral traits unaddressed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no waste. It is front-loaded with the primary action. However, it could be restructured to include key details without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, 2 required, no output schema shown despite presence), the description is insufficient. It fails to specify return format, parameter constraints, or how this tool differs from siblings. The lack of parameter and output documentation leaves the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description adds no explanation for the parameters 'base', 'revision', or 'output_format'. The agent cannot infer input format (e.g., file path vs. URL) or the meaning of 'output_format' options beyond the default 'text'. This is a critical gap given the lack of schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Compare two OpenAPI documents and return the complete structural diff,' which specifies the verb (compare) and resource (OpenAPI documents) and distinguishes this tool from siblings like validate_spec, list_breaking_changes, and generate_changelog.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, when-not-to-use, or refer to sibling tools, leaving the agent to infer usage from the purpose alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_changelogC

Generate a categorized changelog between two OpenAPI documents.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseYes
revisionYes
output_formatNotext

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavioral traits, but it only states it 'generates a changelog'. It does not mention if the tool is read-only, requires specific permissions, or what 'categorized' entails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, which is efficient, but it lacks any structure (e.g., bullet points) and omits critical details, making it overly brief.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no schema description coverage, and an output schema exists but is not described, the description is severely incomplete. It provides no guidance on usage, behavior, or parameter semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description provides no details about the parameters base, revision, or output_format. It fails to explain their meaning, expected format (e.g., file paths or raw content), or allowed values for output_format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'generate', the resource 'categorized changelog', and the scope 'between two OpenAPI documents'. This effectively distinguishes it from sibling tools like validate_spec, compare_specs, and list_breaking_changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as compare_specs or list_breaking_changes. There is no mention of context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_breaking_changesC

List changes in the revision that may break existing API clients.

ParametersJSON Schema
NameRequiredDescriptionDefault
baseYes
revisionYes
output_formatNotext

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes the basic output (breaking changes) but lacks details on behavior such as whether it returns a list, error scenarios, or if output_format affects content. Since no annotations are provided, the description carries full burden and is moderately transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is very concise but too brief, lacking structure and detail. It front-loads the purpose but omits necessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 parameters and no schema descriptions, the description is incomplete. It does not explain parameters or output details, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description makes no mention of parameters. The agent has no clues about what 'base' and 'revision' represent, nor the options for 'output_format'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's action as listing breaking changes in a revision. It distinguishes from sibling tools: validate_spec (validation), compare_specs (comparison), and generate_changelog (full changelog).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use or not use this tool versus siblings. No context on prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_specA

Validate a local OpenAPI 3.x file without resolving external references.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description effectively discloses the key behavioral trait of not resolving external references, which sets expectations for validation scope. It does not explicitly state that the tool is read-only, but that is implicit for a validator.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys all essential information without redundancy. Every word serves a purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, output schema present), the description provides sufficient context for the agent to understand its behavior and constraints. It could mention that it returns validation results, but the output schema likely covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to the single parameter 'source' by indicating it refers to a local OpenAPI 3.x file, but it does not specify whether it expects a file path or file content. With 0% schema coverage, the description partially compensates, but more detail on input format would help.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Validate'), the resource ('a local OpenAPI 3.x file'), and a key constraint ('without resolving external references'), making the tool's purpose distinct from siblings like compare_specs or list_breaking_changes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (validating a local spec file) but does not explicitly contrast with sibling tools or mention when not to use. It could be improved by specifying that this tool is for local files only and does not compare or generate changelogs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observedcompare_specs
    • First observedgenerate_changelog
    • First observedlist_breaking_changes
    • First observedvalidate_spec
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation5/5

Each tool has a distinct purpose: validation, comparison, breaking changes, and changelog generation. No overlapping functionality.

Naming Consistency5/5

All tool names follow the verb_noun pattern (validate_spec, compare_specs, list_breaking_changes, generate_changelog) with consistent snake_case.

Tool Count5/5

Four tools is appropriate for the focused domain of OpenAPI specification analysis, covering key workflows without unnecessary clutter.

Completeness4/5

The set covers validation, comparison, breaking changes, and changelog generation, but missing features like linting or reference resolution validation.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • swagger-mcp

    yunhwane
    A
    license
    B
    quality
    D
    maintenance
    Enables natural language exploration of OpenAPI/Swagger specs, allowing users to register APIs, browse endpoints, describe schemas, and detect breaking changes through conversational queries.
    9
    214
    MIT

  • SpecShield MCP Server

    specshield-io
    A
    license
    A
    quality
    B
    maintenance
    A read-only API change deploy gate for AI coding agents that analyzes OpenAPI specs to determine if changes are safe to deploy. It provides tools for comparing specs, explaining breaking changes, and generating migration guides.
    5
    73
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/xiaohuxi/openapi-contract-guard-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server