MCP 服务器

swagger-mcp-server

Converts any Swagger/OpenAPI specification into an MCP server, enabling AI assistants to intelligently query API endpoints, schemas, and generate code examples.

README

🚀 Universal Swagger → MCP Server Converter

Stop wrestling with massive API docs in your AI assistant's context window. Start having intelligent conversations about any API.

⭐ Love this project? Give it a star! ⭐

🚀 Help us reach more developers who struggle with API integrations!
Your star makes this project more discoverable and motivates continued development.

⭐ Star this repo | 🍴 Fork it | 📢 Share it

</div>

💡 The Problem Every Developer Faces

You're building an integration with a complex API. The Swagger documentation is 2MB+ of JSON. Your AI assistant can only see tiny fragments at a time. You end up:

❌ Copy-pasting documentation chunks into chat windows
❌ Missing crucial schema relationships between endpoints
❌ Getting outdated or incomplete code examples
❌ Losing context when working across multiple API endpoints
❌ Wasting hours on what should be simple integrations

✨ The Solution: Intelligent API Knowledge for AI

Transform any Swagger/OpenAPI specification into an intelligent MCP server that gives your AI assistant superpowers:

🎯 What Your AI Can Now Do:

# Instead of this painful workflow:
"Here's a 500KB Swagger file, please help me integrate..."
# Error: Context window exceeded

# You get this magical experience:
AI: "I need to create a user and get their profile data"
→ Instantly finds relevant endpoints: POST /users, GET /users/{id}
→ Generates complete TypeScript client with proper types
→ Includes error handling and authentication patterns
→ Shows example requests/responses for testing

🚀 From 0 to AI-Powered API Integration in 30 Seconds:

# 1. Convert any Swagger file to intelligent MCP server
swagger-mcp-server convert your-api.json

# 2. Connect to Cursor, Claude, or VS Code
# Your AI assistant now knows EVERYTHING about your API

# 3. Start building with superhuman API knowledge
"Create a React hook for user authentication with retry logic"
"Generate Python client for the payment endpoints"
"Show me all endpoints that return user data"

🌟 Real-World Impact:

⚡ 10x Faster Integration: From hours to minutes for complex APIs
🎯 Perfect Code Generation: AI understands full API context and relationships
🔍 Instant API Discovery: Natural language search across any documentation size
🛡️ Enterprise Ready: Works offline, handles massive APIs (10MB+), production deployment
🔌 Universal Compatibility: Cursor, Claude, VS Code, or any MCP-compatible tool

Ready to supercharge your API development workflow? Jump to 🚀 Quick Start and experience the future of AI-assisted API integration.

📋 Table of Contents

✨ What is swagger-mcp-server?
🚀 Quick Start - Get running in 5 minutes
🏗️ Architecture - System overview
🔍 MCP Server Methods - API reference
🔧 CLI Commands - Command reference
🤖 AI Tool Integrations - VS Code, Cursor setup
📝 Configuration - Basic setup
💡 Examples - Sample APIs and use cases
🔧 Troubleshooting - Common issues
📚 Complete Documentation - All guides
🆘 Getting Help - Support resources

✨ What is swagger-mcp-server?

swagger-mcp-server bridges the gap between API documentation and AI coding assistants. Instead of AI agents struggling with large API docs in their context window, they can now query specific information on-demand through the Model Context Protocol (MCP).

Key Benefits

🔍 Intelligent Search: Find relevant endpoints using natural language queries
📊 Schema Awareness: Get complete type information and relationships
💻 Code Generation: Generate working examples in multiple languages
⚡ Fast Responses: Sub-200ms search, optimized for AI agent workflows
🔌 Easy Integration: Works with VS Code, Cursor, and custom AI tools
🛡️ Production Ready: SSL, authentication, monitoring, and deployment guides

Use Cases

API Integration: Help AI assistants understand and use your APIs correctly
Documentation Search: Quickly find specific endpoints and schemas
Code Generation: Generate accurate API client code and examples
API Exploration: Discover API capabilities through intelligent search
Development Workflow: Integrate API knowledge into your coding environment

🚀 Quick Start

Step 1: Get Your Swagger JSON File

Before converting, you need to obtain the Swagger/OpenAPI JSON specification from any API documentation site:

🔍 Finding the Swagger JSON (Most Common Method)

Visit any API documentation website (e.g., docs.example.com/api)
Open Browser DevTools (F12 or Cmd/Ctrl + Shift + I)
Go to Network tab and refresh the page
Look for swagger.json or similar files in the network requests
Click on the JSON file and copy the response
Save it to your project in the swagger-openapi-data/ directory:

# Save the JSON content to the existing swagger-openapi-data directory
# Either copy-paste or download directly:
curl -o swagger-openapi-data/your-api.json "https://api.example.com/swagger.json"

# Or save manually by copying the JSON content and pasting it into:
# swagger-openapi-data/your-api.json

📋 Alternative Methods to Get Swagger JSON

Method 2: Direct URL Access

# Many APIs expose Swagger at common endpoints:
curl -o swagger-openapi-data/your-api.json "https://api.example.com/swagger.json"
curl -o swagger-openapi-data/your-api.json "https://api.example.com/v1/swagger.json"
curl -o swagger-openapi-data/your-api.json "https://api.example.com/docs/swagger.json"

Method 3: API Documentation Download Most API documentation sites have a "Download OpenAPI" or "Export JSON" button.

Method 4: Use Our Sample API (Already Included)

# We already include a sample Ozon Performance API for testing:
ls swagger-openapi-data/swagger.json  # 262KB Ozon API ready to use

Step 2: Installation

# Option 1: Install from source (recommended)
git clone https://github.com/salacoste/openapi-mcp-swagger.git
cd openapi-mcp-swagger

# Option 2: Install dependencies
pip install -r requirements.txt

# Option 3: Use standalone script (no installation required)
chmod +x scripts/standalone-mcp.py

Step 3: Convert & Start

# Convert your Swagger file to MCP server
swagger-mcp-server convert swagger-openapi-data/your-api.json --name your-api

# Or use the included sample API
swagger-mcp-server convert swagger-openapi-data/swagger.json --name ozon-api

# Start the MCP server
cd mcp-server-your-api  # or mcp-server-ozon-api
swagger-mcp-server serve

# 4. Test with AI agents or curl
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"searchEndpoints","params":{"keywords":"user"}}'

Step 4: What Happens Next

🎉 Congratulations! Your API is now AI-ready. Here's what you get:

🧠 Intelligent API Knowledge

Complete endpoint mapping with search capability
Schema relationships preserved and queryable
Code examples generated on-demand in multiple languages
Context-aware responses for any API size

🤖 AI Assistant Integration

Connect to your favorite AI coding assistant:

For Cursor IDE:

# Add to .cursor-mcp/config.json
{
  "mcpServers": {
    "your-api": {
      "command": "swagger-mcp-server",
      "args": ["serve", "--port", "8080"]
    }
  }
}

For Claude/VS Code:

# Server will automatically integrate via MCP protocol
# Just point your AI assistant to: http://localhost:8080

✨ Start Building with AI Superpowers

Now you can ask your AI assistant:

"Create a TypeScript client for the user authentication endpoints"
"Show me all endpoints that handle payment processing"  
"Generate a React hook for real-time order status updates"
"What are the required fields for creating a new product?"

📖 Complete Quick Start: Follow our step-by-step Quick Start Tutorial to get your first MCP server running in 5 minutes with sample data.

🏗️ Architecture

The system consists of four main components:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │◄──►│   MCP Server     │◄──►│  Search Engine  │
│                 │    │                  │    │                 │
│ • Claude        │    │ • JSON-RPC API   │    │ • Endpoint Index│
│ • GPT-4         │    │ • Authentication │    │ • Schema Index  │
│ • Cursor        │    │ • Rate Limiting  │    │ • Full-Text     │
│ • VS Code       │    │ • Monitoring     │    │ • Relationships │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │  Swagger Parser  │
                       │                  │
                       │ • Validation     │
                       │ • Schema Extract │
                       │ • Relationship   │
                       │ • Indexing       │
                       └──────────────────┘

Core Components

🔍 Parser: Stream-based JSON parsing for large OpenAPI files (up to 10MB)
💾 Storage: SQLite database with optimized search indexes and relationships
🌐 Server: MCP protocol implementation with JSON-RPC over HTTP
🔗 Search: Intelligent endpoint and schema search with relevance ranking
💻 Examples: Multi-language code generation (cURL, JavaScript, Python, Go)

📖 Detailed Architecture: See docs/architecture/ for complete technical documentation and design decisions.

🔧 Development Setup

Prerequisites

Python 3.11 or higher (tested with Python 3.13.3)
Poetry (recommended for dependency management) or pip
pipx (for Poetry installation)
Git

System Dependencies

Install system dependencies first:

# macOS (using Homebrew)
brew install python@3.13 pipx

# Ubuntu/Debian
sudo apt update
sudo apt install python3.11-dev python3.11-venv python3-pip pipx

# Install Poetry
pipx install poetry

Local Development

Clone and setup:

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

Setup virtual environment and install dependencies:

Option A: Using Poetry (Recommended):

# Install all dependencies including dev dependencies
poetry install --with dev

# Activate virtual environment
poetry shell

Option B: Using pip with virtual environment:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install essential dependencies for development
pip install pytest pytest-asyncio aiosqlite sqlalchemy structlog greenlet

# Install optional dev dependencies
pip install black isort flake8 mypy pytest-cov

Verify installation:

# Test import of main modules
python -c "
import sys; sys.path.append('src')
from swagger_mcp_server.storage.migrations import Migration
print('✅ Installation successful!')
"

Run tests:

# With Poetry
poetry run pytest src/tests/unit/test_storage/ -v

# With pip/venv (make sure .venv is activated)
PYTHONPATH=src python -m pytest src/tests/unit/test_storage/ -v

# Run performance tests
PYTHONPATH=src python -m pytest src/tests/performance/ -v

# Run with coverage
pytest --cov=src/swagger_mcp_server --cov-report=html

Run linting:

# Format code
black src/
isort src/

# Check linting
flake8 src/
mypy src/swagger_mcp_server/

🧪 Testing

The project uses a comprehensive testing strategy:

Unit Tests: 80%+ coverage requirement, focused on individual components
Integration Tests: Full MCP server workflow testing
Performance Tests: Validation of response time requirements (<200ms search, <500ms schema)
Fixtures: Sample OpenAPI specifications for consistent testing

Running Tests

# All tests with coverage
poetry run pytest --cov=swagger_mcp_server --cov-report=html

# Unit tests only
poetry run pytest -m unit

# Integration tests only
poetry run pytest -m integration

# Performance/benchmark tests
poetry run pytest -m performance --benchmark-only

📁 Project Structure

swagger-mcp-server/
├── src/
│   ├── swagger_mcp_server/        # Main package
│   │   ├── parser/                # OpenAPI parsing
│   │   ├── storage/               # Database layer
│   │   ├── server/                # MCP implementation
│   │   ├── config/                # Configuration
│   │   └── examples/              # Code generation
│   └── tests/                     # Test suite
├── scripts/                       # Utility scripts
├── data/                          # Sample data
├── docs/                          # Documentation
├── .github/                       # CI/CD workflows
└── pyproject.toml                 # Project configuration

🔍 MCP Server Methods

The server implements three core MCP methods:

`searchEndpoints(keywords, httpMethods)`

Search for API endpoints using keywords and HTTP method filters.

// Example usage
const results = await mcpClient.call('searchEndpoints', {
  keywords: ['user', 'authentication'],
  httpMethods: ['GET', 'POST']
});

`getSchema(componentName)`

Retrieve complete schema definitions with dependencies.

const schema = await mcpClient.call('getSchema', {
  componentName: 'User'
});

`getExample(endpoint, format)`

Generate working code examples in multiple formats.

const example = await mcpClient.call('getExample', {
  endpoint: '/api/users',
  format: 'curl'  // 'curl', 'javascript', 'python'
});

📖 Complete API Reference: See docs/api/MCP_PROTOCOL.md for detailed protocol documentation, client libraries, and integration examples.

🔧 CLI Commands

Essential commands for everyday use:

# Convert Swagger to MCP server
swagger-mcp-server convert api.json --name my-api --port 8080

# Start server
swagger-mcp-server serve --config config.yaml

# Check server status
swagger-mcp-server status --all

# Configuration management
swagger-mcp-server config create production --output prod-config.yaml

# Setup and installation
swagger-mcp-server setup --verify

📖 Complete CLI Reference: See docs/reference/CLI_REFERENCE.md for all commands, options, and usage examples.

⚡ Performance Requirements

Search Response: < 200ms target, < 500ms maximum
Schema Retrieval: < 500ms target, < 1s maximum
File Processing: < 2s for files up to 5MB
Memory Usage: Process 10MB files within 2GB RAM
Concurrency: Support 100+ concurrent AI agent connections

📖 Performance Tuning: See docs/guides/PERFORMANCE.md for optimization strategies and scaling guidelines.

🤖 AI Tool Integrations

swagger-mcp-server works seamlessly with popular AI coding assistants:

VS Code + Continue

{
  "mcpServers": {
    "my-api": {
      "command": "swagger-mcp-server",
      "args": ["serve", "--config", "config.yaml"]
    }
  }
}

Cursor AI

{
  "mcp": {
    "servers": {
      "api-docs": "http://localhost:8080"
    }
  }
}

📖 Integration Guides: See docs/examples/integrations/ for complete setup instructions for VS Code, Cursor, and custom AI agents.

📝 Configuration

Basic Configuration

# config.yaml
server:
  host: localhost
  port: 8080

database:
  path: ./mcp_server.db

search:
  index_directory: ./search_index

logging:
  level: INFO
  console: true

Environment-Specific Configs

Development: docs/examples/configurations/development.yaml
Production: docs/examples/configurations/production.yaml

📖 Configuration Guide: See docs/guides/BASIC_CONFIG.md for configuration basics and docs/reference/CONFIGURATION.md for complete reference.

💡 Examples

Sample APIs

We provide realistic sample APIs for testing:

E-commerce Platform (45 endpoints): docs/examples/swagger-files/ecommerce-api.json
Banking API (67 endpoints): docs/examples/swagger-files/banking-api.json
Healthcare API (52 endpoints): docs/examples/swagger-files/healthcare-api.json

Quick Test

# Use our sample e-commerce API
swagger-mcp-server examples create-sample --type ecommerce --output sample-api.json
swagger-mcp-server convert sample-api.json --name demo
cd mcp-server-demo && swagger-mcp-server serve

📖 Examples Catalog: See docs/examples/swagger-files/README.md for all available sample APIs and use cases.

🤝 Contributing

We welcome contributions! Please see our contribution guidelines for details.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feat/my-feature
Make your changes with tests
Run the test suite: pytest
Run linting: black src/ && flake8 src/
Commit with conventional commits: git commit -m "feat: add new feature"
Push and create a pull request

Code Quality Standards

Code Coverage: Minimum 80% (target 85%+)
Type Hints: Required for all public functions
Documentation: Comprehensive docstrings for public APIs
Performance: All changes must meet response time requirements
Security: No credentials in logs, input validation required

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🏷️ Version History

v0.1.0: Initial release with core parsing and MCP server functionality

🔧 Troubleshooting

Common Issues

Installation Problems:

# Python version issues
python --version  # Should be 3.9+

# Permission errors
pip install --user swagger-mcp-server

# Package conflicts
python -m venv venv && source venv/bin/activate

Runtime Issues:

# Port already in use
swagger-mcp-server serve --port 9000

# Database locked
swagger-mcp-server stop --all

# Search index corruption
rm -rf search_index/ && swagger-mcp-server serve

📖 Comprehensive Troubleshooting: See docs/troubleshooting/COMMON_ISSUES.md for detailed solutions to installation, configuration, and runtime problems.

📚 Complete Documentation

🚀 Getting Started

Installation Guide - System requirements, installation methods, verification
Quick Start Tutorial - 5-minute setup with sample API
Basic Configuration - Essential configuration for new users

📖 Reference Documentation

CLI Reference - Complete command reference with examples
Configuration Reference - All configuration options and settings
MCP Protocol API - Protocol documentation and client libraries

💡 Examples and Integrations

Sample APIs - Realistic APIs for testing and learning
Configuration Templates - Environment-specific configurations
AI Tool Integrations - VS Code, Cursor, and custom integrations

🔧 Advanced Topics

Deployment Guide - Production deployment and scaling
Performance Tuning - Optimization and monitoring
Security Configuration - Hardening and best practices

🆘 Support and Troubleshooting

Common Issues - Frequently encountered problems
Error Reference - Error messages and solutions
Diagnostic Tools - Debugging and analysis tools

🛠️ Development

Development Setup - Complete development environment setup
Contributing Guide - How to contribute to the project
Architecture Documentation - Technical design and decisions

📖 Main Documentation Hub: See docs/README.md for the complete documentation index with detailed navigation.

🆘 Getting Help

Quick Help

🚀 New Users: Start with Quick Start Tutorial
🔧 Problems: Check Common Issues
⚙️ Configuration: See Basic Configuration
🤖 AI Integration: Follow Integration Guides

Community Support

🐛 Issues: GitHub Issues for bugs and feature requests
💬 Discussions: GitHub Discussions for questions and community support
📖 Documentation: Complete docs with searchable content
💡 Examples: Working examples for common use cases

Before Reporting Issues

✅ Check Common Issues
✅ Search existing issues
✅ Try with minimal configuration
✅ Include system info and logs in your report

🌟 Show Your Support 🌟

If this project helped solve your API integration challenges, please consider starring it!

🎯 Why your star matters:

📈 Increases visibility for developers facing similar challenges
💪 Motivates continued development and new features
🚀 Helps us prioritize community-requested improvements
🤝 Shows appreciation for open-source work

Quick Actions:

⭐ Star • 🍴 Fork • 📋 Issues • 💬 Discuss

Thank you for being part of our community! 🙏