{"id":45687334,"url":"https://github.com/agentic-community/openapi-to-mcp","last_synced_at":"2026-02-24T15:08:59.648Z","repository":{"id":305526915,"uuid":"1021682770","full_name":"agentic-community/openapi-to-mcp","owner":"agentic-community","description":"Transform OpenAPI specifications into production-ready MCP servers   with AI-powered evaluation and enhancement. Leverages LLMs to   analyze, improve, and generate Model Context Protocol   implementations from your existing API documentation.","archived":false,"fork":false,"pushed_at":"2025-07-20T16:25:23.000Z","size":356,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-20T17:20:52.384Z","etag":null,"topics":["ai-tools","anthropic","automation","bedrock","claude","developer-tools","litellm","llm","mcp","model-context-protocol","openapi","swagger"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agentic-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2025-07-17T19:19:59.000Z","updated_at":"2025-07-20T16:25:26.000Z","dependencies_parsed_at":"2025-07-20T17:31:05.758Z","dependency_job_id":null,"html_url":"https://github.com/agentic-community/openapi-to-mcp","commit_stats":null,"previous_names":["agentic-community/openapi-to-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/agentic-community/openapi-to-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-community%2Fopenapi-to-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-community%2Fopenapi-to-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-community%2Fopenapi-to-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-community%2Fopenapi-to-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentic-community","download_url":"https://codeload.github.com/agentic-community/openapi-to-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentic-community%2Fopenapi-to-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29786981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T10:45:18.109Z","status":"ssl_error","status_checked_at":"2026-02-24T10:45:09.911Z","response_time":75,"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-tools","anthropic","automation","bedrock","claude","developer-tools","litellm","llm","mcp","model-context-protocol","openapi","swagger"],"created_at":"2026-02-24T15:08:56.147Z","updated_at":"2026-02-24T15:08:59.639Z","avatar_url":"https://github.com/agentic-community.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenAPI to MCP Converter\n\n[![License](https://img.shields.io/github/license/agentic-community/openapi-to-mcp)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://github.com/modelcontextprotocol)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\u003e Transform your OpenAPI specifications into production-ready Model Context Protocol (MCP) servers with AI-powered enhancement and validation\n\n**OpenAPI to MCP** is a powerful tool that automatically converts OpenAPI/Swagger specifications into fully functional MCP servers. It leverages Large Language Models (LLMs) to analyze, enhance, and generate MCP-compatible server implementations from your existing API documentation.\n\n\u003e [!CAUTION]\n\u003e The examples provided in this repository are for experimental and educational purposes only. They demonstrate concepts and techniques but are not intended for direct use in production environments. Make sure to have Amazon Bedrock Guardrails in place to protect against [prompt injection](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-injection.html). \n\n\n## Table of Contents\n\n- [What's New](#whats-new)\n- [Why This Solution](#why-this-solution)\n- [Architecture](#architecture)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Basic Usage](#basic-usage)\n  - [Command Line Options](#command-line-options)\n  - [Environment Variables](#environment-variables)\n- [Examples](#examples)\n- [Configuration](#configuration)\n- [Output Structure](#output-structure)\n- [AI Providers](#ai-providers)\n- [Contributing](#contributing)\n- [Security](#security)\n- [License](#license)\n\n## What's New\n\n### v0.1.0\n- Initial release with core functionality\n- Support for OpenAPI 3.0 and Swagger 2.0 specifications\n- AI-powered evaluation and enhancement\n- Automatic MCP server and client generation\n- Support for Amazon Bedrock and Anthropic Claude\n- Comprehensive evaluation reports with usage tracking\n\n## Why This Solution\n\nAs enterprises transition towards being AI-ready, a critical piece of the puzzle is ensuring their APIs are AI-ready as well. API specifications that were written for human consumption often lack the level of detail that Large Language Models require for reliable operation. While human developers can rely on domain expertise and tribal knowledge to fill in documentation gaps, LLMs may hallucinate missing information, leading to AI agents that cannot reliably invoke the right tools at the right time.\n\nCommon issues in human-oriented API documentation that impact AI readiness include:\n\n- **Missing or vague descriptions**: Endpoints and parameters that lack detailed explanations of their purpose and behavior\n- **Undefined parameter constraints**: Parameters without clearly defined ranges, formats, or validation rules\n- **Incomplete error handling**: Missing documentation for error responses and edge cases\n- **Unclear data relationships**: Lack of explicit documentation about how different API resources relate to each other\n- **Missing pagination details**: APIs that handle large datasets but don't clearly document pagination mechanisms\n- **Ambiguous filtering options**: Query parameters for filtering that lack comprehensive documentation\n- **Implicit business logic**: Assumptions about workflow and usage patterns that aren't explicitly documented\n\nWhen these incomplete API specifications are directly converted to MCP servers, the resulting tool specifications inherit the same deficiencies. This leads to unpredictable behavior that may be sub-optimal at best and completely broken at worst. The OpenAPI to MCP Converter addresses this gap by using AI to analyze, evaluate, and enhance your API specifications before generating MCP servers, ensuring they meet the quality standards required for reliable AI agent operation.\n\n## Architecture\n\nThe OpenAPI to MCP Converter follows a multi-stage pipeline architecture:\n\n```mermaid\ngraph TD\n    A[OpenAPI Spec] --\u003e B[Specification Loader]\n    B --\u003e C[AI-Powered Evaluator]\n    C --\u003e D{Quality Check}\n    D --\u003e|Pass| E[MCP Generator]\n    D --\u003e|Fail| F[Enhancement Suggestions]\n    E --\u003e G[MCP Server]\n    E --\u003e H[MCP Client]\n    F --\u003e I[Enhanced Spec]\n    \n    J[LLM Provider] --\u003e C\n    J --\u003e E\n    \n    style A fill:#f9f,stroke:#333,stroke-width:2px\n    style G fill:#9f9,stroke:#333,stroke-width:2px\n    style H fill:#9f9,stroke:#333,stroke-width:2px\n```\n\n### Key Components\n\n1. **Specification Loader**: Loads and validates OpenAPI/Swagger specifications from files or URLs\n2. **AI-Powered Evaluator**: Uses LLMs to analyze API quality, completeness, and AI-readiness\n3. **Enhancement Engine**: Provides actionable suggestions to improve your API specification\n4. **MCP Generator**: Creates production-ready MCP server and client implementations\n5. **Output Manager**: Organizes all generated files and reports in a structured format\n\n## Features\n\n### Core Features\n\nThe OpenAPI to MCP Converter provides a seamless bridge between your existing API documentation and the Model Context Protocol ecosystem. With just a single command, you can transform any OpenAPI or Swagger specification into a production-ready MCP server. The tool leverages advanced Large Language Models to not only convert but also analyze and enhance your API specifications, ensuring they meet the highest standards for AI integration.\n\nEvery conversion includes comprehensive evaluation reports that score your API across multiple dimensions including completeness, security, and AI-readiness. The built-in quality thresholds ensure that only specifications meeting your standards proceed to MCP generation, while detailed usage tracking helps you monitor LLM token consumption and associated costs across all operations.\n\n### Evaluation Capabilities\n\nThe evaluation engine performs deep analysis of your OpenAPI specifications across multiple dimensions. It checks for API completeness by identifying missing descriptions, examples, and schemas that could impact usability. Security analysis evaluates your authentication and authorization schemes to ensure they meet modern security standards.\n\nThe AI readiness assessment is particularly valuable, determining how effectively your API will work with AI agents and automation tools. Built-in linting identifies specification issues and violations of OpenAPI best practices, while the operation analysis provides detailed reviews of each endpoint including parameter documentation, response schemas, and error handling.\n\n### Generation Features\n\nWhen your specification meets the quality thresholds, the tool generates a complete MCP implementation package. This includes a fully functional Python-based MCP server that implements all your API operations as MCP tools, along with a ready-to-use client for testing your implementation.\n\nThe generated package includes all necessary dependency files, comprehensive documentation with usage instructions, and detailed tool specifications that describe each operation in MCP format. Everything is organized in a clean directory structure, ready for deployment or further customization.\n\n## Example Results \u0026 Output Guide\n\nWant to see what the converter produces? Check out our pre-generated example results and comprehensive output guide:\n\n**[Explore Example Results](examples/results/anthropic/sample_api/)** - See real evaluation reports, generated MCP servers, and more from our sample space mission API\n\n**[Read the Results Guide](docs/RESULTS_GUIDE.md)** - Understand every file the converter generates, with links to actual examples\n\nThese resources show you exactly what to expect from the conversion process and help you interpret the evaluation scores and generated code.\n\n## Prerequisites\n\n- Python 3.12 or higher\n- [uv](https://github.com/astral-sh/uv) package manager\n- Valid API credentials for your chosen LLM provider:\n  - Amazon Bedrock credentials (for Claude via Bedrock)\n  - Anthropic API key (for direct Claude access)\n\n## Installation\n\n### Installing uv\n\nFirst, install the uv package manager if you haven't already:\n\n```bash\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Or using pip\npip install uv\n```\n\n### Quick Install\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/agentic-community/openapi-to-mcp.git\ncd openapi-to-mcp\n```\n\n2. Create and activate a virtual environment:\n```bash\n# Create virtual environment\nuv venv\n\n# Activate on macOS/Linux\nsource .venv/bin/activate\n\n# Activate on Windows\n.venv\\Scripts\\activate\n```\n\n3. Install dependencies using uv:\n```bash\nuv pip install -e .\n```\n\n4. Set up your environment variables:\n```bash\ncp env.example .env\n# Edit .env with your API credentials\n```\n\n### Development Installation\n\nFor development with additional tools:\n```bash\nuv pip install -e \".[dev]\"\n```\n\n## Usage\n\n### Basic Usage\n\nEvaluate and convert a local OpenAPI specification:\n```bash\n# For a simple example\nopenapi-to-mcp examples/hello.yaml\n\n# For a more complex example\nopenapi-to-mcp examples/sample_api.yaml\n```\n\nEvaluate a specification from a URL:\n```bash\nopenapi-to-mcp --url https://raw.githubusercontent.com/agentic-community/openapi-to-mcp/refs/heads/main/examples/hello.yaml\n```\n\n### Command Line Options\n\n```bash\nopenapi-to-mcp [OPTIONS] [FILENAME]\n\nArguments:\n  FILENAME              OpenAPI specification file (YAML or JSON)\n\nOptions:\n  --url URL            URL to fetch OpenAPI specification from\n  --output FILE        Output file for results (default: auto-generated)\n  --eval-only         Only run evaluation, skip MCP generation\n  --verbose           Enable verbose logging\n  --show-env          Show environment configuration\n```\n\n### Environment Variables\n\nConfigure your LLM provider credentials through environment variables:\n\n#### For Amazon Bedrock:\n```bash\nexport AWS_PROFILE=your-profile-name\nexport AWS_REGION=us-east-1\n```\n\n#### For Anthropic Direct:\n```bash\nexport ANTHROPIC_API_KEY=your-api-key\n```\n\nNote: The model selection is configured in `config/config.yml`, not through environment variables.\n\n## Examples\n\n### Example 1: Evaluate a Simple API\n\n```bash\n# Evaluate the simple hello API example\nopenapi-to-mcp examples/hello.yaml\n\n# Check the generated output\nls output/results_*_hello/\n```\n\n### Example 2: Evaluate a Complex API\n\n```bash\n# Evaluate the more complex sample API with multiple endpoints\nopenapi-to-mcp examples/sample_api.yaml\n\n# This example includes operations for users, products, and more\n```\n\n### Example 3: Evaluate from URL\n\n```bash\n# Evaluate directly from a URL\nopenapi-to-mcp --url https://raw.githubusercontent.com/agentic-community/openapi-to-mcp/refs/heads/main/examples/hello.yaml\n```\n\n### Example 4: Evaluate Only (No Generation)\n\n```bash\n# Just evaluate without generating MCP server\nopenapi-to-mcp examples/sample_api.yaml --eval-only\n```\n\n### Example 5: Custom Output Location\n\n```bash\n# Specify custom output file\nopenapi-to-mcp examples/hello.yaml --output results/my-api-evaluation.json\n```\n\n## Testing with Stub Server\n\nThis repository includes a complete end-to-end demonstration using the `examples/sample_api.yaml` specification. The sample API represents a fictional space mission control system with endpoints for spaceship telemetry, crew management, mission operations, and scientific experiments.\n\nTo facilitate testing without a real backend, we provide:\n- A stub server (`examples/stub_server.py`) that implements the backend API with simulated responses\n- Pre-generated MCP server and client code for immediate testing\n- A complete workflow to test the entire chain from API specification to working MCP tools\n\n### Pre-Generated Results\n\nFor convenience, we've included pre-generated results from evaluating `sample_api.yaml` in:\n```\nexamples/results/anthropic/sample_api/\n```\n\nThis directory contains evaluation reports, enhanced specifications, and a ready-to-run MCP server. See [RESULTS_GUIDE.md](docs/RESULTS_GUIDE.md) for detailed information about these files.\n\n### Running the End-to-End Demo\n\nFollow these steps to test the complete integration:\n\n### Step 1: Start the Stub Server\n\nFirst, run the stub server that simulates your API backend:\n\n```bash\n# Start stub server on port 9002\nuv run examples/stub_server.py --port 9002\n```\n\nThis creates a mock backend that responds to API requests with simulated data.\n\n### Step 2: Set Authentication Token\n\nExport the authentication token required by the MCP server:\n\n```bash\nexport AUTH_TOKEN=\"your-secret-token\"\n```\n\n### Step 3: Start the MCP Server\n\nIn a new terminal, navigate to the generated MCP server directory and start it:\n\n```bash\n# Navigate to the generated server directory\ncd examples/results/anthropic/sample_api/mcpserver/\n\n# Start the MCP server on port 9001, pointing to stub server on port 9002\npython server.py --port 9001 --base-url http://localhost:9002\n```\n\n### Step 4: Test with the MCP Client\n\nIn another terminal, run the MCP client to interact with your server:\n\n```bash\n# From the same mcpserver directory\npython client.py --server-url http://localhost:9001/mcp\n```\n\nThe client will connect to the MCP server and allow you to test all the available tools.\n\n### Example Workflow\n\n```bash\n# Terminal 1: Start stub server\nuv run examples/stub_server.py --port 9002\n\n# Terminal 2: Set auth and start MCP server\nexport AUTH_TOKEN=\"my-secret-token\"\ncd examples/results/anthropic/sample_api/mcpserver/\npython server.py --port 9001 --base-url http://localhost:9002\n\n# Terminal 3: Run client\ncd examples/results/anthropic/sample_api/mcpserver/\npython client.py --server-url http://localhost:9001/mcp\n```\n\n## Configuration\n\n### Configuration File\n\nThe tool uses `config/config.yml` for all settings including model selection:\n\n```yaml\n# Model configuration - specify your model here\nmodel: bedrock/us.anthropic.claude-3-5-sonnet-20241022-v2:0\n# Or for Anthropic direct:\n# model: anthropic/claude-3-5-sonnet-20241022\n\n# Model parameters\nmax_tokens: 8192\ntemperature: 0.0\ntimeout_seconds: 300\n\n# Evaluation thresholds\ngood_evaluation_threshold: 3.0\ngenerate_mcp_threshold: 3.0\n\n# Feature flags\ndebug: false\n```\n\n### Quality Thresholds\n\n- **good_evaluation_threshold**: Minimum score for \"good\" evaluation (default: 3/5)\n- **generate_mcp_threshold**: Minimum score to generate MCP server (default: 3/5)\n\nBoth completeness and AI readiness scores must meet the threshold for MCP generation.\n\n## Output Structure\n\nAfter running the tool, you'll find the following structure:\n\n```\noutput/\n└── results_YYYYMMDD_HHMMSS_\u003cspec-name\u003e_\u003cprovider\u003e/\n    ├── evaluation_YYYYMMDD_HHMMSS.json      # Detailed evaluation results\n    ├── summary_YYYYMMDD_HHMMSS.md           # Human-readable summary\n    ├── usage_YYYYMMDD_HHMMSS.json           # Token usage and costs\n    ├── enhanced_spec_YYYYMMDD_HHMMSS.yaml   # Enhanced specification\n    ├── original_spec_YYYYMMDD_HHMMSS.yaml   # Original specification\n    └── mcpserver/                            # Generated MCP server (if criteria met)\n        ├── server.py                         # MCP server implementation\n        ├── client.py                         # MCP client for testing\n        ├── requirements.txt                  # Python dependencies\n        ├── README.md                         # Usage documentation\n        └── tool_spec.txt                     # Tool specifications\n```\n\n## Understanding the Results\n\nThe OpenAPI to MCP Converter generates comprehensive evaluation reports and MCP implementations. To help you understand and work with these outputs:\n\n**[View the Results Guide](docs/RESULTS_GUIDE.md)**\n\nThis guide explains:\n- What each generated file contains and its purpose\n- How to interpret evaluation scores and quality metrics\n- Understanding pagination and filtering support indicators\n- Working with the generated MCP server and client code\n- Links to example files from our pre-generated sample API results\n\nThe pre-generated results in `examples/results/anthropic/sample_api/` serve as a reference implementation showing what a high-quality conversion looks like.\n\n## AI Providers\n\n### Supported Providers\n\n1. **Amazon Bedrock**\n   - Models: Claude 3.5 Sonnet, Claude 4 Sonnet\n   - Region support: All AWS regions with Bedrock\n   - Pricing: Pay per token via AWS\n\n2. **Anthropic (Direct)**\n   - Models: All Claude models\n   - Global availability\n   - Pricing: Pay per token via Anthropic\n\n### Provider Selection\n\nThis solution uses [LiteLLM](https://github.com/BerriAI/litellm) for LLM provider management. The provider is automatically detected based on the prefix in the MODEL environment variable:\n\n- Models prefixed with `bedrock/` use Amazon Bedrock\n- Models prefixed with `anthropic/` use Anthropic directly\n- Without a prefix, the model defaults to Anthropic\n\nWhile LiteLLM supports many providers, this tool has been specifically tested and optimized for the Claude family of models through both Amazon Bedrock and Anthropic.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n1. Fork the repository\n2. Create a feature branch\n3. Install development dependencies: `uv pip install -e \".[dev]\"`\n   - This installs pytest, black, ruff, and other development tools\n4. Make your changes\n5. Run tests and code quality checks\n6. Submit a pull request\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run tests with coverage\nuv run pytest --cov=src --cov-report=html\n\n# Run specific test file\nuv run pytest tests/test_spec_loader.py\n\n# Run tests in verbose mode\nuv run pytest -v\n```\n\n### Code Quality Tools\n\n#### Black (Code Formatting)\n```bash\n# Format all Python files in src directory\nuv run black src\n\n# Check formatting without making changes\nuv run black --check src\n\n# Format specific file\nuv run black src/services/spec_loader.py\n```\n\n#### Ruff (Linting)\n```bash\n# Run linter on src directory\nuv run ruff check src\n\n# Fix auto-fixable issues\nuv run ruff check --fix src\n\n# Check specific file\nuv run ruff check src/services/spec_loader.py\n```\n\n#### Pre-commit Checks\nRun all quality checks before committing:\n```bash\n# Run black formatting\nuv run black src\n\n# Run ruff linting\nuv run ruff check --fix src\n\n# Run tests\nuv run pytest\n```\n\n## Security\n\n### Security Best Practices\n\nWhen using this tool, please follow these security guidelines:\n\n1. **Sensitive Data in OpenAPI Specs**: Ensure that your OpenAPI specifications do not contain sensitive data such as real API keys, passwords, or personally identifiable information (PII) when testing with cloud-based LLM providers.\n\n2. **Use Local Models for Sensitive Data**: If your OpenAPI specifications contain sensitive information, consider using locally hosted LLM models instead of third party model providers to maintain data privacy.\n\n3. **Security Testing of Generated Code**: Always thoroughly review and test the generated MCP server code for security vulnerabilities before deploying to production. This includes:\n   - Input validation and sanitization\n   - Authentication and authorization checks\n   - Rate limiting and abuse prevention\n   - Secure handling of API credentials\n   - Protection against common vulnerabilities (injection attacks, XSS, etc.)\n\n4. **Environment Variables**: Never commit `.env` files or expose API credentials in your code repository. Use secure credential management practices.\n\n### Reporting Security Issues\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for information on reporting security vulnerabilities in this project.\n\n## Roadmap\n\n### Large OpenAPI Specification Support\n- Implement path-based batch processing for handling large API specifications that exceed LLM context windows ([#1](https://github.com/agentic-community/openapi-to-mcp/issues/1))\n\n## License\n\nThis project is licensed under the Apache-2.0 License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentic-community%2Fopenapi-to-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentic-community%2Fopenapi-to-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentic-community%2Fopenapi-to-mcp/lists"}