npm - webcake-landing-mcp - Versions diffs - 1.0.33 → 1.0.35 - Mend

webcake-landing-mcp 1.0.33 → 1.0.35

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 (12) hide show

package/README.md +5 -0
package/dist/changelog.json +14 -14
package/dist/domains/landing/guide.js +2 -1
package/dist/domains/landing/instructions.js +2 -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.35",
+    "d": "08/06/2026",
+    "type": "Changed",
+    "en": "get_generation_guide now includes an explicit workflow step (3b) directing the agent to call search_images for every image a page needs (hero,…",
+    "vi": "get_generation_guide nay bổ sung bước workflow rõ ràng (3b) yêu cầu agent gọi search_images cho mọi hình ảnh trang cần (hero, sản phẩm, giới thiệu,…"
+  },
+  {
+    "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",
@@ -26,19 +40,5 @@
     "type": "Changed",
     "en": "The server instructions now direct the agent to gather all get_element and get_generation_guide results before assembling the page source, build the…",
     "vi": "Hướng dẫn cho agent nay yêu cầu thu thập toàn bộ kết quả get_element và get_generation_guide trước khi lắp ráp nguồn trang, xây dựng cây phần tử đầy…"
-  },
-  {
-    "v": "1.0.29",
-    "d": "08/06/2026",
-    "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…"
   }
 ]

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

@@ -78,7 +78,7 @@ SECTION BUILD HINTS (apply to whichever sections the chosen archetype uses)
 RULES
 - Visible content goes in "specials" (text-block.specials.text, image-block.specials.src…), NEVER in "styles".
 - Colors as rgba(r,g,b,a). fontSize/borderWidth/top/left/width/height are NUMBERS (px).
-- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). There is NO image API yet, so set image-block specials.src to a PLACEHOLDER URL sized to the box: "https://placehold.co/<width>x<height>". NEVER leave src empty — it renders blank and the page looks broken. gallery.media = array of OBJECTS {type:'image', link:'<placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster placeholder. The user replaces these later.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). PREFER REAL PHOTOS: call search_images with a short English subject (e.g. 'fresh coffee cup', 'modern office team') and put a returned URL into image-block specials.src — use src.large for a hero/banner, src.medium for a card/thumb (avg_color helps pick a matching section background). ONLY if search_images returns ok:false (or is unreachable) FALL BACK to a PLACEHOLDER sized to the box: "https://placehold.co/<width>x<height>". NEVER leave src empty — it renders blank and the page looks broken. gallery.media = array of OBJECTS {type:'image', link:'<real-or-placeholder-url>', linkVideo:'', typeVideo:'youtube', imageCompression:true} (NOT plain URL strings — the gallery reads item.link); video.specials.img = a poster image (real photo, else placeholder).
 - CONTRAST: text must contrast with the section background (dark text on light sections, light text on dark sections). Don't put light-gray text on white or faint text on a dark background.
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.
@@ -108,6 +108,7 @@ WORKFLOW (recommended)
 1. Call get_generation_guide (this) once, then new_page_skeleton for the top-level shape.
 2. For each element type you'll use, call get_element to learn its specials & see an example.
 3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
+3b. For every image the page needs (hero, product, about, feature, gallery), call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
 4. Assemble { page, popup, settings, options, cartConfigs }.
 5. Call validate_page and fix every error.
 6. To save: call list_organizations, show the orgs to the user and ask which to use (default to is_default). Then create_page (dry_run first, then dry_run:false with the chosen organization_id).

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/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.33",
+  "version": "1.0.35",
   "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",