名称： yapi
描述： 查询与同步 YApi 接口文档。当用户提及“yapi 接口文档”、YAPI 文档、询问请求/响应详情，或需要同步文档时使用。当用户粘贴的 YApi URL 与配置的 base_url 匹配时也会触发。

YApi 接口文档

URL 检测

当用户提供 URL 时，检查其是否与配置的 YApi 实例匹配：

1. 读取配置获取 base_url：

cat ~/.yapi/config.toml | grep base_url

2. 若 URL 的 origin 与 base_url 匹配，则使用 yapi CLI 进行操作：
   - 从 URL 路径中提取 project_id（例如 /project/123/... → project_id=123）
   - 从 URL 路径中提取 api_id（例如 .../api/456 → api_id=456）
   - 使用 yapi --path /api/interface/get --query id=<api_id> 获取详情

3. URL 模式示例：
   - https://yapi.example.com/project/123/interface/api/456 → project=123, api=456
   - https://yapi.example.com/project/123/interface/api/cat_789 → project=123, category=789

前置条件

检查 yapi CLI 是否已安装

yapi --version

若未安装，请用户全局安装

npm install -g @leeguoo/yapi-mcp
# 或
pnpm add -g @leeguoo/yapi-mcp

检查登录状态

yapi whoami

若未登录，则进行交互式登录

yapi login

此命令将提示输入：
- YApi 基础 URL（例如 https://yapi.example.com）
- 邮箱
- 密码

配置将保存至 ~/.yapi/config.toml。

工作流程

1. 若用户提供 YApi URL，检查其是否与 ~/.yapi/config.toml 中配置的 base_url 匹配。
2. 确保 yapi CLI 已安装（若缺失则提示用户全局安装）。
3. 使用 yapi whoami 检查登录状态；若未登录，则运行 yapi login。
4. 从 ~/.yapi/config.toml 加载配置（base_url、auth_mode、邮箱/密码或令牌，以及可选的 project_id）。
5. 通过 ID、URL 或关键词识别目标接口；必要时询问项目/分类 ID。
6. 使用 CLI 调用 YApi 端点（见下方示例）以获取原始 JSON 数据。
7. 总结方法、路径、请求头、查询/请求体结构、响应结构及示例。

CLI 使用

• 配置位置：~/.yapi/config.toml
• 认证缓存：~/.yapi-mcp/auth-*.json

常用命令

# 检查版本
yapi --version

# 显示帮助
yapi -h

# 检查当前用户
yapi whoami

# 登录（交互式）
yapi login

# 搜索接口
yapi search --q 关键词

# 通过 ID 获取接口
yapi --path /api/interface/get --query id=123

# 列出分类中的接口
yapi --path /api/interface/list_cat --query catid=123

文档同步

• 使用 yapi docs-sync bind add --name <绑定名> --dir <路径> --project-id <项目ID> --catid <分类ID> 将本地文档绑定到 YApi 分类（存储于 .yapi/docs-sync.json）。
• 使用 yapi docs-sync --binding <绑定名> 同步指定绑定，或运行 yapi docs-sync 同步所有绑定。
• 默认仅同步已更改的文件；使用 --force 可强制同步全部文件。
• Mermaid 渲染依赖 mmdc（若可能则自动安装；失败不会阻塞同步）。
• 如需完整的 Markdown 渲染，请安装 pandoc（需手动安装）。
• 额外生成的映射文件（在绑定模式下运行 docs-sync 后生成）：
• .yapi/docs-sync.links.json：本地文档到 YApi 文档 URL 的映射。
• .yapi/docs-sync.projects.json：缓存的项目元数据与环境信息。
• .yapi/docs-sync.deployments.json：本地文档到部署 URL 的映射。

接口创建提示

• 添加接口时，务必设置 req_body_type（不确定时使用 json）并提供 res_body（建议使用 JSON Schema）。空值可能导致 /api/interface/add 调用失败。
• 将请求/响应结构保持在 req_* / res_body 字段中，而非塞入 desc 或 markdown 字段。