Swagger MCP Server

# 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 安装（推荐） ```bash # 全局安装 npm install -g swagger-mcp # 或者使用 npx（无需安装） npx swagger-mcp --url https://petstore.swagger.io/v2/swagger.json ``` ### 方式二：从源码安装 1. 克隆项目： ```bash git clone <repository-url> cd swagger-mcp ``` 2. 安装依赖： ```bash npm install ``` 3. 准备你的 `swagger.json` 文件，放在项目根目录下。 ## 使用方法 ### 启动服务器 #### 使用本地 Swagger 文件 ```bash npm start ``` 或者使用启动脚本： ```bash ./start.sh ``` #### 使用远程 Swagger URL ```bash # 直接使用 Node.js node src/index.js --url https://petstore.swagger.io/v2/swagger.json # 或者使用启动脚本 ./start.sh --url https://petstore.swagger.io/v2/swagger.json # 也可以使用 --swagger 参数 ./start.sh --swagger https://api.example.com/docs/swagger.json ``` #### 开发模式（支持热重载） ```bash npm run dev ``` ### URL 参数支持 服务器支持以下方式指定 Swagger 文档： 1. **本地文件**（默认）：从项目根目录的 `swagger.json` 文件读取 2. **远程 URL**：通过 `--url` 或 `--swagger` 参数指定远程 Swagger 文档 #### 远程 URL 功能特性 - ✅ **自动验证**: 验证 URL 格式和响应内容 - ✅ **超时控制**: 可配置的请求超时时间（默认 10 秒） - ✅ **缓存支持**: 可选择将远程文档缓存到本地 - ✅ **错误处理**: 详细的错误信息和重试机制 - ✅ **安全控制**: 可在配置中禁用远程 URL 功能 #### 配置选项 在 `config.json` 中可以配置以下选项： ```json { "swagger": { "allowRemoteUrl": true, // 是否允许远程URL "urlTimeout": 10000, // URL请求超时时间(ms) "cacheRemoteSpec": true // 是否缓存远程文档 } } ``` ### Swagger 文件格式 确保你的 `swagger.json` 文件符合 Swagger 2.0 规范。示例结构： ```json { "swagger": "2.0", "info": { "title": "My API", "version": "1.0.0" }, "host": "api.example.com", "basePath": "/v1", "schemes": ["https"], "paths": { "/users": { "get": { "summary": "获取用户列表", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "required": false } ] } } } } ``` ## 工具命名规则 MCP 工具的命名遵循以下规则： - 格式：`{HTTP方法}_{路径}` - 路径中的 `/` 替换为 `_` - 路径参数的 `{}` 被移除 示例： - `GET /users` → `GET_users` - `POST /users/{id}/posts` → `POST_users_id_posts` - `PUT /articles/{articleId}` → `PUT_articles_articleId` ## 参数处理 服务器支持以下类型的参数： ### 路径参数 (Path Parameters) ```json { "name": "id", "in": "path", "required": true, "type": "integer" } ``` ### 查询参数 (Query Parameters) ```json { "name": "limit", "in": "query", "required": false, "type": "integer" } ``` ### 请求头 (Header Parameters) ```json { "name": "Authorization", "in": "header", "required": true, "type": "string" } ``` ### 表单数据 (Form Data) ```json { "name": "file", "in": "formData", "required": true, "type": "file" } ``` ### 请求体 (Body Parameters) ```json { "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } } } } ``` ## 响应格式 服务器返回的响应包含： - HTTP 状态码 - 响应数据（JSON 或文本格式） 示例响应： ``` 状态码: 200 响应数据: { "id": 1, "name": "John Doe", "email": "john@example.com" } ``` ## 错误处理 服务器会处理以下类型的错误： - 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 ```bash ./start.sh --url https://petstore.swagger.io/v2/swagger.json ``` #### 2. JSONPlaceholder API ```bash ./start.sh --url https://jsonplaceholder.typicode.com/swagger.json ``` #### 3. 自定义 API ```bash # 使用你自己的 API 文档 ./start.sh --url https://your-api.com/swagger.json # 或者使用不同的端点路径 ./start.sh --swagger https://your-api.com/api-docs ``` ### 在 Cursor 中使用 #### 1. 配置 MCP 服务器 在 Cursor 的 MCP 配置文件中（通常位于 `~/.cursor/mcp.json`）添加以下配置： ```json { "mcpServers": { "swagger-mcp": { "command": "npx", "args": [ "swagger-mcp", "--url", "https://petstore.swagger.io/v2/swagger.json" ] } } } ``` #### 2. 多个 API 配置示例 ```json { "mcpServers": { "petstore-api": { "command": "npx", "args": [ "swagger-mcp", "--url", "https://petstore.swagger.io/v2/swagger.json" ] }, "my-custom-api": { "command": "npx", "args": [ "swagger-mcp", "--swagger", "https://your-api.com/swagger.json" ] }, "local-swagger": { "command": "npx", "args": ["swagger-mcp"] } } } ``` #### 3. 重启 Cursor 配置完成后，重启 Cursor 即可使用 Swagger API 工具。 ### 使用流程示例 1. **配置 MCP 服务器**： 在 Cursor 中配置 MCP 服务器（如上所示） 2. **重启 Cursor**： 重启后 Cursor 会自动连接到 MCP 服务器 3. **使用 API 工具**： 在 Cursor 中直接调用 API，例如： - 询问："帮我查找状态为 available 的宠物" - 询问："创建一个新的宠物记录" - 询问："获取商店库存信息" ## 开发 ### 项目结构 ``` swagger-mcp/ ├── src/ │ └── index.js # 主服务器文件 ├── swagger.json # Swagger API 规范 ├── package.json # 项目配置 └── README.md # 项目文档 ``` ### 自定义配置 你可以通过修改 `swagger.json` 文件来配置不同的 API： 1. 更新 `host` 字段指向你的 API 服务器 2. 修改 `basePath` 设置 API 基础路径 3. 添加或修改 `paths` 定义你的 API 端点 4. 更新 `definitions` 定义数据模型 ## 发布到 npm 如果您想发布自己的版本： 1. **修改包名**： 在 `package.json` 中修改 `name` 字段为您的包名 2. **登录 npm**： ```bash npm login ``` 3. **发布包**： ```bash npm publish ``` 4. **使用发布的包**： ```bash npx your-package-name --url https://your-api.com/swagger.json ``` ## 许可证 MIT License ## 贡献 欢迎提交 Issue 和 Pull Request！ ## 故障排除 ### 常见问题 #### 1. 远程 URL 无法访问 ``` ❌ 无法从远程URL获取Swagger文档: HTTP错误: 404 Not Found ``` **解决方案**： - 检查 URL 是否正确 - 确认 API 文档是否公开可访问 - 检查网络连接 #### 2. URL 格式错误 ``` ❌ 无效的URL格式: invalid-url ``` **解决方案**： - 确保 URL 以 `http://` 或 `https://` 开头 - 检查 URL 拼写是否正确 #### 3. 配置不允许远程 URL ``` ❌ 配置不允许使用远程URL ``` **解决方案**： - 在 `config.json` 中设置 `"allowRemoteUrl": true` #### 4. 请求超时 ``` ❌ 远程URL请求超时 (10000ms) ``` **解决方案**： - 检查网络连接 - 在 `config.json` 中增加 `urlTimeout` 值 - 尝试使用其他网络环境 #### 5. Swagger 文档格式错误 ``` ❌ 不是有效的Swagger 2.0文档 ``` **解决方案**： - 确认文档是 Swagger 2.0 格式（不是 OpenAPI 3.0） - 检查 JSON 格式是否正确 - 验证必需字段是否存在 ### 调试技巧 1. **启用详细日志**： 在 `config.json` 中设置 `"enableConsole": true` 2. **检查缓存文件**： 如果启用了缓存，检查生成的 `swagger-cache-*.json` 文件 3. **测试 URL 可访问性**： ```bash curl -H "Accept: application/json" https://your-api.com/swagger.json ``` 4. **验证 Swagger 文档**： 使用在线工具如 [Swagger Editor](https://editor.swagger.io/) 验证文档格式 ## 支持 如果你遇到任何问题，请： 1. 检查上述故障排除指南 2. 确认 `swagger.json` 文件或远程 URL 格式是否正确 3. 确认 API 服务器是否可访问 4. 查看控制台错误信息 5. 提交 Issue 描述问题详情，包括： - 使用的命令 - 错误信息 - Swagger 文档 URL（如果使用远程 URL）