Swagger Explorer

🚀 Swagger 探索器 MCP 服務器

Swagger 探索器 MCP 服務器是一個管理控制平面（MCP）服務器，可藉助 Claude 對 Swagger/OpenAPI 規範進行探索與分析，為 API 開發和管理提供便利。

🚀 快速開始

你可以使用 npx 全局安裝並運行該服務器：

npx -y @johnneerdael/swagger-mcp

也能通過環境變量進行安裝：

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

📦 安裝指南

針對 Claude Desktop 用戶的安裝說明

1. 打開工具和集成菜單。
2. 點擊“添加 MCP 服務器”按鈕。
3. 輸入以下配置：
   • 地址：localhost
   • 端口：3000
4. 完成後，MCP 服務器將自動運行。

💻 使用示例

基本探索

Claude: 你能通過 Swagger 接口幫我列出所有可用的 API 端點嗎？
你：當然可以！請提供 Swagger URL。

分析特定端點

Claude: GET /users 端點返回的數據格式是什麼？
你：讓我查看一下 Swagger 文檔。該端點返回一個包含用戶信息的對象，包括 ID、用戶名和電子郵件。

✨ 主要特性

1. 認證支持：通過 bearer 令牌進行身份驗證。
2. 自定義響應格式：支持 Minimal 和 Detailed 兩種響應模式。
3. 模式分析：自動解析並展示 API 接口的結構。
4. API 探索：提供完整的 API 文檔瀏覽功能。

📚 詳細文檔

配置說明

1. 環境變量設置
   • BASE_URL：服務的基礎 URL，默認為/api
   • AUTH_TOKEN：訪問令牌，用於身份驗證
   • PORT：服務運行的端口，默認為 3000
   • SWAGGER_URL：Swagger 文檔的 URL 地址

API 端點使用說明

探索 API

curl http://localhost:3000/explore \
  -H "Authorization: Bearer your-token"

獲取模式詳情

curl http://localhost:3000/schema-details \
  -H "Authorization: Bearer your-token" \
  -d '{"schemaName":"User"}'

獲取響應模式

curl http://localhost:3000/response-schemas \
  -H "Authorization: Bearer your-token"

響應格式

Minimal 模式

{
  "status": "success",
  "data": {}
}

Detailed 模式

{
  "status": "success",
  "data": {},
  "description": "完整的 API 接口文檔"
}

常見使用場景

1. 探索和分析 API 端點。
2. 獲取特定模式的詳細信息。
3. 分析和驗證響應格式。

故障排除

1. 連接問題
   • 確保 Swagger URL 可用
   • 檢查令牌是否正確
   • 驗證端口未被佔用
2. 授權錯誤
   • 確認 AUTH_TOKEN 設置正確
   • 請求中包含 bearer 令牌
3. 模式未找到
   • 檢查模式名稱是否準確
   • 確保 Swagger 規範已正確加載

安全注意事項

1. MCP 需要認證，若設置 AUTH_TOKEN 則必須提供。
2. 所有請求都會被記錄以備調試。
3. 敏感信息不會被緩存。
4. 實施速率限制以防止濫用。

開發說明

1. 克隆倉庫：

git clone [倉庫地址]

2. 安裝依賴項：

npm install

3. 構建項目：

npm run build

4. 本地運行：

npm start

📄 許可證

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