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 features through the MCP protocol, facilitating integration with large language models
- **Optimized Large Document Handling**:
- Memory and file system caching mechanisms
- Lazy loading parsing strategy
- Incremental parsing and partial result return
- Progress feedback
- Automatically identifies Swagger UI URLs in different formats
## Quick Start
### Install Dependencies
```bash
npm install
# Or use pnpm
pnpm install
```
### Start the Server
```bash
node start-server.js
```
The server uses standard input/output communication by default.
### Use MCP Tools
You can communicate with the MCP server via 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 Parsing Tool (parse-swagger)
```json
{
"method": "parse-swagger",
"params": {
"url": "https://petstore3.swagger.io/api/v3/openapi.json",
"includeSchemas": true,
"includeDetails": true
}
}
```
#### Optimized Parsing Tool (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 Parsing Tool (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 Writer 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 configurations:
1. Use the optimized version of the tools, enabling caching and lazy loading
2. Use tag or path prefix filtering to only retrieve the required 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 comprehensive Promise-based HTTP client
- **Fetch**: Browser native API, no additional dependencies required
- **React Query**: A data fetching and caching library for React applications, providing hooks and caching features
Example - Generating 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 cache is stored in the `.api-cache` directory. If you need 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 clutter):
```bash
npx @modelcontextprotocol/inspector -- node start-server.js
```
## Project Roadmap
See 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
