YApi interface docs
Command policy
Prefer yapi command. If missing, fallback to one-shot npx without forcing global install:
yapi -h
fallback:
npx -y @leeguoo/yapi-mcp -h
In command examples below, yapi can be replaced by npx -y @leeguoo/yapi-mcp .
Quick workflow
-
If user gives a YApi URL, verify it belongs to configured base_url .
-
Confirm auth (yapi whoami ), then run yapi login --browser when needed (open base URL, finish login in browser, then press Enter to sync cookie).
-
Resolve target by api_id / keyword / category.
-
Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples.
-
For docs sync tasks, do --dry-run first, then real sync.
URL detection
- Read configured base_url from ~/.yapi/config.toml .
rg -n "^base_url\s*=" ~/.yapi/config.toml
-
If URL origin matches base_url , extract IDs from path:
-
/project/123/... -> project_id=123
-
.../api/456 -> api_id=456
-
.../api/cat_789 -> catid=789
-
Prefer direct lookup when api_id exists:
yapi --path /api/interface/get --query id=<api_id>
Common commands
version/help
yapi --version yapi -h
auth
yapi whoami yapi login --browser yapi login --login-url https://your-yapi-domain.com/ yapi logout
search / fetch
yapi search --q keyword --project-id 310 yapi --path /api/interface/get --query id=123 yapi --path /api/interface/list_cat --query catid=123
Config cache locations:
-
Config: ~/.yapi/config.toml
-
Auth cache: ~/.yapi-mcp/auth-*.json
Browser login dependency:
agent-browser-stealth -V
install once if missing browser runtime
agent-browser-stealth install
Docs sync
Binding mode (recommended):
yapi docs-sync bind add --name projectA --dir docs/release-notes --project-id 267 --catid 3667 yapi docs-sync --binding projectA --dry-run yapi docs-sync --binding projectA
Notes:
-
Binding file: .yapi/docs-sync.json
-
Mapping outputs: .yapi/docs-sync.links.json , .yapi/docs-sync.projects.json , .yapi/docs-sync.deployments.json
-
Default behavior syncs changed files only; use --force for full sync.
-
Compatible with directory .yapi.json config as fallback (without binding).
-
Mermaid/PlantUML/Graphviz/D2 rendering depends on local tool availability; missing tools do not block basic sync.
Interface creation guardrails
-
Always set req_body_type (use json if unsure) and provide res_body (prefer JSON Schema) when creating/updating interfaces.
-
Put structured request/response fields in req_* / res_body , not only in free-text desc /markdown .