webcake-storefront-mcp 1.1.4 → 1.3.0

package/README.md

@@ -149,7 +149,7 @@ Base URLs come from a **named environment** — set `WEBCAKE_ENV` (or `--env`) a
 | **`prod`** (default) | `https://api.storefront.webcake.io` | `https://webcake.io` | `<site_slug>.webcake.me` |
 
 Override a preset with `WEBCAKE_API_URL` / `WEBCAKE_APP_URL`. Optional, configured server-side:
-`PEXELS_API_KEY` (search_images), `MONGO_URI` (image-alt cache). Token / session / site can also be set
+`PEXELS_API_KEY` (search_images). Token / session / site can also be set
 in chat via `update_auth` and `switch_site` — saved to a local config file at `~/.webcake-storefront-mcp/`.
 
 <details>
@@ -171,7 +171,7 @@ in chat via `update_auth` and `switch_site` — saved to a local config file at
 | Group | Tools | Needs |
 |-------|-------|-------|
 | **Build a page** | `get_build_guide` · `list_elements` · `get_element` · `new_element` · `new_section` · `new_page_skeleton` · `validate_page` · `build_page` · `add_section` | catalog tools: nothing |
-| **Media & ingest** | `search_images` (Pexels) · `upload_image` (CDN) · `ingest_html` · `ingest_url` (recreate a reference page) | — |
+| **Media & ingest** | `search_images` (Pexels) · `upload_images` (CDN) · `ingest_html` · `ingest_url` (recreate a reference page) | — |
 | **Pages & code** | `list_pages` · `get_page_source` · `search_page_elements` · `get_page_element` · `update_page_element(s)` · `create_page` · `update_page` · `update_page_source` · custom CSS/JS · page contents · global sections · `publish_site` | token + session |
 | **Commerce** | products · orders · collections · promotions · combos | token + session |
 | **Content & store** | blog articles · themes / site style · apps · customers · `send_mail` | token + session |

package/README.vi.md

@@ -148,7 +148,7 @@ URL gốc lấy theo **môi trường có tên** — đặt `WEBCAKE_ENV` (hoặ
 | **`prod`** (mặc định) | `https://api.storefront.webcake.io` | `https://webcake.io` | `<site_slug>.webcake.me` |
 
 Override bằng `WEBCAKE_API_URL` / `WEBCAKE_APP_URL`. Tuỳ chọn, đặt phía server:
-`PEXELS_API_KEY` (search_images), `MONGO_URI` (cache alt ảnh). Token / session / site cũng có thể đặt
+`PEXELS_API_KEY` (search_images). Token / session / site cũng có thể đặt
 trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình tại `~/.webcake-storefront-mcp/`.
 
 <details>
@@ -170,7 +170,7 @@ trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình
 | Nhóm | Tool | Cần |
 |-------|-------|-------|
 | **Dựng trang** | `get_build_guide` · `list_elements` · `get_element` · `new_element` · `new_section` · `new_page_skeleton` · `validate_page` · `build_page` · `add_section` | tool catalog: không cần |
-| **Media & ingest** | `search_images` (Pexels) · `upload_image` (CDN) · `ingest_html` · `ingest_url` (dựng lại trang tham khảo) | — |
+| **Media & ingest** | `search_images` (Pexels) · `upload_images` (CDN) · `ingest_html` · `ingest_url` (dựng lại trang tham khảo) | — |
 | **Trang & code** | `list_pages` · `get_page_source` · `search_page_elements` · `get_page_element` · `update_page_element(s)` · `create_page` · `update_page` · `update_page_source` · custom CSS/JS · nội dung trang · global section · `publish_site` | token + session |
 | **Thương mại** | sản phẩm · đơn hàng · collection · khuyến mãi · combo | token + session |
 | **Nội dung & store** | bài blog · theme / site style · app · khách hàng · `send_mail` | token + session |

package/dist/api.js

@@ -70,6 +70,12 @@ export class WebcakeCmsApi {
     listMySites(query) {
         return this.request("GET", `/api/v1/dashboard/site/all`, { query });
     }
+    /** Create a brand-new personal site. The backend seeds sample categories/products/blog
+     *  but NO pages. Returns { data: { site: { id, site_slug:{slug}, ... } } }.
+     *  Fails with 403 when the account's site quota is reached (free plan: 4 sites). */
+    createSite(params) {
+        return this.request("POST", `/api/v1/dashboard/site/create`, { body: params, timeout: 60000 });
+    }
     getSiteInfo() {
         return this.request("GET", `/api/v1/site/${this.siteId}/`);
     }
@@ -208,6 +214,32 @@ export class WebcakeCmsApi {
     async updateSiteSettings(newSettings) {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/update_site`, { body: { settings: newSettings }, timeout: 60000 });
     }
+    /** Read the full site.settings object (parsed). Empty object if unset/unparseable. */
+    async getSiteSettings() {
+        const siteRes = await this.request("GET", `/api/v1/site/${this.siteId}/`, { timeout: 60000 });
+        const raw = (siteRes && siteRes.data && siteRes.data.settings) || "";
+        if (raw && typeof raw === "object")
+            return raw;
+        if (typeof raw === "string" && raw.trim()) {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        }
+        return {};
+    }
+    /** Ensure a site data-source flag (use_store/use_member/use_blog/use_error/use_maintain)
+     *  is enabled so special pages' bindings resolve. Merges into existing settings;
+     *  no-op if already on. */
+    async enableSiteFeature(flag) {
+        const settings = await this.getSiteSettings();
+        if (settings[flag] === true)
+            return { changed: false, flag };
+        await this.updateSiteSettings({ ...settings, [flag]: true });
+        return { changed: true, flag };
+    }
     // ── Collections ──
     listCollections(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { query });

package/dist/builder/grid.js

@@ -0,0 +1,68 @@
+// Breakpoint + grid model, ported from builderx_spa (composable/grid.js + common/index.js).
+//
+// CRITICAL: BuilderX persists each node's style/layout under per-breakpoint keys
+// `bp1`/`bp2`/`bp3`/`bp4` — each `{ style, config }` — NOT under `runtime`. The
+// `runtime` key the factory emits is only a staging area inside the Vue editor; the
+// storefront renderer reads `node[breakpointActive]` (see getStyle/getConfig in
+// builderx_spa/src/composable/get.js) and does NOT fall back to `runtime`. A node that
+// only has `runtime` renders with no styles/grid placement (a broken-looking page).
+// page.ts:finalizeForRender() converts runtime -> bp1..bp4 before a page is saved.
+/** Site default breakpoints, largest first. [minWidth, maxWidth]. bp1 is the base. */
+export const BREAKPOINTS = {
+    bp1: [1320, 1e9], // desktop  (base / largest, default active)
+    bp2: [993, 1319], // laptop
+    bp3: [641, 992], // tablet
+    bp4: [320, 640], // mobile
+};
+export const BREAKPOINT_KEYS = Object.keys(BREAKPOINTS); // ['bp1','bp2','bp3','bp4']
+export const BASE_BP = "bp1";
+// Position / layout keys that are breakpoint-specific. The builder does NOT copy these
+// when syncing one breakpoint onto another (placement differs per device). We keep them
+// in whichever breakpoint they were authored, and copy only the non-async keys across.
+export const STYLE_ASYNC = ["top", "left", "right", "bottom", "width", "height", "zIndex", "position", "fontSize"];
+export const CONFIG_ASYNC = [
+    "constraintX", "constraintY", "leftUnit", "rightUnit", "relLeft", "relRight", "absRight",
+    "relWidth", "widthUnit", "topUnit", "bottomUnit", "relTop", "relBottom", "absBottom", "absLeftCenterX",
+    "relLeftCenterX", "leftCenterXUnit", "absRightCenterX", "relRightCenterX", "rightCenterXUnit", "topCenterYUnit",
+    "absTopCenterY", "relTopCenterY", "bottomCenterYUnit", "absBottomCenterY", "relBottomCenterY", "heightUnit",
+    "relHeight", "vhHeight", "columnStart", "columnEnd", "rowStart", "rowEnd", "isHidden", "columns", "rows", "grid",
+    "is_use_width_outer_parent", "area", "lockCellGrid", "slideWidth", "slideWidthUnit", "relSlideWidth",
+    "posts_per_row", "is_pin_video", "sizeThumbnail", "layout", "scrollDirection",
+];
+/**
+ * Section "centered content" grid for a given breakpoint width — verbatim port of
+ * builderx_spa composable/grid.js:genGridByBp. A section is a 3-column grid: a flexible
+ * margin on each side and the page content in the centre column (max 1300px on desktop).
+ * `rows` here is a single placeholder row; callers override `rows`/`grid` for the real
+ * number of stacked children.
+ */
+export function genGridByBp(bp) {
+    const rows = [{ unit: "min/max", min: { unit: "px", absValue: 600 }, max: { unit: "max-c" } }];
+    if (bp >= 1320) {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "fr", value: 1 }, { unit: "px", absValue: 1300, value: 1 }, { unit: "fr", value: 1 }],
+            rows,
+            loaded: true,
+        };
+    }
+    else if (bp >= 993) {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "px", absValue: 10 }, { unit: "fr", value: 1 }, { unit: "px", absValue: 10 }],
+            rows,
+            loaded: true,
+        };
+    }
+    else {
+        return {
+            grid: "3x1",
+            columns: [{ unit: "px", absValue: 5 }, { unit: "fr", value: 1 }, { unit: "px", absValue: 5 }],
+            rows,
+            loaded: true,
+        };
+    }
+}
+/** The centre (content) column index in a section's 3-column grid (1-based grid lines). */
+export const SECTION_CONTENT_COL_START = 2;
+export const SECTION_CONTENT_COL_END = 3;

package/dist/builder/guide.js

@@ -27,23 +27,40 @@ fills the correct defaults, then edit specials/style.
 ## Layout = CSS grid (NOT absolute top/left)
 This is the key difference from landing-page builders. A section/container positions its
 children with a grid:
-- container \`runtime.config\`: \`grid: "1xN"\`, \`columns: [{unit:'fr',value:1}]\`,
-  \`rows: [{unit:'min/max', min:{unit:'px',absValue:H}, max:{unit:'max-c'}}, ...]\`.
-- each child \`runtime.config\`: \`columnStart/columnEnd\`, \`rowStart/rowEnd\` (1-based grid
-  lines), \`constraintX\` (['left'|'right'|'centerLeft']), \`constraintY\` (['top'|'bottom'|'centerTop']).
-new_section does this for you: pass children and they are stacked one row each. To build
-multi-column layouts, nest a container child and give it its own grid.
+- A SECTION uses a centred 3-column grid: \`grid: "3xN"\`, columns
+  \`[{unit:'fr',value:1}, {unit:'px',absValue:1300,value:1}, {unit:'fr',value:1}]\` —
+  flexible margin · 1300px content · flexible margin. Children sit in the CENTRE column
+  (\`columnStart:2, columnEnd:3\`). \`rows\` = one \`{unit:'min/max', min:{unit:'px',absValue:H}, max:{unit:'max-c'}}\` per child.
+- A nested CONTAINER uses a simple \`grid: "1xN"\` with \`columns:[{unit:'fr',value:1}]\`;
+  its children sit in \`columnStart:1, columnEnd:2\`.
+- each child config also has \`rowStart/rowEnd\` (1-based grid lines),
+  \`constraintX\` (['left'|'right'|'centerLeft']), \`constraintY\` (['top'|'bottom'|'centerTop']).
+new_section does ALL of this for you: pass children and they are stacked one row each in
+the centre column. To build multi-column layouts, nest a container child with its own grid.
+
+## Where layout/style live: per-breakpoint keys (NOT \`runtime\`)
+new_section / new_element emit a temporary \`runtime: { style, config }\`. That is a
+STAGING shape — the storefront does NOT read \`runtime\`. On save, build_page / add_section
+automatically expand \`runtime\` into the four breakpoint keys the renderer actually reads:
+\`node.bp1\`, \`node.bp2\`, \`node.bp3\`, \`node.bp4\` (each \`{ style, config }\`). You normally
+never write these by hand for new pages. When EDITING an existing page, elements are
+already in this shape — see the \`responsive\` field on get_page_element/update_page_element.
 
 ## Styling
 - \`runtime.style\` holds CSS-ish props: width/height (numbers = px), color, background,
   fontSize ("16px"), fontWeight, textAlign, border*, boxShadow, etc.
 - \`runtime.config.heightUnit\`: "auto" lets content set height (default for text/image).
-- Colours as hex or rgba(). Use the site theme colours where possible.
+- Colours: prefer the site THEME variables \`var(--color_00)\`, \`var(--color_01)\`, …
+  (the published site themes them); plain hex or rgba() also work.
 
 ## Responsive breakpoints
-Override style/config per breakpoint by adding a key on the node: \`bp1\`, \`tablet\`,
-\`laptop\` → \`{ style: {...}, config: {...} }\`. Desktop values live in \`runtime\`.
-Breakpoint widths: large_desktop 1920, desktop 1280, laptop 992, tablet 640.
+The four breakpoints (largest → smallest), keyed bp1..bp4, are:
+- \`bp1\` ≥1320px (desktop, the base) · \`bp2\` 993–1319 (laptop) · \`bp3\` 641–992 (tablet) · \`bp4\` 320–640 (mobile).
+For NEW pages you author once in \`runtime\` (desktop) and build_page copies it to all four
+breakpoints automatically — the page renders identically across devices. To make a node
+look DIFFERENT on a smaller screen, set that breakpoint's key explicitly, e.g.
+\`node.bp4 = { style: { fontSize: "20px" }, config: {...} }\`. (There is no \`tablet\`/\`laptop\`
+key — only bp1..bp4.)
 
 ## Content & data
 - Text: \`specials.text\` (HTML allowed), \`specials.tag\` ("h1".."p").
@@ -51,8 +68,31 @@ Breakpoint widths: large_desktop 1920, desktop 1280, laptop 992, tablet 640.
 - Form: wrap inputs in a \`form\`; set \`form.specials.type\`
   (form_order | form_login | form_signup | form_discount | order_tracking). Each input
   needs \`specials.field_name\`.
-- Dataset elements (text-dataset, image-dataset, grid-product...) use \`bindings\` to pull
-  product/category/blog data — leave bindings to dataset-driven pages.
+- Dataset elements (text-dataset, image-dataset, rectangle-dataset...) pull live data via
+  a \`bindings\` array. Each binding is \`{ id:"BINDING"+random, name:<source>, target:"<source>::<field>" }\`.
+  Real target field names (use these EXACTLY — there is no \`product::price\`):
+  - product:  \`product::product_image\`, \`product::product_name\`, \`product::product_price\`
+  - cart_item: \`cart_item::cart_item_image\`, \`cart_item::cart_item_name\`, \`cart_item::cart_item_price\`, \`cart_item::cart_item_total_price\`, \`cart_item::cart_item_prod_attr\`
+  - order_item: \`order_item::product_image\`, \`order_item::product_name\`, \`order_item::product_quantity\`, \`order_item::items_sum_up_price\`, \`order_item::product_attrs\`
+  - customer_address: \`customer_address::full_name\`, \`customer_address::phone_number\`, \`customer_address::address\`, \`customer_address::pdc\`
+  A target only resolves on a page of the matching \`type\` (see below).
+
+## Page types & data sources (IMPORTANT for special pages)
+A page's \`type\` decides which live data it can bind to. A SPECIAL page only works if the
+matching site data-source flag (on site.settings) is enabled — otherwise the page renders
+but every product/customer/blog binding resolves to NULL (an empty, broken-looking page).
+\`build_page\` enables the right flag for you when you pass \`type\`:
+- \`main\`    — homepage / normal content. No flag needed.
+- \`store\`   — product detail, category, cart, checkout, thank-you. Needs \`use_store\`.
+            Bindings: \`product::product_*\`, \`cart_item::cart_item_*\`.
+- \`member\`  — login, register, profile, order history. Needs \`use_member\`.
+            Bindings: \`customer_address::*\`, \`order_item::*\`.
+- \`blog\`    — blog list, article/post. Needs \`use_blog\`.
+- \`error\` / \`maintain\` — 404 / maintenance. Need \`use_error\` / \`use_maintain\`.
+- \`custom\`  — a free page with no special data. No flag needed.
+Rule of thumb: if the page shows products, a cart, customer/order data, or blog posts,
+set \`type\` accordingly so the binding source is turned on. A binding target like
+\`product::product_price\` REQUIRES its page to be the matching type.
 
 ## Workflow (do this every time)
 1. Intake: confirm goal, brand, colours, sections wanted (ask 3-5 questions if unclear).

package/dist/builder/page.js

@@ -6,6 +6,8 @@
 // produce that structure the same way the builder does, so generated pages render.
 import { buildElement, isKnownType, ELEMENT_TYPES } from "./catalog.js";
 import { randomString } from "./factory.js";
+import { BREAKPOINTS, genGridByBp, SECTION_CONTENT_COL_START, SECTION_CONTENT_COL_END, } from "./grid.js";
+const clone = (o) => structuredClone(o);
 /** Walk every node in a source tree (depth-first). Return false from fn to stop. */
 export function walk(source, fn) {
     const sections = source && Array.isArray(source.sections) ? source.sections : [];
@@ -42,10 +44,15 @@ export function reassignIds(node) {
     return node;
 }
 /**
- * Lay children out vertically inside a section/container using a single-column grid —
- * the same shape the builder emits. `children` are placed top-to-bottom, one grid row each.
+ * Lay children out vertically inside a section/container — one grid row per child,
+ * top-to-bottom — the same shape the builder emits. Values are written to `runtime`;
+ * finalizeForRender() later expands `runtime` into the per-breakpoint keys the
+ * storefront actually reads (bp1..bp4).
  */
-export function stackChildren(container, children) {
+export function stackChildren(container, children, opts = {}) {
+    const gridCols = opts.gridCols || 1;
+    const colStart = opts.contentColStart || 1;
+    const colEnd = opts.contentColEnd || 2;
     const rows = children.map((child) => {
         const h = (child.runtime && child.runtime.style && child.runtime.style.height) || 50;
         return { unit: "min/max", min: { unit: "px", absValue: h }, max: { unit: "max-c" } };
@@ -53,8 +60,8 @@ export function stackChildren(container, children) {
     container.runtime = container.runtime || {};
     container.runtime.config = {
         ...(container.runtime.config || {}),
-        grid: `1x${children.length || 1}`,
-        columns: [{ unit: "fr", value: 1 }],
+        grid: `${gridCols}x${children.length || 1}`,
+        columns: opts.columns || [{ unit: "fr", value: 1 }],
         rows: rows.length ? rows : [{ unit: "min/max", min: { unit: "px", absValue: 50 }, max: { unit: "max-c" } }],
         heightUnit: "auto",
     };
@@ -62,8 +69,8 @@ export function stackChildren(container, children) {
         child.runtime = child.runtime || {};
         child.runtime.config = {
             ...(child.runtime.config || {}),
-            columnStart: 1,
-            columnEnd: 2,
+            columnStart: colStart,
+            columnEnd: colEnd,
             rowStart: i + 1,
             rowEnd: i + 2,
             constraintX: (child.runtime.config && child.runtime.config.constraintX) || ["centerLeft"],
@@ -77,11 +84,19 @@ export function stackChildren(container, children) {
 /**
  * Build a ready-to-place section from a list of child specs.
  * Each spec: { type, opts?, children? } where children is a nested array of specs.
+ * A section uses the builder's centred 3-column grid (margin · content · margin); the
+ * children live in the centre content column. finalizeForRender() sets the correct
+ * per-breakpoint column widths via genGridByBp.
  */
 export function buildSection(childSpecs = [], sectionOpts = {}) {
     const section = buildElement("section", sectionOpts);
     const children = childSpecs.map((spec) => buildFromSpec(spec));
-    stackChildren(section, children);
+    stackChildren(section, children, {
+        gridCols: 3,
+        columns: genGridByBp(BREAKPOINTS.bp1[0]).columns,
+        contentColStart: SECTION_CONTENT_COL_START,
+        contentColEnd: SECTION_CONTENT_COL_END,
+    });
     return section;
 }
 function buildFromSpec(spec) {
@@ -146,4 +161,49 @@ export function validatePage(source) {
         stats: { sections: source.sections.length, total_elements: total, element_types: typeCounts },
     };
 }
+/**
+ * Expand one node's `runtime.{style,config}` into the per-breakpoint keys the storefront
+ * renderer reads (bp1..bp4). Mirrors builderx_spa's syncBreakpoint: the authored
+ * (desktop) values are copied onto every breakpoint. Sections additionally get their
+ * centred 3-column grid recomputed per breakpoint via genGridByBp (the side-margin
+ * widths shrink on smaller screens). Nodes already in breakpoint shape are left as-is,
+ * so this is safe to run over a mixed source (e.g. add_section onto an existing page).
+ */
+function expandNodeToBreakpoints(node) {
+    const rt = node && node.runtime;
+    if (rt && (rt.style || rt.config)) {
+        const baseStyle = rt.style || {};
+        const baseConfig = { ...(rt.config || {}), loaded: true };
+        const isSection = node.type === "section";
+        for (const [bp, [minW]] of Object.entries(BREAKPOINTS)) {
+            const style = clone(baseStyle);
+            const config = clone(baseConfig);
+            if (isSection) {
+                const g = genGridByBp(minW);
+                const sectionRows = baseConfig.rows && baseConfig.rows.length ? clone(baseConfig.rows) : clone(g.rows);
+                config.columns = clone(g.columns);
+                config.rows = sectionRows;
+                config.grid = `3x${sectionRows.length}`;
+                config.heightUnit = config.heightUnit || "auto";
+            }
+            node[bp] = { style, config };
+        }
+        delete node.runtime;
+    }
+    for (const child of node.children || [])
+        expandNodeToBreakpoints(child);
+    return node;
+}
+/**
+ * Convert a freshly-built page source (whose nodes carry `runtime`) into the shape the
+ * storefront actually renders: every node gets bp1..bp4 `{style,config}` and `runtime`
+ * is removed. MUST be called before saving a page built with new_section/new_element —
+ * otherwise the page renders with no styling or grid placement.
+ */
+export function finalizeForRender(source) {
+    const sections = source && Array.isArray(source.sections) ? source.sections : [];
+    for (const s of sections)
+        expandNodeToBreakpoints(s);
+    return source;
+}
 export { ELEMENT_TYPES };

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.3.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "New create_site tool creates a brand-new storefront site for the current account (seeded with sample products, categories, and a blog), optionally…",
+    "vi": "Tool mới create_site tạo một site storefront hoàn toàn mới cho tài khoản hiện tại (kèm sản phẩm, danh mục và blog mẫu), tự động chuyển sang site vừa…"
+  },
+  {
+    "v": "1.2.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "upload_images replaces upload_image with batch support (1–20 sources per call), parallel uploads, and a dry_run mode that previews what would be…",
+    "vi": "upload_images thay thế upload_image với khả năng xử lý hàng loạt (1–20 nguồn mỗi lần gọi), tải song song, và chế độ dry_run cho phép xem trước những…"
+  },
   {
     "v": "1.1.4",
     "d": "23/06/2026",
@@ -26,19 +40,5 @@
     "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à…"
-  },
-  {
-    "v": "1.1.0",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "The serve (remote Streamable-HTTP) mode now embeds a full OAuth 2.1 Authorization Server at /authorize, /token, /revoke, /register, and…",
-    "vi": "Chế độ serve (remote Streamable-HTTP) nay tích hợp sẵn một Authorization Server OAuth 2.1 đầy đủ tại các endpoint /authorize, /token, /revoke,…"
-  },
-  {
-    "v": "1.0.3",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "MIT license (Copyright vuluu2k) added to the package.",
-    "vi": "Thêm giấy phép MIT (Copyright vuluu2k) vào package."
   }
 ]

package/dist/db.js

@@ -1,8 +1,8 @@
-// Tiny JSON-file persistence (no native deps) for: (1) the saved connection config
-// (token / session / site / api_url / confirm_mode) and (2) the image-alt cache.
+// Tiny JSON-file persistence (no native deps) for the saved connection config
+// (token / session / site / api_url / confirm_mode).
 //
 // Stored under a stable home dir so it survives `npx` (ephemeral package cache) and
-// container restarts. Two flat JSON files instead of SQLite — keeps the package light
+// container restarts. A flat JSON file instead of SQLite — keeps the package light
 // and works in any runtime (Alpine, Docker `--ignore-scripts`, serverless) with no
 // native binding to build. The API is synchronous to match the call sites.
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -11,7 +11,6 @@ import { join } from "node:path";
 const CONFIG_DIR = process.env.WEBCAKE_CONFIG_DIR || join(homedir(), ".webcake-storefront-mcp");
 mkdirSync(CONFIG_DIR, { recursive: true });
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-const ALT_FILE = join(CONFIG_DIR, "image-alt-cache.json");
 function readJson(file, fallback) {
     try {
         return JSON.parse(readFileSync(file, "utf-8"));
@@ -44,40 +43,3 @@ export function delConfig(key) {
 export function getAllConfig() {
     return { ...config };
 }
-const altCache = readJson(ALT_FILE, {});
-export function getImageAlt(urlKey) {
-    return altCache[urlKey] || null;
-}
-export function getImageAlts(urlKeys) {
-    const out = new Map();
-    for (const k of urlKeys) {
-        const row = altCache[k];
-        if (row)
-            out.set(k, row);
-    }
-    return out;
-}
-export function setImageAlt({ url_key, url, alt, source = "ai" }) {
-    altCache[url_key] = { url_key, url, alt, source, updated_at: Date.now() };
-    writeJson(ALT_FILE, altCache);
-}
-export function setImageAlts(items) {
-    for (const it of items) {
-        altCache[it.url_key] = {
-            url_key: it.url_key,
-            url: it.url,
-            alt: it.alt,
-            source: it.source || "ai",
-            updated_at: Date.now(),
-        };
-    }
-    writeJson(ALT_FILE, altCache);
-}
-export function listImageAlts(limit = 100, offset = 0) {
-    return Object.values(altCache)
-        .sort((a, b) => b.updated_at - a.updated_at)
-        .slice(offset, offset + limit);
-}
-export function countImageAlts() {
-    return Object.keys(altCache).length;
-}

package/dist/http.js

@@ -385,7 +385,7 @@ export async function startHttpServer(port) {
                             transports.delete(transport.sessionId);
                     };
                     const api = apiFromRequest(req);
-                    const server = createServer(api);
+                    const server = createServer(api, { allowLocalFiles: false }); // remote: never read server-side files
                     await server.connect(transport);
                     await transport.handleRequest(req, res, body);
                     return;

package/dist/index.js

@@ -58,7 +58,7 @@ async function main() {
     // no env is required to start — auth (token + session) is set via env or `login`,
     // and the site is chosen at runtime with switch_site.
     const api = makeApi();
-    const server = createServer(api);
+    const server = createServer(api, { allowLocalFiles: true }); // stdio = user's own machine
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[webcake-storefront] MCP server ready on stdio.");

package/dist/server.js

@@ -23,7 +23,7 @@ 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.
 
 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).
+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.
 3. When building a page, read get_build_guide first and validate before saving.
 4. Always reply in the user's language; keep Vietnamese with full diacritics.`;
@@ -31,7 +31,7 @@ function makeResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
 /** Build a fully-wired MCP server bound to the given API client. */
-export function createServer(api) {
+export function createServer(api, opts = {}) {
     const server = new McpServer({ name: "webcake-storefront", version: "1.0.0" }, { instructions: INSTRUCTIONS });
     const handle = async (fn) => {
         try {
@@ -58,6 +58,6 @@ export function createServer(api) {
     registerGlobalSourceTools(server, api, handle);
     registerImageTools(server, api, handle);
     registerBuilderTools(server, api, handle);
-    registerBuilderExtraTools(server, api, handle);
+    registerBuilderExtraTools(server, api, handle, { allowLocalFiles: opts.allowLocalFiles === true });
     return server;
 }

package/dist/smoke.js

@@ -3,7 +3,7 @@
  * building blocks so a release can verify them without a client. Run: npm run smoke
  */
 import { listElements, getElement, buildElement, ELEMENT_TYPES, isKnownType } from "./builder/catalog.js";
-import { newPageSkeleton, buildSection, validatePage, reassignIds, walk, } from "./builder/page.js";
+import { newPageSkeleton, buildSection, validatePage, finalizeForRender, reassignIds, walk, } from "./builder/page.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -49,13 +49,22 @@ console.log("== page: grid composition + validation ==");
         { type: "text", opts: { text: "Welcome" } },
         { type: "button", opts: { text: "Buy" } },
     ]);
-    check("section grid is 1xN", hero.runtime.config.grid === "1x2", hero.runtime.config.grid);
-    check("children get grid positions", hero.children.every((c) => c.runtime.config.columnStart === 1));
+    // A section uses the builder's centred 3-column grid; children sit in the centre column.
+    check("section grid is 3xN", hero.runtime.config.grid === "3x2", hero.runtime.config.grid);
+    check("children placed in centre column", hero.children.every((c) => c.runtime.config.columnStart === 2));
     const src = newPageSkeleton();
     src.sections.push(hero);
     const v = validatePage(src);
     check("built page validates", v.valid === true, v.errors);
     check("stats count elements", v.stats.total_elements === 3, v.stats);
+    // finalizeForRender must convert runtime -> bp1..bp4 (the shape the storefront renders).
+    finalizeForRender(src);
+    const sec0 = src.sections[0];
+    check("finalize removes runtime", !("runtime" in sec0), Object.keys(sec0));
+    check("finalize adds bp1..bp4", ["bp1", "bp2", "bp3", "bp4"].every((bp) => sec0[bp]?.config), Object.keys(sec0));
+    check("section bp4 is mobile grid", sec0.bp4.config.grid === "3x2" && sec0.bp4.config.columns[0].absValue === 5, sec0.bp4.config.columns?.[0]);
+    check("child bp1 keeps centre column", sec0.children[0].bp1.config.columnStart === 2, sec0.children[0].bp1?.config);
+    check("finalize is idempotent", (finalizeForRender(src), !("runtime" in sec0)));
     // duplicate ids must fail validation
     const dup = newPageSkeleton();
     const a = buildElement("section");

package/dist/tools/builder-extras.js

@@ -1,7 +1,41 @@
 import { z } from "zod";
 import { resolvePreviewUrl } from "../config.js";
 import { parse as parseHtml } from "node-html-parser";
+import { stat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 const ALLOWED_IMG = /^image\/(jpe?g|png|webp)$/;
+const LOCAL_MAX = 200 * 1024 * 1024; // 200 MB, matches the backend multipart limit
+/** Is this entry a LOCAL filesystem path (vs an http(s) URL or data: URI)? */
+function isLocalPath(s) {
+    if (s.startsWith("data:") || /^https?:\/\//i.test(s))
+        return false;
+    return s.startsWith("file://") || s.startsWith("/") || s.startsWith("~") || /^[a-zA-Z]:[\\/]/.test(s);
+}
+/** Resolve ~ and file:// to an absolute path. */
+function resolveLocalPath(s) {
+    if (s.startsWith("file://"))
+        return fileURLToPath(s);
+    if (s.startsWith("~"))
+        return join(homedir(), s.slice(1));
+    return s;
+}
+/** Read a local image file into a buffer (with a size cap) + guess its content type. */
+async function readLocalImage(s) {
+    const p = resolveLocalPath(s);
+    const st = await stat(p);
+    if (st.size > LOCAL_MAX)
+        throw new Error(`File too large (${st.size} bytes, max ${LOCAL_MAX}).`);
+    const buf = await readFile(p);
+    const ext = (p.split(".").pop() || "").toLowerCase();
+    const contentType = ext === "png" ? "image/png"
+        : ext === "webp" ? "image/webp"
+            : ext === "gif" ? "image/gif"
+                : ext === "jpg" || ext === "jpeg" ? "image/jpeg"
+                    : "application/octet-stream";
+    return { buf, contentType };
+}
 /** Fetch a URL into a Buffer with a size cap. */
 async function fetchBuffer(url, maxBytes = 15 * 1024 * 1024) {
     const res = await fetch(url, { redirect: "follow" });
@@ -21,7 +55,7 @@ async function toAllowedImage(buf, contentType) {
     const out = await sharp(buf).jpeg({ quality: 85 }).toBuffer();
     return { buf: out, contentType: "image/jpeg" };
 }
-export function registerBuilderExtraTools(server, api, handle) {
+export function registerBuilderExtraTools(server, api, handle, opts = {}) {
     // ── Stock images (Pexels) ──────────────────────────────────────────────────
     server.tool("search_images", `Search stock photos (Pexels) to use on a page. Returns hosted image URLs you can put straight into an image element's runtime.config.src.
 Requires the PEXELS_API_KEY environment variable.`, {
@@ -52,29 +86,78 @@ Requires the PEXELS_API_KEY environment variable.`, {
         }));
         return { query, total_results: json.total_results, photos };
     }));
-    // ── Upload an image to the site CDN ─────────────────────────────────────────
-    server.tool("upload_image", `Upload an image to the site's CDN and get back a hosted URL. Accepts an http(s) URL or a data:image/...;base64 data URI. Non jpeg/png/webp inputs are converted to JPEG.
-Use this for the user's own images; stock photos from search_images are already hosted and don't need uploading.`, {
-        url: z.string().describe("http(s) URL or data:image/...;base64,... data URI"),
-    }, ({ url }) => handle(async () => {
-        let buf, contentType;
-        if (url.startsWith("data:")) {
-            const m = url.match(/^data:([^;]+);base64,(.*)$/s);
-            if (!m)
-                return { error: "Malformed data URI." };
-            contentType = m[1];
-            buf = Buffer.from(m[2], "base64");
-        }
-        else {
-            ({ buf, contentType } = await fetchBuffer(url));
+    // ── Upload images to the site CDN ───────────────────────────────────────────
+    server.tool("upload_images", `Convert external image URLs, data: URIs, or LOCAL FILE PATHS into site-hosted CDN URLs by reading/downloading each image and re-uploading it to the WebCake backend. Use this whenever the user supplies their OWN images (their URLs or files from their machine), or a page is built from a reference HTML/URL. The returned hosted URLs go straight into an image element's specials.src / runtime.config.src — same as search_images results. Stock photos from search_images are already hosted and don't need uploading.
+Processes up to 20 entries per call in parallel; non jpeg/png/webp inputs are converted to JPEG. UPLOADS BY DEFAULT (dry_run defaults to FALSE — this touches no account data): returns an "images" map (original source → hosted URL). Pass dry_run:true to only preview the entries that WOULD be processed (local paths report whether the file exists + its size) without any network/filesystem upload. Local file paths are only permitted when the MCP server runs locally (stdio); on the remote HTTP transport they are rejected per-entry.`, {
+        urls: z
+            .array(z.string())
+            .min(1)
+            .max(20)
+            .describe("Image sources — 1–20 per call. Accepts: http(s) URLs, data:image/...;base64,... URIs, or local file paths (absolute /path, ~/path, file:// — stdio mode only)."),
+        dry_run: z
+            .boolean()
+            .default(false)
+            .describe("Default FALSE — actually reads/downloads and uploads, returning hosted URLs. Set true to only preview what would be processed."),
+    }, ({ urls, dry_run }) => handle(async () => {
+        const deduped = [...new Set(urls)];
+        const localAllowed = opts.allowLocalFiles === true;
+        if (dry_run) {
+            const entries = await Promise.all(deduped.map(async (entry) => {
+                if (entry.startsWith("data:"))
+                    return { entry, kind: "data-uri" };
+                if (isLocalPath(entry)) {
+                    if (!localAllowed)
+                        return { entry, kind: "local", error: "Local file paths are only supported in stdio mode." };
+                    try {
+                        const st = await stat(resolveLocalPath(entry));
+                        return { entry, kind: "local", exists: true, size: st.size };
+                    }
+                    catch (e) {
+                        return { entry, kind: "local", exists: false, error: e?.message ?? String(e) };
+                    }
+                }
+                return { entry, kind: "url" };
+            }));
+            return { dry_run: true, count: deduped.length, entries };
         }
-        const norm = await toAllowedImage(buf, contentType);
-        const dataUri = `data:${norm.contentType};base64,${norm.buf.toString("base64")}`;
-        const res = await api.uploadImageBase64({ base64: dataUri, content_type: norm.contentType });
-        const hosted = (res && res.data) || (res && res.url) || null;
-        if (!hosted)
-            return { error: "Upload returned no URL.", raw: res };
-        return { success: true, url: hosted, content_type: norm.contentType };
+        const images = {};
+        const errors = [];
+        await Promise.all(deduped.map(async (entry) => {
+            try {
+                let buf, contentType;
+                if (entry.startsWith("data:")) {
+                    const m = entry.match(/^data:([^;]+);base64,(.*)$/s);
+                    if (!m)
+                        throw new Error("Malformed data URI.");
+                    contentType = m[1];
+                    buf = Buffer.from(m[2], "base64");
+                }
+                else if (isLocalPath(entry)) {
+                    if (!localAllowed)
+                        throw new Error("Local file paths are only supported when the server runs locally (stdio). Send a public URL or data: URI instead.");
+                    ({ buf, contentType } = await readLocalImage(entry));
+                }
+                else {
+                    ({ buf, contentType } = await fetchBuffer(entry));
+                }
+                const norm = await toAllowedImage(buf, contentType);
+                const dataUri = `data:${norm.contentType};base64,${norm.buf.toString("base64")}`;
+                const res = await api.uploadImageBase64({ base64: dataUri, content_type: norm.contentType });
+                const hosted = (res && res.data) || (res && res.url) || null;
+                if (!hosted)
+                    throw new Error("Upload returned no URL.");
+                images[entry] = hosted;
+            }
+            catch (e) {
+                errors.push({ url: entry, error: e?.message ?? String(e) });
+            }
+        }));
+        return {
+            uploaded: Object.keys(images).length,
+            failed: errors.length,
+            images,
+            ...(errors.length ? { errors } : {}),
+        };
     }));
     // ── Publish the site ────────────────────────────────────────────────────────
     server.tool("publish_site", `Publish the whole site live — snapshots all current page sources into the live (published) version.
@@ -143,7 +226,7 @@ Two-step safety: dry_run=true (default) describes what will happen; dry_run=fals
             images,
             buttons,
             palette: [...colors].slice(0, 24),
-            hint: "Rebuild this as BuilderX sections: map each heading group + its text/image/button into a new_section call. Generate fresh copy where useful; re-host external images with upload_image if you want them on the site CDN. This is a structural blueprint, not a 1:1 clone.",
+            hint: "Rebuild this as BuilderX sections: map each heading group + its text/image/button into a new_section call. Generate fresh copy where useful; re-host external images with upload_images if you want them on the site CDN. This is a structural blueprint, not a 1:1 clone.",
         };
     }
     server.tool("ingest_html", "Parse reference HTML into a structural blueprint (title, headings, paragraphs, images, buttons, colour palette) you can rebuild as BuilderX sections with new_section. Not a 1:1 clone.", {

package/dist/tools/builder.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { BUILD_GUIDE } from "../builder/guide.js";
 import { listElements, getElement, buildElement } from "../builder/catalog.js";
-import { buildSection, newPageSkeleton, validatePage, reassignIds, } from "../builder/page.js";
+import { buildSection, newPageSkeleton, validatePage, finalizeForRender, reassignIds, } from "../builder/page.js";
 // Recursive spec for new_section / build_page children.
 const elementSpec = z.object({
     type: z.string().describe("Element type (see list_elements)"),
@@ -16,6 +16,18 @@ function parseSource(src) {
 function newPageId(res) {
     return (res && res.data && res.data.id) || (res && res.id) || null;
 }
+// BuilderX page kinds. The numeric `type` is what the backend stores (PAGE_TYPE in
+// builderx_spa); SPECIAL kinds also require a site-level data-source flag enabled on
+// site.settings, otherwise components that bind to store/customer/blog data render
+// with null bindings. build_page sets both for you.
+const PAGE_TYPE_NUM = {
+    main: 1, store: 2, member: 3, blog: 4, custom: 5, error: 6, maintain: 7,
+};
+const PAGE_TYPE_FLAG = {
+    store: "use_store", member: "use_member", blog: "use_blog",
+    error: "use_error", maintain: "use_maintain",
+};
+const PAGE_KINDS = ["main", "store", "member", "blog", "custom", "error", "maintain"];
 export function registerBuilderTools(server, api, handle) {
     server.tool("get_build_guide", "Get the BuilderX page authoring guide: page shape, the grid layout model, styling, breakpoints, forms/data, and the build workflow. Read this before building or heavily editing a page.", {}, () => handle(async () => ({ guide: BUILD_GUIDE })));
     server.tool("list_elements", "List all BuilderX element/component types you can place on a page, grouped by category with a one-line summary and whether each is a container.", {}, () => handle(async () => listElements()));
@@ -45,36 +57,60 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         name: z.string().describe("Page name"),
         slug: z.string().describe("URL slug, e.g. '/landing' or '/about'"),
         source: z.any().describe("Full page source { sections: [...] } (object or JSON string)"),
-        type: z.string().optional().describe("Page type (optional)"),
+        type: z
+            .enum(PAGE_KINDS)
+            .optional()
+            .describe("Page kind. SPECIAL pages need a site data-source enabled — build_page does this automatically: store→use_store (product/cart bindings), member→use_member (customer/order bindings), blog→use_blog, error→use_error, maintain→use_maintain. 'main'/'custom' need nothing. Omit for a normal content page (defaults to 'main' for the homepage)."),
         is_homepage: z.boolean().default(false).describe("Set as the site homepage"),
         dry_run: z.boolean().default(true).describe("Preview+validate only (true) or create+save (false)"),
     }, ({ name, slug, source, type, is_homepage, dry_run }) => handle(async () => {
         const parsed = parseSource(source);
         const validation = validatePage(parsed);
+        // Resolve numeric page type + the site data-source flag a special page needs.
+        const kind = type || (is_homepage ? "main" : undefined);
+        const typeNum = kind ? PAGE_TYPE_NUM[kind] : undefined;
+        const requiredFlag = kind ? PAGE_TYPE_FLAG[kind] : undefined;
         if (dry_run) {
             return {
                 dry_run: true,
                 validation,
-                request: { name, slug, type, is_homepage, sections: (parsed && parsed.sections || []).length },
+                request: { name, slug, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
+                will_enable_feature: requiredFlag ?? null,
+                renders_at_breakpoints: ["bp1", "bp2", "bp3", "bp4"],
                 hint: validation.valid
-                    ? "Looks valid. Call again with dry_run=false to create and save the page."
+                    ? `Looks valid. On save, every node's runtime is expanded into the bp1..bp4 keys the storefront renders. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
                     : "Fix the errors above before saving.",
             };
         }
         if (!validation.valid) {
             return { error: "Validation failed — not saving.", validation };
         }
-        const created = await api.createPage({ name, slug, type, is_homepage });
+        // A special page is useless if its site data-source flag is off (bindings
+        // return null). Enable it BEFORE creating the page so the page works on first load.
+        let feature = null;
+        if (requiredFlag) {
+            try {
+                feature = await api.enableSiteFeature(requiredFlag);
+            }
+            catch (e) {
+                return { error: `Could not enable site.settings.${requiredFlag} (needed for a '${kind}' page). ${e?.message ?? e}` };
+            }
+        }
+        const created = await api.createPage({ name, slug, ...(typeNum != null ? { type: typeNum } : {}), is_homepage });
         const pageId = newPageId(created);
         if (!pageId) {
             return { error: "Page created but no id was returned; cannot save source.", created };
         }
+        // Expand runtime -> bp1..bp4 so the saved source actually renders on the storefront.
+        finalizeForRender(parsed);
         const saved = await api.updatePageSource(pageId, { source: parsed });
         return {
             success: true,
             page_id: pageId,
             name,
             slug,
+            page_type: kind ?? null,
+            ...(feature ? { data_source: { flag: feature.flag, newly_enabled: feature.changed } } : {}),
             page_source_id: saved && saved.data && saved.data.id,
             stats: validation.stats,
         };
@@ -112,6 +148,9 @@ Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
         }
         if (!validation.valid)
             return { error: "Validation failed — not saving.", validation };
+        // Expand the newly-added section's runtime -> bp1..bp4 (existing sections are
+        // already in breakpoint shape and are left untouched).
+        finalizeForRender(source);
         const saved = await api.updatePageSource(page_id, { source });
         return {
             success: true,

package/dist/tools/context.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { getConfig, setConfig } from "../db.js";
+import { resolvePreviewUrl } from "../config.js";
 /** Read all saved credentials from the local config file for startup */
 export function getSavedConfig() {
     return {
@@ -62,6 +63,58 @@ export function registerContextTools(server, api, handle) {
             page,
         };
     }));
+    server.tool("create_site", `Create a brand-new storefront site for the current account, then (by default) switch to it.
+The backend seeds sample categories, products and a blog, but creates NO pages — so after this,
+build a homepage: get_build_guide → new_section → build_page (type:'main', is_homepage:true).
+Note: free accounts are limited to 4 sites (creation fails with a quota error past that).`, {
+        name: z.string().describe("Display name of the new site, e.g. 'My Coffee Shop'"),
+        slug: z
+            .string()
+            .describe("URL-safe site slug (lowercase letters, digits, hyphens), e.g. 'my-coffee-shop'. Becomes the preview subdomain and must be unique."),
+        switch_to: z
+            .boolean()
+            .default(true)
+            .describe("Switch the session to the new site after creating it (saved for next session). Default true."),
+    }, ({ name, slug, switch_to }) => handle(async () => {
+        let res;
+        try {
+            res = await api.createSite({ name, slug });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("403")) {
+                throw new Error("Cannot create site: your account's site quota is reached (free plan allows up to 4 sites). Delete an unused site or upgrade your plan, then retry.");
+            }
+            throw new Error(`Site creation failed: ${msg}. Check the slug is unique and URL-safe (lowercase, hyphens).`);
+        }
+        const site = res?.data?.site || res?.data || res?.site || res;
+        const newId = site?.id;
+        if (!newId) {
+            throw new Error("Site was not created (no id returned by the backend).");
+        }
+        const createdSlug = site?.site_slug?.slug || slug;
+        let switched = false;
+        let previewUrl = null;
+        const previousSiteId = api.siteId;
+        if (switch_to) {
+            api.switchSite(newId);
+            setConfig("site_id", newId);
+            setConfig("site_name", site?.name || name);
+            setConfig("site_domain", createdSlug || "");
+            switched = true;
+            previewUrl = await resolvePreviewUrl(api).catch(() => null);
+        }
+        return {
+            success: true,
+            site_id: newId,
+            name: site?.name || name,
+            slug: createdSlug,
+            switched,
+            ...(switched ? { current_site_id: api.siteId, previous_site_id: previousSiteId } : {}),
+            preview_url: previewUrl,
+            next_step: "New site has sample products/categories/blog but NO pages. Create a homepage with build_page (type:'main', is_homepage:true), then add store/member/blog pages as needed. Publish site-level with publish_site.",
+        };
+    }));
     server.tool("switch_site", `Switch to a different site by site_id. All subsequent tool calls will target the new site.
 The choice is saved to local database — next session will auto-connect to this site.
 Use list_my_sites first to find the site_id`, {

package/dist/tools/images.js

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { getImageAlt, setImageAlts as dbSetImageAlts, listImageAlts, countImageAlts } from "../db.js";
-import { isMongoEnabled, mongoUpsertAlts, mongoFindAlts, mongoListAlts } from "../mongo.js";
 const IMAGE_EXT_RE = /\.(jpe?g|png|gif|webp|svg|avif|bmp|ico)(\?[^"')\s]*)?$/i;
 const URL_IN_CSS_RE = /url\(\s*['"]?([^'")\s]+)['"]?\s*\)/g;
 const HTTP_URL_RE = /https?:\/\/[^\s"'<>)]+/g;
@@ -405,7 +403,6 @@ Note: global_sections are read-only via the API and are not included.`, {
                 const { src, alt, src_path, alt_path } = probeImagePaths(node);
                 if (only_missing_alt && alt && alt.trim())
                     return;
-                const cached = src ? getImageAlt(normalizeUrl(src)) : null;
                 out.push({
                     source_type: meta.source_type,
                     source_id: meta.source_id,
@@ -416,7 +413,6 @@ Note: global_sections are read-only via the API and are not included.`, {
                     alt: alt || "",
                     src_path,
                     alt_path,
-                    ...(cached && { cached_alt: cached.alt, cached_source: cached.source, cached_at: cached.updated_at }),
                 });
             });
         }
@@ -571,30 +567,11 @@ If alt_path is omitted, it is auto-detected via the same probe used by list_imag
             }
             try {
                 await saver(source);
-                // Auto-cache: save alt per src URL so re-runs can skip OCR
-                const cacheBatch = [];
-                for (const u of perItem) {
-                    if (u.error || !u._src)
-                        continue;
-                    if (!/^https?:\/\//i.test(u._src))
-                        continue;
-                    cacheBatch.push({ url_key: normalizeUrl(u._src), url: u._src, alt: u.after, source: "ai" });
-                }
-                if (cacheBatch.length) {
-                    try {
-                        dbSetImageAlts(cacheBatch);
-                    }
-                    catch { /* cache best-effort */ }
-                    if (isMongoEnabled()) {
-                        mongoUpsertAlts(cacheBatch).catch(() => { });
-                    }
-                }
                 results.push({
                     source_type,
                     source_id,
                     success: true,
                     updated: perItem.filter((u) => !u.error).length,
-                    cached: cacheBatch.length,
                     updates: perItem.map(({ _src, ...rest }) => rest),
                 });
             }
@@ -604,137 +581,21 @@ If alt_path is omitted, it is auto-detected via the same probe used by list_imag
         }
         return { dry_run, sources: results.length, results };
     }));
-    // ── Alt cache tools ──
-    server.tool("get_cached_image_alts", `Look up cached alt descriptions for image URLs. URLs are matched by normalized form (query string stripped, lowercase). Use BEFORE running read_image/OCR — skip already-described URLs.
-When MONGO_URI is set, misses are then checked against MongoDB and successful hits are backfilled into the local cache for fast re-lookup.`, {
-        urls: z.array(z.string()).min(1).describe("Image URLs to look up"),
-    }, ({ urls }) => handle(async () => {
-        const hits = [];
-        let misses = [];
-        const keyToUrl = new Map();
-        for (const u of urls) {
-            if (!/^https?:\/\//i.test(u)) {
-                misses.push(u);
-                continue;
-            }
-            const key = normalizeUrl(u);
-            keyToUrl.set(key, u);
-            const row = getImageAlt(key);
-            if (row)
-                hits.push({ url: u, url_key: key, alt: row.alt, source: row.source, updated_at: row.updated_at });
-            else
-                misses.push(u);
-        }
-        let mongo_hits = 0;
-        if (isMongoEnabled() && misses.length) {
-            const missKeys = misses
-                .filter((u) => /^https?:\/\//i.test(u))
-                .map((u) => normalizeUrl(u));
-            try {
-                const found = await mongoFindAlts(missKeys);
-                if (found.size) {
-                    const backfill = [];
-                    const stillMissing = [];
-                    for (const u of misses) {
-                        const k = /^https?:\/\//i.test(u) ? normalizeUrl(u) : null;
-                        if (k && found.has(k)) {
-                            const doc = found.get(k);
-                            hits.push({ url: u, url_key: k, alt: doc.alt, source: doc.source || "mongo", updated_at: doc.updated_at, origin: "mongo" });
-                            backfill.push({ url_key: k, url: doc.url || u, alt: doc.alt, source: doc.source || "mongo" });
-                            mongo_hits++;
-                        }
-                        else {
-                            stillMissing.push(u);
-                        }
-                    }
-                    if (backfill.length) {
-                        try {
-                            dbSetImageAlts(backfill);
-                        }
-                        catch { /* best-effort */ }
-                    }
-                    misses = stillMissing;
-                }
-            }
-            catch { /* fall through with original misses */ }
-        }
-        return { hits_count: hits.length, miss_count: misses.length, mongo_hits, hits, misses };
-    }));
-    server.tool("save_image_alts_cache", `Manually save image URL → alt entries to the local cache. Useful for bulk import or saving descriptions generated outside the set_image_alts flow.`, {
-        items: z.array(z.object({
-            url: z.string().describe("Image URL"),
-            alt: z.string().describe("Alt/description text"),
-            source: z.string().optional().describe("Origin tag (e.g. 'ai', 'manual', 'imported'). Default 'manual'"),
-        })).min(1),
-    }, ({ items }) => handle(async () => {
-        const batch = [];
-        const skipped = [];
-        for (const it of items) {
-            if (!/^https?:\/\//i.test(it.url)) {
-                skipped.push({ url: it.url, reason: "non-http URL" });
-                continue;
-            }
-            batch.push({ url_key: normalizeUrl(it.url), url: it.url, alt: it.alt, source: it.source || "manual" });
-        }
-        if (batch.length) {
-            dbSetImageAlts(batch);
-            if (isMongoEnabled()) {
-                mongoUpsertAlts(batch).catch(() => { });
-            }
-        }
-        return { saved: batch.length, skipped, mongo: isMongoEnabled() ? "queued" : "disabled" };
-    }));
-    server.tool("list_image_alts_cache", `List entries in the alt cache, most recently updated first.`, {
-        limit: z.number().default(100).describe("Max entries (default 100)"),
-        offset: z.number().default(0).describe("Pagination offset"),
-    }, ({ limit, offset }) => handle(async () => {
-        const total = countImageAlts();
-        const rows = listImageAlts(limit, offset);
-        return { total, count: rows.length, entries: rows };
-    }));
-    // ── Mongo sync (active when MONGO_URI is set) ──
-    server.tool("sync_image_alts_to_mongo", `Push local alt cache entries up to MongoDB. Bulk upsert keyed by url_key. Use when you want to back up local-only entries to the shared central store, or after a session of heavy AI describes.
-Requires MONGO_URI env var.`, {
-        limit: z.number().default(1000).describe("Max entries to push per call"),
-        offset: z.number().default(0).describe("Offset into local cache"),
-    }, ({ limit, offset }) => handle(async () => {
-        if (!isMongoEnabled())
-            return { error: "MONGO_URI not configured" };
-        const rows = listImageAlts(limit, offset);
-        if (!rows.length)
-            return { pushed: 0, total_local: countImageAlts() };
-        const res = await mongoUpsertAlts(rows.map((r) => ({ url_key: r.url_key, url: r.url, alt: r.alt, source: r.source })));
-        return { pushed: rows.length, ...res, total_local: countImageAlts() };
-    }));
-    server.tool("sync_image_alts_from_mongo", `Pull MongoDB alt entries down into local cache. Useful when starting on a new machine/site to warm the local cache from the central store.
-Requires MONGO_URI env var.`, {
-        limit: z.number().default(1000).describe("Max entries to pull"),
-        offset: z.number().default(0).describe("Offset into Mongo collection"),
-    }, ({ limit, offset }) => handle(async () => {
-        if (!isMongoEnabled())
-            return { error: "MONGO_URI not configured" };
-        const { total, entries } = await mongoListAlts(limit, offset);
-        if (entries.length) {
-            dbSetImageAlts(entries.map((e) => ({ url_key: e.url_key, url: e.url, alt: e.alt, source: e.source || "mongo" })));
-        }
-        return { pulled: entries.length, total_remote: total, total_local: countImageAlts() };
-    }));
     // ── Combo: fetch images + metadata in one call so Claude can describe + call set_image_alts once ──
     server.tool("fetch_images_for_alt_fill", `One-shot helper for filling image_alt across the site. Returns image bytes + element metadata in a single response so Claude can describe everything in one pass, then call set_image_alts once.
 
 Workflow:
 1. Call this tool with scope/limit.
-2. Tool returns each image inline with its element_id + source_type + source_id (and skips URLs already in cache).
+2. Tool returns each image inline with its element_id + source_type + source_id.
 3. Claude reads images, drafts an alt for each, then calls set_image_alts(items) once with the template at the end of the response.
 
 The pre-built "items" template at the end contains placeholders — fill in "alt" and call set_image_alts.`, {
         scope: z.enum(["all", "pages", "global_sources"]).default("all"),
         page_id: z.string().optional(),
         only_missing_alt: z.boolean().default(true).describe("Default true — skip elements that already have alt"),
-        skip_cached: z.boolean().default(true).describe("Skip URLs already in alt cache (Claude doesn't need to describe again)"),
         limit: z.number().default(10).describe("Max images per call (cap 20)"),
         max_size_mb: z.number().default(8),
-    }, async ({ scope, page_id, only_missing_alt, skip_cached, limit, max_size_mb }) => {
+    }, async ({ scope, page_id, only_missing_alt, limit, max_size_mb }) => {
         try {
             const cap = Math.min(Math.max(limit, 1), 20);
             // 1. Collect candidate elements
@@ -790,17 +651,9 @@ The pre-built "items" template at the end contains placeholders — fill in "alt
                         });
                 }
             }
-            // 2. Resolve cache hits → auto-prepare items; misses → need vision
-            const autoItems = [];
+            // 2. Take up to `cap` candidates that need a vision-generated description
             const needVision = [];
             for (const c of candidates) {
-                if (skip_cached) {
-                    const cached = getImageAlt(normalizeUrl(c.src));
-                    if (cached && cached.alt) {
-                        autoItems.push({ source_type: c.source_type, source_id: c.source_id, element_id: c.element_id, alt: cached.alt });
-                        continue;
-                    }
-                }
                 needVision.push(c);
                 if (needVision.length >= cap)
                     break;
@@ -812,7 +665,7 @@ The pre-built "items" template at the end contains placeholders — fill in "alt
             const content = [];
             content.push({
                 type: "text",
-                text: `Fetched ${needVision.length} image(s) needing description. ${autoItems.length} auto-filled from cache. ${candidates.length - needVision.length - autoItems.length} skipped.
+                text: `Fetched ${needVision.length} image(s) needing description. ${Math.max(0, candidates.length - needVision.length)} more candidate(s) not included in this batch.
 
 For each image below, write a short alt description in the language of the site (Vietnamese unless content suggests otherwise). Focus on the SUBJECT visible — avoid generic phrases like "image of...".
 
@@ -838,9 +691,8 @@ When done, call set_image_alts with the items array. The template is at the bott
                 }
             }
             const template = {
-                auto_from_cache: autoItems,
                 to_describe: visionItems,
-                next_step: "Replace each <FILL_ALT_FOR_#N> with your description, then call set_image_alts with items = [...auto_from_cache, ...to_describe].",
+                next_step: "Replace each <FILL_ALT_FOR_#N> with your description, then call set_image_alts with items = to_describe.",
             };
             content.push({ type: "text", text: JSON.stringify(template, null, 2) });
             return { content };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.1.4",
+  "version": "1.3.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",
@@ -35,7 +35,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mongodb": "^6.21.0",
     "node-html-parser": "^8.0.2",
     "sharp": "^0.34.5",
     "zod": "^3.25.0"

package/dist/mongo.js

@@ -1,102 +0,0 @@
-// Optional MongoDB sync layer for the image alt cache.
-// Activates when MONGO_URI env var is set. Silently no-op when absent.
-const MONGO_URI = process.env.MONGO_URI || "";
-const MONGO_DB = process.env.MONGO_DB || "webcake_mcp";
-const MONGO_COLLECTION = process.env.MONGO_COLLECTION || "image_alt_cache";
-let _client = null;
-let _collection = null;
-let _connecting = null;
-async function connect() {
-    if (!MONGO_URI)
-        return null;
-    if (_collection)
-        return _collection;
-    if (_connecting)
-        return _connecting;
-    _connecting = (async () => {
-        try {
-            const { MongoClient } = await import("mongodb");
-            _client = new MongoClient(MONGO_URI, { serverSelectionTimeoutMS: 5000 });
-            await _client.connect();
-            const db = _client.db(MONGO_DB);
-            _collection = db.collection(MONGO_COLLECTION);
-            await _collection.createIndex({ url_key: 1 }, { unique: true });
-            return _collection;
-        }
-        catch (e) {
-            _connecting = null;
-            throw e;
-        }
-    })();
-    return _connecting;
-}
-export function isMongoEnabled() {
-    return !!MONGO_URI;
-}
-export async function mongoUpsertAlts(items) {
-    if (!isMongoEnabled())
-        return { ok: false, reason: "MONGO_URI not set" };
-    const col = await connect();
-    if (!col)
-        return { ok: false, reason: "no collection" };
-    if (!items.length)
-        return { ok: true, upserted: 0 };
-    const now = Date.now();
-    const ops = items.map((it) => ({
-        updateOne: {
-            filter: { url_key: it.url_key },
-            update: {
-                $set: {
-                    url_key: it.url_key,
-                    url: it.url,
-                    alt: it.alt,
-                    source: it.source || "ai",
-                    updated_at: now,
-                },
-                $setOnInsert: { created_at: now },
-            },
-            upsert: true,
-        },
-    }));
-    const res = await col.bulkWrite(ops, { ordered: false });
-    return { ok: true, upserted: res.upsertedCount, modified: res.modifiedCount };
-}
-export async function mongoFindAlts(urlKeys) {
-    if (!isMongoEnabled() || !urlKeys.length)
-        return new Map();
-    const col = await connect();
-    if (!col)
-        return new Map();
-    const cursor = col.find({ url_key: { $in: urlKeys } });
-    const map = new Map();
-    for await (const doc of cursor) {
-        map.set(doc.url_key, doc);
-    }
-    return map;
-}
-export async function mongoListAlts(limit = 100, offset = 0) {
-    if (!isMongoEnabled())
-        return { total: 0, entries: [] };
-    const col = await connect();
-    if (!col)
-        return { total: 0, entries: [] };
-    const total = await col.countDocuments();
-    const entries = await col
-        .find({}, { projection: { _id: 0 } })
-        .sort({ updated_at: -1 })
-        .skip(offset)
-        .limit(limit)
-        .toArray();
-    return { total, entries };
-}
-export async function mongoCloseQuietly() {
-    if (_client) {
-        try {
-            await _client.close();
-        }
-        catch { /* ignore */ }
-        _client = null;
-        _collection = null;
-        _connecting = null;
-    }
-}