mcp-swagger-server/README_EN.md

MCP Swagger Server(mss)

A tool that converts OpenAPI/Swagger specifications to Model Context Protocol (MCP) format

Languages: English | 中文

---

🎬 Quick Demo

🎯 Project Screenshots

🎯 Project Overview

MCP Swagger Server is a tool that converts OpenAPI/Swagger specifications to Model Context Protocol (MCP) format.

📦 Project Structure

mcp-swagger-server/
├── packages/
│   ├── mcp-swagger-server/     # 🔧 Core MCP Server (Available)
│   ├── mcp-swagger-parser/     # 📝 OpenAPI Parser (Available)
│   ├── mcp-swagger-ui/         # 🎨 Web Interface (In Development)
│   └── mcp-swagger-api/        # 🔗 REST API Backend (Available)
└── scripts/                    # 🔨 Build Scripts

✨ Core Features

• 🔄 Zero Configuration: Input OpenAPI spec, get MCP tools instantly
• 🎯 Progressive Command Line: Provides step-by-step guided command line interface for easy user configuration
• 🔌 Multi-Transport: Support for SSE, Streamable, and Stdio transports
• 🔐 Secure Authentication: Bearer Token authentication to protect API access

🚀 Quick Start

Prerequisites

• Node.js ≥ 20.0.0
• pnpm ≥ 8.0.0 (recommended)

Installation

npm i mcp-swagger-server -g

Command Guide

• mss: interactive terminal UI (default)
• mcp-swagger-server / mcp-swagger: standard CLI (best for scripts and AI client integration)
• mss --openapi ...: direct mode (skip interactive UI)

Note: interactive session mode does not support starting STDIO servers. Use mss --openapi ... --transport stdio (alias still works: mcp-swagger-server --transport stdio ...) for STDIO.

Quick Launch

Interactive Launch (recommended for first-time setup)

mss

One-Command Launch (non-interactive)

mss --openapi https://api.example.com/openapi.json \
  --operation-filter-methods GET \
  --operation-filter-methods POST \
  --transport streamable \
  --auth-type bearer \
  --bearer-token "your-token-here"

# Using configuration file
mss --config config.json

📖 Usage Guide

🔧 mcp-swagger-server Package

This is the core package of the project, providing complete MCP server functionality.

Installation and Usage

# Global installation
npm install -g mcp-swagger-server

# Command line usage
mss --openapi https://petstore.swagger.io/v2/swagger.json --transport streamable --port 3322

Supported Transport Protocols

• stdio: For command-line integration
• sse: Server-Sent Events, suitable for web applications
• streamable: HTTP streaming transport, suitable for modern web applications

Command Line Options

# Basic usage
mss [options]

# Options:
--openapi, -o       OpenAPI specification URL or file path
--transport, -t     Transport protocol (stdio|sse|streamable)
--port, -p          Port number
--endpoint, -e      Custom endpoint path (default: sse=/sse, streamable=/mcp)
--base-url          Override API base URL (highest priority)
--watch, -w         Monitor file changes
--env               Environment file path (.env)

# Bearer Token authentication options:
--auth-type         Authentication type (bearer)
--bearer-token      Directly specify Bearer Token
--bearer-env        Read token from environment variable
--config, -c        Configuration file path
--custom-header     Custom header "Key=Value" (repeatable)
--custom-header-env Environment header "Key=VAR_NAME" (repeatable)
--custom-headers-config  Custom headers config file (JSON)
--debug-headers     Enable header debug logging

# Operation filtering options:
--operation-filter-methods <method>         HTTP method filtering (repeatable) [Example: GET]
--operation-filter-paths <path>             Path filtering (supports wildcards, repeatable) [Example: /api/*]
--operation-filter-operation-ids <id>       Operation ID filtering (repeatable) [Example: getUserById]
--operation-filter-status-codes <code>      Status code filtering (repeatable) [Example: 200]
--operation-filter-parameters <param>       Parameter filtering (repeatable) [Example: userId]

Note: to use direct mode with mss, you must pass --openapi. If your OpenAPI spec uses relative servers.url values (for example /v1), prefer loading from a remote URL, or set --base-url explicitly. Swagger 2.0 specs are auto-converted to OpenAPI 3.x on startup (including host/basePath mapping).

Examples

# Use local OpenAPI file
mss --openapi ./swagger.json --transport sse --port 3322

# Use remote OpenAPI URL
mss --openapi https://api.example.com/openapi.json --transport streamable --port 3323

# Monitor file changes
mss --openapi ./api.yaml --transport stdio --watch

# Use Bearer Token authentication
mss --openapi https://api.example.com/openapi.json --auth-type bearer --bearer-token "your-token-here" --transport sse --port 3322

# Read token from environment variable
export API_TOKEN="your-token-here"
mss --openapi https://api.example.com/openapi.json --auth-type bearer --bearer-env API_TOKEN --transport stdio

# Using operation filtering options
# Include only GET and POST method endpoints
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-methods GET \
  --operation-filter-methods POST \
  --transport streamable

# Include only specific path endpoints
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-paths "/api/users/*" \
  --operation-filter-paths "/api/orders/*" \
  --transport streamable

# Include only specific operation ID endpoints
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-operation-ids "getUserById" \
  --operation-filter-operation-ids "createUser" \
  --transport streamable

# Include only specific status code endpoints
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-status-codes "200" \
  --operation-filter-status-codes "201" \
  --operation-filter-status-codes "204" \
  --transport streamable

# Include only endpoints with specific parameters
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-parameters "userId" \
  --operation-filter-parameters "email" \
  --transport streamable

# Combine multiple filtering options
mss --openapi https://api.example.com/openapi.json \
  --operation-filter-methods GET \
  --operation-filter-methods POST \
  --operation-filter-paths "/api/users/*" \
  --operation-filter-status-codes "200" \
  --operation-filter-status-codes "201" \
  --transport streamable

🔐 Bearer Token Authentication

mcp-swagger-server supports Bearer Token authentication to protect API access that requires authentication.

Authentication Methods

1. Direct Token Specification

mss --auth-type bearer --bearer-token "your-token-here" --openapi https://api.example.com/openapi.json --transport streamable

2. Environment Variable Method

# Set environment variable
export API_TOKEN="your-token-here"

# Use environment variable
mss --auth-type bearer --bearer-env API_TOKEN --openapi https://api.example.com/openapi.json

3. Configuration File Method

{
  "transport": "sse",
  "port": 3322,
  "openapi": "https://api.example.com/openapi.json",
  "auth": {
    "type": "bearer",
    "bearer": {
      "token": "your-token-here",
      "source": "static"
    }
  }
}

# Use configuration file
mss --config config.json

Environment Variable Configuration

Create a .env file:

# Basic configuration
MCP_PORT=3322
MCP_TRANSPORT=stdio
MCP_OPENAPI_URL=https://api.example.com/openapi.json
MCP_ENDPOINT=/mcp
MCP_BASE_URL=https://api.example.com/v1

# Authentication configuration
MCP_AUTH_TYPE=bearer
API_TOKEN=your-bearer-token-here

🤖 AI Assistant Integration

Claude Desktop Configuration

{
  "mcpServers": {
    "swagger-converter": {
      "command": "mss",
      "args": [
        "--openapi", "https://petstore.swagger.io/v2/swagger.json",
        "--transport", "stdio"
      ]
    },
    "secured-api": {
      "command": "mss",
      "args": [
        "--openapi", "https://api.example.com/openapi.json",
        "--transport", "stdio",
        "--auth-type", "bearer",
        "--bearer-env", "API_TOKEN"
      ],
      "env": {
        "API_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

Programmatic Usage

import axios from 'axios';
import { createMcpServer, startStreamableMcpServer } from 'mcp-swagger-server';

const openApiData = (await axios.get('https://api.example.com/openapi.json')).data;

const server = await createMcpServer({
  openApiData,
  authConfig: {
    type: 'bearer',
    bearer: {
      source: 'static',
      token: 'your-token-here'
    }
  }
});

await startStreamableMcpServer(server, '/mcp', 3322);

🛠️ Development

Build System

# Build all packages
pnpm build

# Build only backend packages
pnpm build:packages

# Development mode
pnpm dev

# Clean build artifacts
pnpm clean

Testing and Debugging

# Run tests
pnpm test

# Code linting
pnpm lint

# Type checking
pnpm type-check

# Project health check
pnpm diagnostic

MCP Server Development

cd packages/mcp-swagger-server

# Development mode startup
pnpm dev

# Run CLI tools
pnpm cli --help

# Debug with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

📊 Project Status

Package	Status	Description
mcp-swagger-server	✅ Available	Core MCP server with multi-transport support
mcp-swagger-parser	✅ Available	OpenAPI parser and conversion tools
mcp-swagger-ui	🚧 In Development	Vue.js web interface
mcp-swagger-api	✅ Available	NestJS REST API backend

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide first.

📄 License

MIT License - see the LICENSE file for details.

---

Built with ❤️ by ZhaoYaNan(ZTE)

⭐ Star • 🐛 Issues • 💬 Discussions