Swagger MCP

🚀 Swagger MCP 服務器

Swagger MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它藉助 Swagger/OpenAPI 文檔，為探索和測試 API 提供了實用工具。該服務器能夠自動檢測多個 IDE 中的配置文件，並具備全面的 API 交互能力。

✨ 主要特性

• 🔍 可從任意 URL 獲取並解析 Swagger/OpenAPI 文檔。
• 🧪 能直接通過 MCP 界面 測試 API 端點。
• 📊 可用於 探索 API 架構，深入瞭解數據結構。
• 🔧 支持多 IDE - 可自動檢測來自 VS Code、Cursor、Windsurf 等 IDE 的配置。
• 🌐 靈活的認證方式 - 支持 API 密鑰、基本認證和令牌認證。
• ⚡ 自動發現功能 - 能夠自動查找文檔 URL。

📦 安裝指南

IDE 設置

在您的 IDE 配置目錄中創建一個 MCP 配置文件：

• VS Code：~/.vscode/mcp.json 或項目中的 .vscode/mcp.json。
• Cursor：~/.cursor/mcp.json 或項目中的 .cursor/mcp.json。
• Windsurf：~/.windsurf/mcp.json 或項目中的 .windsurf/mcp.json。
• 任意 IDE：項目根目錄下的 mcp.json 或 .mcp/config.json。

認證選項

選項 1：使用 API 密鑰

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y",
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_KEY": "your-api-key-here"
  }
}

選項 2：使用用戶名和密碼

"swagger-mcp": {
  "command": "npx",
  "args": [
    "-y", 
    "swagger-mcp@latest"
  ],
  "env": {
    "API_BASE_URL": "https://api.example.com",
    "API_DOCS_URL": "https://api.example.com/swagger.json",
    "API_USERNAME": "your-username",
    "API_PASSWORD": "your-password"
  }
}

配置選項

🔧 技術細節

認證流程

服務器能夠智能處理認證：

1. 對於 API 請求：使用 API_KEY 作為令牌，若不可用則使用基本認證。
2. 對於認證端點：自動注入用戶名/密碼憑證。
3. 令牌管理：自動存儲並重用登錄響應中的令牌。
4. 自動刷新：在收到 401 未授權響應時嘗試刷新令牌。

可用工具

• fetch_swagger_info：從給定 URL 獲取並解析 Swagger/OpenAPI 文檔，以發現可用的 API 端點。
• list_endpoints：獲取 Swagger 文檔後，列出所有可用的 API 端點，顯示方法、路徑和摘要。
• get_endpoint_details：獲取特定 API 端點的詳細信息，包括參數、請求/響應架構和示例。
• execute_api_request：向特定端點執行 API 請求，處理認證、參數、頭部和請求體。
• validate_api_response：根據 Swagger 文檔中的架構定義驗證 API 響應，確保合規性。

💻 使用示例

配置完成後，您可以在支持 AI 的編輯器中使用 MCP 服務器來：

• 探索 API：“顯示此 API 中的可用端點”。
• 測試端點：“使用此數據測試 POST /users 端點”。
• 理解架構：“解釋用戶模型結構”。
• 調試 API 調用：“幫助我排查此 API 請求的問題”。
• 驗證響應：“檢查此響應是否符合 API 架構”。

📚 詳細文檔

支持的 IDE

服務器會自動檢測以下位置的配置文件：

• VS Code (.vscode/mcp.json)
• Cursor (.cursor/mcp.json)
• Windsurf (.windsurf/mcp.json)
• 根目錄 (mcp.json)
• 備用位置 (.mcp/config.json)

開發

# 克隆倉庫
git clone https://github.com/amrsa1/SwaggerMCP.git
cd SwaggerMCP

# 安裝依賴
npm install

# 以開發模式運行
npm run dev

# 構建生產版本
npm run build

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

貢獻說明

歡迎貢獻代碼！請隨時提交拉取請求。