Swagger To MCP Generator

🚀 OpenAPI 到 MCP 的轉換工具文檔

本項目提供了一個 Java 工具，可將 OpenAPI 規範轉換為 Model Context Protocol (MCP) 服務器。藉助 Swagger Parser 解析 OpenAPI 文件，生成對應的 MCP 工具類。該工具支持多種 HTTP 方法、內容類型處理、錯誤處理和身份驗證，為開發者提供了便捷的轉換方案。

🚀 快速開始

1. 添加依賴項

在項目中添加以下依賴項：

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

2. 使用工具生成 MCP 服務器代碼

運行 OpenAPIToMCPGenerator 工具：

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

3. 配置環境變量

設置必要的環境變量：

• API_KEY：API 密鑰
• BEARER_TOKEN：Bearer Token
• BASIC_AUTH_USER：Basic Auth 用戶名
• BASIC_AUTH_PASSWORD：Basic Auth 密碼

4. 示例代碼

以下是一個簡單的示例，展示如何使用生成的 MCP 工具類：

@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) {
        // 實現 HTTP 請求邏輯
    }

}

✨ 主要特性

• OpenAPI 解析：使用 Swagger Parser 解析 OpenAPI 規範。
• 端點轉換：將每個 API 端點轉換為 @Tool 註解方法。
• 參數映射：
  • 路徑參數：整合到 URL 中。
  • 查詢參數：添加到 URL 構建器中。
  • 請求正文：正確格式化並附加到請求中。
• HTTP 客戶端生成：帶有詳細錯誤處理的 HTTP 客戶端代碼生成。
• 響應格式化：根據內容類型（如 JSON）進行美化輸出。
• 身份驗證支持：基於環境變量的身份驗證（API 密鑰、Bearer Token 和 Basic Auth）。
• 多服務器支持：支持從 OpenAPI 規範中選擇多個服務器 URL。

📚 詳細文檔

MCP 協議簡介

MCP 是一個標準化協議，允許工具和 LLM 之間進行通信。其主要特點包括：

1. 工具暴露功能：工具可以通過 MCP 向 LLM 展示其功能。
2. LLM 工具發現：LLM 可以發現並使用符合 MCP 接口的工具，而無需瞭解具體實現細節。
3. 一致接口：提供統一的工具規範和調用接口。

OpenAPI 到 MCP 的轉換流程

1. 解析 OpenAPI 規範：使用 Swagger Parser 解析輸入的 OpenAPI 文件。
2. 端點轉換：將每個 API 端點映射為一個 @Tool 註解方法。
3. 參數處理：
   • 路徑參數整合到 URL 中。
   • 查詢參數添加到 URL 構建器中。
   • 請求正文正確格式化並附加到請求中。
4. 生成 HTTP 客戶端代碼：帶有詳細錯誤處理和超時配置的 HTTP 客戶端代碼生成。
5. 響應格式化：根據內容類型（如 JSON）進行美化輸出。

高級功能

• 多 HTTP 方法支持：支持 GET、POST、PUT、DELETE 和 PATCH。
• 內容類型處理：正確處理不同內容類型。
• 錯誤處理：詳細錯誤報告，包括狀態碼和響應正文。
• 身份驗證：支持 API 密鑰、Bearer Token 和 Basic 身份驗證。
• 超時配置：可配置的連接超時、讀取超時和寫入超時。

🔧 技術細節

jbang-wrapper.sh 腳本解決了在 Claude Desktop（macOS）等 AI 助手環境中運行時的環境問題，確保 PATH 和環境變量正確設置。

🚧 未來計劃

• 擴展功能：
  • 支持表單數據和文件上傳。
  • 實現更復雜的參數驗證邏輯。
• 優化性能：提升解析和生成代碼的速度。
• 增加測試覆蓋率：完善單元測試和集成測試。
• 文檔改進：添加更多示例和使用指南。

🤝 貢獻指南

歡迎社區貢獻！請參考 CONTRIBUTING.md 瞭解如何參與項目。