Swagger MCP Server for API Documentation and Code Generation

Overview

The Swagger MCP Server is a Model Context Protocol (MCP)-based server designed to parse Swagger/OpenAPI documents and generate TypeScript types and API client code. It supports both Swagger v2 and OpenAPI v3 specifications and integrates seamlessly with large language models through the MCP protocol.

Key Features

• Swagger/OpenAPI Parsing: Supports both v2 and v3 specifications.
• TypeScript Type Generation: Automatically generates TypeScript type definitions.
• API Client Code Generation: Generates client code for frameworks like Axios, Fetch, and React Query.
• Optimized for Large Documents: Includes memory and file system caching, lazy loading, and incremental parsing.
• Progress Tracking: Provides feedback on the progress of large document processing.

Quick Start

Installation

npm install
# or using pnpm
pnpm install

Starting the Server

node start-server.js

Using MCP Tools

You can interact with the MCP server using standard input/output. Examples include:

# Parse Swagger document
node examples/optimized-swagger-parser-example.js

# Generate TypeScript types
node examples/typescript-generator-example.js

# Generate API client
node examples/api-client-generator-example.js

Available Tools

1. Swagger/OpenAPI Parsing Tools

Standard Parser (parse-swagger)

{
  "method": "parse-swagger",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": true,
    "includeDetails": true
  }
}

Optimized Parser (parse-swagger-optimized)

{
  "method": "parse-swagger-optimized",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": true,
    "includeDetails": true,
    "useCache": true,
    "skipValidation": true,
    "cacheTTLMinutes": 60,
    "lazyLoading": false,
    "filterTag": "pet"
  }
}

Lite Parser (parse-swagger-lite)

{
  "method": "parse-swagger-lite",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": false,
    "includeDetails": false,
    "useCache": true,
    "skipValidation": true
  }
}

2. TypeScript Type Generation Tools

Standard Type Generator (generate-typescript-types)

{
  "method": "generate-typescript-types",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/types",
    "namespace": "PetStore",
    "strictTypes": true,
    "generateEnums": true,
    "generateIndex": true
  }
}

Optimized Type Generator (generate-typescript-types-optimized)

{
  "method": "generate-typescript-types-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/types",
    "namespace": "PetStore",
    "strictTypes": true,
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "includeSchemas": ["Pet", "Order", "User"]
  }
}

3. API Client Generation Tools

Standard API Client Generator (generate-api-client)

{
  "method": "generate-api-client",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/api",
    "clientType": "axios",
    "generateTypeImports": true,
    "typesImportPath": "../types",
    "groupBy": "tag"
  }
}

Optimized API Client Generator (generate-api-client-optimized)

{
  "method": "generate-api-client-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/api",
    "clientType": "react-query",
    "generateTypeImports": true,
    "typesImportPath": "../types",
    "groupBy": "tag",
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "includeTags": ["pet", "store"]
  }
}

4. File Writing Tool (file-writer)

{
  "method": "file-writer",
  "params": {
    "filePath": "./output.txt",
    "content": "Hello, world!",
    "createDirs": true
  }
}

Handling Large API Documents

For large API documents, it is recommended to use the following configuration:

{
  "method": "parse-swagger-lite",
  "params": {
    "url": "https://your-large-api-doc-url.json",
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "filterTag": "your-specific-tag",
    "includeSchemas": false
  }
}

Supported Client Frameworks

• Axios: A promise-based HTTP client.
• Fetch: The browser-native API, no additional dependencies required.
• React Query: A data-fetching and caching library for React applications.

Example: Generating a React Query client:

{
  "method": "generate-api-client-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/react-query",
    "clientType": "react-query",
    "generateTypeImports": true
  }
}

Cache Management

API document caches are stored in the .api-cache directory. To clear the cache:

1. Delete the .api-cache directory.
2. Or set useCache: false in the parameters.

Configuration Options

Customize server settings in swagger-mcp-config.json:

{
  "name": "Swagger MCP Server",
  "version": "1.0.0",
  "transport": "stdio"
}

Development and Debugging

Start the debug server:

node start-server.js

Connect using MCP Inspector:

npx @modelcontextprotocol/inspector pipe -- node start-server.js

Project Roadmap

Refer to road.md for development plans and progress.

Installation via Smithery

To automatically install the Swagger MCP Server for Claude Desktop using Smithery:

npx -y @smithery/cli install @tuskermanshu/swagger-mcp-server --client claude

Build

# Build the project
npm run build

# Or using pnpm
pnpm build

Available MCP Tools

1. parse-swagger - Parses Swagger/OpenAPI documents and returns API operation information.
2. parse-swagger-optimized - Optimized version of the Swagger/OpenAPI parser.
3. parse-swagger-lite - Lightweight parser optimized for large documents.
4. generate-typescript-types - Generates TypeScript type definitions from Swagger/OpenAPI documents.
5. generate-typescript-types-optimized - Optimized version of the TypeScript type generator.
6. generate-api-client - Generates API client code from Swagger/OpenAPI documents.
7. generate-api-client-optimized - Optimized version of the API client generator.
8. file-writer - Writes content to the file system.