OpenAPI Analyzer for Agents

A Model Context Protocol (MCP) server for analyzing large OpenAPI/Swagger documents (100K–1M+ lines) with AI agents — without overwhelming their context windows.

Large OpenAPI documents are impractical to feed directly to an LLM. This server keeps documents on disk and exposes targeted query tools — AI agents receive only structured results, never raw OpenAPI content.

Choose your path:

Mode	Best for	Jump to
Quick Start	Try it now with GitHub Copilot, no linting setup needed	↓
With Linting	(optional) Execute spectral rulesets using a linting orchestrator	↓
With Changelog	(optional) Compare versions, generate changelogs, detect breaking changes	↓
Local Development	Clone, build, test, or contribute	↓

MCP Tools

Document Management

get_upload_instructions — retrieve instructions for uploading and analyzing documents
list_documents — list documents with pagination and sorting (limit, offset, sortBy, sortOrder)
search_datastore — search by name, tags, organization, version, or isLatest flag

Document Analysis

get_document_info — retrieve document title, version, servers
list_operations — list all operations; filter by method, optionally exclude deprecated
search_operations — search by path, summary, description, operationId, or tags
extract_operations — paginated detailed extraction; filter by method, tag, deprecated (page_size up to 200)
get_security_schemes — all authentication and authorization schemes
get_schemas — all data models and schemas
validate_structure — basic OpenAPI structure validation
get_statistics — operation counts, method distribution

Linting (requires orchestrator)

list_rulesets — list available rulesets
lint_document — execute a lint job with the specified documents and ruleset
get_lint_status — check a lint job status
get_lint_results — retrieve lint findings; filter by severity
invalidate_lint_cache — clear cached results of a lint job

Linting requires the spectifyd orchestrator daemon, not included with npm install. Tools are always registered and return a 503 when the orchestrator is unavailable — all other tools are unaffected.

See With Linting Integration for setup instructions.

Comparison (requires oasdiff)

compare_documents — generate a changelog between two API versions
detect_breaking_changes — identify breaking changes between versions

oasdiff is an external Go binary, not included with npm install. Tools are always registered and return install guidance when the binary is not found on PATH.

See With Changelog / API Comparison for setup instructions.

Quick Start: Analysis with Copilot

Analyze OpenAPI documents using GitHub Copilot in minutes — no linting setup required.

1. Install and start

# Clone the MCP repo
git clone https://github.com/cisco-open/openapi-mcp-analyzer.git

# Install and start MCP (document-store is pulled from npm)
cd openapi-mcp-analyzer
npm install
npm run build
npm start

The server starts two listeners:

Upload API: http://localhost:3002 — accepts OpenAPI files via HTTP
MCP endpoint: http://localhost:3001/mcp — serves AI agents

2. Configure the AI Assistant

Add to your MCP settings (.vscode/mcp.json or VS Code user settings):

{
  "mcpServers": {
    "openapi-analysis": {
      "url": "http://localhost:3001/mcp",
      "transport": "streamable-http"
    }
  }
}

3. Upload an OpenAPI document

# Using the helper script
./tests/upload.sh path/to/your-api.yaml
# Returns: { "documentId": "abc-123-..." }

Or with curl and optional metadata:

curl -X POST http://localhost:3002/upload \
  -H "Content-Type: application/x-yaml" \
  -H "X-Filename: my-api.yaml" \
  -H "X-API-Name: My REST API" \
  -H "X-Tags: rest,v2,public" \
  -H "X-Organization: Engineering" \
  --data-binary @my-api.yaml

4. Analyze with Copilot

You: I uploaded an OpenAPI document with ID abc-123.
     What operations does it expose?

Copilot: [calls list_operations]
         The API exposes 18 operations across 5 resource types:
         - GET /pets, POST /pets, DELETE /pets/{id}  (Pets)
         - GET /users, POST /users, GET /users/{id}, PUT /users/{id}  (Users)
         ...

You: Are there any deprecated endpoints I should migrate away from?

Copilot: [calls list_operations with deprecated=true]
         3 deprecated operations found:
         - DELETE /legacy/pets — use DELETE /pets/{id} instead
         - GET /v1/status — replaced by GET /health
         ...

You: Show me the authentication schemes in use.

Copilot: [calls get_security_schemes]
         The API uses two auth schemes:
         - OAuth 2.0 (Authorization Code flow) — required on all /users endpoints
         - API Key (header: X-API-Key) — alternative for /pets endpoints

Start With Linting Integration

Add automated linting against configurable rulesets and breaking-change detection between API versions. Linting requires the spectifyd orchestrator daemon. The MCP server starts without it and auto-reconnects — analysis tools are always available.

Start the full stack

Option A — automated:

Pre-requisite: you've cloned and built both openapi-mcp-analyzer & linting-orchestrator repos

npm run start+orchestrator

Option B — manual (two terminals):

# Terminal 1: run the orchestrator daemon in companion mode and passthrough document-store
spectifyd

# Terminal 2: MCP server connects 
npm start

When connected:

✅ Spectify connection restored — linting features enabled
MCP Tools: 25 total (13 base + 5 linting + 5 batch + 2 oasdiff)

When the orchestrator is unavailable (graceful degradation):

⚠️  Spectify connection failed — linting features disabled
✅ MCP ready (upload, search, analysis work normally)

Example conversation with linting

You: Lint document abc-123 against the 'Contract Completeness' ruleset.

Copilot: [calls lint_document]
         Linting complete — 2 errors, 5 warnings.

         ERRORS (blocking):
         - POST /users: missing operation description  (rule: operation-description-required)
         - GET /orders/{id}: response 404 not documented  (rule: response-codes-defined)

         WARNINGS:
         - 3 operations missing example values
         - 2 schema properties lack descriptions

You: What rulesets are available?

Copilot: [calls list_rulesets]
         Available rulesets:
         - oas-recommended (default) — 42 rules
         - contract-completeness — 18 rules
         - custom-internal — 7 rules

You: I have a new version of the API. Are there any breaking changes from abc-123?

Copilot: [calls detect_breaking_changes with base=abc-123, revision=xyz-456]
         3 breaking changes detected:
         - DELETE /users/{id}: response body schema changed (removed field "legacyId")
         - POST /orders: required field "currency" added to request body
         - GET /products: path parameter renamed from "product_id" to "id"

For architecture details see ORCHESTRATOR_MCP_INTEGRATION_ARCHITECTURE.md and GRACEFUL_DEGRADATION.md.

With Changelog / API Comparison

Compare two uploaded API versions to generate a changelog or identify breaking changes. This uses oasdiff, an external Go binary that must be installed separately. The MCP server starts without it — comparison tools are always registered and return install guidance when the binary is not found on PATH.

Install oasdiff

brew install oasdiff                                                           # macOS
curl -fsSL https://raw.githubusercontent.com/oasdiff/oasdiff/main/install.sh | sh  # Linux/macOS
go install github.com/oasdiff/oasdiff@latest                                  # Go toolchain

See oasdiff.com for more options. No server restart is needed after installing — the MCP server detects the binary on the next tool call.

Example conversation with changelog

You: Upload the old version as abc-123 and the new version as xyz-456.
     What changed between them?

Copilot: [calls compare_documents with base=abc-123, revision=xyz-456]
         Changelog (12 changes):
         - GET /pets: added optional query parameter "status"
         - POST /orders: added required field "currency" to request body
         - DELETE /legacy/pets: endpoint removed
         ...

You: Are any of those breaking changes?

Copilot: [calls detect_breaking_changes]
         3 breaking changes detected:
         - POST /orders: required field "currency" added (existing clients will break)
         - DELETE /legacy/pets: endpoint removed
         - GET /products: path parameter renamed from "product_id" to "id"

Documentation

Quick Start Guide
Architecture
Linting Integration Architecture
Graceful Degradation
Pagination Configuration
MCP Compatibility Guide
StreamableHTTP Best Practices
Logging
Changelog
AGENTS.md — instructions for AI coding agents --

Local Development Setup

Prerequisites

Node.js ≥ 20.x
The @cisco_open/linting-document-store dependency is pulled from npm automatically via npm install.
Optional: a local clone of linting-orchestrator side-by-side, only if you want to run the spectifyd linting daemon from source:

parent-dir/
├── openapi-mcp-analyzer/    ← this repo
└── linting-orchestrator/    ← optional companion repo (linting daemon)

Clone and build

git clone https://github.com/cisco-open/openapi-mcp-analyzer.git

# Install and build MCP (document-store is pulled from npm)
cd openapi-mcp-analyzer
npm install
npm run build

Dependency note: @cisco_open/linting-document-store is resolved from the npm registry (latest) in package.json. Run npm install to pull the latest published version.

Development scripts

npm run dev                  # watch mode (tsc + node --watch)
npm start                    # production (pre-built)
npm run start+orchestrator   # full stack with spectifyd
npm run build                # compile TypeScript only

Testing

The test suite uses Bats (Bash Automated Testing System) — 50 independent test cases across three files.

Automated (starts and stops the server for you):

npm run test:integration                # 28 tests — no orchestrator needed
npm run test:integration+orchestrator   # 50 tests — full stack

Manual (server already running in another terminal):

npm run test:base           # 14 base tool tests
npm run test:orchestrator   # 22 linting tool tests
npm run test:oasdiff        # 14 comparison tool tests
npm run test:all            # all 50

Test coverage:

Test file	Tests	Tools covered
`test-tools.bats`	14	get_document_info, list_operations, extract_operations, search_operations, get_schemas, get_security_schemes, get_statistics, validate_structure
`test-orchestrator-integration.bats`	22	lint_document, get_lint_status, get_lint_results, list_rulesets, invalidate_lint_cache
`test-oasdiff-integration.bats`	14	compare_documents, detect_breaking_changes
Total	50	All 25 MCP tools

See tests/README.md for detailed test documentation.

--

HTTP API Reference

Method	Endpoint	Description
`POST`	`/upload`	Upload an OpenAPI document
`GET`	`/documents`	List all documents with metadata
`GET`	`/documents/:id`	Get document metadata
`DELETE`	`/documents/:id`	Delete a document
`POST`	`/search`	Search documents by metadata
`GET`	`/stats`	Cache and datastore statistics
`GET`	`/health`	Health check

Upload headers:

Content-Type: application/json or application/x-yaml (required)
X-Filename: document filename (required)
X-API-Name, X-Tags, X-Owner, X-Organization, X-Description: optional metadata

Configuration

Priority order: CLI arguments > environment variables > config.yaml > defaults.

# config.yaml
logLevel: INFO          # DEBUG | INFO | WARN | ERROR  (default: DEBUG)
uploadPort: 3002        # HTTP upload server port
mcpPort: 3001           # MCP server port
datastoreDir: ./datastore
datastoreQuotaGB: 10
cacheMaxSize: 100       # max documents in memory cache
defaultPageSize: 50     # default pagination size

Equivalent environment variables: LOG_LEVEL, UPLOAD_PORT, MCP_PORT, DATASTORE_DIR, DATASTORE_QUOTA_GB, CACHE_MAX_SIZE, DEFAULT_PAGE_SIZE.

See docs/PAGINATION_CONFIG.md and docs/maintainers/LOGGING.md for details.

Architecture

Why MCP + separate HTTP upload?

MCP is designed for structured JSON messages, not multi-megabyte file transfers. A separate HTTP endpoint handles uploads via standard curl or multipart. MCP then exposes targeted query tools — LLMs receive only structured results, never raw OpenAPI content.

curl / upload.sh ──────▶  HTTP Upload API (port 3002)
                          Fastify + metadata headers
                                    │
                          DocumentCoordinator
                    ┌───────────────┴────────────────┐
               DocumentCache              DatastoreManager
               (1h TTL, LRU)          (./datastore/, no expiry)
                    └───────────────┬────────────────┘
                                    │
Copilot / Claude ──────▶  MCP Server (port 3001)
                          StreamableHTTP, stateless
                          Analyzer + Extractor

Storage model

All documents persisted to ./datastore/ — no automatic expiry, 10 GB default quota
In-memory cache (1h TTL, max 100 docs) — write-through on upload, cache-aside on miss
Cache and datastore are architecturally separated (supports future migration to Redis/S3)

Linting orchestrator

MCP connects to the spectifyd daemon over HTTP (port 3004 companion mode, 3003 standalone)
Graceful degradation: linting tools return 503 when the orchestrator is unavailable; all other tools unaffected
Auto-reconnection every 30 seconds

Extending analysis

To add a custom analysis tool:

Add a method to src/analyzer.ts
Register the tool in src/mcp-streamable-server.ts
Rebuild: npm run build

See docs/maintainers/ARCHITECTURE.md for the full system design.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md for our security policy and how to report vulnerabilities.

Code of Conduct

See CODE_OF_CONDUCT.md.

License

This software is licensed under the Apache License 2.0. See LICENSE for details.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github		.github
changelogs		changelogs
docs		docs
dumps		dumps
examples		examples
openapi		openapi
scripts		scripts
src		src
tests		tests
tools		tools
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MAINTAINERS.md		MAINTAINERS.md
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
config-orchestrator-disabled.yaml		config-orchestrator-disabled.yaml
config-pagination-10.yaml		config-pagination-10.yaml
config.yaml		config.yaml
mcp-config.example.json		mcp-config.example.json
package-lock.json		package-lock.json
package.json		package.json
test-results.xml		test-results.xml
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

OpenAPI Analyzer for Agents

MCP Tools

Document Management

Document Analysis

Linting (requires orchestrator)

Comparison (requires oasdiff)

Quick Start: Analysis with Copilot

1. Install and start

2. Configure the AI Assistant

3. Upload an OpenAPI document

4. Analyze with Copilot

Start With Linting Integration

Start the full stack

Example conversation with linting

With Changelog / API Comparison

Install oasdiff

Example conversation with changelog

Documentation

Local Development Setup

Prerequisites

Clone and build

Development scripts

Testing

HTTP API Reference

Configuration

Architecture

Why MCP + separate HTTP upload?

Storage model

Linting orchestrator

Extending analysis

Contributing

Security

Code of Conduct

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Uh oh!

Contributors

Uh oh!

Languages