webcake-storefront-mcp 1.3.0 → 1.5.0

package/dist/api.js

@@ -266,6 +266,22 @@ export class WebcakeCmsApi {
     deleteArticle(id) {
         return this.request("DELETE", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
     }
+    /** Create a blog/article category. Command-based: pass a `commands` array whose entries
+     *  each carry a caller-generated `data.id` (the new category id). Response is generic. */
+    createBlogCategory(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/categories/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
+    /** Create a blog article via the dashboard command pipeline (supports category linkage,
+     *  images, summary, content). Caller generates the article id in each command's data.id. */
+    createBlogArticle(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/blog/articles/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
     // ── Products ──
     listProducts(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/products/all`, { query });
@@ -282,6 +298,22 @@ export class WebcakeCmsApi {
     getProductsByCategory(categoryId) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/categories/products`, { query: { category_id: categoryId } });
     }
+    /** Create a product. Body wraps fields in `product_params`; the backend generates the
+     *  id/slug and sets is_published. Pass variations (price/stock per SKU) + categories. */
+    createProduct(productParams) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/products/create`, {
+            body: { site_id: this.siteId, product_params: productParams },
+            timeout: 60000,
+        });
+    }
+    /** Create a product category. Command-based: pass a `commands` array whose entries each
+     *  carry a caller-generated `data.id` (the new category id). Response is generic. */
+    createProductCategory(commands) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/categories/create`, {
+            body: { site_id: this.siteId, commands },
+            timeout: 60000,
+        });
+    }
     // ── Orders ──
     listOrders(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/orders/all`, { query });

package/dist/auth/login.js

@@ -1,9 +1,9 @@
-// Browser login: spins up a loopback server, opens the builder app's /mcp-connect
+// Browser login: spins up a loopback server, opens the builder app's /mcp-storefront
 // page, and receives the user's token back on the local callback — then saves it to
 // the local config db so the stdio server picks it up automatically.
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import { spawn } from "node:child_process";
+import { spawn, execFile } from "node:child_process";
 import { resolveSettings } from "../config.js";
 import { setConfig } from "../db.js";
 function parseArgs(argv) {
@@ -24,37 +24,144 @@ function parseArgs(argv) {
     return opts;
 }
 function openBrowser(url) {
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    const platform = process.platform;
     try {
-        spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+        if (platform === "win32") {
+            // `cmd /c start` parses an unquoted `&` as a command separator, which would cut
+            // the connect URL right before `&state=...`. Pass args verbatim with the URL
+            // double-quoted; the first quoted arg ("") is `start`'s window title.
+            spawn("cmd", ["/c", "start", '""', `"${url}"`], {
+                stdio: "ignore",
+                detached: true,
+                windowsVerbatimArguments: true,
+            }).unref();
+            return;
+        }
+        const cmd = platform === "darwin" ? "open" : "xdg-open";
+        spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
     }
     catch {
         /* user can open the URL manually */
     }
 }
-const SUCCESS_HTML = "<!doctype html><meta charset=utf-8><title>Connected</title><body style='font:16px system-ui;padding:3rem;text-align:center'><h2>✓ Connected to WebCake</h2><p>You can close this tab and return to your terminal.</p></body>";
+// Chrome won't let a page close a tab it didn't open (window.close() is blocked),
+// so instead we bring the user's terminal back to the foreground from Node. We
+// snapshot whatever app is frontmost just before opening the browser (that's the
+// terminal/IDE that ran the command) and re-activate it once the token arrives.
+// macOS only (AppleScript); a no-op elsewhere — the success page still shows.
+function captureFrontmostApp() {
+    if (process.platform !== "darwin")
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            resolve(v);
+        };
+        const child = execFile("osascript", ["-e", 'tell application "System Events" to get name of first application process whose frontmost is true'], (err, stdout) => finish(err ? undefined : stdout.trim() || undefined));
+        // Never let login stall: the first run may hang on the macOS Automation
+        // permission prompt. Give up after 2s (re-focus is just a nicety).
+        setTimeout(() => {
+            try {
+                child.kill();
+            }
+            catch { /* noop */ }
+            finish(undefined);
+        }, 2000).unref();
+    });
+}
+function activateApp(name) {
+    if (!name || process.platform !== "darwin")
+        return;
+    // Re-focus by process name via System Events (works for terminals whose app
+    // name differs from the process, e.g. iTerm/Terminal/Warp/VS Code).
+    execFile("osascript", ["-e", `tell application "System Events" to set frontmost of (first application process whose name is "${name.replace(/"/g, '\\"')}") to true`], () => { });
+}
+const SUCCESS_HTML = `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Connected to WebCake</title>
+<style>
+  :root{color-scheme:light dark}
+  *{box-sizing:border-box}
+  body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+    font-family:system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+    background:linear-gradient(135deg,#e7f6f0 0%,#eafaf4 100%);color:#0f2e23}
+  @media(prefers-color-scheme:dark){body{background:linear-gradient(135deg,#0b1f18 0%,#06140f 100%);color:#dcf2e8}}
+  .card{background:#fff;border-radius:20px;padding:48px 40px;max-width:430px;width:calc(100% - 32px);
+    text-align:center;box-shadow:0 20px 60px rgba(16,139,103,.20);animation:rise .5s cubic-bezier(.2,.8,.2,1)}
+  @media(prefers-color-scheme:dark){.card{background:#10241c;box-shadow:0 20px 60px rgba(0,0,0,.5)}}
+  @keyframes rise{from{opacity:0;transform:translateY(16px)}to{opacity:1;transform:none}}
+  .badge{width:84px;height:84px;margin:0 auto 24px;border-radius:50%;display:flex;align-items:center;justify-content:center;
+    background:linear-gradient(135deg,#13a87b,#108B67);box-shadow:0 8px 24px rgba(16,139,103,.42);animation:pop .45s .15s both cubic-bezier(.2,1.4,.4,1)}
+  @keyframes pop{from{transform:scale(0)}to{transform:scale(1)}}
+  .badge svg{width:44px;height:44px;stroke:#fff;stroke-width:3.5;fill:none;stroke-linecap:round;stroke-linejoin:round}
+  .badge path{stroke-dasharray:32;stroke-dashoffset:32;animation:draw .4s .4s forwards ease-out}
+  @keyframes draw{to{stroke-dashoffset:0}}
+  h1{margin:0 0 10px;font-size:1.55rem;font-weight:700}
+  p{margin:0;font-size:1rem;line-height:1.6;color:#4b6a5f}
+  @media(prefers-color-scheme:dark){p{color:#9cc7b8}}
+  .hint{margin-top:24px;display:inline-flex;align-items:center;gap:8px;padding:10px 16px;border-radius:10px;
+    background:#f0f7f4;font-size:.9rem;color:#3d5b50}
+  @media(prefers-color-scheme:dark){.hint{background:#0b1f18;color:#9cc7b8}}
+  .hint code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-weight:600;color:#108B67}
+  @media(prefers-color-scheme:dark){.hint code{color:#5fd3ac}}
+</style></head>
+<body>
+  <main class="card">
+    <div class="badge"><svg viewBox="0 0 24 24"><path d="M5 13l4 4L19 7"/></svg></div>
+    <h1>Connected to WebCake</h1>
+    <p>Your storefront account is linked. You can close this tab now.</p>
+    <div class="hint">👉 Return to your <code>terminal</code> to continue</div>
+  </main>
+  <script>
+    // The terminal is re-focused from the CLI side. Still try window.close() for
+    // browsers that allow it (no-op in Chrome for tabs it didn't open) — no alert,
+    // which would only steal focus back from the terminal.
+    setTimeout(function(){ try { window.close(); } catch (e) {} }, 800);
+  </script>
+</body></html>`;
 function readQuery(url) {
     const q = (url ?? "").indexOf("?");
     return new URLSearchParams(q === -1 ? "" : (url ?? "").slice(q + 1));
 }
+function pathOf(url) {
+    const u = url ?? "/";
+    const q = u.indexOf("?");
+    return q === -1 ? u : u.slice(0, q);
+}
 export async function runLogin(argv) {
     const opts = parseArgs(argv);
     const settings = resolveSettings({ apiUrl: opts.apiUrl, appUrl: opts.appUrl });
     const appUrl = settings.appUrl.replace(/\/$/, "");
     const apiUrl = settings.apiUrl.replace(/\/$/, "");
     const state = randomBytes(16).toString("hex");
+    // Remember the terminal that's frontmost now, so we can re-focus it once the
+    // browser hands the token back (Chrome can't auto-close its own tab).
+    const terminalApp = await captureFrontmostApp();
     await new Promise((resolve, reject) => {
+        // `close()` only stops NEW connections; a browser keep-alive socket would keep
+        // the event loop (and the CLI) alive, so drop the live ones too.
+        const shutdown = () => {
+            server.close();
+            server.closeAllConnections?.();
+        };
         const server = createServer((req, res) => {
+            // Ignore stray requests (favicon, etc.) so they don't trip the token check.
+            if (pathOf(req.url) !== "/callback") {
+                res.writeHead(404, { "content-type": "text/plain" }).end("Not found");
+                return;
+            }
             const params = readQuery(req.url);
             const token = params.get("token") || params.get("jwt");
             const wsid = params.get("wsid") || params.get("session_id") || "";
             const returnedState = params.get("state");
             if (!token) {
-                res.writeHead(400, { "content-type": "text/html" }).end("<p>Missing token.</p>");
-                return;
+                res.writeHead(400, { "content-type": "text/html" }).end("<p>Missing token — re-run the command.</p>");
+                return; // keep listening — the user can retry until the timeout
             }
             if (returnedState && returnedState !== state) {
-                res.writeHead(400, { "content-type": "text/html" }).end("<p>State mismatch.</p>");
+                res.writeHead(400, { "content-type": "text/html" }).end("<p>State mismatch (login link truncated or expired) — re-run the command.</p>");
                 return;
             }
             setConfig("token", token);
@@ -66,9 +173,12 @@ export async function runLogin(argv) {
                 setConfig("site_id", opts.siteId);
             res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
             console.error(`\n✓ Connected. Token${wsid ? " + session" : ""} saved to local config (api ${apiUrl || "<unset>"}).`);
-            server.close();
+            // Pull the terminal/IDE back to the front (best-effort; no-op off macOS).
+            activateApp(terminalApp);
+            shutdown();
             resolve();
         });
+        server.on("error", reject);
         server.listen(opts.port ?? 0, "127.0.0.1", () => {
             const addr = server.address();
             const port = typeof addr === "object" && addr ? addr.port : opts.port;
@@ -80,7 +190,7 @@ export async function runLogin(argv) {
                 openBrowser(full);
         });
         setTimeout(() => {
-            server.close();
+            shutdown();
             reject(new Error("login timed out after 180s."));
         }, 180_000).unref();
     });

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.5.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "New create_product tool creates a storefront product (simple name + price, or advanced with named attributes and per-SKU variations); accepts hosted…",
+    "vi": "Tool mới create_product tạo sản phẩm cho storefront (đơn giản với tên + giá, hoặc nâng cao với attributes và variations theo từng SKU); nhận URL ảnh…"
+  },
+  {
+    "v": "1.4.0",
+    "d": "23/06/2026",
+    "type": "Changed",
+    "en": "The install command's interactive wizard now presents numbered choices with ANSI colour output and a completion summary.",
+    "vi": "Trình hướng dẫn tương tác của lệnh install nay hiển thị các lựa chọn được đánh số kèm màu ANSI và thông báo tóm tắt sau khi hoàn tất."
+  },
   {
     "v": "1.3.0",
     "d": "23/06/2026",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "The install command's interactive wizard now runs a three-step flow: environment selection (prod / staging / local), authentication, then IDE…",
     "vi": "Trình hướng dẫn tương tác của lệnh install nay chạy theo 3 bước: chọn môi trường (prod / staging / local), xác thực, rồi cấu hình IDE."
-  },
-  {
-    "v": "1.1.2",
-    "d": "23/06/2026",
-    "type": "Fixed",
-    "en": "The server no longer crashes at startup in container environments built with npm ci --ignore-scripts; the better-sqlite3 native SQLite module has…",
-    "vi": "Server không còn bị crash khi khởi động trong môi trường container được build bằng npm ci --ignore-scripts; module SQLite native better-sqlite3 đã…"
-  },
-  {
-    "v": "1.1.1",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "The serve command's OAuth token store now optionally uses Postgres (via DATABASE_URL) for durable persistence across restarts and shared state…",
-    "vi": "Kho lưu trữ token OAuth của lệnh serve nay hỗ trợ tùy chọn sử dụng Postgres (qua DATABASE_URL) để lưu token bền vững qua các lần khởi động lại và…"
   }
 ]

package/dist/install.js

@@ -1,17 +1,51 @@
 // Installer: writes (or removes) this MCP server's entry in the config files of the
-// supported IDEs. Flag-driven; falls back to a couple of interactive prompts on a TTY.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
+// supported IDEs / agents. Flag-driven; falls back to a friendly numbered wizard on a
+// TTY. Mirrors webcake-landing-mcp's installer (numbered choices, colours, multi-IDE).
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline/promises";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
 import { runLogin } from "./auth/login.js";
-const SERVER_KEY = "webcake-storefront";
+const NAME = "webcake-storefront";
+const PKG = "webcake-storefront-mcp";
+const HOME = homedir();
+const PLAT = platform(); // 'darwin' | 'linux' | 'win32'
+const APPDATA = process.env.APPDATA || join(HOME, "AppData", "Roaming");
+const LOCALAPPDATA = process.env.LOCALAPPDATA || join(HOME, "AppData", "Local");
+// ── tiny ANSI palette + log helpers (mirrors webcake-landing-mcp's installer) ──
+const c = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    magenta: "\x1b[35m",
+    gray: "\x1b[90m",
+};
+const log = (m = "", color = "") => console.log(`${color}${m}${c.reset}`);
+const info = (m) => log(`  ${c.cyan}›${c.reset} ${m}`);
+const ok = (m) => log(`  ${c.green}✓${c.reset} ${m}`);
+const warn = (m) => log(`  ${c.yellow}!${c.reset} ${m}`);
+/** One-shot prompt on stdout (fresh readline per question — simple + robust). */
+function ask(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+// ── arg parsing ──────────────────────────────────────────────────────────────
 function parseArgs(argv) {
     const o = { uninstall: false, ides: [] };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
-        if (a === "--uninstall")
+        if (a === "--uninstall" || a === "uninstall")
             o.uninstall = true;
         else if (a === "--ide")
             o.ides.push(...(argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean));
@@ -32,25 +66,15 @@ function parseArgs(argv) {
     }
     return o;
 }
-const HOME = homedir();
-const APP_SUPPORT = process.platform === "darwin" ? join(HOME, "Library", "Application Support") : join(HOME, ".config");
-// IDE -> config file + whether it nests under "mcpServers" (vs "mcp").
-const IDE_CONFIGS = {
-    "claude-desktop": { path: join(APP_SUPPORT, "Claude", "claude_desktop_config.json"), key: "mcpServers" },
-    "claude-code": { path: join(HOME, ".claude.json"), key: "mcpServers" },
-    cursor: { path: join(HOME, ".cursor", "mcp.json"), key: "mcpServers" },
-    windsurf: { path: join(HOME, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers" },
-    vscode: { path: join(APP_SUPPORT, "Code", "User", "mcp.json"), key: "mcpServers" },
-};
-const ALL_IDES = Object.keys(IDE_CONFIGS);
+// ── launch command (npx vs local node) ───────────────────────────────────────
 function resolveLaunch(opts) {
     const self = fileURLToPath(import.meta.url);
     const ranViaNpx = self.includes("/_npx/") || self.includes("\\_npx\\");
     const useNpx = opts.launch === "npx" || (opts.launch !== "local" && ranViaNpx);
     if (useNpx)
-        return { command: "npx", args: ["-y", "webcake-storefront-mcp"] };
+        return { command: "npx", args: ["-y", PKG] };
     const entry = join(dirname(self), "index.js");
-    return { command: "node", args: [entry] };
+    return { command: process.execPath, args: [entry] };
 }
 function buildEnv(opts) {
     const env = {};
@@ -66,118 +90,416 @@ function buildEnv(opts) {
         env.WEBCAKE_SITE_ID = opts.siteId;
     return env;
 }
-function readJson(path) {
-    if (!existsSync(path))
-        return {};
-    try {
-        return JSON.parse(readFileSync(path, "utf-8"));
+// ── generic JSON config (Claude Desktop/Code, Cursor, Windsurf, VS Code, …) ───
+function mergeJson(file, launch, env) {
+    mkdirSync(dirname(file), { recursive: true });
+    let cfg = {};
+    if (existsSync(file)) {
+        const raw = readFileSync(file, "utf8").trim();
+        if (raw) {
+            try {
+                cfg = JSON.parse(raw);
+            }
+            catch (e) {
+                warn(`Skip ${file} (invalid JSON: ${e.message})`);
+                return false;
+            }
+        }
     }
-    catch {
-        return {};
-    }
-}
-function writeJson(path, data) {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
-}
-function applyToIde(ide, opts, launch, env) {
-    const cfg = IDE_CONFIGS[ide];
-    if (!cfg)
-        return `skip ${ide} (unknown)`;
-    const json = readJson(cfg.path);
-    const bag = (json[cfg.key] ||= {});
-    if (opts.uninstall) {
-        if (!(SERVER_KEY in bag))
-            return `${ide}: nothing to remove`;
-        delete bag[SERVER_KEY];
-        writeJson(cfg.path, json);
-        return `${ide}: removed (${cfg.path})`;
-    }
-    bag[SERVER_KEY] = {
+    if (typeof cfg.mcpServers !== "object" || !cfg.mcpServers)
+        cfg.mcpServers = {};
+    cfg.mcpServers[NAME] = {
         command: launch.command,
         args: launch.args,
         ...(Object.keys(env).length ? { env } : {}),
     };
-    writeJson(cfg.path, json);
-    return `${ide}: configured (${cfg.path})`;
+    writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+    return true;
+}
+// ── OpenCode config (its own shape, not mcpServers) ──────────────────────────
+// { "mcp": { "<name>": { "type": "local", "command": [cmd, ...args], "environment": {…} } } }
+function mergeOpencodeJson(file, launch, env) {
+    mkdirSync(dirname(file), { recursive: true });
+    let cfg = {};
+    if (existsSync(file)) {
+        const raw = readFileSync(file, "utf8").trim();
+        if (raw) {
+            try {
+                cfg = JSON.parse(raw);
+            }
+            catch (e) {
+                warn(`Skip ${file} (invalid JSON: ${e.message})`);
+                return false;
+            }
+        }
+    }
+    if (typeof cfg.mcp !== "object" || !cfg.mcp)
+        cfg.mcp = {};
+    cfg.mcp[NAME] = {
+        type: "local",
+        command: [launch.command, ...launch.args],
+        enabled: true,
+        ...(Object.keys(env).length ? { environment: env } : {}),
+    };
+    writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+    return true;
+}
+// ── TOML config (Codex) ──────────────────────────────────────────────────────
+function configureCodex(launch, env) {
+    const dir = join(HOME, ".codex");
+    const cfg = join(dir, "config.toml");
+    mkdirSync(dir, { recursive: true });
+    const argsToml = launch.args.map((a) => `"${a}"`).join(", ");
+    const envParts = Object.entries(env)
+        .map(([k, v]) => `"${k}" = "${v}"`)
+        .join(", ");
+    const envLine = envParts ? `env = { ${envParts} }\n` : "";
+    const block = `\n[mcp_servers.${NAME}]\ncommand = "${launch.command}"\nargs = [${argsToml}]\n${envLine}`;
+    let content = existsSync(cfg) ? readFileSync(cfg, "utf8") : "# WebCake Storefront MCP\n";
+    content = content.replace(new RegExp(`\\n?\\[mcp_servers\\.${NAME}\\][\\s\\S]*?(?=\\n\\[|$)`), "");
+    content = content.trimEnd() + "\n" + block;
+    writeFileSync(cfg, content);
+}
+// ── IDE config-file locations ────────────────────────────────────────────────
+function claudeDesktopPath() {
+    if (PLAT === "win32") {
+        // Microsoft Store build is MSIX-sandboxed: it reads/writes config inside its
+        // package container, NOT %APPDATA%\Claude. Detect that container first.
+        const packages = join(LOCALAPPDATA, "Packages");
+        if (existsSync(packages)) {
+            try {
+                const pkg = readdirSync(packages).find((n) => /^Claude_/i.test(n));
+                if (pkg)
+                    return join(packages, pkg, "LocalCache", "Roaming", "Claude", "claude_desktop_config.json");
+            }
+            catch {
+                /* fall through to the Win32 default */
+            }
+        }
+        return join(APPDATA, "Claude", "claude_desktop_config.json");
+    }
+    const mac = join(HOME, "Library", "Application Support", "Claude");
+    const dir = existsSync(mac) ? mac : join(HOME, ".config", "Claude");
+    return join(dir, "claude_desktop_config.json");
+}
+function vscodeUserDir() {
+    if (PLAT === "win32")
+        return join(APPDATA, "Code", "User");
+    const mac = join(HOME, "Library", "Application Support", "Code", "User");
+    if (existsSync(mac))
+        return mac;
+    const lin = join(HOME, ".config", "Code", "User");
+    if (existsSync(lin))
+        return lin;
+    return join(HOME, ".vscode");
+}
+const vscodeUserPath = () => join(vscodeUserDir(), "mcp.json");
+const cursorPath = () => join(HOME, ".cursor", "mcp.json");
+const windsurfPath = () => join(HOME, ".codeium", "windsurf", "mcp_config.json");
+const claudeJsonPath = () => join(HOME, ".claude.json");
+const antigravityPath = () => join(HOME, ".gemini", "antigravity", "mcp_config.json");
+const geminiPath = () => join(HOME, ".gemini", "settings.json");
+const kiroPath = () => join(HOME, ".kiro", "settings", "mcp.json");
+const clinePath = () => join(vscodeUserDir(), "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json");
+const opencodePath = () => join(HOME, ".config", "opencode", "opencode.json");
+function hasClaudeCli() {
+    const probe = spawnSync(PLAT === "win32" ? "where" : "which", ["claude"], { stdio: "ignore" });
+    return probe.status === 0;
+}
+// ── per-IDE configure ────────────────────────────────────────────────────────
+function configureClaudeCode(launch, env) {
+    info("Claude Code…");
+    if (hasClaudeCli()) {
+        spawnSync("claude", ["mcp", "remove", NAME], { stdio: "ignore" });
+        const envFlags = Object.entries(env).flatMap(([k, v]) => ["-e", `${k}=${v}`]);
+        const r = spawnSync("claude", ["mcp", "add", NAME, ...envFlags, "--", launch.command, ...launch.args], {
+            stdio: "inherit",
+        });
+        if (r.status === 0) {
+            ok("Claude Code configured via CLI — verify: claude mcp list");
+            return;
+        }
+        warn("claude CLI failed — falling back to ~/.claude.json");
+    }
+    if (mergeJson(claudeJsonPath(), launch, env))
+        ok(`Claude Code configured (${claudeJsonPath()})`);
+}
+function configureClaudeDesktop(launch, env) {
+    info("Claude Desktop…");
+    if (mergeJson(claudeDesktopPath(), launch, env)) {
+        ok(`Claude Desktop configured (${claudeDesktopPath()})`);
+        warn("Restart Claude Desktop to load the server.");
+    }
+}
+function configureCursor(launch, env) {
+    info("Cursor…");
+    if (mergeJson(cursorPath(), launch, env))
+        ok(`Cursor configured (${cursorPath()})`);
+}
+function configureWindsurf(launch, env) {
+    info("Windsurf…");
+    if (mergeJson(windsurfPath(), launch, env))
+        ok(`Windsurf configured (${windsurfPath()})`);
+}
+function configureAugment(launch, env) {
+    info("Augment / VS Code…");
+    if (mergeJson(vscodeUserPath(), launch, env))
+        ok(`VS Code configured (${vscodeUserPath()})`);
+}
+function configureCodexIde(launch, env) {
+    info("Codex…");
+    configureCodex(launch, env);
+    ok(`Codex configured (${join(HOME, ".codex", "config.toml")}) — restart Codex.`);
+}
+function configureAntigravity(launch, env) {
+    info("Antigravity…");
+    if (mergeJson(antigravityPath(), launch, env)) {
+        ok(`Antigravity configured (${antigravityPath()})`);
+        warn("In Antigravity: Agent Manager → Manage MCP Servers → Refresh (or restart).");
+    }
+}
+function configureGemini(launch, env) {
+    info("Gemini CLI…");
+    if (mergeJson(geminiPath(), launch, env))
+        ok(`Gemini CLI configured (${geminiPath()})`);
+}
+function configureCline(launch, env) {
+    info("Cline…");
+    if (mergeJson(clinePath(), launch, env))
+        ok(`Cline configured (${clinePath()})`);
+}
+function configureKiro(launch, env) {
+    info("Kiro…");
+    if (mergeJson(kiroPath(), launch, env))
+        ok(`Kiro configured (${kiroPath()})`);
+}
+function configureOpencode(launch, env) {
+    info("OpenCode…");
+    if (mergeOpencodeJson(opencodePath(), launch, env))
+        ok(`OpenCode configured (${opencodePath()})`);
+}
+const CONFIGURATORS = {
+    "claude-desktop": { label: "Claude Desktop", run: configureClaudeDesktop },
+    "claude-code": { label: "Claude Code (CLI)", run: configureClaudeCode },
+    cursor: { label: "Cursor", run: configureCursor },
+    windsurf: { label: "Windsurf", run: configureWindsurf },
+    augment: { label: "Augment / VS Code", run: configureAugment },
+    codex: { label: "Codex", run: configureCodexIde },
+    antigravity: { label: "Antigravity", run: configureAntigravity },
+    gemini: { label: "Gemini CLI", run: configureGemini },
+    cline: { label: "Cline", run: configureCline },
+    kiro: { label: "Kiro", run: configureKiro },
+    opencode: { label: "OpenCode", run: configureOpencode },
+};
+// Numbered wizard order = insertion order of CONFIGURATORS.
+const IDE_ORDER = Object.keys(CONFIGURATORS);
+const IDE_ALIASES = {
+    "claude-desktop": "claude-desktop",
+    desktop: "claude-desktop",
+    "claude-code": "claude-code",
+    claude: "claude-code",
+    code: "claude-code",
+    cursor: "cursor",
+    windsurf: "windsurf",
+    augment: "augment",
+    vscode: "augment",
+    "vs-code": "augment",
+    codex: "codex",
+    antigravity: "antigravity",
+    gemini: "gemini",
+    "gemini-cli": "gemini",
+    cline: "cline",
+    kiro: "kiro",
+    opencode: "opencode",
+    all: "all",
+};
+function normalizeIdes(ides) {
+    const set = new Set();
+    for (const raw of ides) {
+        const id = IDE_ALIASES[raw.trim().toLowerCase()];
+        if (id === "all")
+            return [...IDE_ORDER];
+        if (id)
+            set.add(id);
+        else
+            warn(`Unknown IDE: ${raw}`);
+    }
+    return [...set];
+}
+function runConfigure(ides, launch, env) {
+    for (const id of ides) {
+        const conf = CONFIGURATORS[id];
+        if (conf)
+            conf.run(launch, env);
+        else
+            warn(`Unknown IDE: ${id}`);
+    }
+}
+// ── uninstall ────────────────────────────────────────────────────────────────
+function removeFromJson(file) {
+    if (!existsSync(file))
+        return;
+    try {
+        const cfg = JSON.parse(readFileSync(file, "utf8"));
+        if (cfg.mcpServers && cfg.mcpServers[NAME]) {
+            delete cfg.mcpServers[NAME];
+            writeFileSync(file, JSON.stringify(cfg, null, 2) + "\n");
+            ok(`Cleaned ${file}`);
+        }
+    }
+    catch {
+        /* ignore unparseable files */
+    }
+}
+function uninstall() {
+    log(`\n${c.bold}  Removing ${PKG} from every IDE config${c.reset}\n`);
+    if (hasClaudeCli())
+        spawnSync("claude", ["mcp", "remove", NAME], { stdio: "ignore" });
+    [
+        claudeJsonPath(),
+        claudeDesktopPath(),
+        join(HOME, ".config", "Claude", "claude_desktop_config.json"),
+        cursorPath(),
+        windsurfPath(),
+        vscodeUserPath(),
+        antigravityPath(),
+        geminiPath(),
+        clinePath(),
+        kiroPath(),
+    ].forEach(removeFromJson);
+    // OpenCode keeps the server under its own `mcp` key, not `mcpServers`.
+    const oc = opencodePath();
+    if (existsSync(oc)) {
+        try {
+            const cfg = JSON.parse(readFileSync(oc, "utf8"));
+            if (cfg.mcp && cfg.mcp[NAME]) {
+                delete cfg.mcp[NAME];
+                writeFileSync(oc, JSON.stringify(cfg, null, 2) + "\n");
+                ok(`Cleaned ${oc}`);
+            }
+        }
+        catch {
+            /* ignore unparseable files */
+        }
+    }
+    const codex = join(HOME, ".codex", "config.toml");
+    if (existsSync(codex)) {
+        let content = readFileSync(codex, "utf8");
+        content = content.replace(new RegExp(`\\n?\\[mcp_servers\\.${NAME}\\][\\s\\S]*?(?=\\n\\[|$)`), "");
+        writeFileSync(codex, content.trimEnd() + "\n");
+        ok("Cleaned Codex config.toml");
+    }
+    log(`\n${c.green}${c.bold}  ✓ Removed. Restart your IDE.${c.reset}\n`);
 }
 /**
- * Interactive wizard (TTY only): pick environment → authenticate (browser login,
- * recommended, or paste a token) → pick IDEs. Mirrors webcake-landing-mcp's
- * installer. Returns whether a browser login completed (token then lives in the
- * local config db, so it is NOT written into the IDE env block).
+ * Interactive numbered wizard (TTY only): pick environment → authenticate (browser
+ * login, recommended, or paste a token) → pick IDEs by number. Returns whether a
+ * browser login completed (token then lives in the local config db, so it is NOT
+ * written into the IDE env block) and a short auth note for the summary.
  */
 async function promptInteractive(opts) {
     let loggedIn = false;
+    let authNote = opts.token ? "token (from flag)" : "";
     if (!process.stdin.isTTY || !process.stdout.isTTY)
-        return { loggedIn };
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    try {
-        // 1) Environment — drives which API/app URLs are used (default prod).
-        if (!opts.uninstall && !opts.env && !process.env.WEBCAKE_ENV) {
-            const e = (await rl.question("Environment [prod] / staging / local: ")).trim().toLowerCase();
-            if (e === "staging" || e === "local")
-                opts.env = e;
-        }
-        if (opts.env)
-            process.env.WEBCAKE_ENV = opts.env; // so the login flow opens the right app
-        // 2) Authentication — browser login (recommended) or paste a token. An explicit
-        //    --token/--jwt or an ambient WEBCAKE_TOKEN skips this entirely.
-        if (!opts.uninstall && !opts.token && !process.env.WEBCAKE_TOKEN) {
-            console.error("\nHow do you want to connect your WebCake account?");
-            console.error("  1) Log in via browser   (recommended — opens WebCake, saves a token)");
-            console.error("  2) Paste a token manually");
-            const choice = (await rl.question("Choose [1]: ")).trim() || "1";
-            if (choice === "1") {
-                try {
-                    rl.pause();
-                    await runLogin([]); // loopback browser flow → saves token + session to local config db
-                    loggedIn = true;
-                }
-                catch (e) {
-                    console.error(`Login didn't complete (${e?.message ?? e}). Paste a token now, or run \`npx -y webcake-storefront-mcp login\` later.`);
-                }
+        return { loggedIn, authNote };
+    // 1) Environment — one choice sets the API + app base URLs (default prod).
+    if (!opts.env && !process.env.WEBCAKE_ENV) {
+        log(`\n${c.bold}1) Environment${c.reset} ${c.gray}(sets the WebCake API + app URLs)${c.reset}`);
+        log(`  ${c.bold}1${c.reset}) prod      ${c.gray}api.storefront.webcake.io${c.reset}  ${c.gray}(default)${c.reset}`);
+        log(`  ${c.bold}2${c.reset}) staging   ${c.gray}api.staging.storecake.io${c.reset}`);
+        log(`  ${c.bold}3${c.reset}) local     ${c.gray}localhost:24679${c.reset}`);
+        const pick = (await ask(`  ${c.cyan}Select [1=prod, Enter to accept]:${c.reset} `)).trim();
+        opts.env = { "1": "prod", "2": "staging", "3": "local" }[pick] ?? "prod";
+    }
+    if (opts.env)
+        process.env.WEBCAKE_ENV = opts.env; // so the login flow opens the right app
+    // 2) Authentication — browser login (recommended), paste a token, or skip.
+    if (!opts.token && !process.env.WEBCAKE_TOKEN) {
+        log(`\n${c.bold}2) Connect your WebCake account${c.reset}`);
+        log(`  ${c.bold}1${c.reset}) Log in via browser   ${c.gray}(recommended — opens WebCake, saves a token)${c.reset}`);
+        log(`  ${c.bold}2${c.reset}) Paste a token manually`);
+        log(`  ${c.bold}3${c.reset}) Skip for now         ${c.gray}(set credentials later with the login command)${c.reset}`);
+        const choice = (await ask(`  ${c.cyan}Select [1]:${c.reset} `)).trim() || "1";
+        if (choice === "1") {
+            info("Opening your browser to log in…");
+            try {
+                await runLogin([]); // loopback browser flow → saves token + session to local config db
+                loggedIn = true;
+                authNote = "browser login (saved to local config)";
             }
-            if (!loggedIn && choice !== "1") {
-                const t = (await rl.question("  Token (paste JWT): ")).trim();
+            catch (e) {
+                warn(`Login didn't complete (${e?.message ?? e}). Paste a token now, or run \`npx -y ${PKG} login\` later.`);
+                const t = (await ask(`  ${c.cyan}Token (paste JWT, or Enter to skip):${c.reset} `)).trim();
                 if (t)
                     opts.token = t;
-                const s = (await rl.question("  Session id (x-session-id): ")).trim();
+                const s = t ? (await ask(`  ${c.cyan}Session id (x-session-id):${c.reset} `)).trim() : "";
                 if (s)
                     opts.sessionId = s;
             }
         }
-        // 3) IDEs to configure.
-        if (!opts.ides.length) {
-            const ans = (await rl.question(`\nIDE(s) to configure [${ALL_IDES.join(", ")}, all]: `)).trim();
-            opts.ides = ans === "all" || ans === "" ? ALL_IDES : ans.split(",").map((s) => s.trim());
+        else if (choice === "2") {
+            const t = (await ask(`  ${c.cyan}Token (paste JWT):${c.reset} `)).trim();
+            if (t)
+                opts.token = t;
+            const s = (await ask(`  ${c.cyan}Session id (x-session-id):${c.reset} `)).trim();
+            if (s)
+                opts.sessionId = s;
+            authNote = opts.token ? "pasted token" : "none";
         }
-        // Site is chosen at runtime — use the list_my_sites / switch_site tools in chat.
     }
-    finally {
-        try {
-            rl.close();
-        }
-        catch {
-            /* already closed */
-        }
+    if (!authNote)
+        authNote = opts.token || process.env.WEBCAKE_TOKEN ? "token" : "none — log in later";
+    // 3) IDEs to configure — numbered, comma-separated (e.g. 1,2 or the "All" number).
+    if (!opts.ides.length) {
+        log(`\n${c.bold}3) Which IDE(s) / agent(s) to configure?${c.reset}`);
+        IDE_ORDER.forEach((id, i) => {
+            const n = `${c.bold}${String(i + 1).padStart(2)}${c.reset}`;
+            log(`  ${n}) ${CONFIGURATORS[id].label}`);
+        });
+        const allNum = IDE_ORDER.length + 1;
+        log(`  ${c.bold}${String(allNum).padStart(2)}${c.reset}) ${c.green}All of the above${c.reset}     ${c.gray} 0) Skip${c.reset}`);
+        const pick = await ask(`  ${c.cyan}Select (comma-separated, e.g. 1,2):${c.reset} `);
+        const picks = pick.split(",").map((s) => s.trim()).filter(Boolean);
+        if (picks.includes(String(allNum)))
+            opts.ides = [...IDE_ORDER];
+        else
+            opts.ides = picks.map((n) => IDE_ORDER[Number(n) - 1]).filter(Boolean);
+    }
+    else {
+        opts.ides = normalizeIdes(opts.ides);
     }
-    return { loggedIn };
+    // Site is chosen at runtime — use the list_my_sites / switch_site tools in chat.
+    return { loggedIn, authNote };
 }
 export async function runInstaller(argv) {
     const opts = parseArgs(argv);
-    const { loggedIn } = await promptInteractive(opts);
-    let ides = opts.ides.length ? opts.ides : ALL_IDES;
-    if (ides.includes("all"))
-        ides = ALL_IDES;
+    log(`\n${c.magenta}${c.bold}  WebCake Storefront MCP${c.reset} ${c.gray}— installer${c.reset}`);
+    log(`${c.gray}  Build sites, pages, products & orders on WebCake from a prompt.${c.reset}`);
+    if (opts.uninstall)
+        return uninstall();
+    const { loggedIn, authNote } = await promptInteractive(opts);
+    // Normalize IDE selection (expands "all", resolves aliases). The wizard already
+    // yields canonical keys; this also covers the flag-driven / non-TTY path where
+    // promptInteractive returns early without touching opts.ides.
+    const ides = normalizeIdes(opts.ides);
+    if (!ides.length) {
+        if (!process.stdin.isTTY) {
+            warn("No --ide given (or not a TTY). Nothing to configure.");
+            log(`${c.gray}  Try: npx -y ${PKG} install --ide all${c.reset}\n`);
+        }
+        else {
+            warn("No IDE selected — nothing to configure.");
+        }
+        return;
+    }
     const launch = resolveLaunch(opts);
     const env = buildEnv(opts);
-    console.error(opts.uninstall ? "Removing webcake-storefront MCP…" : "Configuring webcake-storefront MCP…");
-    for (const ide of ides)
-        console.error("  " + applyToIde(ide, opts, launch, env));
-    if (!opts.uninstall) {
-        if (loggedIn)
-            console.error("\n✓ Logged in — your token is saved to the local config (no token written into IDE files).");
-        console.error("\nDone. Restart your IDE to pick up the new MCP server.");
-    }
+    log(`\n${c.bold}Writing config${c.reset} ${c.gray}(launch: ${launch.command} ${launch.args.join(" ")})${c.reset}`);
+    runConfigure(ides, launch, env);
+    log(`\n${c.green}${c.bold}  ✓ Done.${c.reset}`);
+    log(`  ${c.gray}Environment : ${opts.env || process.env.WEBCAKE_ENV || "prod"}${c.reset}`);
+    log(`  ${c.gray}Auth        : ${authNote}${c.reset}`);
+    if (loggedIn)
+        log(`  ${c.gray}Token saved to local config (not written into IDE files).${c.reset}`);
+    log(`  ${c.cyan}Restart your IDE, then ask the AI to build a storefront page.${c.reset}\n`);
 }

package/dist/server.js

@@ -7,6 +7,7 @@ import { registerArticleTools } from "./tools/articles.js";
 import { registerCustomerTools } from "./tools/customers.js";
 import { registerAutomationTools } from "./tools/automation.js";
 import { registerProductTools } from "./tools/products.js";
+import { registerCatalogWriteTools } from "./tools/catalog-write.js";
 import { registerOrderTools } from "./tools/orders.js";
 import { registerSiteStyleTools } from "./tools/site-style.js";
 import { registerAppTools } from "./tools/apps.js";
@@ -22,6 +23,8 @@ IMPORTANT: When the user asks ANY question about their website, store, products,
 
 You can also BUILD pages: use get_build_guide, list_elements, get_element to learn the BuilderX component model, new_section/new_element to compose, validate_page to check, then build_page (dry_run first) to create. Publishing is site-level via publish_site.
 
+To make a generated site look real, also CREATE DATA so dataset bindings resolve: create_product_category + create_product (storefront), create_blog_category + create_article (blog). Get image URLs from search_images / upload_images first, then reference them. A good flow for a fresh site: create_site → create a few categories → create products in them → build_page (home + store/blog pages) → publish_site.
+
 Workflow:
 1. On first interaction, call get_current_context. The site is NOT set from env — if no site is selected yet, call list_my_sites and ask the user which site to work on, then switch_site (the choice is saved and reused next session). To start from scratch, create_site makes a new site and switches to it; then build a homepage with build_page (type:'main', is_homepage:true).
 2. Before answering a site-specific question, query the relevant tool.
@@ -50,6 +53,7 @@ export function createServer(api, opts = {}) {
     registerCustomerTools(server, api, handle);
     registerAutomationTools(server, api, handle);
     registerProductTools(server, api, handle);
+    registerCatalogWriteTools(server, api, handle);
     registerOrderTools(server, api, handle);
     registerSiteStyleTools(server, api, handle);
     registerAppTools(server, api, handle);

package/dist/tools/articles.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { randomUUID } from "node:crypto";
 export function registerArticleTools(server, api, handle) {
     server.tool("list_articles", "List blog articles (metadata only, without HTML content). Use get_article to get full content", {
         page: z.number().optional().describe("Page number"),
@@ -27,16 +28,36 @@ export function registerArticleTools(server, api, handle) {
     server.tool("get_article", "Get article details by ID", {
         id: z.string().describe("Article ID"),
     }, ({ id }) => handle(() => api.getArticle(id)));
-    server.tool("create_article", "Create a new blog article", {
+    server.tool("create_article", `Create a blog article so blog/post pages (post-list, grid-blog, post-overlay) have content.
+Built via the dashboard command pipeline: title + optional summary, HTML content, image URLs, and
+category linkage. Pass category_ids from create_blog_category / list articles' categories so the
+post shows up under those categories (it is also auto-filed under the default category). Image URLs
+must be hosted (search_images / upload_images). The backend generates the id and slug.`, {
         name: z.string().describe("Article title"),
-        slug: z.string().describe("URL slug"),
-        content: z.string().describe("HTML content"),
-        summary: z.string().optional().describe("Summary"),
-        category_id: z.string().optional().describe("Category ID"),
-        tags: z.array(z.string()).optional().describe("Tags"),
-        images: z.array(z.string()).optional().describe("Image URLs"),
-        is_hidden: z.boolean().default(false).describe("Hide from public"),
-    }, (params) => handle(() => api.createArticle(params)));
+        content: z.string().optional().describe("HTML content of the post"),
+        summary: z.string().optional().describe("Short summary / excerpt"),
+        images: z.array(z.string()).optional().describe("Hosted image URLs; the first is the cover image"),
+        category_ids: z.array(z.string()).optional().describe("Blog category IDs to file the post under (from create_blog_category)"),
+    }, ({ name, content, summary, images, category_ids }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [{ name: "create_article", data: { id, name } }];
+        if (summary)
+            commands.push({ name: "summary_article", data: { id, summary } });
+        if (images && images.length)
+            commands.push({ name: "image_article", data: { id, images } });
+        if (content)
+            commands.push({ name: "content_article", data: { id, content } });
+        if (category_ids && category_ids.length)
+            commands.push({ name: "bulk_add_category_to_article", data: { id, ids: category_ids } });
+        await api.createBlogArticle(commands);
+        return {
+            success: true,
+            article_id: id,
+            name,
+            categories: category_ids || [],
+            cover: images?.[0] || null,
+        };
+    }));
     server.tool("update_article", "Update a blog article", {
         id: z.string().describe("Article ID"),
         name: z.string().optional().describe("New title"),

package/dist/tools/catalog-write.js

@@ -0,0 +1,126 @@
+// Write tools for catalog DATA — products, product categories, blog categories — so a
+// generated site has real content to render (grid-product / grid-category / post-list
+// bindings resolve only when these exist). Articles already have create_article.
+//
+// The category endpoints are COMMAND-based and the CALLER must generate the new id
+// (the response is a generic {code:success}), so we mint a UUID and return it.
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+const variationSpec = z.object({
+    retail_price: z.number().describe("Selling price (what the customer pays)"),
+    original_price: z.number().optional().describe("List/compare-at price (defaults to retail_price)"),
+    remain_quantity: z.number().optional().describe("Stock quantity (default 100)"),
+    custom_id: z.string().optional().describe("SKU for this variation (auto-generated if omitted)"),
+    images: z.array(z.string()).optional().describe("Hosted image URLs for this variation"),
+    weight: z.number().optional().describe("Weight in grams (default 0)"),
+    fields: z
+        .array(z.object({ name: z.string(), value: z.string() }))
+        .optional()
+        .describe("Attribute values for this variation, e.g. [{name:'Color',value:'Đen'},{name:'Size',value:'M'}]"),
+});
+export function registerCatalogWriteTools(server, api, handle) {
+    server.tool("create_product", `Create a product so the storefront has real merchandise (grid-product / slider-product bindings need this).
+Simple use: pass name + price (+ images, category_ids). One default variation with the price/stock is created for you.
+Advanced use: pass attributes (e.g. Color/Size) + variations for a multi-SKU product.
+Images must be HOSTED URLs — get them from search_images or upload_images first. The backend generates id, slug and publishes the product.`, {
+        name: z.string().describe("Product name"),
+        price: z.number().optional().describe("Selling price (used when you don't pass variations). Required unless variations are given."),
+        original_price: z.number().optional().describe("List/compare-at price for the simple single-variation case"),
+        stock: z.number().default(100).describe("Stock quantity for the simple single-variation case"),
+        sku: z.string().optional().describe("SKU / custom_id for the simple case (auto-generated if omitted)"),
+        images: z.array(z.string()).optional().describe("Hosted image URLs (search_images/upload_images). First image becomes the product thumbnail."),
+        description: z.string().optional().describe("Product description (HTML allowed)"),
+        category_ids: z.array(z.string()).optional().describe("Product category IDs to file the product under (from create_product_category / list_categories)"),
+        attributes: z
+            .array(z.object({ name: z.string(), values: z.array(z.string()) }))
+            .optional()
+            .describe("Variant axes, e.g. [{name:'Color',values:['Đen','Trắng']},{name:'Size',values:['S','M','L']}]"),
+        variations: z.array(variationSpec).optional().describe("Explicit per-SKU variations. Omit to auto-build one from price/stock/sku."),
+    }, ({ name, price, original_price, stock, sku, images, description, category_ids, attributes, variations }) => handle(async () => {
+        let vars = variations;
+        if (!vars || !vars.length) {
+            if (price == null)
+                throw new Error("Provide `price` (or explicit `variations`) to create a product.");
+            vars = [
+                {
+                    custom_id: sku || `SKU-${randomUUID().slice(0, 8)}`,
+                    retail_price: price,
+                    original_price: original_price ?? price,
+                    remain_quantity: stock ?? 100,
+                    images: images || [],
+                    weight: 0,
+                    fields: [],
+                },
+            ];
+        }
+        else {
+            // Normalise: fill SKU / original_price / stock defaults per variation.
+            vars = vars.map((v) => ({
+                custom_id: v.custom_id || `SKU-${randomUUID().slice(0, 8)}`,
+                retail_price: v.retail_price,
+                original_price: v.original_price ?? v.retail_price,
+                remain_quantity: v.remain_quantity ?? 100,
+                images: v.images || [],
+                weight: v.weight ?? 0,
+                fields: v.fields || [],
+                is_hidden: false,
+            }));
+        }
+        const productParams = {
+            name,
+            variations: vars,
+            ...(description ? { description } : {}),
+            ...(attributes ? { product_attributes: attributes } : {}),
+            ...(category_ids ? { categories: category_ids } : {}),
+            ...(images && images.length ? { image: images[0] } : {}),
+        };
+        const res = await api.createProduct(productParams);
+        const data = res?.data;
+        const productId = data?.attributes?.id || data?.id || data?.product?.id || null;
+        return {
+            success: true,
+            product_id: productId,
+            name,
+            slug: data?.attributes?.slug || data?.slug || null,
+            variations: vars.length,
+            categories: category_ids || [],
+            raw: productId ? undefined : res, // surface raw response only if we couldn't find the id
+        };
+    }));
+    server.tool("create_product_category", `Create a product category (so grid-category / a category page has something to show, and products can be filed under it).
+Returns the new category id — pass it to create_product's category_ids. Image must be a hosted URL.`, {
+        name: z.string().describe("Category name"),
+        image: z.string().optional().describe("Hosted image URL for the category card"),
+        description: z.string().optional().describe("Category description"),
+        parent_id: z.string().optional().describe("Parent category id for a sub-category"),
+    }, ({ name, image, description, parent_id }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [
+            { name: "create_category", data: { id, name, ...(parent_id ? { parent_id } : {}) } },
+        ];
+        if (image)
+            commands.push({ name: "image_category", data: { id, image } });
+        if (description) {
+            commands.push({
+                name: "multi_description",
+                data: { id, multi_description: [{ id: randomUUID(), title: name, description }] },
+            });
+        }
+        await api.createProductCategory(commands);
+        return { success: true, category_id: id, name, ...(parent_id ? { parent_id } : {}) };
+    }));
+    server.tool("create_blog_category", `Create a blog/article category. Returns the new category id — pass it to create_article's category_id so posts are grouped (post-list / blog pages bind to it). Image must be a hosted URL.`, {
+        name: z.string().describe("Blog category name"),
+        image: z.string().optional().describe("Hosted image URL"),
+        description: z.string().optional().describe("Category description"),
+    }, ({ name, image, description }) => handle(async () => {
+        const id = randomUUID();
+        const commands = [{ name: "create_category", data: { id, name } }];
+        if (description)
+            commands.push({ name: "description_category", data: { id, description } });
+        if (image)
+            commands.push({ name: "image_category", data: { id, image } });
+        await api.createBlogCategory(commands);
+        return { success: true, category_id: id, name };
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",