{"id":31646409,"url":"https://github.com/salacoste/openapi-mcp-swagger","last_synced_at":"2026-04-08T18:02:04.223Z","repository":{"id":316829834,"uuid":"1064118995","full_name":"salacoste/openapi-mcp-swagger","owner":"salacoste","description":"Solve AI context window limits for API docs | Convert any Swagger/OpenAPI to searchable MCP server | AI-powered endpoint discovery \u0026 code generation | Works with Cursor, Claude, VS Code","archived":false,"fork":false,"pushed_at":"2025-10-02T00:34:38.000Z","size":4546,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-07T05:56:36.869Z","etag":null,"topics":["ai-assistant","ai-tools","api-client","api-documentation","api-integration","claude","code-generation","cursor","developer-tools","devtools","javascript","mcp","mcp-server","model-context-protocol","openapi","python","rest-api","swagger","typescript","vs-code"],"latest_commit_sha":null,"homepage":"https://salacoste.github.io/openapi-mcp-swagger/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/salacoste.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-25T15:08:03.000Z","updated_at":"2025-10-02T00:34:41.000Z","dependencies_parsed_at":"2025-09-27T01:25:25.624Z","dependency_job_id":"186a37f7-7025-4974-a397-a9c751fddc4f","html_url":"https://github.com/salacoste/openapi-mcp-swagger","commit_stats":null,"previous_names":["salacoste/openapi-mcp-swagger"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/salacoste/openapi-mcp-swagger","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salacoste%2Fopenapi-mcp-swagger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salacoste%2Fopenapi-mcp-swagger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salacoste%2Fopenapi-mcp-swagger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salacoste%2Fopenapi-mcp-swagger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/salacoste","download_url":"https://codeload.github.com/salacoste/openapi-mcp-swagger/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/salacoste%2Fopenapi-mcp-swagger/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31567227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assistant","ai-tools","api-client","api-documentation","api-integration","claude","code-generation","cursor","developer-tools","devtools","javascript","mcp","mcp-server","model-context-protocol","openapi","python","rest-api","swagger","typescript","vs-code"],"created_at":"2025-10-07T05:49:36.804Z","updated_at":"2026-04-08T18:02:04.201Z","avatar_url":"https://github.com/salacoste.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Universal Swagger → MCP Server Converter\n\n\u003e **Stop wrestling with massive API docs in your AI assistant's context window. Start having intelligent conversations about any API.**\n\n[![CI](https://github.com/salacoste/openapi-mcp-swagger/workflows/CI/badge.svg)](https://github.com/salacoste/openapi-mcp-swagger/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![GitHub stars](https://img.shields.io/github/stars/salacoste/openapi-mcp-swagger?style=social)](https://github.com/salacoste/openapi-mcp-swagger/stargazers)\n\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io)\n[![Cursor](https://img.shields.io/badge/Cursor-Ready-green.svg)](https://cursor.sh/)\n[![Claude](https://img.shields.io/badge/Claude-Integration-orange.svg)](https://claude.ai/)\n[![VS Code](https://img.shields.io/badge/VS%20Code-Extension-blue.svg)](https://code.visualstudio.com/)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### ⭐ **Love this project? Give it a star!** ⭐\n\n\u003ca href=\"https://github.com/salacoste/openapi-mcp-swagger/stargazers\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/salacoste/openapi-mcp-swagger?style=for-the-badge\u0026logo=github\u0026logoColor=white\u0026color=gold\" alt=\"GitHub stars\"/\u003e\n\u003c/a\u003e\n\n**🚀 Help us reach more developers who struggle with API integrations!**  \n*Your star makes this project more discoverable and motivates continued development.*\n\n[⭐ **Star this repo**](https://github.com/salacoste/openapi-mcp-swagger/stargazers) | [🍴 **Fork it**](https://github.com/salacoste/openapi-mcp-swagger/fork) | [📢 **Share it**](https://twitter.com/intent/tweet?text=Stop%20wrestling%20with%20massive%20API%20docs!%20Check%20out%20this%20Universal%20Swagger%20→%20MCP%20Server%20Converter%20for%20AI%20assistants\u0026url=https://github.com/salacoste/openapi-mcp-swagger)\n\n\u003c/div\u003e\n\n---\n\n## 💡 **The Problem Every Developer Faces**\n\nYou'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:\n\n- ❌ **Copy-pasting documentation chunks** into chat windows\n- ❌ **Missing crucial schema relationships** between endpoints  \n- ❌ **Getting outdated or incomplete code examples**\n- ❌ **Losing context** when working across multiple API endpoints\n- ❌ **Wasting hours** on what should be simple integrations\n\n## ✨ **The Solution: Intelligent API Knowledge for AI**\n\nTransform any Swagger/OpenAPI specification into an intelligent MCP server that gives your AI assistant **superpowers**:\n\n### 🎯 **What Your AI Can Now Do:**\n\n```bash\n# Instead of this painful workflow:\n\"Here's a 500KB Swagger file, please help me integrate...\"\n# Error: Context window exceeded\n\n# You get this magical experience:\nAI: \"I need to create a user and get their profile data\"\n→ Instantly finds relevant endpoints: POST /users, GET /users/{id}\n→ Generates complete TypeScript client with proper types\n→ Includes error handling and authentication patterns\n→ Shows example requests/responses for testing\n```\n\n### 🚀 **From 0 to AI-Powered API Integration in 30 Seconds:**\n\n```bash\n# 1. Convert any Swagger file to intelligent MCP server\nswagger-mcp-server convert your-api.json\n\n# 2. Connect to Cursor, Claude, or VS Code\n# Your AI assistant now knows EVERYTHING about your API\n\n# 3. Start building with superhuman API knowledge\n\"Create a React hook for user authentication with retry logic\"\n\"Generate Python client for the payment endpoints\"\n\"Show me all endpoints that return user data\"\n```\n\n### 🌟 **Real-World Impact:**\n\n- **⚡ 10x Faster Integration:** From hours to minutes for complex APIs\n- **🎯 Perfect Code Generation:** AI understands full API context and relationships  \n- **🔍 Instant API Discovery:** Natural language search across any documentation size\n- **🛡️ Enterprise Ready:** Works offline, handles massive APIs (10MB+), production deployment\n- **🔌 Universal Compatibility:** Cursor, Claude, VS Code, or any MCP-compatible tool\n\n---\n\n**Ready to supercharge your API development workflow?** Jump to [🚀 Quick Start](#-quick-start) and experience the future of AI-assisted API integration.\n\n## 📋 Table of Contents\n\n- [✨ What is swagger-mcp-server?](#-what-is-swagger-mcp-server)\n- [🚀 Quick Start](#-quick-start) - Get running in 5 minutes\n- [🏗️ Architecture](#️-architecture) - System overview\n- [🔍 MCP Server Methods](#-mcp-server-methods) - API reference\n- [🔧 CLI Commands](#-cli-commands) - Command reference\n- [🤖 AI Tool Integrations](#-ai-tool-integrations) - VS Code, Cursor setup\n- [📝 Configuration](#-configuration) - Basic setup\n- [💡 Examples](#-examples) - Sample APIs and use cases\n- [🔧 Troubleshooting](#-troubleshooting) - Common issues\n- [📚 Complete Documentation](#-complete-documentation) - All guides\n- [🆘 Getting Help](#-getting-help) - Support resources\n\n## ✨ What is swagger-mcp-server?\n\nswagger-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).\n\n### Key Benefits\n- **🔍 Intelligent Search**: Find relevant endpoints using natural language queries\n- **📊 Schema Awareness**: Get complete type information and relationships\n- **💻 Code Generation**: Generate working examples in multiple languages\n- **⚡ Fast Responses**: Sub-200ms search, optimized for AI agent workflows\n- **🔌 Easy Integration**: Works with VS Code, Cursor, and custom AI tools\n- **🛡️ Production Ready**: SSL, authentication, monitoring, and deployment guides\n\n### Use Cases\n- **API Integration**: Help AI assistants understand and use your APIs correctly\n- **Documentation Search**: Quickly find specific endpoints and schemas\n- **Code Generation**: Generate accurate API client code and examples\n- **API Exploration**: Discover API capabilities through intelligent search\n- **Development Workflow**: Integrate API knowledge into your coding environment\n\n## 🚀 Quick Start\n\n### Step 1: Get Your Swagger JSON File\n\nBefore converting, you need to obtain the Swagger/OpenAPI JSON specification from any API documentation site:\n\n#### 🔍 **Finding the Swagger JSON (Most Common Method)**\n\n1. **Visit any API documentation website** (e.g., `docs.example.com/api`)\n2. **Open Browser DevTools** (`F12` or `Cmd/Ctrl + Shift + I`)\n3. **Go to Network tab** and refresh the page\n4. **Look for `swagger.json` or similar files** in the network requests\n5. **Click on the JSON file** and copy the response\n6. **Save it to your project** in the `swagger-openapi-data/` directory:\n\n```bash\n# Save the JSON content to the existing swagger-openapi-data directory\n# Either copy-paste or download directly:\ncurl -o swagger-openapi-data/your-api.json \"https://api.example.com/swagger.json\"\n\n# Or save manually by copying the JSON content and pasting it into:\n# swagger-openapi-data/your-api.json\n```\n\n#### 📋 **Alternative Methods to Get Swagger JSON**\n\n**Method 2: Direct URL Access**\n```bash\n# Many APIs expose Swagger at common endpoints:\ncurl -o swagger-openapi-data/your-api.json \"https://api.example.com/swagger.json\"\ncurl -o swagger-openapi-data/your-api.json \"https://api.example.com/v1/swagger.json\"\ncurl -o swagger-openapi-data/your-api.json \"https://api.example.com/docs/swagger.json\"\n```\n\n**Method 3: API Documentation Download**\nMost API documentation sites have a \"Download OpenAPI\" or \"Export JSON\" button.\n\n**Method 4: Use Our Sample API (Already Included)**\n```bash\n# We already include a sample Ozon Performance API for testing:\nls swagger-openapi-data/swagger.json  # 262KB Ozon API ready to use\n```\n\n### Step 2: Installation\n\n```bash\n# Option 1: Install from source (recommended)\ngit clone https://github.com/salacoste/openapi-mcp-swagger.git\ncd openapi-mcp-swagger\n\n# Option 2: Install dependencies\npip install -r requirements.txt\n\n# Option 3: Use standalone script (no installation required)\nchmod +x scripts/standalone-mcp.py\n```\n\n### Step 3: Convert \u0026 Start\n\n```bash\n# Convert your Swagger file to MCP server\nswagger-mcp-server convert swagger-openapi-data/your-api.json --name your-api\n\n# Or use the included sample API\nswagger-mcp-server convert swagger-openapi-data/swagger.json --name ozon-api\n\n# Start the MCP server\ncd mcp-server-your-api  # or mcp-server-ozon-api\nswagger-mcp-server serve\n\n# 4. Test with AI agents or curl\ncurl -X POST http://localhost:8080 \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"searchEndpoints\",\"params\":{\"keywords\":\"user\"}}'\n```\n\n### Step 4: What Happens Next\n\n🎉 **Congratulations!** Your API is now AI-ready. Here's what you get:\n\n#### 🧠 **Intelligent API Knowledge**\n- **Complete endpoint mapping** with search capability\n- **Schema relationships** preserved and queryable  \n- **Code examples** generated on-demand in multiple languages\n- **Context-aware responses** for any API size\n\n#### 🤖 **AI Assistant Integration**\nConnect to your favorite AI coding assistant:\n\n**For Cursor IDE:**\n```bash\n# Add to .cursor-mcp/config.json\n{\n  \"mcpServers\": {\n    \"your-api\": {\n      \"command\": \"swagger-mcp-server\",\n      \"args\": [\"serve\", \"--port\", \"8080\"]\n    }\n  }\n}\n```\n\n**For Claude/VS Code:**\n```bash\n# Server will automatically integrate via MCP protocol\n# Just point your AI assistant to: http://localhost:8080\n```\n\n#### ✨ **Start Building with AI Superpowers**\nNow you can ask your AI assistant:\n\n```\n\"Create a TypeScript client for the user authentication endpoints\"\n\"Show me all endpoints that handle payment processing\"  \n\"Generate a React hook for real-time order status updates\"\n\"What are the required fields for creating a new product?\"\n```\n\n\u003e **📖 Complete Quick Start**: Follow our step-by-step [Quick Start Tutorial](docs/guides/QUICKSTART.md) to get your first MCP server running in 5 minutes with sample data.\n\n## 🏗️ Architecture\n\nThe system consists of four main components:\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   AI Agent      │◄──►│   MCP Server     │◄──►│  Search Engine  │\n│                 │    │                  │    │                 │\n│ • Claude        │    │ • JSON-RPC API   │    │ • Endpoint Index│\n│ • GPT-4         │    │ • Authentication │    │ • Schema Index  │\n│ • Cursor        │    │ • Rate Limiting  │    │ • Full-Text     │\n│ • VS Code       │    │ • Monitoring     │    │ • Relationships │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n                                │\n                                ▼\n                       ┌──────────────────┐\n                       │  Swagger Parser  │\n                       │                  │\n                       │ • Validation     │\n                       │ • Schema Extract │\n                       │ • Relationship   │\n                       │ • Indexing       │\n                       └──────────────────┘\n```\n\n### Core Components\n- **🔍 Parser**: Stream-based JSON parsing for large OpenAPI files (up to 10MB)\n- **💾 Storage**: SQLite database with optimized search indexes and relationships\n- **🌐 Server**: MCP protocol implementation with JSON-RPC over HTTP\n- **🔗 Search**: Intelligent endpoint and schema search with relevance ranking\n- **💻 Examples**: Multi-language code generation (cURL, JavaScript, Python, Go)\n\n\u003e **📖 Detailed Architecture**: See [docs/architecture/](docs/architecture/) for complete technical documentation and design decisions.\n\n## 🔧 Development Setup\n\n### Prerequisites\n\n- **Python 3.11 or higher** (tested with Python 3.13.3)\n- **Poetry** (recommended for dependency management) or pip\n- **pipx** (for Poetry installation)\n- **Git**\n\n### System Dependencies\n\nInstall system dependencies first:\n\n```bash\n# macOS (using Homebrew)\nbrew install python@3.13 pipx\n\n# Ubuntu/Debian\nsudo apt update\nsudo apt install python3.11-dev python3.11-venv python3-pip pipx\n\n# Install Poetry\npipx install poetry\n```\n\n### Local Development\n\n1. **Clone and setup:**\n   ```bash\n   git clone https://github.com/salacoste/openapi-mcp-swagger.git\n   cd openapi-mcp-swagger\n   ```\n\n2. **Setup virtual environment and install dependencies:**\n\n   **Option A: Using Poetry (Recommended):**\n   ```bash\n   # Install all dependencies including dev dependencies\n   poetry install --with dev\n\n   # Activate virtual environment\n   poetry shell\n   ```\n\n   **Option B: Using pip with virtual environment:**\n   ```bash\n   # Create virtual environment\n   python3 -m venv .venv\n   source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n   # Upgrade pip\n   pip install --upgrade pip\n\n   # Install essential dependencies for development\n   pip install pytest pytest-asyncio aiosqlite sqlalchemy structlog greenlet\n\n   # Install optional dev dependencies\n   pip install black isort flake8 mypy pytest-cov\n   ```\n\n3. **Verify installation:**\n   ```bash\n   # Test import of main modules\n   python -c \"\n   import sys; sys.path.append('src')\n   from swagger_mcp_server.storage.migrations import Migration\n   print('✅ Installation successful!')\n   \"\n   ```\n\n4. **Run tests:**\n   ```bash\n   # With Poetry\n   poetry run pytest src/tests/unit/test_storage/ -v\n\n   # With pip/venv (make sure .venv is activated)\n   PYTHONPATH=src python -m pytest src/tests/unit/test_storage/ -v\n\n   # Run performance tests\n   PYTHONPATH=src python -m pytest src/tests/performance/ -v\n\n   # Run with coverage\n   pytest --cov=src/swagger_mcp_server --cov-report=html\n   ```\n\n5. **Run linting:**\n   ```bash\n   # Format code\n   black src/\n   isort src/\n\n   # Check linting\n   flake8 src/\n   mypy src/swagger_mcp_server/\n   ```\n\n## 🧪 Testing\n\nThe project uses a comprehensive testing strategy:\n\n- **Unit Tests**: 80%+ coverage requirement, focused on individual components\n- **Integration Tests**: Full MCP server workflow testing\n- **Performance Tests**: Validation of response time requirements (\u003c200ms search, \u003c500ms schema)\n- **Fixtures**: Sample OpenAPI specifications for consistent testing\n\n### Running Tests\n\n```bash\n# All tests with coverage\npoetry run pytest --cov=swagger_mcp_server --cov-report=html\n\n# Unit tests only\npoetry run pytest -m unit\n\n# Integration tests only\npoetry run pytest -m integration\n\n# Performance/benchmark tests\npoetry run pytest -m performance --benchmark-only\n```\n\n## 📁 Project Structure\n\n```\nswagger-mcp-server/\n├── src/\n│   ├── swagger_mcp_server/        # Main package\n│   │   ├── parser/                # OpenAPI parsing\n│   │   ├── storage/               # Database layer\n│   │   ├── server/                # MCP implementation\n│   │   ├── config/                # Configuration\n│   │   └── examples/              # Code generation\n│   └── tests/                     # Test suite\n├── scripts/                       # Utility scripts\n├── data/                          # Sample data\n├── docs/                          # Documentation\n├── .github/                       # CI/CD workflows\n└── pyproject.toml                 # Project configuration\n```\n\n## 🔍 MCP Server Methods\n\nThe server implements three core MCP methods:\n\n### `searchEndpoints(keywords, httpMethods)`\nSearch for API endpoints using keywords and HTTP method filters.\n\n```javascript\n// Example usage\nconst results = await mcpClient.call('searchEndpoints', {\n  keywords: ['user', 'authentication'],\n  httpMethods: ['GET', 'POST']\n});\n```\n\n### `getSchema(componentName)`\nRetrieve complete schema definitions with dependencies.\n\n```javascript\nconst schema = await mcpClient.call('getSchema', {\n  componentName: 'User'\n});\n```\n\n### `getExample(endpoint, format)`\nGenerate working code examples in multiple formats.\n\n```javascript\nconst example = await mcpClient.call('getExample', {\n  endpoint: '/api/users',\n  format: 'curl'  // 'curl', 'javascript', 'python'\n});\n```\n\n\u003e **📖 Complete API Reference**: See [docs/api/MCP_PROTOCOL.md](docs/api/MCP_PROTOCOL.md) for detailed protocol documentation, client libraries, and integration examples.\n\n## 🔧 CLI Commands\n\nEssential commands for everyday use:\n\n```bash\n# Convert Swagger to MCP server\nswagger-mcp-server convert api.json --name my-api --port 8080\n\n# Start server\nswagger-mcp-server serve --config config.yaml\n\n# Check server status\nswagger-mcp-server status --all\n\n# Configuration management\nswagger-mcp-server config create production --output prod-config.yaml\n\n# Setup and installation\nswagger-mcp-server setup --verify\n```\n\n\u003e **📖 Complete CLI Reference**: See [docs/reference/CLI_REFERENCE.md](docs/reference/CLI_REFERENCE.md) for all commands, options, and usage examples.\n\n## ⚡ Performance Requirements\n\n- **Search Response**: \u003c 200ms target, \u003c 500ms maximum\n- **Schema Retrieval**: \u003c 500ms target, \u003c 1s maximum\n- **File Processing**: \u003c 2s for files up to 5MB\n- **Memory Usage**: Process 10MB files within 2GB RAM\n- **Concurrency**: Support 100+ concurrent AI agent connections\n\n\u003e **📖 Performance Tuning**: See [docs/guides/PERFORMANCE.md](docs/guides/PERFORMANCE.md) for optimization strategies and scaling guidelines.\n\n## 🤖 AI Tool Integrations\n\nswagger-mcp-server works seamlessly with popular AI coding assistants:\n\n### VS Code + Continue\n```json\n{\n  \"mcpServers\": {\n    \"my-api\": {\n      \"command\": \"swagger-mcp-server\",\n      \"args\": [\"serve\", \"--config\", \"config.yaml\"]\n    }\n  }\n}\n```\n\n### Cursor AI\n```json\n{\n  \"mcp\": {\n    \"servers\": {\n      \"api-docs\": \"http://localhost:8080\"\n    }\n  }\n}\n```\n\n\u003e **📖 Integration Guides**: See [docs/examples/integrations/](docs/examples/integrations/) for complete setup instructions for VS Code, Cursor, and custom AI agents.\n\n## 📝 Configuration\n\n### Basic Configuration\n```yaml\n# config.yaml\nserver:\n  host: localhost\n  port: 8080\n\ndatabase:\n  path: ./mcp_server.db\n\nsearch:\n  index_directory: ./search_index\n\nlogging:\n  level: INFO\n  console: true\n```\n\n### Environment-Specific Configs\n- **Development**: [docs/examples/configurations/development.yaml](docs/examples/configurations/development.yaml)\n- **Production**: [docs/examples/configurations/production.yaml](docs/examples/configurations/production.yaml)\n\n\u003e **📖 Configuration Guide**: See [docs/guides/BASIC_CONFIG.md](docs/guides/BASIC_CONFIG.md) for configuration basics and [docs/reference/CONFIGURATION.md](docs/reference/CONFIGURATION.md) for complete reference.\n\n## 💡 Examples\n\n### Sample APIs\nWe provide realistic sample APIs for testing:\n\n- **E-commerce Platform** (45 endpoints): [docs/examples/swagger-files/ecommerce-api.json](docs/examples/swagger-files/ecommerce-api.json)\n- **Banking API** (67 endpoints): [docs/examples/swagger-files/banking-api.json](docs/examples/swagger-files/banking-api.json)\n- **Healthcare API** (52 endpoints): [docs/examples/swagger-files/healthcare-api.json](docs/examples/swagger-files/healthcare-api.json)\n\n### Quick Test\n```bash\n# Use our sample e-commerce API\nswagger-mcp-server examples create-sample --type ecommerce --output sample-api.json\nswagger-mcp-server convert sample-api.json --name demo\ncd mcp-server-demo \u0026\u0026 swagger-mcp-server serve\n```\n\n\u003e **📖 Examples Catalog**: See [docs/examples/swagger-files/README.md](docs/examples/swagger-files/README.md) for all available sample APIs and use cases.\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [contribution guidelines](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feat/my-feature`\n3. Make your changes with tests\n4. Run the test suite: `pytest`\n5. Run linting: `black src/ \u0026\u0026 flake8 src/`\n6. Commit with conventional commits: `git commit -m \"feat: add new feature\"`\n7. Push and create a pull request\n\n### Code Quality Standards\n\n- **Code Coverage**: Minimum 80% (target 85%+)\n- **Type Hints**: Required for all public functions\n- **Documentation**: Comprehensive docstrings for public APIs\n- **Performance**: All changes must meet response time requirements\n- **Security**: No credentials in logs, input validation required\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🏷️ Version History\n\n- **v0.1.0**: Initial release with core parsing and MCP server functionality\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n**Installation Problems**:\n```bash\n# Python version issues\npython --version  # Should be 3.9+\n\n# Permission errors\npip install --user swagger-mcp-server\n\n# Package conflicts\npython -m venv venv \u0026\u0026 source venv/bin/activate\n```\n\n**Runtime Issues**:\n```bash\n# Port already in use\nswagger-mcp-server serve --port 9000\n\n# Database locked\nswagger-mcp-server stop --all\n\n# Search index corruption\nrm -rf search_index/ \u0026\u0026 swagger-mcp-server serve\n```\n\n\u003e **📖 Comprehensive Troubleshooting**: See [docs/troubleshooting/COMMON_ISSUES.md](docs/troubleshooting/COMMON_ISSUES.md) for detailed solutions to installation, configuration, and runtime problems.\n\n## 📚 Complete Documentation\n\n### 🚀 Getting Started\n- **[Installation Guide](docs/INSTALLATION.md)** - System requirements, installation methods, verification\n- **[Quick Start Tutorial](docs/guides/QUICKSTART.md)** - 5-minute setup with sample API\n- **[Basic Configuration](docs/guides/BASIC_CONFIG.md)** - Essential configuration for new users\n\n### 📖 Reference Documentation\n- **[CLI Reference](docs/reference/CLI_REFERENCE.md)** - Complete command reference with examples\n- **[Configuration Reference](docs/reference/CONFIGURATION.md)** - All configuration options and settings\n- **[MCP Protocol API](docs/api/MCP_PROTOCOL.md)** - Protocol documentation and client libraries\n\n### 💡 Examples and Integrations\n- **[Sample APIs](docs/examples/swagger-files/README.md)** - Realistic APIs for testing and learning\n- **[Configuration Templates](docs/examples/configurations/)** - Environment-specific configurations\n- **[AI Tool Integrations](docs/examples/integrations/)** - VS Code, Cursor, and custom integrations\n\n### 🔧 Advanced Topics\n- **[Deployment Guide](docs/guides/DEPLOYMENT.md)** - Production deployment and scaling\n- **[Performance Tuning](docs/guides/PERFORMANCE.md)** - Optimization and monitoring\n- **[Security Configuration](docs/guides/SECURITY.md)** - Hardening and best practices\n\n### 🆘 Support and Troubleshooting\n- **[Common Issues](docs/troubleshooting/COMMON_ISSUES.md)** - Frequently encountered problems\n- **[Error Reference](docs/troubleshooting/ERROR_REFERENCE.md)** - Error messages and solutions\n- **[Diagnostic Tools](docs/troubleshooting/DIAGNOSTICS.md)** - Debugging and analysis tools\n\n### 🛠️ Development\n- **[Development Setup](DEVELOPMENT.md)** - Complete development environment setup\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute to the project\n- **[Architecture Documentation](docs/architecture/)** - Technical design and decisions\n\n\u003e **📖 Main Documentation Hub**: See [docs/README.md](docs/README.md) for the complete documentation index with detailed navigation.\n\n## 🆘 Getting Help\n\n### Quick Help\n- **🚀 New Users**: Start with [Quick Start Tutorial](docs/guides/QUICKSTART.md)\n- **🔧 Problems**: Check [Common Issues](docs/troubleshooting/COMMON_ISSUES.md)\n- **⚙️ Configuration**: See [Basic Configuration](docs/guides/BASIC_CONFIG.md)\n- **🤖 AI Integration**: Follow [Integration Guides](docs/examples/integrations/)\n\n### Community Support\n- **🐛 Issues**: [GitHub Issues](https://github.com/salacoste/openapi-mcp-swagger/issues) for bugs and feature requests\n- **💬 Discussions**: [GitHub Discussions](https://github.com/salacoste/openapi-mcp-swagger/discussions) for questions and community support\n- **📖 Documentation**: [Complete docs](docs/README.md) with searchable content\n- **💡 Examples**: [Working examples](docs/examples/) for common use cases\n\n### Before Reporting Issues\n1. ✅ Check [Common Issues](docs/troubleshooting/COMMON_ISSUES.md)\n2. ✅ Search [existing issues](https://github.com/salacoste/openapi-mcp-swagger/issues)\n3. ✅ Try with [minimal configuration](docs/guides/BASIC_CONFIG.md)\n4. ✅ Include system info and logs in your report\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n## 🌟 **Show Your Support** 🌟\n\nIf this project helped solve your API integration challenges, **please consider starring it!**\n\n\u003ca href=\"https://github.com/salacoste/openapi-mcp-swagger/stargazers\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/salacoste/openapi-mcp-swagger?style=for-the-badge\u0026logo=star\u0026logoColor=white\u0026color=ffd700\" alt=\"Star this repository\"/\u003e\n\u003c/a\u003e\n\n**🎯 Why your star matters:**\n- 📈 **Increases visibility** for developers facing similar challenges\n- 💪 **Motivates continued development** and new features\n- 🚀 **Helps us prioritize** community-requested improvements\n- 🤝 **Shows appreciation** for open-source work\n\n### **Quick Actions:**\n[⭐ Star](https://github.com/salacoste/openapi-mcp-swagger/stargazers) • [🍴 Fork](https://github.com/salacoste/openapi-mcp-swagger/fork) • [📋 Issues](https://github.com/salacoste/openapi-mcp-swagger/issues) • [💬 Discuss](https://github.com/salacoste/openapi-mcp-swagger/discussions)\n\n**Thank you for being part of our community! 🙏**\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalacoste%2Fopenapi-mcp-swagger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsalacoste%2Fopenapi-mcp-swagger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsalacoste%2Fopenapi-mcp-swagger/lists"}