Content
# 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 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:
```bash
git clone https://github.com/dcolley/swagger-mcp.git
cd swagger-mcp
```
2. Install dependencies:
```bash
yarn install
```
3. Create a `.env` file based on the example:
```bash
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 configuration in `config.json` with your server settings:
```json
{
"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:
```bash
yarn dev
```
2. Build for production:
```bash
yarn build
```
3. Start the production server:
```bash
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:
```bash
# 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
```json
{
"defaultAuth": {
"type": "basic",
"username": "your-username",
"password": "your-password"
}
}
```
### Bearer Token
```json
{
"defaultAuth": {
"type": "bearer",
"token": "your-bearer-token"
}
}
```
### API Key
```json
{
"defaultAuth": {
"type": "apiKey",
"apiKey": "your-api-key",
"apiKeyName": "X-API-Key",
"apiKeyIn": "header"
}
}
```
### OAuth2
```json
{
"defaultAuth": {
"type": "oauth2",
"token": "your-oauth-token"
}
}
```
## Development
1. Start the development server:
```bash
yarn dev
```
<!-- 2. Make changes to the code
3. Run tests to ensure everything works:
```bash
yarn test
```
4. Build the project:
```bash
yarn build
``` -->
<!-- ## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request -->
## 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
