YAPI MCP PRO

# 📋 YApi MCP 项目通用规则 ## 🎯 核心原则 ### 1. 明确性原则 - **始终明确指定项目ID和分类ID**，避免模糊表达 - **使用具体的接口ID**进行更新操作 - **提供完整的接口信息**，包括名称、方法、路径、参数、返回值 ### 2. 渐进式操作 - **先查询再操作**：创建接口前先获取项目分类列表 - **逐步确认**：批量操作时逐个确认每个接口 - **验证结果**：操作完成后验证接口是否正确创建 ### 3. 标准化格式 - **统一命名规范**：接口名称使用中文描述功能 - **路径规范**：遵循 RESTful API 设计原则 - **参数格式**：使用标准 JSON 格式描述参数 ## 🛠️ 可用工具清单 | 工具名称 | 功能描述 | 使用场景 | |---------|----------|----------| | `yapi_list_projects` | 列出所有可用项目 | 查看项目列表，获取项目ID | | `yapi_get_categories` | 获取项目分类列表 | 查看分类结构，获取分类ID | | `yapi_search_apis` | 搜索接口 | 查找现有接口，避免重复创建 | | `yapi_get_api_desc` | 获取接口详情 | 查看完整接口定义 | | `yapi_save_api` | 新增/更新接口 | 创建新接口或修改现有接口 | ## 📝 标准操作流程 ### 🔍 1. 项目探索流程 ``` 第一步：请列出所有可用的YApi项目 第二步：请获取项目[ID]的接口分类列表 第三步：请搜索项目中是否已存在类似接口 ``` ### ✏️ 2. 接口创建流程 ``` 第一步：确认项目ID和分类ID 第二步：检查是否存在重复接口 第三步：创建接口（使用完整参数） 第四步：验证创建结果 ``` ### 🔄 3. 接口更新流程 ``` 第一步：获取现有接口详情 第二步：明确需要修改的内容 第三步：执行更新操作 第四步：验证更新结果 ``` ## 🎨 命令模板库 ### 📊 项目管理模板 #### 查看项目列表 ``` 请列出所有可用的YApi项目 ``` #### 查看项目分类 ``` 请获取项目[项目ID]的接口分类列表 ``` #### 搜索现有接口 ``` 请搜索项目[项目ID]中包含"[关键字]"的接口 请搜索路径包含"[路径关键字]"的接口 ``` ### ✏️ 接口创建模板 #### 基础接口创建 ``` 请在YApi中创建接口： - 项目ID：[项目ID] - 分类ID：[分类ID]（[分类名称]） - 接口名称：[接口名称] - 请求方法：[GET/POST/PUT/DELETE] - 接口路径：[接口路径] - 接口描述：[详细描述] - 请求参数： - [参数名]: [类型]，[描述]，[必填/选填] - 返回数据： - [字段名]: [类型]，[描述] ``` #### RESTful API 套件创建 ``` 请为[功能模块]创建完整的CRUD接口套件： 1. 列表查询 - 方法：GET - 路径：/api/[模块]/list - 查询参数：page, limit, keyword 2. 详情查询 - 方法：GET - 路径：/api/[模块]/{id} - 路径参数：id 3. 新增记录 - 方法：POST - 路径：/api/[模块] - 请求体：[模块]信息JSON 4. 更新记录 - 方法：PUT - 路径：/api/[模块]/{id} - 路径参数：id - 请求体：更新的[模块]信息JSON 5. 删除记录 - 方法：DELETE - 路径：/api/[模块]/{id} - 路径参数：id 请创建到项目[项目ID]的"[分类名称]"分类中。 ``` #### 文件上传接口模板 ``` 请创建文件上传接口： - 项目：[项目名称]（ID: [项目ID]） - 分类：[分类名称]（ID: [分类ID]） - 接口名称：[文件类型]文件上传 - 请求方法：POST - 接口路径：/api/[模块]/upload - 请求体类型：form（表单） - 表单参数： - file: 文件，[文件描述]，必填 - [其他参数]: [类型]，[描述]，[必填/选填] - 请求头： - Authorization: Bearer token，必填 - Content-Type: multipart/form-data - 返回数据： - code: 状态码（200成功，400失败） - message: 返回消息 - data: 文件信息对象 ``` ### 🔄 接口更新模板 #### 基础更新 ``` 请更新接口ID为[接口ID]的信息： - 修改接口描述：[新描述] - 添加请求参数： - [参数名]: [类型]，[描述]，[必填/选填] - 修改返回数据： - [字段名]: [类型]，[描述] ``` #### 批量更新 ``` 请批量更新以下接口的状态为"已完成"： - 接口ID：[ID1] - [接口名称1] - 接口ID：[ID2] - [接口名称2] - 接口ID：[ID3] - [接口名称3] ``` ### 🤖 代码分析模板 #### 后端代码分析 ``` 分析以下[框架名称]代码，并在YApi中创建对应的接口文档： ```[语言] [粘贴代码内容] ``` 请创建到项目[项目ID]的"[分类名称]"分类中。 要求： 1. 自动识别请求方法和路径 2. 解析请求参数和响应格式 3. 生成完整的接口文档 4. 添加适当的示例数据 ``` #### 前端代码分析 ``` 分析以下前端API调用代码，帮我在YApi中创建对应的接口： ```[语言] [粘贴前端代码] ``` 请根据代码中的API调用创建接口文档，项目ID：[项目ID] ``` ## 📋 JSON 参数标准格式 ### 路径参数格式 ```json [ { "name": "id", "desc": "记录ID", "required": "1" } ] ``` ### 查询参数格式 ```json [ { "name": "page", "desc": "页码", "required": "1", "example": "1" }, { "name": "limit", "desc": "每页数量", "required": "0", "example": "20" }, { "name": "keyword", "desc": "搜索关键字", "required": "0", "example": "搜索内容" } ] ``` ### 请求头格式 ```json [ { "name": "Authorization", "value": "Bearer token", "desc": "认证令牌", "required": "1" }, { "name": "Content-Type", "value": "application/json", "desc": "内容类型", "required": "1" } ] ``` ### 表单参数格式 ```json [ { "name": "username", "type": "text", "desc": "用户名", "required": "1", "example": "zhangsan" }, { "name": "avatar", "type": "file", "desc": "头像文件", "required": "0" } ] ``` ### 标准响应格式 ```json { "code": 200, "message": "操作成功", "data": { "id": 12345, "name": "示例数据", "createdAt": "2024-01-01T00:00:00Z" }, "timestamp": 1704067200000 } ``` ## ⚠️ 重要注意事项 ### 🔐 认证相关 1. **Cookie 认证**： - Cookie 可能会过期，需要重新获取 - 确保复制完整的 Cookie 内容 - 包含 `_yapi_token` 和 `_yapi_uid` 2. **Token 认证**： - 确保项目ID与Token匹配 - Token 格式：`projectId:token` - 多项目用逗号分隔 ### 📊 操作限制 1. **频率限制**：大量操作时注意API调用频率 2. **权限检查**：确保有目标项目的编辑权限 3. **数据验证**：JSON 参数格式必须正确 ### 🔧 故障处理 1. **连接问题**： ```bash ./start-mcp.sh status # 检查服务器状态 ./start-mcp.sh restart # 重启服务器 ./start-mcp.sh logs # 查看日志 ``` 2. **权限错误**： - 检查 Cookie 或 Token 有效性 - 确认项目访问权限 - 重新获取认证信息 3. **数据错误**： - 验证 JSON 格式正确性 - 检查必填参数是否完整 - 确认项目ID和分类ID存在 ## 🎯 最佳实践 ### 1. 命名规范 - **接口名称**：使用中文，清晰描述功能 - **路径设计**：遵循 RESTful 原则 - **参数命名**：使用驼峰命名法 ### 2. 文档质量 - **完整描述**：提供详细的接口说明 - **示例数据**：包含真实的请求/响应示例 - **错误处理**：说明可能的错误情况 ### 3. 团队协作 - **统一标准**：团队内使用相同的接口规范 - **及时更新**：代码变更后及时更新接口文档 - **版本管理**：重大变更时创建新版本 ### 4. 安全考虑 - **敏感信息**：不在示例中包含真实的敏感数据 - **权限控制**：合理设置接口访问权限 - **数据验证**：确保输入参数的安全性 ## 🚀 高效使用技巧 ### 1. 快速查找 ``` # 查找特定功能的接口 请搜索包含"用户"和"登录"的接口 # 查找特定路径的接口 请搜索路径包含"/api/v1/user"的接口 ``` ### 2. 批量操作 ``` # 批量创建相关接口 请为用户管理模块创建以下接口：[列出所有接口] # 批量更新接口状态 请将以下接口状态更新为"已完成"：[列出接口ID] ``` ### 3. 代码同步 ``` # 从代码生成接口 分析这段代码并创建对应的YApi接口：[粘贴代码] # 更新现有接口 根据新的代码更新接口ID为[ID]的定义：[粘贴新代码] ``` --- ## 📞 支持与反馈 遇到问题时，请按以下顺序排查： 1. 检查服务器状态和日志 2. 验证认证信息有效性 3. 确认参数格式正确性 4. 查看项目权限设置 **记住**：明确、完整、标准化是使用 YApi MCP 的三大关键原则！🎯