/yapi

name: yapi
description: Query and sync YApi interface documentation. Use when user mentions "yapi 接口文档", YAPI docs, asks for request/response details, or needs docs sync. Also triggers when user pastes a YApi URL that matches the configured base_url.

YApi interface docs

Install / update

Preferred install / refresh flow:

npx skills add leeguooooo/cross-request-master -y -g

Preferred config bootstrap after skill install:

yapi config init --base-url=https://your-yapi-domain.com --auth-mode=global --email=YOUR_EMAIL
yapi login --base-url=https://your-yapi-domain.com --browser

Compatibility path when the user also wants to write `~/.yapi/config.toml` in one step:

npm install -g @leeguoo/yapi-mcp
yapi install-skill --yapi-base-url=https://your-yapi-domain.com --yapi-auth-mode=global --yapi-email=YOUR_EMAIL --force

Command policy

Always use the real `yapi` CLI directly; **do not call plugin-local `node scripts/...` files from the user's project**. Inside Cursor or Claude Code, commands run from the user's workspace, so relative plugin paths are unreliable.

Prefer `yapi` command. If missing, fallback to one-shot npx without forcing global install:

yapi -h
# fallback:
npx -y -p @leeguoo/yapi-mcp yapi -h

In command examples below, `yapi` can be replaced by `npx -y -p @leeguoo/yapi-mcp yapi`. When CLI version is newer than the installed skill snapshot, `yapi` warns and asks to rerun:

npx skills add leeguooooo/cross-request-master -y -g
# compatibility:
npx -y -p @leeguoo/yapi-mcp yapi install-skill --force

Setup / auth bootstrap

1. Read configured `base_url` from `~/.yapi/config.toml` when available. 2. If config is missing, prefer browser login bootstrap:

yapi login --base-url https://your-yapi-domain.com --browser
# optional explicit page:
yapi login --base-url https://your-yapi-domain.com --login-url https://your-yapi-domain.com/

3. If the user provides email/password, global auth also works:

yapi login --base-url https://your-yapi-domain.com --email you@example.com --password '***'

4. Validate login before deeper operations:

yapi whoami

Quick workflow

1. **Classify the user input first** — do not pick a strategy until you know which it is:

• **A. YApi page URL** (`https://yapi.example.com/project/123/api/456`) → extract IDs from path → `yapi interface get --id 456`. Skip search.
• **B. HTTP endpoint path** (`/api/auth/token`, `/v1/users/:id`) → see `## Find interface by HTTP path` below. **`yapi search` does not index paths**, do not use it for this case.
• **C. Product keyword** (`语音房列表`, `voice room`) → `yapi search` with keyword expansion (see `## Keyword expansion`).
• **D. Numeric `api_id`** → `yapi interface get --id <api_id>` directly.

2. Confirm auth (`yapi whoami`), then run `yapi login --browser` when needed (open base URL, finish login in browser, then press Enter to sync cookie). 3. Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples. 4. For docs sync tasks, do `--dry-run` first, then real sync. 5. If docs sync still hits `413`, note that CLI already retries the file with `--mermaid-classic`; if it still fails, split the doc or reduce embedded diagrams.

Find interface by HTTP path

When the user gives an HTTP endpoint path like `/api/auth/token` (not a YApi page URL), `yapi search` will return empty because YApi's project search **does not index interface paths**. Use `yapi interface list-menu` with the built-in `--path` filter instead — the CLI does the filtering, no shell pipes needed.

**Required input**: project ID. If the user did not provide one, ask first or list candidates (`yapi project list --group-id <id>`); do not start enumerating projects/groups speculatively.

# substring match, case-insensitive (matches /api/auth/token, /api/auth/token/refresh, etc.)
yapi interface list-menu --project-id 365 --path /api/auth/token

# narrow further by HTTP method (case-insensitive exact match)
yapi interface list-menu --project-id 365 --path /api/auth/token --method POST

# combine to find all POST endpoints under a prefix
yapi interface list-menu --project-id 365 --path /api/auth --method POST

The filtered response shape is:

{
  "errcode": 0,
  "data": {
    "matches": [
      { "project_id": 365, "catid": 100, "cat_name": "Auth",
        "_id": 31400, "title": "Get Token", "path": "/api/auth/token", "method": "POST" }
    ],
    "total": 1
  }
}

After locating the `_id`, fetch full details:

yapi interface get --id 31400

**Anti-patterns — do not do these**:

• ❌ `yapi search --q '/api/auth/token'` (project search does not index paths; will return empty)
• ❌ `yapi interface list --project-id X --limit all | python ...` (slow, brittle, blocked by most security gates)
• ❌ Enumerating groups → projects → repeated `search` to guess where the path lives. Ask the user for the project instead.

Keyword expansion

Do not stop after one failed `yapi search`.

When the user asks with fuzzy product wording such as "语音房列表", "房间列表", "房间详情", "推荐房间", "语音房", "直播间", or similar:

1. Search the original phrase first. 2. If there is no direct hit, immediately retry 3-6 closely related variants before asking the user for more detail. 3. Prefer Chinese variants, English variants, and endpoint-style nouns. 4. If there are still no interface hits, search likely related nouns/categories separately before giving up.

Suggested expansions for room-style queries:

• `语音房列表`
• `房间列表`
• `语音房`
• `房间详情`
• `房间推荐`
• `room list`
• `room detail`
• `voice room`

Example:

yapi search --q "语音房列表"
yapi search --q "房间列表"
yapi search --q "语音房"
yapi search --q "房间详情"
yapi search --q "room list"
yapi search --q "voice room"

Only ask the user for project name / extra keywords after the expanded search pass still returns no useful interface results.

URL detection

1. Read con