oaslint-mcp

Ask your AI agent "is this API change safe to release?" and get a real answer.

oaslint-mcp is an MCP server that lints OpenAPI and Swagger specs and, above all, detects breaking changes between two versions of a spec. It runs offline, reads files only, and never fetches a URL.

Why another OpenAPI diff tool?

Other MCP servers already diff OpenAPI specs (for example Specwise, which needs OpenAPI 3.x for diffs, or the hosted Apify actors). What this one does differently:

• One engine for Swagger 2.0, OpenAPI 3.0 and 3.1, including across versions. A 2.0 spec and its 3.1 rewrite show no changes (nullable: true equals type: [x, "null"], const equals a one-value enum, consumes/produces equal content, csv arrays equal explode: false).

• Request/response variance. The same edit is breaking in a request and harmless in a response (and the reverse): removing an enum value, adding a property, loosening a limit. Each finding says which question it answered.

• Flattened before compared. allOf is merged, $ref and inline are the same thing, reordered keys and renamed components do not show up.

• Honest about uncertainty. oneOf/anyOf/discriminator changes and enum values added to a response are reported as POTENTIALLY_BREAKING with the reason, not guessed.

• Lints and validates too, with a JSON pointer and the source line on every finding.

• Local and sandboxed: nothing leaves your machine; file access is limited to --dir.

Related MCP server: mcp-api-guardian

Tools

spec, old and new are paths to .yaml/.yml/.json files inside the allowed directory (relative paths work), or the spec text pasted inline.

What counts as breaking

In a request the server validates input, so tightening breaks clients: a new required parameter or property, a narrower type, removed enum values, a new pattern, a higher minimum, additionalProperties: false, a removed content type, stricter auth or extra scopes. In a response clients rely on output, so loosening or dropping a guarantee breaks them: a removed property, required to optional, a changed type, nullable added, a removed success code or content type. Enum values added to a response are POTENTIALLY_BREAKING (strict clients). operationId changes are non-breaking but called out.

Install

Needs uv. Replace the folder with the one that holds your specs.

Claude Code

claude mcp add oaslint -- uvx oaslint-mcp --dir "/path/to/your/specs"

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "oaslint": {
      "command": "uvx",
      "args": ["oaslint-mcp", "--dir", "C:\\path\\to\\your\\specs"]
    }
  }
}

--dir (or the OASLINT_DIR environment variable) defaults to the current directory.

Try asking

• "Give me an overview of openapi.yaml."

• "Lint openapi.yaml and fix the errors first."

• "Compare api-v1.yaml with api-v2.yaml. Is it safe to release? List every breaking change."

• "Write the changelog for v2 as markdown."

• "Which endpoints are tagged orders and still use POST?"

• "Describe PATCH /orders/{id}, including what a 409 returns."

• "Is {"name": "x", "qty": "3"} a valid request body for POST /orders?"

Security

• Read-only and offline. The server never writes files and never opens a network connection. Remote $refs (http://, https://) are reported as unresolved with a note, never fetched.

• Sandboxed. Every file, including relative $ref targets, must resolve (symlinks followed) to a path inside --dir. ../ traversal, absolute paths and symlink escapes are refused.

• Hostile input guards. 50 MB file cap, line cap, nesting-depth cap, YAML alias-bomb (billion laughs) cap, yaml.safe_load semantics only (no Python tags), duplicate keys warned about, catastrophic-backtracking patterns skipped with a note.

• No secrets in output. Values that look like secrets (API keys, JWTs, long tokens, values under keys such as password, URL credentials) are shown as <redacted>; names are kept.

Limits to know about: JSON Schema pattern is evaluated with Python's regex engine (ECMA-262 differences are possible), not / if / patternProperties / prefixItems are compared as opaque text and reported as POTENTIALLY_BREAKING when they change, and line numbers are best-effort (the nearest existing node when a pointer goes through allOf or a $ref).

Development

uv sync --extra test
uv run pytest
uv run ruff check src tests
uv run mypy --strict src

Learn how it works by building a small version yourself: oaslint-mcp-the-hard-way.

MIT licensed.