Swagger 2.0 MCP 服务器

这是一个基于 Model Context Protocol (MCP) 的服务器，可以自动将 Swagger 2.0 API 规范转换为 MCP 工具，让 AI 助手能够直接调用 REST API。

功能特性

• 🔄 自动转换: 自动将 Swagger 2.0 规范转换为 MCP 工具

• 📝 完整参数支持: 支持路径参数、查询参数、请求头、表单数据和请求体

• 🛡️ 类型验证: 基于 Swagger 规范进行参数类型验证

• 🌐 HTTP 方法支持: 支持 GET、POST、PUT、DELETE 等所有 HTTP 方法

• 📊 响应处理: 智能处理 JSON 和文本响应

• 🚨 错误处理: 完善的错误处理和状态码报告

安装

方式一：通过 npm 安装（推荐）

方式二：从源码安装

1. 克隆项目：

2. 安装依赖：

3. 准备你的 swagger.json 文件，放在项目根目录下。

使用方法

启动服务器

使用本地 Swagger 文件

或者使用启动脚本：

使用远程 Swagger URL

开发模式（支持热重载）

URL 参数支持

服务器支持以下方式指定 Swagger 文档：

1. 本地文件（默认）：从项目根目录的 swagger.json 文件读取

2. 远程 URL：通过 --url 或 --swagger 参数指定远程 Swagger 文档

远程 URL 功能特性

• ✅ 自动验证: 验证 URL 格式和响应内容

• ✅ 超时控制: 可配置的请求超时时间（默认 10 秒）

• ✅ 缓存支持: 可选择将远程文档缓存到本地

• ✅ 错误处理: 详细的错误信息和重试机制

• ✅ 安全控制: 可在配置中禁用远程 URL 功能

配置选项

在 config.json 中可以配置以下选项：

Swagger 文件格式

确保你的 swagger.json 文件符合 Swagger 2.0 规范。示例结构：

工具命名规则

MCP 工具的命名遵循以下规则：

• 格式：{HTTP方法}_{路径}

• 路径中的 / 替换为 _

• 路径参数的 {} 被移除

示例：

• GET /users → GET_users

• POST /users/{id}/posts → POST_users_id_posts

• PUT /articles/{articleId} → PUT_articles_articleId

参数处理

服务器支持以下类型的参数：

路径参数 (Path Parameters)

查询参数 (Query Parameters)

请求头 (Header Parameters)

表单数据 (Form Data)

请求体 (Body Parameters)

响应格式

服务器返回的响应包含：

• HTTP 状态码

• 响应数据（JSON 或文本格式）

示例响应：

错误处理

服务器会处理以下类型的错误：

• Swagger 文件读取错误

• 无效的工具名称

• API 调用失败

• 网络连接错误

所有错误都会以 MCP 错误格式返回，包含详细的错误信息。

示例

本地示例

项目包含一个示例 swagger.json 文件，使用 JSONPlaceholder API 进行演示。你可以直接运行服务器来测试以下功能：

• 获取所有文章：GET_posts

• 根据 ID 获取文章：GET_posts_id

• 创建新文章：POST_posts

• 更新文章：PUT_posts_id

• 删除文章：DELETE_posts_id

• 获取用户列表：GET_users

• 根据 ID 获取用户：GET_users_id

远程 URL 示例

你可以使用以下公开的 Swagger API 进行测试：

1. Swagger Petstore API

2. JSONPlaceholder API

3. 自定义 API

在 Cursor 中使用

1. 配置 MCP 服务器

在 Cursor 的 MCP 配置文件中（通常位于 ~/.cursor/mcp.json）添加以下配置：

2. 多个 API 配置示例

3. 重启 Cursor

配置完成后，重启 Cursor 即可使用 Swagger API 工具。

使用流程示例

1. 配置 MCP 服务器： 在 Cursor 中配置 MCP 服务器（如上所示）

2. 重启 Cursor： 重启后 Cursor 会自动连接到 MCP 服务器

3. 使用 API 工具： 在 Cursor 中直接调用 API，例如：

   • 询问："帮我查找状态为 available 的宠物"

   • 询问："创建一个新的宠物记录"

   • 询问："获取商店库存信息"

开发

项目结构

自定义配置

你可以通过修改 swagger.json 文件来配置不同的 API：

1. 更新 host 字段指向你的 API 服务器

2. 修改 basePath 设置 API 基础路径

3. 添加或修改 paths 定义你的 API 端点

4. 更新 definitions 定义数据模型

发布到 npm

如果您想发布自己的版本：

1. 修改包名： 在 package.json 中修改 name 字段为您的包名

2. 登录 npm：

   npm login

3. 发布包：

   npm publish

4. 使用发布的包：

   npx your-package-name --url https://your-api.com/swagger.json

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

故障排除

常见问题

1. 远程 URL 无法访问

解决方案：

• 检查 URL 是否正确

• 确认 API 文档是否公开可访问

• 检查网络连接

2. URL 格式错误

解决方案：

• 确保 URL 以 http:// 或 https:// 开头

• 检查 URL 拼写是否正确

3. 配置不允许远程 URL

解决方案：

• 在 config.json 中设置 "allowRemoteUrl": true

4. 请求超时

解决方案：

• 检查网络连接

• 在 config.json 中增加 urlTimeout 值

• 尝试使用其他网络环境

5. Swagger 文档格式错误

解决方案：

• 确认文档是 Swagger 2.0 格式（不是 OpenAPI 3.0）

• 检查 JSON 格式是否正确

• 验证必需字段是否存在

调试技巧

1. 启用详细日志： 在 config.json 中设置 "enableConsole": true

2. 检查缓存文件： 如果启用了缓存，检查生成的 swagger-cache-*.json 文件

3. 测试 URL 可访问性：

   curl -H "Accept: application/json" https://your-api.com/swagger.json

4. 验证 Swagger 文档： 使用在线工具如 Swagger Editor 验证文档格式

支持

如果你遇到任何问题，请：

1. 检查上述故障排除指南

2. 确认 swagger.json 文件或远程 URL 格式是否正确

3. 确认 API 服务器是否可访问

4. 查看控制台错误信息

5. 提交 Issue 描述问题详情，包括：

   • 使用的命令

   • 错误信息

   • Swagger 文档 URL（如果使用远程 URL）