项目简介

Swagger MCP 是一个基于 Model Context Protocol (MCP) 实现的服务器，专为增强 LLM 客户端（如 AI 助手）处理 Swagger/OpenAPI API 定义的能力而设计。它不直接作为现有 API 的 MCP 封装，而是作为一种辅助工具，帮助 AI 理解 API 结构并生成集成所需的代码（如 MCP 工具定义和数据模型）。

主要功能点

• 获取 Swagger 定义: 从指定的 URL 下载 Swagger 或 OpenAPI 定义文件，并保存在本地。
• 列出 API 端点: 解析本地 Swagger 文件，列出所有可用的 API 端点、对应的 HTTP 方法和简要描述。
• 列出端点模型: 识别特定 API 端点在其请求或响应中使用的所有数据模型。
• 生成模型代码: 根据 Swagger 定义中的数据模型生成相应的 TypeScript 代码。
• 生成工具代码: 根据 Swagger 定义中的特定 API 端点生成对应的 MCP 工具定义 TypeScript 代码，包含详细的输入 Schema 信息。
• 提供工作流提示: 提供预定义的 Prompt 模板（如添加新端点），引导 AI 助手逐步完成任务。

安装步骤

1. 克隆仓库:

   git clone https://github.com/Vizioz/Swagger-MCP.git
   cd Swagger-MCP
   

2. 安装依赖:

   npm install
   

3. 配置环境变量: 复制示例配置文件并按需修改（通常只需设置端口等基础信息）。

   cp .env.example .env
   

4. 构建应用: 编译 TypeScript 代码。

   npm run build
   

服务器配置

MCP 客户端需要配置本服务器的启动命令和传输方式。本服务器支持 'stdio' 传输方式。

客户端配置（例如 Cursor 或其他 MCP 客户端）通常需要以下信息：

• 服务器名称: 例如 "Swagger MCP"
• 传输方式: 'stdio'
• 启动命令 (command): 运行编译后的 Node.js 文件的命令。例如，如果您的仓库克隆在 '/Users/username/projects/swagger-mcp'，则命令为 'node'。
• 命令参数 (args): 启动 Node.js 的脚本路径。例如，'["/Users/username/projects/swagger-mcp/build/index.js"]'。

服务器本身的配置（如端口、日志级别）通过 '.env' 文件管理，无需在客户端配置中提供命令行参数。

基本使用方法

一旦服务器通过 MCP 客户端连接成功，AI 助手即可使用其暴露的工具和 Prompt。典型的使用流程涉及以下步骤：

1. 使用 'getSwaggerDefinition' 工具下载目标 API 的 Swagger/OpenAPI 定义，并将保存的文件路径记录下来（通常需要手动创建 '.swagger-mcp' 文件并写入 'SWAGGER_FILEPATH=保存路径'）。
2. 使用 'listEndpoints' 工具查看 API 的所有可用端点。
3. 使用 'listEndpointModels' 工具查看特定端点涉及的数据模型。
4. 使用 'generateModelCode' 工具生成所需模型的 TypeScript 代码。
5. 使用 'generateEndpointToolCode' 工具为特定端点生成 MCP 工具定义代码。
6. 将生成的模型代码和工具代码集成到您的项目中，并根据需要实现工具处理逻辑（如实际的 API 调用、认证、错误处理等）。
7. 在您的主 MCP 服务器中注册新生成的工具。

也可以直接使用 'add-endpoint' 等 Prompt，让 AI 助手引导完成上述部分或全部流程。