Swagger MCP Server

🚀 Swagger MCP 服務器

一個基於 Model Context Protocol (MCP) 的服務器，可解析 Swagger/OpenAPI 文檔，進而生成 TypeScript 類型和 API 客戶端代碼，為開發工作帶來便利。

🚀 快速開始

啟動服務器

node start-server.js

MCP Inspector 連接

啟動調試服務器後，可以使用以下命令連接：

npx @modelcontextprotocol/inspector pipe -- node start-server.js

或者直接方式（可能導致輸出混亂）：

npx @modelcontextprotocol/inspector -- node start-server.js

✨ 主要特性

此服務器能夠解析 Swagger 和 OpenAPI 文檔，並根據這些文檔生成 TypeScript 類型定義和 API 客戶端代碼。它支持多種客戶端框架，包括 Axios、Fetch 和 React Query，並且提供了優化功能以處理大型 API 文檔。

📦 安裝指南

通過 Smithery 安裝

要通過 Smithery 為 Claude Desktop 自動安裝 swagger-mcp-server：

npx -y @smithery/cli install @tuskermanshu/swagger-mcp-server --client claude

💻 使用示例

基礎用法

支持的 MCP 工具

1. parse-swagger - 解析 Swagger/OpenAPI 文檔，返回 API 操作信息
2. parse-swagger-optimized - 解析 Swagger/OpenAPI 文檔（優化版）
3. parse-swagger-lite - 輕量級解析 Swagger/OpenAPI 文檔，專為大型文檔優化
4. generate-typescript-types - 從 Swagger/OpenAPI 文檔生成 TypeScript 類型定義
5. generate-typescript-types-optimized - 從 Swagger/OpenAPI 文檔生成 TypeScript 類型定義（優化版）
6. generate-api-client - 從 Swagger/OpenAPI 文檔生成 API 客戶端代碼
7. generate-api-client-optimized - 從 Swagger/OpenAPI 文檔生成 API 客戶端代碼（優化版）
8. file-writer - 將內容寫入文件系統

支持的客戶端框架

• Axios: 功能全面的 Promise 基 HTTP 客戶端
• Fetch: 瀏覽器原生 API，無需額外依賴
• React Query: 用於 React 應用的數據獲取和緩存庫，提供 hooks 和緩存功能

高級用法

處理大型文檔

對於大型 API 文檔，建議使用以下配置：

1. 使用優化工具，啟用緩存和懶加載
2. 使用標籤或路徑前綴過濾，僅獲取需要的 API 操作
3. 僅在必要時包含模式定義
4. 設置合理的緩存有效期，避免頻繁重新解析

示例：

{
  "method": "parse-swagger-lite",
  "params": {
    "url": "https://your-large-api-doc-url.json",
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "filterTag": "your-specific-tag",
    "includeSchemas": false
  }
}

生成 React Query 客戶端

{
  "method": "generate-api-client-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/react-query",
    "clientType": "react-query",
    "generateTypeImports": true
  }
}

📚 詳細文檔

緩存管理

API 文檔緩存存儲在 .api-cache 目錄中。如果需要清除緩存，請刪除該目錄或設置 useCache: false 參數。

配置選項

可以在 swagger-mcp-config.json 中自定義服務器設置：

{
  "name": "Swagger MCP Server",
  "version": "1.0.0",
  "transport": "stdio"
}

項目路線圖

有關開發計劃和進度，請參見 road.md 文件。

構建項目

# 使用 npm 構建
npm run build

# 或使用 pnpm
pnpm build