星战科技xingzhan.cloud
返回市场
swagger-mcp-服务器

swagger-mcp-服务器

作者：tuskermanshu16 星标更新：2025-03-20
安装使用来源：spider==github.com

项目介绍

Swagger MCP Server

smithery 徽章

基于模型上下文协议（MCP）的服务器，用于解析Swagger/OpenAPI文档并生成TypeScript类型定义和API客户端代码。

功能

  • 分析Swagger/OpenAPI文档，支持v2和v3规范
  • 生成TypeScript类型定义
  • 为不同框架生成API客户端代码（如Axios、Fetch、React Query等）
  • 通过MCP协议提供这些功能，便于与大型语言模型集成
  • 优化大型文档处理：
    • 内存和文件系统缓存机制
    • 延迟加载解析策略
    • 增量解析和部分结果返回
    • 进度反馈
    • 自动识别不同格式的Swagger UI URL

快速开始

安装依赖

npm install
# 或者使用pnpm
pnpm install

启动服务器

node start-server.js

服务器默认使用标准输入/输出通信。

使用MCP工具

可以通过标准输入/输出与MCP服务器通信。这里有一些示例：

# 解析Swagger文档
node examples/optimized-swagger-parser-example.js

# 生成TypeScript类型
node examples/typescript-generator-example.js

# 生成API客户端
node examples/api-client-generator-example.js

可用工具

1. Swagger/OpenAPI解析工具

标准解析工具 (parse-swagger)

{
  "method": "parse-swagger",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": true,
    "includeDetails": true
  }
}

优化解析工具 (parse-swagger-optimized)

适用于带有高级选项的完全解析：

{
  "method": "parse-swagger-optimized",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": true,
    "includeDetails": true,
    "useCache": true,
    "skipValidation": true,
    "cacheTTLMinutes": 60,
    "lazyLoading": false,
    "filterTag": "pet"
  }
}

轻量级解析工具 (parse-swagger-lite)

针对大型文档快速优化，但仅返回基本信息：

{
  "method": "parse-swagger-lite",
  "params": {
    "url": "https://petstore3.swagger.io/api/v3/openapi.json",
    "includeSchemas": false,
    1. "includeDetails": false,
    "useCache": true,
    "skipValidation": true
  }
}

2. TypeScript类型生成工具

生成TypeScript类型

{
  "method": "generate-typescript-types",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/types",
    "namespace": "PetStore",
    "strictTypes": true,
    "generateEnums": true,
    "generateIndex": true
  }
}

优化类型生成器 (generate-typescript-types-optimized)

{
  "method": "generate-typescript-types-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/types",
    "namespace": "PetStore",
    "strictTypes": true,
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "includeSchemas": ["Pet", "Order", "User"]
  }
}

3. API客户端生成工具

标准API客户端生成器 (generate-api-client)

{
  "method": "generate-api-client",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/api",
    "clientType": "axios",
    "generateTypeImports": true,
    "typesImportPath": "../types",
    "groupBy": "tag"
  }
}

优化API客户端生成器 (generate-api-client-optimized)

{
  "method": "generate-api-client-optimized",
  "params": {
    "swaggerUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
    "outputDir": "./generated/api",
    "clientType": "react-query",
    "generateTypeImports": true,
    "typesImportPath": "../types",
    "groupBy": "tag",
    "useCache": true,
    "skipValidation": true,
    "lazyLoading": true,
    "includeTags": ["pet", "store"]
  }
}

4. 文件写入工具

{
  "method": "file-writer",
  "params": {
    "filePath": "./output.txt",
    "content": "Hello, world!",
    "createDirs": true
  }
}

处理大型API文档

对于大型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
  }
}

支持的客户端框架

目前支持以下API客户端框架：

  • Axios：一个基于Promise的全功能HTTP客户端
  • Fetch：浏览器原生API，无需额外依赖
  • React Query：一个用于React应用的数据获取和缓存库，提供钩子和缓存功能

示例 - 生成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目录中。如果需要清除缓存：

  1. 删除.api-cache目录
  2. 或设置useCache: false参数

配置选项

可以在swagger-mcp-config.json中自定义服务器设置：

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

开发和调试

启动调试服务器：

node start-server.js

然后使用MCP Inspector连接：

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

或者直接（但可能会导致输出混乱）：

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

项目路线图

参见road.md文档了解开发计划和进度。

安装

通过Smithery安装

要通过Smithery自动安装Swagger MCP Server到Claude Desktop：

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

构建

# 构建项目
npm run build

# 或使用pnpm
pnpm build

可用的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 - 将内容写入文件系统