webcake-storefront-mcp 1.7.0 → 1.9.0

package/dist/api.js

@@ -363,6 +363,13 @@ export class WebcakeCmsApi {
     getApp(type) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/get_app`, { query: { type } });
     }
+    /** Install (register) an application on the site. type = Enum.Application value
+     *  (e.g. automation=2, send_email=7). Body: { site_id, type, is_active }. */
+    registerApp(type, is_active = true) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/register`, {
+            body: { site_id: this.siteId, type, is_active },
+        });
+    }
     // ── Promotions ──
     listPromotions(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/all`, { query });
@@ -425,6 +432,24 @@ export class WebcakeCmsApi {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/multilingual/update_global_source_contents`, { body: params });
     }
     // ── Automation ──
+    /** List the site's automations (id, name, rule/trigger, status). Use this to find the
+     *  automation_id to pass to send_mail. Returns { data: [...], total_entries, ... }. */
+    listAutomations(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/automations/all`, { query });
+    }
+    createAutomation(automationAttrs) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/create`, {
+            body: { automation_attrs: { ...automationAttrs, site_id: this.siteId } },
+        });
+    }
+    updateAutomation(automationAttrs) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/update`, {
+            body: { automation_attrs: automationAttrs },
+        });
+    }
+    deleteAutomations(ids) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/delete`, { body: { ids } });
+    }
     sendMail(params) {
         return this.request("POST", `/api/v1/cms_function/${this.siteId}/application/automation/send_mail`, { body: params });
     }

package/dist/builder/guide.js

@@ -64,7 +64,9 @@ key — only bp1..bp4.)
 
 ## Content & data
 - Text: \`specials.text\` (HTML allowed), \`specials.tag\` ("h1".."p").
-- Image: \`runtime.config.src\` (URL). Use search_images / upload before referencing.
+- Image: \`runtime.config.src\` (URL). The URL MUST be a WebCake CDN url — the storefront
+  whitelists image domains, so external URLs (Pexels, random sites) won't render. Get CDN
+  urls from search_images (uploads by default → use its cdn_url) or upload_images.
 - 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\`.

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.9.0",
+    "d": "24/06/2026",
+    "type": "Added",
+    "en": "search_images now accepts an upload parameter (default true) that re-hosts each Pexels result on the WebCake CDN and adds a cdn_url field to every…",
+    "vi": "search_images nay nhận thêm tham số upload (mặc định true) để tự động tải từng kết quả Pexels lên WebCake CDN và bổ sung trường cdn_url vào mỗi ảnh,…"
+  },
+  {
+    "v": "1.8.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "New list_automations tool returns each automation's id, name, status, and trigger info so agents can find the automation_id required by send_mail or…",
+    "vi": "Tool mới list_automations trả về id, name, status và thông tin trigger của từng automation, giúp agent tìm được automation_id cần truyền vào…"
+  },
   {
     "v": "1.7.0",
     "d": "23/06/2026",
@@ -26,19 +40,5 @@
     "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",
-    "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…"
   }
 ]

package/dist/db.js

@@ -43,3 +43,18 @@ export function delConfig(key) {
 export function getAllConfig() {
     return { ...config };
 }
+// ── Image upload cache (source URL/path → WebCake CDN URL, per site) ──────────
+// Re-hosting the same stock photo / external image twice wastes an upload, so we
+// remember the CDN URL the first time. Keyed by site because CDN URLs are per-site.
+const IMAGE_CACHE_FILE = join(CONFIG_DIR, "image-cache.json");
+const imageCache = readJson(IMAGE_CACHE_FILE, {});
+export function getCachedUpload(siteId, source) {
+    const k = `${siteId}::${source}`;
+    return k in imageCache ? imageCache[k] : null;
+}
+export function setCachedUpload(siteId, source, cdnUrl) {
+    if (!siteId || !source || !cdnUrl)
+        return;
+    imageCache[`${siteId}::${source}`] = cdnUrl;
+    writeJson(IMAGE_CACHE_FILE, imageCache);
+}

package/dist/enums.js

@@ -0,0 +1,46 @@
+// WebCake enum reference, mirrored from builderx_api so the AI knows what the numeric
+// codes / string values mean. Sources:
+//   - Enum.Application (lib/builderx_api/enum.ex) — application/app types
+//   - Automation schema (lib/builderx_api/automations/automation.ex) — type/status
+//   - Enum.PageType (page kinds) — kept here for one-stop reference
+/** Application types (the `type` used by get_app / install_app / register). */
+export const APP_TYPES = {
+    product_review: 0,
+    articles_review: 1,
+    automation: 2,
+    telegram: 3,
+    affiliates: 4,
+    multilingual: 5,
+    appointment: 6,
+    send_email: 7,
+    botcake: 8,
+    sale_channel: 9,
+    product_design: 10,
+    auth_otp: 11,
+    personal_product_design: 12,
+    course: 14,
+    zalo_mini_app: 15,
+    cms: 16,
+    recaptcha: 17,
+    pwa: 18,
+};
+export const APP_NAMES = Object.keys(APP_TYPES);
+/** name -> code and code -> name helpers. */
+export const APP_TYPE_BY_NAME = { ...APP_TYPES };
+export const APP_NAME_BY_TYPE = Object.fromEntries(Object.entries(APP_TYPES).map(([k, v]) => [v, k]));
+/** Automation.status values. */
+export const AUTOMATION_STATUS = ["ACTIVE", "INACTIVE"];
+/** Automation.type — user-built automations default to CUSTOM. */
+export const AUTOMATION_TYPE_DEFAULT = "CUSTOM";
+/** Page kinds (Enum.PageType) — numeric value stored on a page. */
+export const PAGE_TYPES = {
+    main: 1,
+    store: 2,
+    member: 3,
+    blog: 4,
+    custom: 5,
+    error: 6,
+    maintain: 7,
+};
+/** A compact human-readable summary, handy to surface in tool output. */
+export const APP_TYPE_REFERENCE = APP_NAMES.map((n) => `${APP_TYPES[n]}=${n}`).join(", ");

package/dist/guides.js

@@ -2,65 +2,127 @@ export const HTTP_FUNCTION_GUIDE = `
 # HTTP Function Guide
 
 ## Syntax
-export const [method]_[FunctionName] = (request) => { return result; }
-- Method: lowercase (get, post, put, patch, delete)
-- FunctionName: PascalCase
+export const [method]_[FunctionName] = async (request) => { return result; }
+- Method: lowercase (get, post, put, patch, delete) — picked from the export-name prefix.
+- FunctionName: keep it stable; it becomes the endpoint name.
+- Make it async; the return value is JSON-serialized and sent back to the caller.
 - Examples: get_Products, post_CreateOrder, delete_RemoveItem
 
-## Request object
-- request.params    — query params or body params
-- request.customer  — logged-in customer { id, name, email, first_name, last_name, phone_number, avatar }
-- request.account   — admin account { id, name, email, first_name, last_name, phone_number, avatar }
-- request.data      — full request params (including query string)
-
-## API endpoint after deploy
-GET/POST/PUT/PATCH /api/v1/{site_id}/_functions/{FunctionName}
-
-## webcake-data (Database SDK, built-in, no config needed)
+## The request argument
+Your function is called with ONE object: { params, customer, site_id, account, data }.
+- request.params    — the arguments the caller passed (query string for GET, body for POST/…).
+- request.customer  — the logged-in storefront customer (when authenticated), else {}. Fields: id, name, email, first_name, last_name, phone_number, avatar.
+- request.account   — the logged-in admin account (when called by an admin), else {}.
+- request.site_id   — the current site id (string).
+- request.data      — extra request data (usually {}).
+IMPORTANT: pass request through to the @webcake/* module functions (their first arg).
+
+## Endpoint after deploy
+ANY method → /api/v1/{site_id}/_functions/{FunctionName}
+The caller receives your return value as data.result. From the storefront, the
+webcake-fn client (api.method_FunctionName(params)) returns that result directly.
+
+## webcake-data — Database SDK (built-in)
 import { DBConnection } from 'webcake-data';
-const db = new DBConnection();
-const Model = db.model('table_name');
+const db = new DBConnection();              // auto-uses the sandbox global site/token
+const Model = db.model('collection_name');
 
-### CRUD
-- Model.create({ field: value })
-- Model.insertMany([...])
-- Model.find(filter).sort().limit().skip().select().exec()
+### Model CRUD (all async unless noted)
+- Model.create(doc)                         → created doc
+- Model.insertMany([doc, ...])              → array
+- Model.find(filter)                        → QueryBuilder (NOT a promise — chain then .exec()/await)
 - Model.findOne(filter, { select, sort, populate })
-- Model.findById(id)
-- Model.updateOne(filter, update)
-- Model.findByIdAndUpdate(id, update)
+- Model.findById(id, { select, populate })
+- Model.updateOne(filter, update)           → { acknowledged, matchedCount, modifiedCount }
+- Model.findByIdAndUpdate(id, update, { new: true })
+- Model.findOneAndUpdate(filter, update)
 - Model.updateMany(filter, update)
-- Model.deleteOne(filter)
-- Model.findByIdAndDelete(id)
+- Model.deleteOne(filter)                   → { acknowledged, deletedCount }
+- Model.findByIdAndDelete(id) / Model.findOneAndDelete(filter)
 - Model.deleteMany(filter)
-- Model.countDocuments(filter)
-- Model.exists(filter)
-
-### QueryBuilder
-Model.find().where('age').gte(25).lte(40).in('role', ['admin']).like('email', '%@ex.com').sort({ age: -1 }).limit(20).skip(10).select('name email').exec()
-
-### Populate (joins)
-Model.find().populate({ field: 'posts', table: 'posts', referenceField: 'user_id', select: 'title', where: {}, sort: {}, limit: 5 }).exec()
-
-### Operators
-where, eq, ne, gt, gte, lt, lte, in, nin, between, like, sort, limit, skip, select, populate
-
-## Built-in Modules
-- import { findArticleById, findArticle, createArticle, updateArticleById, deleteArticleById } from '@webcake/article'
-- import { findCustomerById, findCustomerByPhone, findCustomerByEmail } from '@webcake/customer'
-- import { addBonus } from '@webcake/promotion'
-- import { getAccessToken } from '@webcake/token'
-- import { sendMail } from '@webcake/app/automation'
-All module functions take (request, ...args) and auto-use global token/site_id.
-
-## Sandbox Globals (no import needed)
-- fetch(url, options) — HTTP requests
-- URLSearchParams — URL query building
-- console.log/warn/error — logging (captured in debug mode)
+- Model.countDocuments(filter)              → number
+- Model.exists(filter)                      → boolean
+
+### QueryBuilder (from Model.find())
+Chain then terminate with .exec() (or just await the chain):
+Model.find().where('age').gte(25).lte(40).in('role',['admin']).like('email','%@ex.com')
+  .sort({ age:-1 }).limit(20).skip(10).select('name email').exec()
+Operators: where, eq, ne, gt, gte, lt, lte, in, nin, between, like, sort, limit, skip, select, populate.
+
+### Populate (join another collection)
+Model.find().populate({
+  field:'posts', table:'posts', referenceField:'user_id',
+  select:'title', where:{}, sort:{ created_at:-1 }, limit:5, skip:0, justOne:false
+}).exec()
+
+## Built-in @webcake/* modules (first arg is always request; they auth via global.token)
+Thin wrappers over the backend's /cms_function/{site_id}/... endpoints. Pass request so
+they pick up site_id. Below is EXACTLY what each call sends to the backend + what it returns.
+
+- '@webcake/article'  (backend: /cms_function/{site}/blog/article…)
+    findArticleById(request, id, opts?)
+        GET .../blog/article/{id}?opts=<json>   → the article object ({} if not found)
+    findArticle(request, payload, opts?)
+        GET .../blog/article/all?<payload>&filters=<json>&opts=<json>
+        payload: { filters?:{...}, page?, limit? }   → { data:[...], ... }
+    createArticle(request, data)            POST .../blog/article   → full response
+        data the backend accepts: { name (required), summary, content (HTML),
+        images: string[] (hosted URLs), tags: string[], status_approval,
+        render_inserted_at, render_expired_at }.  slug is auto-generated; the article is
+        auto-filed under the default blog category (this endpoint takes NO category_id —
+        use the create_article MCP tool if you need explicit category linkage).
+        creator_id/customer_id come from the authenticated request.
+    updateArticleById(request, id, data)    PATCH .../blog/article/{id}   (same fields) → response
+    deleteArticleById(request, id)          DELETE .../blog/article/{id}  → response
+
+- '@webcake/customer'  (backend: /cms_function/{site}/customer/…)  → customer object ({} if none)
+    findCustomerById(request, id)     GET .../customer/identity/{id}
+    findCustomerByPhone(request, phone) GET .../customer/phone/{phone}
+    findCustomerByEmail(request, email) GET .../customer/email/{email}
+
+- '@webcake/promotion'  (backend: /cms_function/{site}/promotion/add_bonus)
+    addBonus(request, data)   POST add_bonus → response.
+        It ADDS REWARD POINTS to a customer. data: { customer_id (required),
+        point (number, required), message? (defaults "Bạn được cộng điểm") }.
+
+- '@webcake/token'  (backend: /external/oauth/token)
+    getAccessToken(request)   → access_token string (throws if none).
+        Needs request.x_storecake_refresh_token present (sent as x-storecake-refresh-token).
+
+- '@webcake/app/automation'  (backend: /cms_function/{site}/application/automation/send_mail)
+    sendMail(request, automationId, data)   → response (throws if send fails).
+        Sends body { automation_id, data }. automation_id MUST be a valid UUID of an
+        automation set up on the site — find it with the MCP tool list_automations.
+        data is the payload passed into that automation/email template.
+
+## Sandbox globals (no import)
+- fetch(url, options)            — HTTP requests; response.ok/status/text()/json().
+- URLSearchParams                — build/parse query strings.
+- console.log / warn / error     — captured in debug mode (returned in data.logs).
+- encodeURIComponent / decodeURIComponent / encodeURI / decodeURI
 - global.domain, global.siteId, global.token, global.headers
+- Standard JS: JSON, Math, Date, Object, Array, String, Number, Map, Set, Promise, Error.
+NOT available: require()/import at runtime, Buffer, crypto, fs, process, setTimeout/setInterval, eval/Function.
+
+## Limits
+Runs sandboxed: ~4 MB memory, ~30 s timeout. The return value MUST be JSON-serializable.
 
-## Cron Jobs (jobs_config JSON)
+## Cron jobs (jobs_config JSON)
 { "jobs": [{ "functionLocation": "backend/http_function", "functionName": "myFunc", "executionConfig": { "cronExpression": "0 2 * * *" } }] }
+
+## Example
+import { DBConnection } from 'webcake-data';
+import { findCustomerById } from '@webcake/customer';
+export const post_RecentOrders = async (request) => {
+  const { params, customer } = request;
+  const db = new DBConnection();
+  const orders = await db.model('orders')
+    .find().where('customer_id').eq(customer.id || params.customer_id)
+    .sort({ created_at:-1 }).limit(10)
+    .populate({ field:'items', table:'order_items', referenceField:'order_id', limit:50 })
+    .exec();
+  return { count: orders.length, orders };
+};
 `;
 export const CUSTOM_CODE_GUIDE = `
 # Custom Code Guide

package/dist/persistence/imageCache.js

@@ -0,0 +1,42 @@
+// Image-upload cache (source URL/path → WebCake CDN URL), keyed per site.
+//
+// WHERE IT LIVES:
+//   - Remote (`serve`) with REDIS_URL set → Redis (shared across all requests/instances,
+//     survives container restarts/redeploys; this is the right place for multi-user mode).
+//   - stdio / npx / no Redis → a local JSON file (~/.webcake-storefront-mcp/image-cache.json)
+//     via db.ts. Single-user, persists on the user's machine.
+// Redis is tried first; on any Redis miss/error we fall back to the file store, so the
+// cache degrades gracefully and never blocks an upload.
+import { getRedis } from "./redis.js";
+import { getCachedUpload as fileGet, setCachedUpload as fileSet } from "../db.js";
+const TTL_MS = 1000 * 60 * 60 * 24 * 30; // 30 days — CDN urls are effectively permanent
+const redisKey = (siteId, source) => `imgc:${siteId}:${source}`;
+export async function getCachedUpload(siteId, source) {
+    const redis = getRedis();
+    if (redis) {
+        try {
+            const v = await redis.get(redisKey(siteId, source));
+            if (v)
+                return v;
+        }
+        catch {
+            /* fall through to the file store */
+        }
+    }
+    return fileGet(siteId, source);
+}
+export async function setCachedUpload(siteId, source, cdnUrl) {
+    if (!siteId || !source || !cdnUrl)
+        return;
+    const redis = getRedis();
+    if (redis) {
+        try {
+            await redis.set(redisKey(siteId, source), cdnUrl, "PX", TTL_MS);
+            return;
+        }
+        catch {
+            /* fall through to the file store */
+        }
+    }
+    fileSet(siteId, source, cdnUrl);
+}

package/dist/tools/apps.js

@@ -1,7 +1,40 @@
 import { z } from "zod";
+import { APP_TYPES, APP_NAMES, APP_TYPE_REFERENCE, APP_NAME_BY_TYPE } from "../enums.js";
 export function registerAppTools(server, api, handle) {
-    server.tool("list_apps", "List all installed applications/subscriptions of the site. Returns app type, status, and settings", {}, () => handle(() => api.listApps()));
-    server.tool("get_app", "Get a specific installed app by type ID. Common types: 1=CMS, 2=Product Design, 10=Multilingual, etc.", {
-        type: z.string().describe("App type ID"),
-    }, ({ type }) => handle(() => api.getApp(type)));
+    server.tool("list_apps", `List the site's installed applications (type, status, settings).
+App type codes: ${APP_TYPE_REFERENCE}.`, {}, () => handle(async () => {
+        const res = await api.listApps();
+        const raw = res?.data ?? res ?? [];
+        const list = Array.isArray(raw) ? raw : raw?.data || [];
+        return {
+            apps: list.map((a) => ({
+                type: a.type,
+                type_name: APP_NAME_BY_TYPE[a.type] ?? undefined,
+                status: a.status,
+                id: a.id,
+            })),
+            app_types: APP_TYPES,
+        };
+    }));
+    server.tool("get_app", `Get one installed app by its type code (returns null if not installed).
+App type codes: ${APP_TYPE_REFERENCE}. You may pass the number or the name.`, {
+        type: z.union([z.number(), z.string()]).describe(`App type — a code (e.g. 2) or a name (e.g. "automation"). Codes: ${APP_TYPE_REFERENCE}`),
+    }, ({ type }) => handle(() => {
+        const code = typeof type === "string" && type in APP_TYPES ? APP_TYPES[type] : type;
+        return api.getApp(code);
+    }));
+    server.tool("install_app", `Install (register) an application on the current site so its features become usable.
+For example, automations need the "automation" app installed first.
+App types: ${APP_TYPE_REFERENCE}.`, {
+        app: z.enum(APP_NAMES).describe("App to install (by name)"),
+        is_active: z.boolean().default(true).describe("Activate the app on install"),
+    }, ({ app, is_active }) => handle(async () => {
+        const type = APP_TYPES[app];
+        const existing = await api.getApp(type).catch(() => null);
+        if (existing?.app ?? existing?.data) {
+            return { app, type, already_installed: true };
+        }
+        await api.registerApp(type, is_active);
+        return { app, type, installed: true };
+    }));
 }

package/dist/tools/automation.js

@@ -1,8 +1,78 @@
 import { z } from "zod";
+import { APP_TYPES } from "../enums.js";
 export function registerAutomationTools(server, api, handle) {
-    server.tool("send_mail", "Send email via CMS automation", {
-        to: z.string().describe("Recipient email"),
-        subject: z.string().describe("Email subject"),
-        body: z.string().describe("Email body (supports HTML)"),
-    }, (params) => handle(() => api.sendMail(params)));
+    server.tool("list_automations", `List the site's automations so you can find an automation_id (e.g. to call send_mail, or to trigger from an HTTP function via @webcake/app/automation sendMail).
+Returns each automation's id, name, status and trigger info. Filter with 'term'. The id is what send_mail / the cms automation flow needs.`, {
+        term: z.string().optional().describe("Search by automation name"),
+        page: z.number().default(1).describe("Page number"),
+        limit: z.number().default(50).describe("Items per page"),
+    }, ({ term, page, limit }) => handle(async () => {
+        const res = await api.listAutomations({ ...(term ? { term } : {}), page, limit });
+        // Response shape: { automations: { data:[...], total_entries, page, limit }, ... }
+        const body = res?.automations || res?.data || res;
+        const raw = body?.data || body || [];
+        const list = Array.isArray(raw) ? raw : [];
+        const automations = list.map((a) => ({
+            id: a.id,
+            name: a.name,
+            status: a.status ?? (a.is_completed ? "completed" : undefined),
+            is_completed: a.is_completed,
+            // surface the trigger so the agent can tell which automation does what
+            trigger: a.rule?.trigger?.triggerType || a.rule?.trigger?.triggerKey || a.trigger_type || undefined,
+            updated_at: a.updated_at,
+        }));
+        return {
+            automations,
+            total: body?.total_entries ?? automations.length,
+            page,
+            hint: "Pass an automation's id as send_mail.automation_id (or to sendMail(request, automationId, data) inside an HTTP function).",
+        };
+    }));
+    // Automation lives behind the "Automation" application (Enum.Application automation = 2).
+    // Creating an automation requires that app installed, so we ensure it first.
+    const AUTOMATION_APP = APP_TYPES.automation;
+    async function ensureAutomationApp() {
+        const res = await api.getApp(AUTOMATION_APP).catch(() => null);
+        const app = res?.app ?? res?.data ?? null;
+        if (app)
+            return { installed: true, just_installed: false };
+        await api.registerApp(AUTOMATION_APP, true);
+        return { installed: true, just_installed: true };
+    }
+    server.tool("create_automation", `Create an automation. Checks the Automation app is installed first and installs it if needed.
+An automation = { name, type, status, rule }. 'rule' holds the trigger + actions (a map; shape depends on the trigger). Returns the new automation id (use it with send_mail for cms-triggered email).`, {
+        name: z.string().describe("Automation name"),
+        description: z.string().optional().describe("Description"),
+        type: z.string().default("CUSTOM").describe("Automation type (default CUSTOM)"),
+        status: z.enum(["ACTIVE", "INACTIVE"]).default("ACTIVE").describe("ACTIVE to run it, INACTIVE to keep it off"),
+        rule: z.record(z.any()).default({}).describe("Trigger + actions map. Leave {} for a blank automation you wire up later."),
+    }, ({ name, description, type, status, rule }) => handle(async () => {
+        const app = await ensureAutomationApp();
+        const res = await api.createAutomation({ name, ...(description ? { description } : {}), type, status, rule });
+        const a = res?.automation ?? res?.data ?? res;
+        return { success: true, automation_id: a?.id ?? null, name, status, app, hint: "Pass automation_id to send_mail to trigger it." };
+    }));
+    server.tool("update_automation", "Update an automation by id. Pass only the fields to change (name, description, type, status, rule).", {
+        id: z.string().describe("Automation id"),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        type: z.string().optional(),
+        status: z.enum(["ACTIVE", "INACTIVE"]).optional(),
+        rule: z.record(z.any()).optional().describe("Replace the trigger + actions map"),
+    }, ({ id, ...fields }) => handle(async () => {
+        const res = await api.updateAutomation({ id, ...fields });
+        const a = res?.automation ?? res?.data ?? res;
+        return { success: true, automation_id: a?.id ?? id, updated: Object.keys(fields) };
+    }));
+    server.tool("delete_automation", "Delete one or more automations by id.", {
+        ids: z.array(z.string()).describe("Automation ids to delete"),
+    }, ({ ids }) => handle(async () => {
+        await api.deleteAutomations(ids);
+        return { success: true, deleted: ids };
+    }));
+    server.tool("send_mail", `Trigger a CMS automation to send an email (same endpoint @webcake/app/automation sendMail uses).
+Requires the automation_id — get it from list_automations. 'data' is the payload passed to that automation/email template.`, {
+        automation_id: z.string().describe("Automation id (a UUID) — from list_automations"),
+        data: z.record(z.any()).default({}).describe("Data object passed into the automation (e.g. recipient, variables for the email template)"),
+    }, ({ automation_id, data }) => handle(() => api.sendMail({ automation_id, data })));
 }

package/dist/tools/builder-extras.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { resolvePreviewUrl } from "../config.js";
+import { getCachedUpload, setCachedUpload } from "../persistence/imageCache.js";
 import { parse as parseHtml } from "node-html-parser";
 import { stat, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -55,14 +56,49 @@ async function toAllowedImage(buf, contentType) {
     const out = await sharp(buf).jpeg({ quality: 85 }).toBuffer();
     return { buf: out, contentType: "image/jpeg" };
 }
+/** Re-host one external image (http(s) URL or data: URI) on the WebCake CDN, with a
+ *  per-site cache so the same source is never uploaded twice. Returns the hosted URL.
+ *  The storefront only renders whitelisted (WebCake CDN) image domains, so every image
+ *  used on a page/product MUST go through this — external URLs (Pexels, etc.) won't show. */
+async function cdnUpload(api, source) {
+    const cached = await getCachedUpload(api.siteId, source);
+    if (cached)
+        return cached;
+    let buf, contentType;
+    if (source.startsWith("data:")) {
+        const m = source.match(/^data:([^;]+);base64,(.*)$/s);
+        if (!m)
+            throw new Error("Malformed data URI.");
+        contentType = m[1];
+        buf = Buffer.from(m[2], "base64");
+    }
+    else {
+        ({ buf, contentType } = await fetchBuffer(source));
+    }
+    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.");
+    await setCachedUpload(api.siteId, source, hosted);
+    return hosted;
+}
 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.
+    server.tool("search_images", `Search stock photos (Pexels) for a page/product. IMPORTANT: the storefront only renders
+images served from the WebCake CDN (image domains are whitelisted) — raw Pexels URLs will
+NOT display. By default this re-hosts each result on the WebCake CDN and returns a ready-to-use
+cdn_url (cached, so repeats are free). Use cdn_url for image src / product images.
 Requires the PEXELS_API_KEY environment variable.`, {
         query: z.string().describe("Subject to search, e.g. 'coffee shop interior'"),
         per_page: z.number().min(1).max(30).default(6).describe("How many results (default 6)"),
         orientation: z.enum(["landscape", "portrait", "square"]).optional().describe("Preferred orientation"),
-    }, ({ query, per_page, orientation }) => handle(async () => {
+        upload: z
+            .boolean()
+            .default(true)
+            .describe("Re-host each result on the WebCake CDN and return cdn_url (default true — required for the image to show). Set false to only browse Pexels URLs."),
+    }, ({ query, per_page, orientation, upload }) => handle(async () => {
         const key = process.env.PEXELS_API_KEY;
         if (!key)
             return { error: "PEXELS_API_KEY env var is not set. Add it to use stock image search." };
@@ -75,7 +111,7 @@ Requires the PEXELS_API_KEY environment variable.`, {
         if (!res.ok)
             return { error: `Pexels error ${res.status}` };
         const json = await res.json();
-        const photos = (json.photos || []).map((p) => ({
+        let photos = (json.photos || []).map((p) => ({
             url: p.src && (p.src.large || p.src.original),
             thumbnail: p.src && p.src.medium,
             width: p.width,
@@ -84,10 +120,28 @@ Requires the PEXELS_API_KEY environment variable.`, {
             credit: p.photographer,
             source: p.url,
         }));
-        return { query, total_results: json.total_results, photos };
+        if (upload) {
+            photos = await Promise.all(photos.map(async (ph) => {
+                try {
+                    return { ...ph, cdn_url: await cdnUpload(api, ph.url) };
+                }
+                catch (e) {
+                    return { ...ph, cdn_url: null, upload_error: e?.message ?? String(e) };
+                }
+            }));
+        }
+        return {
+            query,
+            total_results: json.total_results,
+            uploaded_to_cdn: upload,
+            note: upload
+                ? "Use each photo's cdn_url (WebCake-hosted) for image src / product images — NOT url (Pexels, not whitelisted)."
+                : "These are Pexels URLs and will NOT render on the storefront. Run upload_images (or upload:true) to re-host them on the CDN first.",
+            photos,
+        };
     }));
     // ── 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.
+    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 CDN URLs go straight into an image element's specials.src / runtime.config.src, or a product/category image. This is REQUIRED for any external image (incl. Pexels search results) because the storefront only renders whitelisted WebCake-CDN image domains. Results are cached per site, so re-uploading the same source is free.
 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())
@@ -124,29 +178,28 @@ Processes up to 20 entries per call in parallel; non jpeg/png/webp inputs are co
         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 (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));
+                    const cached = await getCachedUpload(api.siteId, entry);
+                    if (cached) {
+                        images[entry] = cached;
+                        return;
+                    }
+                    const { buf, contentType } = await readLocalImage(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.");
+                    await setCachedUpload(api.siteId, entry, hosted);
+                    images[entry] = hosted;
                 }
                 else {
-                    ({ buf, contentType } = await fetchBuffer(entry));
+                    // http(s) URL or data: URI — cdnUpload handles fetch/convert/upload + cache.
+                    images[entry] = await cdnUpload(api, 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) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.7.0",
+  "version": "1.9.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",