oaslint MCP — The Hard Way

Build a small MCP server that lints OpenAPI specs and detects breaking changes between two versions of an API, from the first byte of YAML to an agent calling your tools over stdio.

At the end you will have built a compact version of oaslint-mcp yourself, and you will understand the idea that almost every API-diff tool gets subtly wrong: a request and a response vary in opposite directions, so the very same edit is breaking in one and harmless in the other.

Why This Exists

Most MCP tutorials wrap a REST call. The interesting work in a useful server is elsewhere:

• reading hostile, messy input safely (YAML bombs, $ref loops, ../../ paths, URLs that want to be fetched);

• turning three dialects of a format into one model, so the rules are written once;

• deciding what a change means, not just that it happened;

• failing in ways that tell the agent what to do next.

Related MCP server: OpenAPI Contract Guard MCP

Who This Is For

Developers who have a "hello world" MCP server and want to build one that earns its keep, and anyone who has shipped an API change and found out afterwards that it broke a client.

Prerequisites: Python and a rough idea of what OpenAPI is. Nothing to install except pip install -r requirements.txt (the MCP SDK, PyYAML and anyio). No network, no other services.

Modules

Each module contains:

• README.md: the concept, the listing of the new lite/ file (embedded from the real file, and CI fails if they drift apart), a walk-through, how to run it, how to break it, and what the full server does differently;

• main.py: runnable code that uses the new file and asserts its results.

Running It

pip install -r requirements.txt
python verify.py          # every module, the way CI does
python verify.py 05       # one module
python 05-classifying-changes/main.py

The sample APIs are in specs/: the same small shop written as Swagger 2.0, OpenAPI 3.0 and 3.1, a second version with real breaking changes, a recursive schema, and a split spec with file refs plus an evil.yaml that tries to read outside the sandbox.

The Library, File by File

lite/loader.py    01  parse, detect the version, normalise operations
lite/refs.py      02  Resolver: $ref, cycles, sandboxed files
lite/walk.py      03  outline of a (possibly recursive) schema
lite/flat.py      04  flatten allOf, normalise nullable
lite/diff.py      05  classify changes by direction
lite/validate.py  06  validate a JSON document
lite/server.py    07  the MCP server

Each module adds exactly one file. Nothing is hidden in a framework.

MIT licensed.