webcake-storefront-mcp 1.8.0 → 1.9.0

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,11 @@
 [
+  {
+    "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",
@@ -33,12 +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."
   }
 ]

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/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/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.8.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",