Yapi

Query and sync YApi interface documentation. Use when user mentions "yapi 接口文档", YAPI docs, asks for request/response details, or needs docs sync. Also trigg...

Security Scan

The skill's requests and runtime instructions are consistent with a YApi documentation helper: it uses the yapi CLI (or npx fallback), reads YApi config/auth cache under the user's home, and performs doc-sync operations — nothing appears unrelated or excessive.

Purpose & Capability

The name/description (YApi docs query & sync) match the instructions: invoking the yapi CLI or the @leeguoo/yapi-mcp package, resolving api/project IDs, fetching JSON, and running docs-sync. Required files/paths referenced (~/.yapi/config.toml and ~/.yapi-mcp/auth-*.json) are directly relevant to locating the configured base_url and authentication state.

Instruction Scope

SKILL.md explicitly instructs reading the user's YApi config and auth cache and running yapi commands (whoami, login, search, docs-sync). These actions are within the task scope, but reading auth-cache files is sensitive (they may contain credentials/tokens) — the instructions do not attempt to exfiltrate them, but they do rely on local credential files.

Install Mechanism

There is no install spec (instruction-only). The guidance prefers a local yapi binary and falls back to 'npx -y @leeguoo/yapi-mcp'. Using npx executes code fetched from the npm registry on demand, which is common but carries the usual risk of executing third-party package code each run; consider pinning or preinstalling a vetted version if you want to avoid on-the-fly downloads.

Credentials

The skill requests no environment variables and does not require unrelated credentials. It references config and auth cache files in the user's home (appropriate for YApi operations). Those files are sensitive, so access is proportionate but should be treated as sensitive.

Persistence & Privilege

always is false and autonomous invocation is allowed (platform default). The skill's documented behavior may write project-local binding and mapping files (.yapi/docs-sync.json, .yapi.docs-sync.*) during syncs, which is expected and limited to the working project directory. It does not request system-wide or other-skills configuration changes.

Assessment

This skill appears to do what it says: call the yapi CLI (or use the @leeguoo/yapi-mcp npm package) and read your YApi config/auth files to fetch and sync interface docs. Before installing or using it: (1) confirm you trust the @leeguoo/yapi-mcp package (inspect its npm/GitHub source) because the fallback uses npx which runs remote code; (2) be aware the skill reads ~/.yapi/config.toml and ~/.yapi-mcp/auth-*.json (these can contain tokens) — avoid running it with highly privileged accounts unless you trust the environment; (3) if you want to reduce runtime risk, preinstall a vetted yapi CLI or a pinned version of the npm package instead of using npx -y; (4) expect the docs-sync commands to create/update .yapi/*.json files in your project directory — review those outputs before committing them.

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

1. If user gives a YApi URL, verify it belongs to configured base_url.
2. Confirm auth (yapi whoami), then run yapi login only when needed.
3. Resolve target by api_id / keyword / category.
4. Fetch raw JSON first, then summarize: method, path, headers, params, body, response schema/examples.
5. For docs sync tasks, do --dry-run first, then real sync.

URL detection

1. Read configured base_url from ~/.yapi/config.toml.

rg -n "^base_url\\s*=" ~/.yapi/config.toml

2. 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
3. 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

# 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

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.