📌Overview

Purpose: The Swagger MCP Server aims to ingest and serve Swagger/OpenAPI specifications via the Model Context Protocol (MCP).

Overview: This server provides a flexible environment for integrating Swagger/OpenAPI specifications with various authentication methods. It facilitates real-time communication and is designed to automatically generate MCP tools based on defined API endpoints.

Key Features:

Multiple Authentication Methods: Supports Basic Auth, Bearer Token, API Key, and OAuth2, allowing secure access to APIs.
Automatic Tool Generation: Generate MCP tools automatically from the API endpoints, streamlining integration and usability.
Server-Sent Events (SSE) Support: Enable real-time communication with connected clients, enhancing interaction capabilities.
TypeScript Support: Built with TypeScript for improved development experience, type safety, and maintainability.

Swagger MCP Server

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 publicly.

Prerequisites

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

Installation

Clone the repository:

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

Install dependencies:
```
yarn install
```
Create a .env file based on the example:
```
cp .env.example .env
```
Configure your Swagger/OpenAPI specification:
- Place your Swagger file in the project (e.g., swagger.json), or
- Provide a URL to your Swagger specification

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",
    "defaultAuth": {
      "type": "apiKey",
      "apiKey": "your-api-key",
      "apiKeyName": "api_key",
      "apiKeyIn": "header"
    }
  }
}

Note:

The server prioritizes servers array URLs in the Swagger file for base URL
Security schemes from the Swagger file are used for authentication if defined
Config file settings act as fallbacks if missing from the Swagger file

Usage

Start the development server:
```
yarn dev
```
Build for production:
```
yarn build
```
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

Configure authentication fallbacks in config.json when not specified in Swagger:

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

Start the development server:

yarn dev

TODO

Support for user secrets to authenticate requests to the API
Comprehensive test suite

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

License

This project is licensed under the Apache 2.0 License.