npm - webcake-landing-mcp - Versions diffs - 1.0.32 → 1.0.34 - Mend

webcake-landing-mcp 1.0.32 → 1.0.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +5 -0
package/dist/changelog.json +14 -14
package/dist/domains/landing/elements/form.js +4 -1
package/dist/domains/landing/instructions.js +2 -2
package/dist/domains/landing/validate.js +7 -2
package/dist/env.js +59 -0
package/dist/http.js +41 -0
package/dist/index.js +4 -0
package/dist/persistence/pexels-client.js +124 -0
package/dist/smoke.js +32 -0
package/dist/tools/index.js +2 -0
package/dist/tools/media.js +42 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -447,6 +447,11 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 | `new_page_skeleton` | An empty but complete top-level source `{ page, popup, settings, options, cartConfigs }`. |
 | `validate_page` | Structural + semantic validation (ids, event targets, containers, `field_name`). |
+### Media (works out of the box; optional Pexels key)
+| Tool | Description |
+|------|-------------|
+| `search_images` | Find REAL stock photos (Pexels) for a page — returns hotlinkable URLs at several sizes to drop into an image element's `specials.src`. Works with **no setup** (a shared hosted proxy supplies images); set `PEXELS_API_KEY` env or the `x-pexels-key` header to use your own [free Pexels key](https://www.pexels.com/api/) / quota. |
 ### Persistence (needs `WEBCAKE_API_BASE` + `WEBCAKE_JWT`)
 | Tool | Description |
 |------|-------------|

package/dist/changelog.json CHANGED Viewed

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.34",
+    "d": "08/06/2026",
+    "type": "Added",
+    "en": "New search_images tool queries Pexels stock photos by short English subject and returns ready-to-hotlink URLs at several sizes; use src.large for…",
+    "vi": "Công cụ search_images mới truy vấn ảnh stock Pexels theo chủ đề tiếng Anh ngắn gọn và trả về các URL sẵn sàng hotlink ở nhiều kích thước; dùng…"
+  },
+  {
+    "v": "1.0.33",
+    "d": "08/06/2026",
+    "type": "Fixed",
+    "en": "get_element for country-select now marks specials.field_placeholder as required (the renderer crashes without it), and the element seed now emits a…",
+    "vi": "get_element cho country-select nay đánh dấu specials.field_placeholder là bắt buộc (renderer sẽ crash nếu thiếu trường này), và seed phần tử nay…"
+  },
   {
     "v": "1.0.32",
     "d": "08/06/2026",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "The GET / guide page now takes full control of scroll restoration across reloads: native browser scroll restoration is disabled in the <head> script…",
     "vi": "Trang hướng dẫn GET / nay kiểm soát hoàn toàn việc khôi phục vị trí cuộn sau reload: tính năng scroll restoration tự nhiên của trình duyệt bị tắt…"
-  },
-  {
-    "v": "1.0.28",
-    "d": "08/06/2026",
-    "type": "Fixed",
-    "en": "The GET / guide page no longer animates the browser's scroll-position restoration on reload; smooth scrolling is now enabled one animation frame…",
-    "vi": "Trang hướng dẫn GET / không còn tạo hiệu ứng cuộn cho quá trình trình duyệt khôi phục vị trí cuộn khi tải lại trang; smooth scrolling nay chỉ được…"
-  },
-  {
-    "v": "1.0.27",
-    "d": "08/06/2026",
-    "type": "Fixed",
-    "en": "The HTTP server's GET / route now serves the full HTML guide page to social and search crawlers (Facebook, Zalo, Twitter/X, LinkedIn, Slack,…",
-    "vi": "Route GET / của HTTP server nay phục vụ trang hướng dẫn HTML đầy đủ cho các crawler mạng xã hội và công cụ tìm kiếm (Facebook, Zalo, Twitter/X,…"
   }
 ]

package/dist/domains/landing/elements/form.js CHANGED Viewed

@@ -224,6 +224,7 @@ export const FORM = [
         useWhen: "International forms.",
         keySpecials: {
             field_name: "REQUIRED unique data key.",
+            field_placeholder: "REQUIRED — the disabled first-option label. Key is `field_placeholder`, NOT `placeholder`. The country-select renderer crashes if this is missing.",
             countries: "array of country dial-prefix codes (e.g. ['84','1','65']) shown in the dropdown and used to preload address data.",
             autofill_phone: "boolean — listen to sibling phone_number inputs to auto-select the country by dial prefix and auto-prepend the dial code.",
         },
@@ -231,6 +232,7 @@ export const FORM = [
             seedPosition(el);
             setBox(el, 150, 36);
             el.specials.field_name = `country_select_${el.id}`;
+            el.specials.field_placeholder = "Quốc gia";
         },
     },
     {
@@ -322,7 +324,7 @@ export const FORM = [
         useWhen: "Child of group-select only.",
         keySpecials: {
             field_name: "REQUIRED unique data key (becomes 'quantity' when field_quantity=true).",
-            field_placeholder: "string — the item's visible label/placeholder (the editor seeds 'AttrName' for attribute items, 'Quantity' for the quantity item).",
+            field_placeholder: "REQUIRED string — the disabled first-option label (the editor seeds 'AttrName' for attribute items, 'Quantity' for the quantity item). Key is `field_placeholder`, NOT `placeholder`. The renderer crashes if this is missing.",
             field_quantity: "boolean — when true this item is the quantity selector (value goes to parent._setQuantity), not a product attribute. Only one item per group.",
             attrName: "string — the product attribute name this item maps to (e.g. 'Color','Size'); numeric strings ('1','2') index product_attributes for custom products; 'sprod-name'/'sprod-sku' show the product name/SKU.",
             options: "array [{id,name,value}] — STATIC option list used by the quantity item (field_quantity=true), e.g. 1..4; attribute items leave this empty and populate from the catalog at runtime.",
@@ -331,6 +333,7 @@ export const FORM = [
         },
         seed: (el) => {
             el.specials.field_name = `gs_${el.id}`;
+            el.specials.field_placeholder = "Chọn...";
         },
     },
 ];

package/dist/domains/landing/instructions.js CHANGED Viewed

@@ -20,6 +20,6 @@ MODEL (essentials):
 - CENTERING (the #1 layout defect — do the math, don't eyeball): to center a box compute left = round((canvas - width)/2) — 960 desktop, 420 mobile. textAlign:center only centers text inside the box, not the box itself. For a row of N items, center the whole row block (startLeft = round((canvas - (N*item + (N-1)*gap))/2)). Keep 0 ≤ left and left+width ≤ canvas on each breakpoint.
 - STICKY HEADER: a sticky/fixed header (config.sticky) OVERLAYS the page — it does NOT push sections below it down. Offset the first section's top content DOWN by the header height (~60–72px) so nothing hides behind it, and do NOT duplicate the shop name in both the header and the top of the hero. A non-sticky header stacks normally and needs no offset.
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
-- IMAGES: include them (hero/product, feature icons, about photo). No image API yet → set image-block specials.src to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height> (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
+- IMAGES: include them (hero/product, feature icons, about photo). PREFER REAL PHOTOS — call search_images with a short English subject (e.g. 'fresh coffee cup') and put a returned URL (src.large for a hero/banner, src.medium for a card/thumb) into the image-block specials.src; it works out of the box (a shared proxy supplies images). Only if search_images returns ok:false, FALL BACK to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height>. (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, list_organizations, create_page, list_pages, get_page, update_page.`;
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, list_organizations, create_page, list_pages, get_page, update_page.`;

package/dist/domains/landing/validate.js CHANGED Viewed

@@ -31,6 +31,11 @@ const TOP_LEVEL_TYPES = new Set(["section", "dynamic_page", "popup"]);
 // it; select shows a blank option). The correct option shape is {id, name} — NOT
 // the HTML-style {label, value}.
 const OPTION_NAME_FIELDS = new Set(["select", "radio", "checkbox-group"]);
+// Fields whose renderer ALWAYS emits unescapeHTML(field_placeholder) with NO
+// default (renderSelect / renderCountrySelect / renderGroupSelectItem) — a missing
+// field_placeholder throws "Cannot read properties of undefined (reading 'replace')"
+// and the whole page fails to render.
+const PLACEHOLDER_REQUIRED_FIELDS = new Set(["select", "country-select", "group-select-item"]);
 // Fixed canvas reference (matches vocab CANVAS) used for the layout/bounds check.
 const CANVAS_DESKTOP = 960;
 const CANVAS_MOBILE = 420;
@@ -126,8 +131,8 @@ export function validatePage(input) {
                 if (typeof specials.placeholder === "string" && !hasFieldPlaceholder) {
                     warnings.push(`${path} (${type}): uses specials.placeholder — the renderer reads specials.field_placeholder. Rename "placeholder" → "field_placeholder".`);
                 }
-                if (type === "select" && !hasFieldPlaceholder) {
-                    errors.push(`${path} (select): needs a string specials.field_placeholder (the select renderer crashes without it).`);
+                if (PLACEHOLDER_REQUIRED_FIELDS.has(type) && !hasFieldPlaceholder) {
+                    errors.push(`${path} (${type}): needs a string specials.field_placeholder (this element's renderer crashes without it).`);
                 }
             }
             // select/radio/checkbox-group render each option from option.name; a missing

package/dist/env.js ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * Tiny zero-dependency `.env` loader. We publish to npm, so every dependency
+ * ships to users — instead of pulling in `dotenv`, parse a `.env` ourselves.
+ *
+ * Looks for a `.env` in the current working directory first, then next to the
+ * running binary (dist/), so it works both for local dev and a deployed server.
+ * Only sets keys that are NOT already in process.env — real env vars and the
+ * per-request HTTP headers always win over the file. stdout is the MCP channel,
+ * so any parse note goes to stderr.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function parseEnv(text) {
+    const out = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!key)
+            continue;
+        let val = line.slice(eq + 1).trim();
+        // Strip a single surrounding pair of quotes, if present.
+        if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+            val = val.slice(1, -1);
+        }
+        out[key] = val;
+    }
+    return out;
+}
+/** Candidate `.env` locations, in priority order (cwd, then the binary's dir + parent). */
+function candidatePaths() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/ at runtime
+    return [join(process.cwd(), ".env"), join(here, ".env"), join(here, "..", ".env")];
+}
+/** Load the first readable `.env`, assigning only keys absent from process.env. */
+export function loadDotenv() {
+    const seen = new Set();
+    for (const path of candidatePaths()) {
+        let text;
+        try {
+            text = readFileSync(path, "utf8");
+        }
+        catch {
+            continue; // no file here — try the next candidate
+        }
+        for (const [k, v] of Object.entries(parseEnv(text))) {
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            if (process.env[k] === undefined)
+                process.env[k] = v;
+        }
+    }
+}

package/dist/http.js CHANGED Viewed

@@ -19,7 +19,9 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "./server.js";
 import { ICON_SVG, ICON_MIME } from "./branding.js";
 import { guideHtml, ogImageSvg, normalizeLang } from "./web-guide.js";
+import { searchPexels, resolvePexelsKey } from "./persistence/pexels-client.js";
 const MCP_PATH = "/mcp";
+const IMAGES_PATH = "/api/images/search";
 // Social/search crawlers (Facebook, Zalo, Twitter/X, LinkedIn, Slack, Telegram,
 // WhatsApp, Discord, Google, Bing…) fetch the root with `Accept: */*` rather than
 // `text/html`, so they'd otherwise get the JSON health blob and never see the OG
@@ -86,6 +88,42 @@ function applyQueryAuth(req) {
         }
     }
 }
+/**
+ * Shared image proxy: GET /api/images/search?query=…&per_page=…&orientation=…
+ * Holds the server's own PEXELS_API_KEY (from env/.env) and returns the normalized
+ * search result, so `npx` clients without a key get images via this host. CORS is
+ * permissive so a browser can call it too; the key is never sent to the client.
+ */
+async function handleImageSearch(req, res) {
+    const cors = { "access-control-allow-origin": "*", "access-control-allow-headers": "*" };
+    if (req.method === "OPTIONS") {
+        res.writeHead(204, cors);
+        return res.end();
+    }
+    const sendImgJson = (status, body) => {
+        res.writeHead(status, { "content-type": "application/json", ...cors });
+        res.end(JSON.stringify(body));
+    };
+    const key = resolvePexelsKey();
+    if (!key) {
+        return sendImgJson(503, { ok: false, reason: "proxy_no_key", error: "Image proxy has no PEXELS_API_KEY configured." });
+    }
+    const sp = new URL(req.url ?? "/", "http://x").searchParams;
+    const query = sp.get("query")?.trim();
+    if (!query) {
+        return sendImgJson(400, { ok: false, reason: "missing_query", error: "Pass ?query=<subject>." });
+    }
+    const params = {
+        query,
+        perPage: sp.get("per_page") ? Number(sp.get("per_page")) : undefined,
+        page: sp.get("page") ? Number(sp.get("page")) : undefined,
+        orientation: sp.get("orientation") ?? undefined,
+        size: sp.get("size") ?? undefined,
+        color: sp.get("color") ?? undefined,
+    };
+    const result = await searchPexels(key, params);
+    return sendImgJson(result.ok ? 200 : result.status || 502, result);
+}
 export async function startHttpServer(port) {
     // mcp-session-id -> live transport (each bound to its own McpServer instance).
     const transports = new Map();
@@ -134,6 +172,9 @@ export async function startHttpServer(port) {
             }
             return sendJson(res, 200, { ok: true, server: "webcake-landing", transport: "streamable-http", endpoint: MCP_PATH });
         }
+        // Shared image proxy (for `npx` clients without their own Pexels key).
+        if (path === IMAGES_PATH)
+            return handleImageSearch(req, res);
         if (path !== MCP_PATH)
             return rpcError(res, 404, `Not found. Send MCP requests to ${MCP_PATH}.`);
         // Accept credentials via ?jwt=/?api_base=/... (for clients that can't set headers).

package/dist/index.js CHANGED Viewed

@@ -17,6 +17,7 @@
  */
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "./server.js";
+import { loadDotenv } from "./env.js";
 import { ENVIRONMENTS, ENV_NAMES, isEnvName } from "./persistence/config.js";
 /**
  * Global `--env <local|staging|prod>` flag (or `--env=<name>`): selects the API +
@@ -72,6 +73,9 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
+    // Load `.env` (if any) before anything reads process.env — real env vars and
+    // per-request headers still win over the file.
+    loadDotenv();
     // Resolve the named environment (--env / WEBCAKE_ENV) before any config is read.
     applyEnvFlag(process.argv);
     // Subcommand dispatch: `webcake-landing-mcp install|uninstall` runs the

package/dist/persistence/pexels-client.js ADDED Viewed

@@ -0,0 +1,124 @@
+/**
+ * Thin HTTP client to the Pexels stock-photo API (https://www.pexels.com/api/).
+ * Lets the agent fetch REAL, relevant images for a landing page instead of the
+ * grey https://placehold.co/ placeholders — the returned URLs drop straight into
+ * an image element's `specials.src` (or a gallery item's `link`).
+ *
+ * The API key is a SECRET resolved exactly like the Webcake JWT (never hard-coded,
+ * the repo is public): the `PEXELS_API_KEY` env var (stdio / single-user), or the
+ * `x-pexels-key` header per request (remote / multi-user). Pexels allows hotlinking
+ * its image URLs as long as attribution is shown — `normalizePhoto` carries the
+ * photographer + page url so the agent can credit the source. Requires global
+ * fetch (Node 18+). `normalizePhoto` is a pure function so it can be smoke-tested.
+ *
+ * SHARED PROXY: when no key is configured locally (e.g. a plain `npx` user),
+ * `searchImagesViaProxy` calls a hosted endpoint (GET <base>/api/images/search,
+ * default https://mcp.toolvn.io.vn) that holds a shared key and returns the SAME
+ * normalized shape — so images work out of the box with zero setup. The proxy
+ * route is served by this same server in `serve` mode (see src/http.ts).
+ */
+const PEXELS_SEARCH_ENDPOINT = "https://api.pexels.com/v1/search";
+/** Default hosted proxy that holds a shared Pexels key (override with PEXELS_PROXY_BASE). */
+export const PEXELS_PROXY_DEFAULT = "https://mcp.toolvn.io.vn";
+/** Path of the proxy's image-search route (served by this server in `serve` mode). */
+export const PEXELS_PROXY_PATH = "/api/images/search";
+/** Resolve the Pexels API key: per-request override (header) wins over env. */
+export function resolvePexelsKey(override) {
+    const key = override ?? process.env.PEXELS_API_KEY;
+    return key && key.trim() !== "" ? key.trim() : undefined;
+}
+/** Resolve the shared-proxy base URL: override → PEXELS_PROXY_BASE env → the default host. */
+export function resolvePexelsProxyBase(override) {
+    const base = override ?? process.env.PEXELS_PROXY_BASE ?? PEXELS_PROXY_DEFAULT;
+    return base.replace(/\/+$/, "");
+}
+/** Pull the `x-pexels-key` header (remote/multi-user mode), if present. */
+export function pexelsKeyFromHeaders(headers) {
+    const v = headers?.["x-pexels-key"];
+    const raw = Array.isArray(v) ? v[0] : v;
+    return raw && raw.trim() !== "" ? raw.trim() : undefined;
+}
+/** Map one raw Pexels API photo onto the trimmed PexelsPhoto shape (pure). */
+export function normalizePhoto(p) {
+    return {
+        id: p?.id,
+        alt: typeof p?.alt === "string" ? p.alt : "",
+        width: p?.width,
+        height: p?.height,
+        avg_color: typeof p?.avg_color === "string" ? p.avg_color : null,
+        photographer: p?.photographer ?? "",
+        photographer_url: p?.photographer_url ?? "",
+        pexels_url: p?.url ?? "",
+        src: p?.src && typeof p.src === "object" ? p.src : {},
+    };
+}
+/** Build the shared query string for both the direct Pexels call and the proxy. */
+export function buildSearchQuery(params) {
+    const q = new URLSearchParams();
+    q.set("query", params.query);
+    q.set("per_page", String(Math.min(Math.max(params.perPage ?? 5, 1), 80)));
+    if (params.page)
+        q.set("page", String(params.page));
+    if (params.orientation)
+        q.set("orientation", params.orientation);
+    if (params.size)
+        q.set("size", params.size);
+    if (params.color)
+        q.set("color", params.color);
+    return q;
+}
+/** Search Pexels DIRECTLY (needs a key). Returns normalized, hotlinkable URLs. */
+export async function searchPexels(key, params) {
+    const url = `${PEXELS_SEARCH_ENDPOINT}?${buildSearchQuery(params).toString()}`;
+    let res;
+    try {
+        res = await fetch(url, { method: "GET", headers: { Authorization: key } });
+    }
+    catch (e) {
+        return { ok: false, status: 0, error: `Network error calling Pexels: ${e?.message ?? e}` };
+    }
+    const body = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        /* non-JSON */
+    }
+    if (!res.ok) {
+        const msg = json?.error ?? body.slice(0, 200);
+        const hint = res.status === 401 ? " (check PEXELS_API_KEY / x-pexels-key — it may be invalid)" : "";
+        return { ok: false, status: res.status, error: `Pexels returned ${res.status}${msg ? `: ${msg}` : ""}${hint}` };
+    }
+    const photos = (json?.photos ?? []).map(normalizePhoto);
+    return { ok: true, status: res.status, query: params.query, total_results: json?.total_results, photos };
+}
+/**
+ * Search via the SHARED PROXY (no local key needed): GET <base>/api/images/search.
+ * The proxy returns the same normalized shape — we re-`normalizePhoto` defensively
+ * so a slightly different payload still yields the page-builder fields.
+ */
+export async function searchImagesViaProxy(base, params) {
+    const url = `${base.replace(/\/+$/, "")}${PEXELS_PROXY_PATH}?${buildSearchQuery(params).toString()}`;
+    let res;
+    try {
+        res = await fetch(url, { method: "GET", headers: { Accept: "application/json" } });
+    }
+    catch (e) {
+        return { ok: false, status: 0, error: `Network error calling image proxy ${base}: ${e?.message ?? e}` };
+    }
+    const body = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(body);
+    }
+    catch {
+        /* non-JSON */
+    }
+    if (!res.ok) {
+        const msg = json?.error ?? json?.reason ?? body.slice(0, 200);
+        return { ok: false, status: res.status, error: `Image proxy returned ${res.status}${msg ? `: ${msg}` : ""}` };
+    }
+    const photos = (json?.photos ?? []).map(normalizePhoto);
+    return { ok: json?.ok !== false, status: res.status, query: params.query, total_results: json?.total_results, photos, via: "proxy" };
+}

package/dist/smoke.js CHANGED Viewed

@@ -6,6 +6,7 @@ import { createElement, CONTAINER_TYPES, FIELD_TYPES, LIBRARY, ELEMENT_TYPES, EL
 import { validatePage, pageSchema } from "./domains/landing/validate.js";
 import { readConfig, resolveEnv, ENV_NAMES } from "./persistence/config.js";
 import { toEditorUrl } from "./persistence/webcake-client.js";
+import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -240,5 +241,36 @@ console.log("== config: named environment presets (local/staging/prod) ==");
     check("editor url from an absolute api url → builder host", toEditorUrl(localCfg, "http://localhost:5800/editor/v2/abc?x=1") === "http://builder.localhost:5800/editor/v2/abc?x=1");
     check("editor url passthrough when empty", toEditorUrl(localCfg, undefined) === undefined);
 }
+console.log("== pexels: key resolution + photo normalization (offline, no network) ==");
+{
+    for (const k of ["PEXELS_API_KEY"])
+        delete process.env[k];
+    check("no key → undefined", resolvePexelsKey() === undefined);
+    check("header key wins (override)", resolvePexelsKey("hdr-key") === "hdr-key");
+    process.env.PEXELS_API_KEY = "  env-key  ";
+    check("env key is read + trimmed", resolvePexelsKey() === "env-key");
+    delete process.env.PEXELS_API_KEY;
+    check("x-pexels-key header parsed", pexelsKeyFromHeaders({ "x-pexels-key": "abc" }) === "abc");
+    check("array header takes first", pexelsKeyFromHeaders({ "x-pexels-key": ["a", "b"] }) === "a");
+    check("absent header → undefined", pexelsKeyFromHeaders({}) === undefined);
+    const photo = normalizePhoto({
+        id: 42, alt: "a cat", width: 1200, height: 800, avg_color: "#446688",
+        photographer: "Jane", photographer_url: "https://pexels.com/@jane", url: "https://pexels.com/photo/42",
+        src: { large: "https://images.pexels.com/large.jpg", medium: "https://images.pexels.com/medium.jpg" },
+    });
+    check("normalizePhoto keeps the page-builder fields", photo.id === 42 && photo.alt === "a cat" && photo.avg_color === "#446688" && photo.src.large.includes("large.jpg") && photo.pexels_url.endsWith("/42"));
+    const sparse = normalizePhoto({ id: 1 });
+    check("normalizePhoto tolerates missing fields", sparse.alt === "" && sparse.avg_color === null && typeof sparse.src === "object");
+    // shared proxy fallback (used when no local key)
+    delete process.env.PEXELS_PROXY_BASE;
+    check("proxy base defaults to the hosted host", resolvePexelsProxyBase() === PEXELS_PROXY_DEFAULT);
+    check("proxy base override wins + trailing slash trimmed", resolvePexelsProxyBase("https://x.test/") === "https://x.test");
+    process.env.PEXELS_PROXY_BASE = "https://env.test";
+    check("proxy base read from PEXELS_PROXY_BASE env", resolvePexelsProxyBase() === "https://env.test");
+    delete process.env.PEXELS_PROXY_BASE;
+    const q = buildSearchQuery({ query: "coffee cup", perPage: 3, orientation: "landscape" });
+    check("buildSearchQuery encodes query + per_page + orientation", q.get("query") === "coffee cup" && q.get("per_page") === "3" && q.get("orientation") === "landscape");
+    check("buildSearchQuery clamps per_page to 1..80", buildSearchQuery({ query: "x", perPage: 999 }).get("per_page") === "80" && buildSearchQuery({ query: "x", perPage: 0 }).get("per_page") === "1");
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/tools/index.js CHANGED Viewed

@@ -1,8 +1,10 @@
 import { registerReferenceTools } from "./reference.js";
 import { registerGenerationTools } from "./generation.js";
+import { registerMediaTools } from "./media.js";
 import { registerPersistenceTools } from "./persistence.js";
 export function registerTools(server, domain) {
     registerReferenceTools(server, domain);
     registerGenerationTools(server, domain);
+    registerMediaTools(server);
     registerPersistenceTools(server, domain);
 }

package/dist/tools/media.js ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * Media tools: fetch REAL stock images for a page instead of grey placeholders.
+ * `search_images` queries the Pexels API and returns ready-to-hotlink URLs the
+ * agent drops into an image element's `specials.src` (or a gallery item's `link`).
+ *
+ * The Pexels API key is a secret resolved per request: the `x-pexels-key` header
+ * (remote / multi-user) wins, else the `PEXELS_API_KEY` env var (stdio). With a key
+ * we call Pexels directly; WITHOUT one we fall back to the shared hosted proxy
+ * (https://mcp.toolvn.io.vn) so `npx` users get images with zero setup. The page can
+ * still fall back to placeholders if even the proxy is unreachable. No Webcake creds.
+ */
+import { z } from "zod";
+import { text } from "../mcp/response.js";
+import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
+export function registerMediaTools(server) {
+    // 13) Search images ---------------------------------------------------------
+    server.tool("search_images", "Find REAL stock photos (Pexels) for a page so images aren't grey placeholders. Works out of the box (a shared hosted proxy supplies images; set PEXELS_API_KEY env or the x-pexels-key header to use your own Pexels quota — free at https://www.pexels.com/api/). Pass a short English subject query (e.g. 'fresh coffee cup', 'modern office team'). Returns hotlinkable URLs at several sizes — put `src.large` (hero/banner) or `src.medium` (card/thumb) into an image element's specials.src, or a gallery item's `link`; `avg_color` helps pick a matching section background. Show photographer attribution when you use a photo.", {
+        query: z.string().describe("Short English subject to search for, e.g. 'fresh coffee cup', 'spa massage room'."),
+        per_page: z.number().int().min(1).max(80).optional().describe("How many results to return (default 5)."),
+        orientation: z
+            .enum(["landscape", "portrait", "square"])
+            .optional()
+            .describe("Preferred shape — 'landscape' for heroes/banners, 'portrait' for tall cards, 'square' for icons/avatars."),
+        size: z.enum(["large", "medium", "small"]).optional().describe("Minimum photo size to return (default any)."),
+        color: z.string().optional().describe("Optional color filter: a name (red, blue, …) or a hex like '6a8f3c'."),
+        page: z.number().int().min(1).optional().describe("Result page for pagination (default 1)."),
+    }, async ({ query, per_page, orientation, size, color, page }, extra) => {
+        const params = { query, perPage: per_page, page, orientation, size, color };
+        const key = resolvePexelsKey(pexelsKeyFromHeaders(extra?.requestInfo?.headers));
+        // With a key → call Pexels directly; without one → the shared hosted proxy.
+        const result = key
+            ? await searchPexels(key, params)
+            : await searchImagesViaProxy(resolvePexelsProxyBase(), params);
+        if (!result.ok) {
+            return text({
+                ...result,
+                hint: "Couldn't fetch images — set PEXELS_API_KEY (env) or the x-pexels-key header for your own Pexels key (free at https://www.pexels.com/api/), or fall back to https://placehold.co/<width>x<height> placeholders.",
+            });
+        }
+        return text(result);
+    });
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "type": "module",
   "license": "MIT",