# Swagger MCP (Multi-API Edition)
English | **[한국어](./README.md)**
---
An MCP server that helps AI understand and utilize Swagger/OpenAPI documentation.
> This is a custom fork of [Vizioz/Swagger-MCP](https://github.com/Vizioz/Swagger-MCP) with **multi-API support**.
## Key Features
- **Multi-API Support**: Manage multiple APIs with a single MCP server using `apis.yaml` config file
- **API Listing**: View all configured APIs with `listApis` tool
- **Endpoint Listing**: Query all endpoints of a specific API
- **Model Inspection**: View models used by specific endpoints
- **TypeScript Code Generation**: Auto-generate model interfaces and MCP tool definitions
- **Caching**: Local caching of Swagger definitions for faster queries
## Quick Start
### 1. Build Docker Image
```bash
# Clone repository
git clone https://github.com/your-username/swagger-mcp-multi.git
cd swagger-mcp-multi
# Build image
docker build -t swagger-mcp-multi:latest .
```
### 2. Create API Configuration File
Create `apis.yaml` in your **project's `.cursor/` folder**.
Use `apis.yaml.example` as a reference:
```yaml
# .cursor/apis.yaml
apis:
- name: petstore
description: Petstore API (Example)
url: https://petstore.swagger.io/v2/swagger.json
- name: my-api
description: My API Description
url: https://my-api.example.com/v3/api-docs
```
> **Important**: `apis.yaml` may contain sensitive information like API URLs. Consider adding it to your project's `.gitignore`.
### 3. Configure Cursor MCP
Add to your project's `.cursor/mcp.json`:
```json
{
"mcpServers": {
"api-docs": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/your/project/.cursor/apis.yaml:/app/apis.yaml:ro",
"swagger-mcp-multi:latest"
]
}
}
}
```
> **Important**: Replace `/path/to/your/project/.cursor/apis.yaml` with your actual project path.
### 4. Test
```bash
# Test API listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"listApis","arguments":{}}}' | \
docker run -i --rm -v /path/to/apis.yaml:/app/apis.yaml:ro swagger-mcp-multi:latest
```
## Available Tools
### listApis
Lists all configured APIs.
```
Input: None
Output: List of API names, descriptions, and URLs
```
### listEndpoints
Lists all endpoints of a specific API.
```
Input:
- apiName: API name (e.g., "petstore")
Output: List of endpoint paths, HTTP methods, and descriptions
```
### listEndpointModels
Lists models used by a specific endpoint.
```
Input:
- apiName: API name
- path: Endpoint path (e.g., "/users")
- method: HTTP method (e.g., "GET")
Output: Model names and schema information
```
### generateModelCode
Generates TypeScript interface code for a model.
```
Input:
- apiName: API name
- modelName: Model name
Output: TypeScript interface code
```
### generateEndpointToolCode
Generates MCP tool definition code for an endpoint.
```
Input:
- apiName: API name
- path: Endpoint path
- method: HTTP method
Output: MCP tool definition TypeScript code
```
### version
Returns the MCP server version.
## Usage Examples
### Asking AI for API Information
```
"Show me the endpoints of petstore API"
→ AI calls listApis to check APIs, then listEndpoints(apiName: "petstore")
"What models does the /users GET endpoint use in my-api?"
→ AI calls listEndpointModels(apiName: "my-api", path: "/users", method: "GET")
"Generate TypeScript interface for the User model"
→ AI calls generateModelCode(apiName: "petstore", modelName: "User")
```
## Local Development
### Requirements
- Node.js v20 or higher
- npm or pnpm
### Installation & Build
```bash
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run locally
node build/index.js
```
### Docker Compose
```bash
# Start service
docker-compose up -d
# View logs
docker-compose logs -f
```
## File Structure
```
swagger-mcp/ # MCP Server (Git repository)
├── apis.yaml.example # API config example file
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
└── src/
├── index.ts # MCP server entry point
├── tools/ # MCP tool definitions
│ ├── listApis.ts # [NEW] API listing
│ ├── listEndpoints.ts
│ ├── listEndpointModels.ts
│ ├── generateModelCode.ts
│ └── generateEndpointToolCode.ts
├── services/ # Business logic
└── utils/
├── apiConfigLoader.ts # [NEW] API config loader
├── swaggerLoader.ts # Swagger loader (multi-API support)
└── logger.ts
your-project/ # Your project
└── .cursor/
├── apis.yaml # API config file (create here!)
└── mcp.json # MCP server config
```
## Differences from Original Version
| Feature | Original Version | Multi-API Edition |
| ------------- | ---------------- | ------------------- |
| API Count | 1 (CLI argument) | Unlimited (config) |
| Adding APIs | Re-register MCP | Edit apis.yaml only |
| API Selection | Not available | `apiName` parameter |
| Configuration | CLI arguments | YAML config file |
## License
MIT License - Original project: [Vizioz/Swagger-MCP](https://github.com/Vizioz/Swagger-MCP)
