swagger mcp

A server that ingests and serves Swagger/OpenAPI specifications through the Model Context Protocol (MCP).

Features

• Loads Swagger/OpenAPI specifications
• Supports multiple authentication methods:
• Basic Auth
• Bearer Token
• API Key (header or query)
• OAuth2
• Automatically generates MCP tools from API endpoints
• Server-Sent Events (SSE) support for real-time communication
• TypeScript support

Security

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

TODO

• secrets - the MCP server should be able to use secrets from the user to authenticate requests to the API
• 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:

5. Place your Swagger file in the project (e.g., swagger.json)

6. Or provide a URL to your Swagger specification

7. Update the configuration in config.json with your server settings:

   {
     "server": {
       "host": "localhost",
       "port": 3000
     },
     "swagger": {
       "url": "url-or-path/to/your/swagger.json",
       "apiBaseUrl": "https://api.example.com",  // Fallback if not specified in Swagger
       "defaultAuth": {  // Fallback if not specified in Swagger
         "type": "apiKey",
         "apiKey": "your-api-key",
         "apiKeyName": "api_key",
         "apiKeyIn": "header"
       }
     }
   }

Note: The server prioritizes settings from the Swagger specification over the config file: - If the Swagger file contains a servers array, the first server URL will be used as the base URL - If the Swagger file defines security schemes, they will be used for authentication - The config file settings serve as fallbacks when not specified in the Swagger file

Usage

1. Start the development server:

   yarn dev

2. Build for production:

   yarn build

3. Start the production server:

   yarn start

API Endpoints

• GET /health - Check server health status
• GET /sse - Establish Server-Sent Events connection
• POST /messages - Send messages to the MCP server

Testing

Run the test suite:

# Run tests once
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage report
yarn test:coverage

Authentication

The server supports various authentication methods. Configure them in the config.json file as fallbacks when not specified in the Swagger file:

Basic Auth

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

Bearer Token

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

API Key

{
  "defaultAuth": {
    "type": "apiKey",
    "apiKey": "your-api-key",
    "apiKeyName": "X-API-Key",
    "apiKeyIn": "header"
  }
}

OAuth2

{
  "defaultAuth": {
    "type": "oauth2",
    "token": "your-oauth-token"
  }
}

Development

1. Start the development server:

   yarn dev

License

This project is licensed under the Apache 2.0 License.

Environment Variables

• PORT: Server port (default: 3000)
• API_USERNAME: Username for API authentication (fallback)
• API_PASSWORD: Password for API authentication (fallback)
• API_TOKEN: API token for authentication (fallback)
• DEFAULT_API_BASE_URL: Default base URL for API endpoints (fallback)
• DEFAULT_SWAGGER_URL: Default Swagger specification URL