YApi interface docs

URL Detection

When user provides a URL, check if it matches the configured YApi instance:

1. Read config to get base_url:

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

1. If the URL's origin matches base_url, use yapi CLI to operate:

- Extract projectid from URL path (e.g., /project/123/... → projectid=123) - Extract apiid from URL path (e.g., .../api/456 → apiid=456) - Use yapi --path /api/interface/get --query id=<api_id> to fetch details

1. Example URL patterns:

- 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

Prerequisites

Check if yapi CLI is installed

yapi --version

If not installed, ask user to install globally

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

Check login status

yapi whoami

If not logged in, login interactively

yapi login

This will prompt for:

• YApi base URL (e.g., https://yapi.example.com)
• Email
• Password

Config is saved to ~/.yapi/config.toml.

Workflow

1. If user provides a YApi URL, check if it matches configured base_url in ~/.yapi/config.toml.
2. Ensure yapi CLI is installed (prompt user to install globally if missing).
3. Check login status with yapi whoami; if not logged in, run yapi login.
4. Load config from ~/.yapi/config.toml (baseurl, authmode, email/password or token, optional project_id).
5. Identify the target interface by id, URL, or keyword; ask for project/category ids if needed.
6. Call YApi endpoints with the CLI (see examples below) to fetch raw JSON.
7. Summarize method, path, headers, query/body schema, response schema, and examples.

CLI Usage

• Config location: ~/.yapi/config.toml
• Auth cache: ~/.yapi-mcp/auth-*.json

Common commands

# Check version
yapi --version

# Show help
yapi -h

# Check current user
yapi whoami

# Login (interactive)
yapi login

# Search interfaces
yapi search --q keyword

# Get interface by ID
yapi --path /api/interface/get --query id=123

# List interfaces in category
yapi --path /api/interface/list_cat --query catid=123

Docs sync

• Bind local docs to YApi category with yapi docs-sync bind add --name <binding> --dir <path> --project-id <id> --catid <id> (stored in .yapi/docs-sync.json).
• Sync with yapi docs-sync --binding <binding> or run all bindings with yapi docs-sync.
• Default syncs only changed files; use --force to sync everything.
• Mermaid rendering depends on mmdc (auto-installed if possible; failures do not block sync).
• For full Markdown render, install pandoc (manual install required).
• Extra mappings (generated after docs-sync run in binding mode):

- .yapi/docs-sync.links.json: local docs to YApi doc URLs. - .yapi/docs-sync.projects.json: cached project metadata/envs. - .yapi/docs-sync.deployments.json: local docs to deployed URLs.

Interface creation tips

• When adding interfaces, always set reqbodytype (use json if unsure) and provide res_body (prefer JSON Schema). Empty values can make /api/interface/add fail.
• Keep request/response structures in req* / resbody instead of stuffing them into desc or markdown.