swagger-tools

MCP (Model Context Protocol) server for parsing, validating, and querying OpenAPI/Swagger specifications.

Features

• Parse OpenAPI 3.x and Swagger 2.0 specifications
• Validate specs against official schemas with detailed error reporting
• Query endpoints by method, path pattern, tag, or operation ID
• Inspect component schemas with resolved references
• Generate TypeScript interfaces from schemas
• Support both local files and remote URLs

Installation

git clone https://git.hyperlocalplatform.com/rimskij/swagger-tools.git
cd swagger-tools
npm install
npm run build

Configuration

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "swagger-tools": {
      "command": "node",
      "args": ["/path/to/swagger-tools/dist/index.js"]
    }
  }
}

Restart Claude Code after configuration.

Other MCP Clients

The server uses stdio transport. Run with:

node /path/to/swagger-tools/dist/index.js

Communicate via JSON-RPC 2.0 over stdin/stdout.

Tools

parse-spec

Parse an OpenAPI/Swagger spec and return metadata.

Input:

Parameter	Type	Required	Description
path	string	Yes	Path to spec file or URL

Output:

• Version (OpenAPI 3.x or Swagger 2.0)
• Title and description
• Server URLs
• Path count, operation count, schema count
• Tags

Example:

Parse the OpenAPI spec at ./api.yaml

---

validate-spec

Validate a spec against the OpenAPI schema.

Input:

Parameter	Type	Required	Description
path	string	Yes	Path to spec file or URL

Output:

• Validation status (pass/fail)
• Errors with JSON path locations
• Warnings (missing operationId, missing descriptions)

Example:

Validate https://petstore.swagger.io/v2/swagger.json

---

query-endpoints

Search and filter API endpoints.

Input:

Parameter	Type	Required	Description
path	string	Yes	Path to spec file or URL
method	string	No	Filter by HTTP method (GET, POST, etc.)
pathPattern	string	No	Regex pattern to match paths
tag	string	No	Filter by tag name
operationId	string	No	Filter by exact operation ID

Output:

• Matching endpoints with:
  • Method and path
  • Operation ID and summary
  • Tags
  • Parameters (name, location, required, schema)
  • Request body info
  • Response status codes and content types

Examples:

Show all GET endpoints in api.yaml
List endpoints with path matching /users in api.yaml
Find endpoints tagged "authentication" in api.yaml

---

get-schema

Get details of a component schema.

Input:

Parameter	Type	Required	Description
path	string	Yes	Path to spec file or URL
schemaName	string	Yes	Schema name in components/schemas

Output:

• Schema name and type
• Description
• Full JSON schema with resolved $refs

Example:

Show the User schema from api.yaml

---

generate-types

Generate TypeScript interfaces from schemas.

Input:

Parameter	Type	Required	Description
path	string	Yes	Path to spec file or URL
schemas	string[]	No	Specific schemas (all if omitted)

Output:

• TypeScript interface/type definitions
• JSDoc comments from descriptions
• Proper handling of:
  • Required vs optional properties
  • Enums as union types
  • Arrays and nested objects
  • allOf (intersection), oneOf/anyOf (union)
  • additionalProperties as Record<string, T>

Examples:

Generate TypeScript types from api.yaml
Generate only User and Order types from api.yaml

Supported Formats

Format	Version	File Types
OpenAPI	3.0.x	.yaml, .yml, .json
OpenAPI	3.1.x	.yaml, .yml, .json
Swagger	2.0	.yaml, .yml, .json

Input Sources

Source	Example
Local file (relative)	./api.yaml
Local file (absolute)	/path/to/api.yaml
Remote URL (HTTPS)	https://example.com/openapi.json
Remote URL (HTTP)	http://localhost:3000/api-docs

Architecture

src/
├── index.ts              # MCP server entry (stdio transport)
├── tools/
│   ├── parse.ts          # parse-spec implementation
│   ├── validate.ts       # validate-spec implementation
│   ├── query.ts          # query-endpoints implementation
│   ├── schema.ts         # get-schema implementation
│   └── generate.ts       # generate-types implementation
├── lib/
│   ├── parser.ts         # SwaggerParser wrapper
│   ├── validator.ts      # Validation logic
│   └── types.ts          # TypeScript type definitions
└── utils/
    └── format.ts         # Output formatting

Dependencies

Package	Purpose
@modelcontextprotocol/sdk	MCP server framework
@apidevtools/swagger-parser	Parse, validate, dereference specs
zod	Input schema validation

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Type check without emit
npm run typecheck

# Run in development (with tsx)
npm run dev

Testing

Manual test with JSON-RPC:

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js

# Parse a spec
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"parse-spec","arguments":{"path":"test/fixtures/petstore.yaml"}}}' | node dist/index.js

Example Output

parse-spec

# Pet Store API
Version: OpenAPI 3.0.3
Description: A sample Pet Store API

## Statistics
- Paths: 3
- Operations: 5
- Schemas: 5

## Servers
- https://api.petstore.example.com/v1

## Tags
- pets
- store

generate-types

/** A pet in the store */
export interface Pet {
  /** Unique identifier */
  id: number;
  /** Pet name */
  name: string;
  /** Pet availability status */
  status?: 'available' | 'pending' | 'sold';
  tags?: Tag[];
}

/** Pet availability status */
export type PetStatus = 'available' | 'pending' | 'sold';

License

MIT