@leeguoo/yapi-mcp 0.3.16 → 0.3.21

package/dist/yapi-cli.js

@@ -164,6 +164,10 @@ function parseArgs(argv) {
             options.version = true;
             continue;
         }
+        if (arg === "--no-update" || arg === "--no-update-check") {
+            options.noUpdate = true;
+            continue;
+        }
         if (arg === "--config") {
             options.config = argv[++i];
             continue;
@@ -308,6 +312,84 @@ function parseArgs(argv) {
             options.timeout = Number(arg.slice(10));
             continue;
         }
+        if (arg === "--name") {
+            options.name = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--name=")) {
+            options.name = arg.slice(7);
+            continue;
+        }
+        if (arg === "--desc") {
+            options.desc = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--desc=")) {
+            options.desc = arg.slice(7);
+            continue;
+        }
+        if (arg === "--cat-id" || arg === "--catid") {
+            options.catId = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--cat-id=")) {
+            options.catId = arg.slice(9);
+            continue;
+        }
+        if (arg.startsWith("--catid=")) {
+            options.catId = arg.slice(8);
+            continue;
+        }
+        if (arg === "--id") {
+            options.id = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--id=")) {
+            options.id = arg.slice(5);
+            continue;
+        }
+        if (arg === "--group-id") {
+            options.groupId = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--group-id=")) {
+            options.groupId = arg.slice(11);
+            continue;
+        }
+        if (arg === "--type") {
+            options.type = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--type=")) {
+            options.type = arg.slice(7);
+            continue;
+        }
+        if (arg === "--type-id") {
+            options.typeId = argv[++i];
+            continue;
+        }
+        if (arg.startsWith("--type-id=")) {
+            options.typeId = arg.slice(10);
+            continue;
+        }
+        if (arg === "--page") {
+            options.page = Number(argv[++i]);
+            continue;
+        }
+        if (arg.startsWith("--page=")) {
+            options.page = Number(arg.slice(7));
+            continue;
+        }
+        if (arg === "--limit") {
+            const raw = String(argv[++i] ?? "").trim();
+            options.limit = raw.toLowerCase() === "all" ? "all" : Number(raw);
+            continue;
+        }
+        if (arg.startsWith("--limit=")) {
+            const raw = String(arg.slice(8)).trim();
+            options.limit = raw.toLowerCase() === "all" ? "all" : Number(raw);
+            continue;
+        }
         if (arg === "--no-pretty") {
             options.noPretty = true;
             continue;
@@ -462,10 +544,6 @@ function parseDocsSyncArgs(argv) {
                 options.mermaidLook = "handDrawn";
             continue;
         }
-        if (arg === "--d2-sketch") {
-            options.d2Sketch = true;
-            continue;
-        }
         if (arg === "--force") {
             options.force = true;
             continue;
@@ -555,6 +633,10 @@ function usage() {
     return [
         "Usage:",
         "  yapi --path /api/interface/get --query id=123",
+        "  yapi group [options]",
+        "  yapi project [options]",
+        "  yapi interface [options]",
+        "  yapi log [options]",
         "  yapi docs-sync [options] [dir...]",
         "  yapi docs-sync bind <action> [options]",
         "  yapi login [options]",
@@ -565,7 +647,7 @@ function usage() {
         "  --config <path>        config file path (default: ~/.yapi/config.toml)",
         "  --base-url <url>       YApi base URL",
         "  --token <token>        project token (supports projectId:token)",
-        "  --project-id <id>      select token for project",
+        "  --project-id <id>      select token for project (filters search results)",
         "  --auth-mode <mode>     token or global",
         "  --email <email>        login email for global mode",
         "  --password <pwd>       login password for global mode",
@@ -579,6 +661,16 @@ function usage() {
         "  --data <payload>       request body (JSON or text)",
         "  --data-file <file>     request body file",
         "  --timeout <ms>         request timeout in ms",
+        "  --id <id>              resource id (for group/project/interface)",
+        "  --name <name>          category name (for interface cat)",
+        "  --desc <desc>          category description (for interface cat)",
+        "  --cat-id <id>          category id (for interface cat)",
+        "  --group-id <id>        group id (for project list)",
+        "  --type <type>          log type (for log list)",
+        "  --type-id <id>         log type id (for log list)",
+        "  --page <n>             page number (for list)",
+        "  --limit <n|all>        page size (for list)",
+        "  --no-update            disable update check",
         "  --no-pretty            print raw response",
         "Docs-sync options:",
         "  --dir <path>           docs directory (repeatable; default: docs/release-notes)",
@@ -588,7 +680,6 @@ function usage() {
         "  --mermaid-hand-drawn   force mermaid hand-drawn look (default)",
         "  --mermaid-classic      render mermaid with classic look",
         "  --mermaid-hand-drawn-seed <n>  hand-drawn seed (implies hand-drawn look)",
-        "  --d2-sketch            render D2 diagrams in sketch style",
         "  --force                sync all files even if unchanged",
         "Docs-sync bind actions:",
         "  list, get, add, update, remove",
@@ -619,7 +710,6 @@ function docsSyncUsage() {
         "  --mermaid-hand-drawn   force mermaid hand-drawn look (default)",
         "  --mermaid-classic      render mermaid with classic look",
         "  --mermaid-hand-drawn-seed <n>  hand-drawn seed (implies hand-drawn look)",
-        "  --d2-sketch            render D2 diagrams in sketch style",
         "  --force                sync all files even if unchanged",
         "  -h, --help             show help",
     ].join("\n");
@@ -695,6 +785,105 @@ function searchUsage() {
         "  -h, --help             show help",
     ].join("\n");
 }
+function groupUsage() {
+    return [
+        "Usage:",
+        "  yapi group list",
+        "  yapi group get --id <group_id>",
+        "Options:",
+        "  --config <path>        config file path (default: ~/.yapi/config.toml)",
+        "  --base-url <url>       YApi base URL",
+        "  --token <token>        project token (supports projectId:token)",
+        "  --project-id <id>      select token for project",
+        "  --auth-mode <mode>     token or global",
+        "  --email <email>        login email for global mode",
+        "  --password <pwd>       login password for global mode",
+        "  --cookie <cookie>      cookie for global mode",
+        "  --token-param <name>   token query param name (default: token)",
+        "  --timeout <ms>         request timeout in ms",
+        "  --id <id>              group id (for get)",
+        "  --no-pretty            print raw response",
+        "  -h, --help             show help",
+    ].join("\n");
+}
+function projectUsage() {
+    return [
+        "Usage:",
+        "  yapi project list --group-id <group_id> [--page <n>] [--limit <n>]",
+        "  yapi project get --id <project_id>",
+        "  yapi project token --project-id <project_id>",
+        "Options:",
+        "  --config <path>        config file path (default: ~/.yapi/config.toml)",
+        "  --base-url <url>       YApi base URL",
+        "  --token <token>        project token (supports projectId:token)",
+        "  --project-id <id>      select token for project",
+        "  --auth-mode <mode>     token or global",
+        "  --email <email>        login email for global mode",
+        "  --password <pwd>       login password for global mode",
+        "  --cookie <cookie>      cookie for global mode",
+        "  --token-param <name>   token query param name (default: token)",
+        "  --timeout <ms>         request timeout in ms",
+        "  --group-id <id>        group id (for list)",
+        "  --id <id>              project id (for get)",
+        "  --page <n>             page number (default: 1)",
+        "  --limit <n>            page size (default: 10)",
+        "  --no-pretty            print raw response",
+        "  -h, --help             show help",
+    ].join("\n");
+}
+function interfaceUsage() {
+    return [
+        "Usage:",
+        "  yapi interface list --project-id <project_id> [--page <n>] [--limit <n>]",
+        "  yapi interface list-menu --project-id <project_id>",
+        "  yapi interface get --id <api_id>",
+        "  yapi interface cat add --project-id <project_id> --name <name> [--desc <desc>]",
+        "  yapi interface cat update --cat-id <cat_id> --name <name> [--desc <desc>]",
+        "  yapi interface cat delete --cat-id <cat_id>",
+        "Options:",
+        "  --config <path>        config file path (default: ~/.yapi/config.toml)",
+        "  --base-url <url>       YApi base URL",
+        "  --token <token>        project token (supports projectId:token)",
+        "  --project-id <id>      select token for project",
+        "  --auth-mode <mode>     token or global",
+        "  --email <email>        login email for global mode",
+        "  --password <pwd>       login password for global mode",
+        "  --cookie <cookie>      cookie for global mode",
+        "  --token-param <name>   token query param name (default: token)",
+        "  --timeout <ms>         request timeout in ms",
+        "  --id <id>              interface id (for get)",
+        "  --cat-id <id>          category id (for cat update/delete)",
+        "  --name <name>          category name (for cat add/update)",
+        "  --desc <desc>          category description (for cat add/update)",
+        "  --page <n>             page number (default: 1)",
+        "  --limit <n|all>        page size (default: 20)",
+        "  --no-pretty            print raw response",
+        "  -h, --help             show help",
+    ].join("\n");
+}
+function logUsage() {
+    return [
+        "Usage:",
+        "  yapi log list --type <type> --type-id <id> [--page <n>] [--limit <n>]",
+        "Options:",
+        "  --config <path>        config file path (default: ~/.yapi/config.toml)",
+        "  --base-url <url>       YApi base URL",
+        "  --token <token>        project token (supports projectId:token)",
+        "  --project-id <id>      select token for project",
+        "  --auth-mode <mode>     token or global",
+        "  --email <email>        login email for global mode",
+        "  --password <pwd>       login password for global mode",
+        "  --cookie <cookie>      cookie for global mode",
+        "  --token-param <name>   token query param name (default: token)",
+        "  --timeout <ms>         request timeout in ms",
+        "  --type <type>          log type (e.g., group/project)",
+        "  --type-id <id>         log type id",
+        "  --page <n>             page number (default: 1)",
+        "  --limit <n>            page size (default: 10)",
+        "  --no-pretty            print raw response",
+        "  -h, --help             show help",
+    ].join("\n");
+}
 function escapeTomlValue(value) {
     return String(value || "")
         .replace(/\\/g, "\\\\")
@@ -732,8 +921,12 @@ function promptHidden(question) {
         output: process.stdout,
         terminal: true,
     });
+    const output = rl.output || process.stdout;
     const originalWrite = rl
         ._writeToOutput;
+    if (question) {
+        output.write(question);
+    }
     rl.stdoutMuted = true;
     rl._writeToOutput =
         function writeToOutput(value) {
@@ -743,12 +936,15 @@ function promptHidden(question) {
                 originalWrite.call(this, value);
             }
             else {
-                rl.output.write(value);
+                output.write(value);
             }
         };
     return new Promise((resolve) => {
-        rl.question(question, (answer) => {
+        rl.question("", (answer) => {
             rl.stdoutMuted = false;
+            if (question) {
+                output.write("\n");
+            }
             rl.close();
             resolve(answer);
         });
@@ -795,7 +991,7 @@ function readVersion() {
         return "unknown";
     }
 }
-async function runSimpleRequest(rawArgs, usageFn, endpoint, requireBaseUrl, buildQueryItems) {
+async function runSimpleRequest(rawArgs, usageFn, endpoint, requireBaseUrl, buildQueryItems, transform) {
     const options = parseArgs(rawArgs);
     if (options.help) {
         console.log(usageFn());
@@ -865,17 +1061,32 @@ async function runSimpleRequest(rawArgs, usageFn, endpoint, requireBaseUrl, buil
         }
     }
     let queryItems = [];
+    let method = "GET";
+    let data = undefined;
     if (buildQueryItems) {
         const result = buildQueryItems(options);
         if (!result.ok)
             return 2;
         queryItems = result.queryItems || [];
+        if (result.method) {
+            method = result.method;
+        }
+        if (result.data !== undefined) {
+            data = result.data;
+        }
     }
     const url = buildUrl(baseUrl, endpoint, queryItems, authMode === "token" ? token : "", options.tokenParam || "token");
     const sendOnce = async () => {
+        let body;
+        const requestHeaders = { ...headers };
+        if (data !== undefined) {
+            body = JSON.stringify(data);
+            requestHeaders["Content-Type"] = "application/json;charset=UTF-8";
+        }
         const response = await fetchWithTimeout(url, {
-            method: "GET",
-            headers,
+            method,
+            headers: requestHeaders,
+            body,
         }, options.timeout || 30000);
         const text = await response.text();
         return { response, text, json: parseJsonMaybe(text) };
@@ -905,7 +1116,8 @@ async function runSimpleRequest(rawArgs, usageFn, endpoint, requireBaseUrl, buil
     }
     try {
         const payload = result.json ?? JSON.parse(text);
-        console.log(JSON.stringify(payload, null, 2));
+        const nextPayload = transform ? transform(payload, options) : payload;
+        console.log(JSON.stringify(nextPayload ?? payload, null, 2));
     }
     catch {
         console.log(text);
@@ -990,8 +1202,257 @@ async function runSearch(rawArgs) {
             return { ok: false };
         }
         return { ok: true, queryItems: [["q", keyword]] };
+    }, (payload, options) => {
+        const filterProjectId = String(options.projectId || "").trim();
+        if (!filterProjectId)
+            return payload;
+        if (!payload || typeof payload !== "object")
+            return payload;
+        const record = payload;
+        const data = record.data;
+        if (!data || typeof data !== "object")
+            return payload;
+        const nextData = { ...data };
+        if (Array.isArray(data.interface)) {
+            nextData.interface = data.interface.filter((item) => {
+                const projectId = item?.projectId ?? item?.project_id ?? item?.projectID ?? "";
+                return String(projectId) === filterProjectId;
+            });
+        }
+        if (Array.isArray(data.project)) {
+            nextData.project = data.project.filter((item) => {
+                const projectId = item?._id ?? item?.id ?? item?.project_id ?? item?.projectId ?? "";
+                return String(projectId) === filterProjectId;
+            });
+        }
+        return { ...record, data: nextData };
     });
 }
+async function runGroup(rawArgs) {
+    const action = (rawArgs[0] || "list").toLowerCase();
+    const options = parseArgs(rawArgs.slice(1));
+    if (options.help) {
+        console.log(groupUsage());
+        return 0;
+    }
+    if (options.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    if (action === "list") {
+        return await runSimpleRequest(rawArgs.slice(1), groupUsage, "/api/group/list", true);
+    }
+    if (action === "get") {
+        return await runSimpleRequest(rawArgs.slice(1), groupUsage, "/api/group/get", true, (opts) => {
+            const id = String(opts.id || "").trim();
+            if (!id) {
+                console.error("missing --id for group get");
+                return { ok: false };
+            }
+            return { ok: true, queryItems: [["id", id]] };
+        });
+    }
+    console.error(`unknown group action: ${action}`);
+    console.error(groupUsage());
+    return 2;
+}
+async function runProject(rawArgs) {
+    const action = (rawArgs[0] || "list").toLowerCase();
+    const options = parseArgs(rawArgs.slice(1));
+    if (options.help) {
+        console.log(projectUsage());
+        return 0;
+    }
+    if (options.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    if (action === "list") {
+        return await runSimpleRequest(rawArgs.slice(1), projectUsage, "/api/project/list", true, (opts) => {
+            const groupId = String(opts.groupId || "").trim();
+            if (!groupId) {
+                console.error("missing --group-id for project list");
+                return { ok: false };
+            }
+            const page = Number.isFinite(opts.page ?? NaN) ? String(opts.page) : "1";
+            const limit = resolveLimit(opts.limit, "10");
+            return {
+                ok: true,
+                queryItems: [
+                    ["group_id", groupId],
+                    ["page", page],
+                    ["limit", limit],
+                ],
+            };
+        });
+    }
+    if (action === "get") {
+        return await runSimpleRequest(rawArgs.slice(1), projectUsage, "/api/project/get", true, (opts) => {
+            const id = String(opts.id || "").trim();
+            if (!id) {
+                console.error("missing --id for project get");
+                return { ok: false };
+            }
+            return { ok: true, queryItems: [["id", id]] };
+        });
+    }
+    if (action === "token") {
+        return await runSimpleRequest(rawArgs.slice(1), projectUsage, "/api/project/token", true, (opts) => {
+            const projectId = String(opts.projectId || opts.id || "").trim();
+            if (!projectId) {
+                console.error("missing --project-id for project token");
+                return { ok: false };
+            }
+            return { ok: true, queryItems: [["project_id", projectId]] };
+        });
+    }
+    console.error(`unknown project action: ${action}`);
+    console.error(projectUsage());
+    return 2;
+}
+async function runInterface(rawArgs) {
+    const action = (rawArgs[0] || "").toLowerCase();
+    const options = parseArgs(rawArgs.slice(1));
+    if (options.help) {
+        console.log(interfaceUsage());
+        return 0;
+    }
+    if (options.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    if (action === "list") {
+        return await runSimpleRequest(rawArgs.slice(1), interfaceUsage, "/api/interface/list", true, (opts) => {
+            const projectId = String(opts.projectId || "").trim();
+            if (!projectId) {
+                console.error("missing --project-id for interface list");
+                return { ok: false };
+            }
+            const page = Number.isFinite(opts.page ?? NaN) ? String(opts.page) : "1";
+            const limit = resolveLimit(opts.limit, "20");
+            return {
+                ok: true,
+                queryItems: [
+                    ["project_id", projectId],
+                    ["page", page],
+                    ["limit", limit],
+                ],
+            };
+        });
+    }
+    if (action === "list-menu" || action === "menu" || action === "list_menu") {
+        return await runSimpleRequest(rawArgs.slice(1), interfaceUsage, "/api/interface/list_menu", true, (opts) => {
+            const projectId = String(opts.projectId || "").trim();
+            if (!projectId) {
+                console.error("missing --project-id for interface list-menu");
+                return { ok: false };
+            }
+            return { ok: true, queryItems: [["project_id", projectId]] };
+        });
+    }
+    if (action === "get") {
+        return await runSimpleRequest(rawArgs.slice(1), interfaceUsage, "/api/interface/get", true, (opts) => {
+            const id = String(opts.id || "").trim();
+            if (!id) {
+                console.error("missing --id for interface get");
+                return { ok: false };
+            }
+            return { ok: true, queryItems: [["id", id]] };
+        });
+    }
+    if (action === "cat" || action === "category") {
+        const subAction = (rawArgs[1] || "").toLowerCase();
+        const subArgs = rawArgs.slice(2);
+        if (subAction === "add") {
+            return await runSimpleRequest(subArgs, interfaceUsage, "/api/interface/add_cat", true, (opts) => {
+                const projectId = String(opts.projectId || "").trim();
+                const name = String(opts.name || "").trim();
+                if (!projectId || !name) {
+                    console.error("missing --project-id/--name for interface cat add");
+                    return { ok: false };
+                }
+                const payload = {
+                    project_id: projectId,
+                    name,
+                };
+                if (opts.desc !== undefined) {
+                    payload.desc = opts.desc;
+                }
+                return { ok: true, method: "POST", data: payload };
+            });
+        }
+        if (subAction === "update" || subAction === "up") {
+            return await runSimpleRequest(subArgs, interfaceUsage, "/api/interface/up_cat", true, (opts) => {
+                const catId = String(opts.catId || "").trim();
+                const name = String(opts.name || "").trim();
+                if (!catId || !name) {
+                    console.error("missing --cat-id/--name for interface cat update");
+                    return { ok: false };
+                }
+                const payload = {
+                    catid: catId,
+                    name,
+                };
+                if (opts.desc !== undefined) {
+                    payload.desc = opts.desc;
+                }
+                return { ok: true, method: "POST", data: payload };
+            });
+        }
+        if (subAction === "delete" || subAction === "del" || subAction === "remove") {
+            return await runSimpleRequest(subArgs, interfaceUsage, "/api/interface/del_cat", true, (opts) => {
+                const catId = String(opts.catId || "").trim();
+                if (!catId) {
+                    console.error("missing --cat-id for interface cat delete");
+                    return { ok: false };
+                }
+                return { ok: true, method: "POST", data: { catid: catId } };
+            });
+        }
+        console.error(`unknown interface cat action: ${subAction || "(missing)"}`);
+        console.error(interfaceUsage());
+        return 2;
+    }
+    console.error(`unknown interface action: ${action || "(missing)"}`);
+    console.error(interfaceUsage());
+    return 2;
+}
+async function runLog(rawArgs) {
+    const action = (rawArgs[0] || "list").toLowerCase();
+    const options = parseArgs(rawArgs.slice(1));
+    if (options.help) {
+        console.log(logUsage());
+        return 0;
+    }
+    if (options.version) {
+        console.log(readVersion());
+        return 0;
+    }
+    if (action === "list") {
+        return await runSimpleRequest(rawArgs.slice(1), logUsage, "/api/log/list", true, (opts) => {
+            const type = String(opts.type || "").trim();
+            const typeId = String(opts.typeId || "").trim();
+            if (!type || !typeId) {
+                console.error("missing --type/--type-id for log list");
+                return { ok: false };
+            }
+            const page = Number.isFinite(opts.page ?? NaN) ? String(opts.page) : "1";
+            const limit = resolveLimit(opts.limit, "10");
+            return {
+                ok: true,
+                queryItems: [
+                    ["type", type],
+                    ["typeid", typeId],
+                    ["page", page],
+                    ["limit", limit],
+                ],
+            };
+        });
+    }
+    console.error(`unknown log action: ${action}`);
+    console.error(logUsage());
+    return 2;
+}
 function findDocsSyncHome(startDir) {
     let current = path_1.default.resolve(startDir);
     while (true) {
@@ -1130,6 +1591,17 @@ function normalizeBindingDir(rootDir, bindingDir) {
         return resolved;
     return relative;
 }
+function suggestDocsSyncDir(startDir) {
+    const candidates = ["docs", "doc", "documentation", "release-notes"];
+    for (const candidate of candidates) {
+        const candidatePath = path_1.default.resolve(startDir, candidate);
+        if (fs_1.default.existsSync(candidatePath) && fs_1.default.statSync(candidatePath).isDirectory()) {
+            const relative = path_1.default.relative(startDir, candidatePath);
+            return relative && relative !== "." ? relative : candidate;
+        }
+    }
+    return null;
+}
 function loadMapping(dirPath) {
     const mappingPath = path_1.default.join(dirPath, ".yapi.json");
     if (!fs_1.default.existsSync(mappingPath)) {
@@ -1153,9 +1625,6 @@ function buildDocsSyncHash(markdown, options) {
             hash.update(`mermaid-seed:${options.mermaidHandDrawnSeed}\n`);
         }
     }
-    if (options.d2Sketch) {
-        hash.update("d2-sketch\n");
-    }
     hash.update(markdown);
     return hash.digest("hex");
 }
@@ -1226,6 +1695,111 @@ function normalizeProjectEnvs(raw) {
     });
     return result;
 }
+function resolveLimit(value, fallback) {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    if (Number.isFinite(value ?? NaN)) {
+        return String(value);
+    }
+    return fallback;
+}
+const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+function updateCachePath() {
+    const yapiHome = process.env.YAPI_HOME || path_1.default.join(os_1.default.homedir(), ".yapi");
+    return path_1.default.join(yapiHome, "update.json");
+}
+function readUpdateCache() {
+    try {
+        const cachePath = updateCachePath();
+        if (!fs_1.default.existsSync(cachePath))
+            return {};
+        const raw = fs_1.default.readFileSync(cachePath, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateCache(cache) {
+    try {
+        const cachePath = updateCachePath();
+        fs_1.default.mkdirSync(path_1.default.dirname(cachePath), { recursive: true });
+        fs_1.default.writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    }
+    catch {
+    }
+}
+function compareSemver(a, b) {
+    const toParts = (value) => String(value || "")
+        .trim()
+        .split(".")
+        .map((part) => Number(part.replace(/\D/g, "")) || 0);
+    const aParts = toParts(a);
+    const bParts = toParts(b);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i += 1) {
+        const diff = (aParts[i] || 0) - (bParts[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function isNewerVersion(latest, current) {
+    return compareSemver(latest, current) > 0;
+}
+async function fetchLatestVersion(timeoutMs) {
+    try {
+        const encoded = encodeURIComponent("@leeguoo/yapi-mcp");
+        const url = `https://registry.npmjs.org/${encoded}/latest`;
+        const response = await fetchWithTimeout(url, { method: "GET" }, timeoutMs);
+        if (!response.ok)
+            return null;
+        const payload = (await response.json());
+        return typeof payload?.version === "string" ? payload.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function checkForUpdates(options) {
+    if (options.skip || options.noUpdate)
+        return;
+    if (process.env.YAPI_NO_UPDATE_CHECK === "1")
+        return;
+    if (process.env.CI === "1")
+        return;
+    const currentVersion = readVersion();
+    if (!currentVersion || currentVersion === "unknown")
+        return;
+    const cache = readUpdateCache();
+    const now = Date.now();
+    let latest = cache.latest;
+    const shouldCheck = !cache.lastChecked || now - cache.lastChecked > UPDATE_CHECK_TTL_MS || !latest;
+    if (shouldCheck) {
+        const fetched = await fetchLatestVersion(2000);
+        if (fetched) {
+            latest = fetched;
+            cache.latest = fetched;
+        }
+        cache.lastChecked = now;
+    }
+    if (!latest || !isNewerVersion(latest, currentVersion)) {
+        writeUpdateCache(cache);
+        return;
+    }
+    const shouldNotify = cache.lastNotified !== latest || !cache.lastNotifiedAt || now - cache.lastNotifiedAt > UPDATE_CHECK_TTL_MS;
+    if (shouldNotify) {
+        console.warn(`update available: ${currentVersion} -> ${latest}. Run: npm install -g @leeguoo/yapi-mcp@latest`);
+        console.warn("or: pnpm add -g @leeguoo/yapi-mcp@latest");
+        cache.lastNotified = latest;
+        cache.lastNotifiedAt = now;
+    }
+    writeUpdateCache(cache);
+}
 async function fetchProjectInfo(projectId, baseUrl, request) {
     if (!projectId)
         return null;
@@ -1346,7 +1920,7 @@ async function syncDocsDir(dirPath, mapping, options, request) {
     if (!mapping.template_id && envTemplateId)
         mapping.template_id = Number(envTemplateId);
     if (!mapping.project_id || !mapping.catid) {
-        throw new Error("project_id/catid missing; set in binding/.yapi.json or env");
+        throw new Error("缺少 project_id/catid。请先绑定或配置：yapi docs-sync bind add --name <binding> --dir <path> --project-id <id> --catid <id>，或在目录下添加 .yapi.json，或设置环境变量 YAPI_PROJECT_ID/YAPI_CATID。");
     }
     const { byPath, byTitle, byId } = await listExistingInterfaces(Number(mapping.catid), request);
     let updated = 0;
@@ -1402,7 +1976,6 @@ async function syncDocsDir(dirPath, mapping, options, request) {
             logMermaid: true,
             mermaidLook: options.mermaidLook,
             mermaidHandDrawnSeed: options.mermaidHandDrawnSeed,
-            d2Sketch: options.d2Sketch,
             logger: (message) => console.log(`${logPrefix} ${message}`),
             onMermaidError: () => {
                 mermaidFailed = true;
@@ -1675,7 +2248,29 @@ async function runDocsSync(rawArgs) {
             console.error("no docs-sync bindings found (run docs-sync bind add or use --dir)");
             return 2;
         }
+        const usingDefaultDir = !useBindings && !options.dirs.length;
         const dirs = useBindings ? [] : options.dirs.length ? options.dirs : ["docs/release-notes"];
+        if (!useBindings) {
+            const missingDirs = dirs.filter((dir) => {
+                const dirPath = path_1.default.resolve(dir);
+                return !fs_1.default.existsSync(dirPath) || !fs_1.default.statSync(dirPath).isDirectory();
+            });
+            if (missingDirs.length) {
+                const firstMissing = path_1.default.resolve(missingDirs[0]);
+                console.error(`dir not found: ${firstMissing}`);
+                if (usingDefaultDir) {
+                    const suggestion = suggestDocsSyncDir(process.cwd());
+                    if (suggestion) {
+                        console.error(`hint: pass --dir ${suggestion}`);
+                    }
+                    console.error("hint: or bind a directory with yapi docs-sync bind add");
+                }
+                else {
+                    console.error("hint: pass --dir <existing_dir> or bind a directory");
+                }
+                return 2;
+            }
+        }
         let config = {};
         let configPath = options.config || "";
         if (options.config) {
@@ -1880,6 +2475,13 @@ async function runDocsSync(rawArgs) {
 }
 async function main() {
     const rawArgs = process.argv.slice(2);
+    const parsedForUpdate = parseArgs(rawArgs);
+    const skipUpdateCheck = parsedForUpdate.version ||
+        parsedForUpdate.help ||
+        parsedForUpdate.noUpdate ||
+        rawArgs.includes("-h") ||
+        rawArgs.includes("--help");
+    await checkForUpdates({ noUpdate: parsedForUpdate.noUpdate, skip: skipUpdateCheck });
     if (rawArgs[0] === "install-skill") {
         await (0, install_1.runInstallSkill)(rawArgs.slice(1));
         return 0;
@@ -1893,6 +2495,18 @@ async function main() {
     if (rawArgs[0] === "search") {
         return await runSearch(rawArgs.slice(1));
     }
+    if (rawArgs[0] === "group") {
+        return await runGroup(rawArgs.slice(1));
+    }
+    if (rawArgs[0] === "project") {
+        return await runProject(rawArgs.slice(1));
+    }
+    if (rawArgs[0] === "interface") {
+        return await runInterface(rawArgs.slice(1));
+    }
+    if (rawArgs[0] === "log") {
+        return await runLog(rawArgs.slice(1));
+    }
     if (rawArgs[0] === "docs-sync") {
         return await runDocsSync(rawArgs.slice(1));
     }