Swagger To MCP Generator

🚀 OpenAPI to MCP Conversion Tool Documentation

This project offers a Java tool designed to convert OpenAPI specifications into a Model Context Protocol (MCP) server. It parses OpenAPI files using the Swagger Parser and generates corresponding MCP utility classes. The tool supports various HTTP methods, content type handling, error handling, and authentication.

✨ Features

• OpenAPI Parsing: Parse OpenAPI specifications using the Swagger Parser.
• Endpoint Conversion: Convert each API endpoint into a method annotated with @Tool.
• Parameter Mapping:
  • Path Parameters: Integrate into the URL.
  • Query Parameters: Add to the URL builder.
  • Request Body: Format correctly and attach to the request.
• HTTP Client Generation: Generate HTTP client code with detailed error handling.
• Response Formatting: Beautify output according to content types (e.g., JSON).
• Authentication Support: Authentication based on environment variables (API key, Bearer Token, and Basic Auth).
• Multi - Server Support: Support selecting multiple server URLs from the OpenAPI specification.

🚀 Quick Start

1. Add Dependencies

Add the following dependencies to your project:

<dependency>
    <groupId>org.swagger</groupId>
    <artifactId>swagger-parser</artifactId>
    <version>1.2.30</version>
</dependency>

2. Generate MCP Server Code Using the Tool

Run the OpenAPIToMCPGenerator tool:

java -jar openapi-to-mcp-generator.jar --input-spec your_openapi.yaml --output-dir output

3. Configure Environment Variables

Set the necessary environment variables:

• API_KEY: API key
• BEARER_TOKEN: Bearer Token
• BASIC_AUTH_USER: Basic Auth username
• BASIC_AUTH_PASSWORD: Basic Auth password

4. Example Code

Here is a simple example showing how to use the generated MCP utility class:

@Tool(
    name = "Get User",
    description = " retrieves user information by ID.",
    parameters = {
        @Parameter(name = "userId", type = Type.STRING, description = "User ID"),
        @Parameter(name = "includeDetails", type = Type.BOOLEAN, description = "Include detailed information")
    }
)
public class GetUserTool {

    private static final String BASE_URL = "https://api.example.com";

    public static User getUser(String userId, boolean includeDetails) {
        // Implement HTTP request logic
    }

}

📚 Documentation

Introduction to the MCP Protocol

MCP is a standardized protocol that allows communication between tools and LLMs. Its main features include:

1. Tool Function Exposure: Tools can display their functions to LLMs through MCP.
2. LLM Tool Discovery: LLMs can discover and use tools that conform to the MCP interface without knowing the specific implementation details.
3. Consistent Interface: Provide a unified tool specification and call interface.

Conversion Process from OpenAPI to MCP

1. Parse OpenAPI Specification: Parse the input OpenAPI file using the Swagger Parser.
2. Endpoint Conversion: Map each API endpoint to a method annotated with @Tool.
3. Parameter Handling:
   • Integrate path parameters into the URL.
   • Add query parameters to the URL builder.
   • Format the request body correctly and attach it to the request.
4. Generate HTTP Client Code: Generate HTTP client code with detailed error handling and timeout configuration.
5. Response Formatting: Beautify output according to content types (e.g., JSON).

Advanced Features

• Multi - HTTP Method Support: Support GET, POST, PUT, DELETE, and PATCH.
• Content Type Handling: Correctly handle different content types.
• Error Handling: Detailed error reporting, including status codes and response bodies.
• Authentication: Support API key, Bearer Token, and Basic authentication.
• Timeout Configuration: Configurable connection timeout, read timeout, and write timeout.

🔧 Technical Details

The jbang - wrapper.sh script solves environment issues when running in AI assistant environments such as Claude Desktop (macOS), ensuring that the PATH and environment variables are set correctly.

🚧 Future Plans

• Expand Functionality:
  • Support form data and file uploads.
  • Implement more complex parameter validation logic.
• Optimize Performance: Improve the speed of parsing and code generation.
• Increase Test Coverage: Complete unit tests and integration tests.
• Improve Documentation: Add more examples and usage guides.

🤝 Contribution Guide

Contributions from the community are welcome! Please refer to CONTRIBUTING.md to learn how to participate in the project.