Spectacle

An MCP server that lets Claude (and other MCP clients) query, search, and explore OpenAPI specifications. Point it at a spec file and ask questions about endpoints, parameters, schemas, and more.

Supports OpenAPI 3.x (JSON/YAML) and Swagger 2.0 (auto-converted).

Tools

Tool	Description
spec_load	Load an OpenAPI/Swagger spec from a local file path
list_endpoints	List all endpoints, optionally filtered by HTTP method or tag
get_endpoint	Get detailed info about a specific endpoint (brief/normal/full verbosity)
search_endpoints	Full-text search across endpoints with relevance ranking

Setup

Prerequisites

• Node.js 18+
• pnpm

Install

git clone https://github.com/your-username/spectacle-mcp.git
cd spectacle-mcp
pnpm install

Configure in Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "spectacle": {
      "command": "pnpm",
      "args": ["tsx", "/absolute/path/to/spectacle-mcp/src/index.ts"],
    }
  }
}

Usage

Once configured, Claude can use the tools directly. Some example prompts:

"Load the spec at ./openapi.yaml and list all endpoints"

"What parameters does POST /users accept?"

"Search the API for anything related to authentication"

"Show me the full details of GET /orders/{id} including response schemas"

Tool details

spec_load — Load and cache a spec. Swagger 2.0 files are automatically converted to OpenAPI 3.x. Specs are cached in memory and reloaded when the file changes.

list_endpoints — Two output formats:

• compact — one line per endpoint (GET /pets)
• grouped — organized by tag with summaries

get_endpoint — Three verbosity levels:

• brief — method, path, summary
• normal — adds parameters, request body, response codes
• full — adds complete expanded schemas

search_endpoints — Keyword search with AND semantics (all terms must match). Results are ranked by relevance with weighted field scoring (path > operationId > summary > tags > parameters > description). Three return formats: snippets, ids, or full.

Development

pnpm start       # Run the MCP server
pnpm dev         # Run with file watching (auto-restart on changes)

Running tests

pnpm tsx test/smoke.ts         # Integration tests
pnpm tsx test/swagger2-test.ts # Swagger 2.0 conversion tests

Project structure

src/
  index.ts    — MCP server setup and tool registration
  spec.ts     — Spec loading, caching, $ref resolution, and indexing
  format.ts   — Output formatting and search scoring
test/
  petstore.yaml     — OpenAPI 3.0 test fixture
  swagger2.json     — Swagger 2.0 test fixture
  smoke.ts          — Integration tests
  swagger2-test.ts  — Conversion tests