[Feature Request]: OpenAPI to REST Protocol Conversion Tool

[caochenlei]

🧭 Type of Feature

Please select the most appropriate category:

• [x] Enhancement to existing functionality
• [x] New feature or capability
• [ ] New MCP-compliant server
• [ ] New component or integration
• [ ] Developer tooling or test improvement
• [ ] Packaging, automation and deployment (ex: pypi, docker, quay.io, kubernetes, terraform)
• [ ] Other (please describe below)

🧭 Epic

---

Title: OpenAPI to REST Protocol Conversion Tool Goal: Develop an automated tool that converts OpenAPI specifications into MCP-compliant REST client tools and data classes, simplifying API integration workflows within the MCP ecosystem Why now: With the MCP specification stabilizing in the 2025-03-26 release, there's a growing need for standardized API integration tools. This feature will benefit developers working with external REST APIs, MCP server creators, and AI application developers who need seamless API connectivity.

---

🙋♂️ User Story 1

As a: API Developer integrating external REST services I want: to automatically generate MCP-compatible tools from OpenAPI specifications So that: I can quickly expose REST API endpoints as callable tools without manual implementation

✅ Acceptance Criteria

Scenario: Generate tools from OpenAPI JSON file
  Given I have a valid OpenAPI 3.0 specification file
  When I run the OpenAPI conversion tool with the file path
  Then it should generate Python data classes for all schema definitions
  And create MCP tool definitions for each API endpoint

Scenario: Handle authentication schemes
  Given an OpenAPI spec with security schemes
  When the conversion tool processes the specification
  Then it should generate appropriate authentication handlers
  And include security parameters in the generated tools

---

🙋♂️ User Story 2

As a: MCP Server Developer I want: to validate and test generated REST tools during development So that: I can ensure API compatibility and proper error handling

✅ Acceptance Criteria

Scenario: Validate generated tools against live API
  Given I have generated MCP tools from an OpenAPI spec
  When I run the validation suite
  Then it should test each endpoint against the actual API
  And report any mismatches in request/response formats

Scenario: Error handling for invalid specifications
  Given an invalid or malformed OpenAPI file
  When the conversion tool is executed
  Then it should provide clear error messages
  And suggest corrections for common issues

---

🙋♂️ User Story 3

As a: AI Application Developer using MCP Context Forge I want: to dynamically load and use REST API tools at runtime So that: I can extend my AI application's capabilities without code changes

✅ Acceptance Criteria

Scenario: Dynamic tool registration
  Given a generated MCP tool package
  When the MCP server starts
  Then it should automatically register all generated tools
  And make them available to connected clients

Scenario: Runtime configuration of API endpoints
  Given different environment configurations
  When initializing the REST tools
  Then I should be able to configure base URLs and credentials
  Without modifying the generated code

---

📐 Design Sketch (optional)

---

🔗 MCP Standards Check

The rest tool is compliant with MCP standards, but I think the rest API call itself should comply with the open API standard

---

🔄 Alternatives Considered

During the design of the OpenAPI to MCP REST Tool conversion tool, the following alternative approaches were evaluated:

1. Manually Writing MCP REST Tools (Current Workflow) Developers currently read OpenAPI documentation and manually implement tool definitions, data classes, and authentication logic according to the MCP Context Forge specification. Drawbacks: Time-consuming, error-prone, difficult to maintain when APIs evolve, and not scalable for large or frequently updated APIs. Conclusion: While feasible, this approach is inefficient and fails to meet the goal of rapid integration. It was rejected as a sustainable long-term solution.

2. Using Generic Code Generators (e.g., openapi-generator) with Post-Processing Leverage existing tools like openapi-generator or swagger-codegen to generate Python clients, then adapt the output into MCP Tool format via custom scripts. Drawbacks: Generated code structures do not align with MCP’s tool registration and invocation patterns, requiring significant manual adjustments. Maintaining two generation pipelines increases complexity. Conclusion: Although it reuses existing capabilities, the integration overhead is high, and it fails to deliver a "generate-and-use" experience. A dedicated converter was chosen instead.

3. Runtime Dynamic Parsing and Tool Exposure (No Code Generation) Load and parse OpenAPI specifications at MCP server startup, dynamically registering endpoints as callable tools without generating static code. Drawbacks: Loses type safety and IDE support; harder to debug; unusable in offline environments; violates the principle that MCP tools should be explicitly declared. Conclusion: While flexible, this approach compromises developer experience and system stability. Therefore, static Python tool code generation was selected as the superior approach.

4. Generate Only Data Models (Pydantic Classes), Manual Tool Logic The tool would only generate data classes from OpenAPI schemas, while developers manually implement API call logic. Drawbacks: Still requires significant manual coding, failing to fully automate integration. Conclusion: A compromise, but does not achieve the core goal of simplifying API integration. Hence, the decision was made to fully auto-generate data classes, tool definitions, and authentication handlers.

5. Mapping Directly from JSON Schema to MCP Tool Schema Bypass OpenAPI and use raw JSON Schema definitions to generate tools. Drawbacks: Lacks essential information such as paths, parameters, authentication schemes, and HTTP methods, making it impossible to fully represent RESTful behavior. Conclusion: OpenAPI 3.0 provides rich semantic metadata and is a more suitable input format. It was retained as the standard input for the converter.

Final Decision: Develop a dedicated OpenAPI-to-MCP REST Tool converter that directly parses OpenAPI 3.0 specifications and generates compliant Python tool classes, data models, and authentication handlers, enabling a seamless, out-of-the-box integration experience within the MCP ecosystem.

---

📓 Additional Context

Include related issues, links to discussions, issues, etc.