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