Content
# Swagger MCP Server
[](https://smithery.ai/server/@tuskermanshu/swagger-mcp-server)
A server based on Model Context Protocol (MCP) for parsing Swagger/OpenAPI documents and generating TypeScript types and API client code.
## Features
- Parses Swagger/OpenAPI documents, supporting v2 and v3 specifications
- Generates TypeScript type definitions
- Generates API client code for different frameworks (Axios, Fetch, React Query, etc.)
- Provides these functionalities via the MCP protocol, facilitating integration with large language models
- **Optimized handling of large documents**:
- Memory and file system caching mechanisms
- Lazy loading parsing strategy
- Incremental parsing and partial result returns
- Progress feedback
- Automatic recognition of different formats of Swagger UI URLs
## Quick Start
### Install Dependencies
```bash
npm install
# or use pnpm
pnpm install
```
### Start the Server
```bash
node start-server.js
```
The server communicates via standard input/output by default.
### Using MCP Tools
You can communicate with the MCP server through standard input/output. Here are some examples:
```bash
# 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)
```json
{
"method": "parse-swagger",
"params": {
"url": "https://petstore3.swagger.io/api/v3/openapi.json",
"includeSchemas": true,
"includeDetails": true
}
}
```
#### Optimized Parser (parse-swagger-optimized)
Suitable for complete parsing with advanced options:
```json
{
"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"
}
}
```
#### Lightweight Parser (parse-swagger-lite)
Optimized for large documents, fast but only returns basic information:
```json
{
"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)
```json
{
"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)
```json
{
"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)
```json
{
"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)
```json
{
"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
```json
{
"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:
1. Use optimized tools with caching and lazy loading enabled
2. Filter by tags or path prefixes to only retrieve the necessary API operations
3. Include schema definitions only when necessary
4. Set a reasonable cache expiration time to avoid frequent re-parsing
Example:
```json
{
"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
Currently, the following API client frameworks are supported:
- **Axios**: A fully-featured Promise-based HTTP client
- **Fetch**: Native browser API with no additional dependencies
- **React Query**: A data fetching and caching library for React applications, providing hooks and caching functionality
Example - Generating a React Query client:
```json
{
"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 the `useCache: false` parameter
## Configuration Options
You can customize server settings in `swagger-mcp-config.json`:
```json
{
"name": "Swagger MCP Server",
"version": "1.0.0",
"transport": "stdio"
}
```
## Development and Debugging
Start the debug server:
```bash
node start-server.js
```
Then connect using MCP Inspector:
```bash
npx @modelcontextprotocol/inspector pipe -- node start-server.js
```
Or directly (but may cause output confusion):
```bash
npx @modelcontextprotocol/inspector -- node start-server.js
```
## Project Roadmap
Refer to the [road.md](road.md) file for development plans and progress.
## Installation
### Install via Smithery
To automatically install swagger-mcp-server for Claude Desktop via [Smithery](https://smithery.ai/server/@tuskermanshu/swagger-mcp-server):
```bash
npx -y @smithery/cli install @tuskermanshu/swagger-mcp-server --client claude
```
## Build
```bash
# Build the project
npm run build
# Or use pnpm
pnpm build
```
## Available MCP Tools
1. `parse-swagger` - Parses Swagger/OpenAPI documents and returns API operation information
2. `parse-swagger-optimized` - Parses Swagger/OpenAPI documents (optimized version)
3. `parse-swagger-lite` - Lightweight parsing of Swagger/OpenAPI documents, optimized for large documents
4. `generate-typescript-types` - Generates TypeScript type definitions from Swagger/OpenAPI documents
5. `generate-typescript-types-optimized` - Generates TypeScript type definitions from Swagger/OpenAPI documents (optimized version)
6. `generate-api-client` - Generates API client code from Swagger/OpenAPI documents
7. `generate-api-client-optimized` - Generates API client code from Swagger/OpenAPI documents (optimized version)
8. `file-writer` - Writes content to the file system
