rimskij cc789d3b32 feat: initial MCP server for OpenAPI/Swagger parsing

- Parse and validate OpenAPI 3.x / Swagger 2.0 specs
- Query endpoints by method, path pattern, tag, operationId
- Get component schema details
- Generate TypeScript interfaces from schemas
- Support local files and remote URLs

Tools: parse-spec, validate-spec, query-endpoints, get-schema, generate-types

Co-Authored-By: Claude <noreply@anthropic.com>

2026-01-12 14:33:10 +01:00

2.2 KiB

Raw Blame History

swagger-tools

MCP server for parsing, validating, and querying OpenAPI/Swagger specifications.

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run (for testing)
npm start

MCP Server Configuration

Add to ~/.claude.json (or project .mcp.json):

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

After configuring, restart Claude Code. The tools will be available as:

mcp__swagger-tools__parse-spec
mcp__swagger-tools__validate-spec
mcp__swagger-tools__query-endpoints
mcp__swagger-tools__get-schema
mcp__swagger-tools__generate-types

Claude Code Slash Command

Use /openapi for convenient access:

/openapi parse api.yaml          # Parse and show overview
/openapi validate api.yaml       # Validate spec
/openapi endpoints api.yaml      # List all endpoints
/openapi schema api.yaml User    # Get schema details
/openapi types api.yaml          # Generate TypeScript types

Project Structure

src/
├── index.ts           # MCP server entry point (stdio)
├── tools/             # MCP tool implementations
│   ├── parse.ts       # parse-spec tool
│   ├── validate.ts    # validate-spec tool
│   ├── query.ts       # query-endpoints tool
│   ├── schema.ts      # get-schema tool
│   └── generate.ts    # generate-types tool
├── lib/               # Core library
│   ├── parser.ts      # OpenAPI parsing wrapper
│   ├── validator.ts   # Validation logic
│   └── types.ts       # TypeScript types
└── utils/
    └── format.ts      # Output formatting

.claude/
└── commands/
    └── openapi.md     # Slash command definition

Development

# Type check without building
npm run typecheck

# Run with tsx (development)
npm run dev

Supported Formats

OpenAPI 3.0.x
OpenAPI 3.1.x
Swagger 2.0
YAML and JSON files

Dependencies

@modelcontextprotocol/sdk - MCP server framework
@apidevtools/swagger-parser - OpenAPI parsing and validation
zod - Schema validation for tool inputs

2.2 KiB Raw Blame History