Swagger MCP

🚀 Swagger-based MCP Server

This is a server that processes Swagger/OpenAPI specifications through the Model Context Protocol (MCP).

🚀 Quick Start

The Swagger-based MCP Server is designed to handle Swagger/OpenAPI specifications using the Model Context Protocol (MCP). It provides a range of features for API management and interaction.

✨ Features

• Load Swagger/OpenAPI specifications.
• Support multiple authentication methods:
  • Basic Authentication
  • Bearer Token
  • API Key (Header or Query)
  • OAuth2
• Automatically generate MCP tools from API endpoints.
• Support Server-Sent Events (SSE) for real-time communication.
• Provide TypeScript support.

⚠️ Security

⚠️ Important Note

This is a personal server! Do not expose it to the public internet. If the underlying API requires authentication, the MCP server should not be exposed to the public internet.

📋 To-Do

• Secrets - The MCP server should be able to use user secrets to authenticate requests.
• Comprehensive test suite.

📦 Prerequisites

• Node.js (v18 or higher)
• Yarn package manager
• TypeScript

📦 Installation

1. Clone the repository:

git clone https://github.com/dcolley/swagger-mcp.git
cd swagger-mcp

2. Install dependencies:

yarn install

3. Create a .env file based on the example:

cp .env.example .env

4. Configure your Swagger/OpenAPI specification:

   • Place your Swagger file in the project (e.g., swagger.json).
   • Or provide a URL to your Swagger specification.

5. Update the server settings in config.json:

{
  "server": {
    "host": "localhost",
    "port": 3000
  },
  "swagger": {
    "url": "url-or-path/to/your/swagger.json",
    "apiBaseUrl": "https://api.example.com",  // Backup URL if not specified in Swagger
    "defaultAuth": {  // Backup settings if authentication scheme is not specified in Swagger
      "type": "apiKey",
      "apiKey": "your-api-key",
      "name": "Authorization",
      "value": "Bearer ${ apiKey }"
    }
  }
}

💻 Usage Examples

Basic Usage

• Start the development server:

yarn dev

• Build for production:

yarn build

📚 Documentation

API Endpoints

Get all documents

GET /api-docs

Get a document by name

GET /api-docs/{name}

Publish a document

POST /api-docs

Delete a document

DELETE /api-docs/{name}

Authentication Methods

Basic Authentication

Configuration example:

{
  "defaultAuth": {
    "type": "basic",
    "username": "your-username",
    "password": "your-password"
  }
}

Bearer Token

Configuration example:

{
  "defaultAuth": {
    "type": "bearer",
    "token": "your-bearer-token"
  }
}

API Key

Configuration example:

{
  "defaultAuth": {
    "type": "apiKey",
    "key": "your-api-key",
    "name": "X-API-Key",
    "value": "${ key }"
  }
}

OAuth2

Configuration example:

{
  "defaultAuth": {
    "type": "oauth2",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "accessTokenUrl": "https://example.com/oauth/token",
    "authorizationUrl": "https://example.com/oauth/authorize"
  }
}

Environment Variables

• NEXT_PUBLIC_API_BASE_URL - By default, the API base URL.
• NEXT_PUBLIC_SWAGGER_URL - The URL of the default Swagger specification.

🧪 Testing

• Run tests:

yarn test

• Run tests according to the environment:

yarn test:dev

• Run tests with coverage:

yarn test:cov