webcake-landing-mcp 1.0.80 → 1.0.82

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.82",
+    "d": "16/06/2026",
+    "type": "Added",
+    "en": "render_preview now accepts a tiles parameter: pass tiles:true to receive the page as a stack of top-to-bottom horizontal band images instead of one…",
+    "vi": "render_preview nay nhận tham số tiles: truyền tiles:true để nhận trang dưới dạng stack các ảnh dải ngang từ trên xuống dưới thay vì một ảnh…"
+  },
+  {
+    "v": "1.0.81",
+    "d": "16/06/2026",
+    "type": "Changed",
+    "en": "The Playwright screenshot engine that backs render_preview's GET /api/render/screenshot route now defaults to JPEG output instead of PNG, reducing…",
+    "vi": "Engine chụp màn hình Playwright phục vụ route GET /api/render/screenshot của render_preview nay mặc định xuất ảnh JPEG thay vì PNG, giúp giảm kích…"
+  },
   {
     "v": "1.0.80",
     "d": "16/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "The remote serve transport now implements a spec-conformant OAuth 2.1 Authorization Server (Authorization Code + PKCE S256, Dynamic Client…",
     "vi": "Transport serve từ xa nay triển khai một OAuth 2.1 Authorization Server chuẩn spec (Authorization Code + PKCE S256, Dynamic Client Registration,…"
-  },
-  {
-    "v": "1.0.76",
-    "d": "15/06/2026",
-    "type": "Added",
-    "en": "validate_page now warns when specials.custom_css sets layout or structural CSS properties (position, top, left, right, bottom, inset, width, height,…",
-    "vi": "validate_page nay cảnh báo khi specials.custom_css đặt các thuộc tính CSS layout hoặc cấu trúc (position, top, left, right, bottom, inset, width,…"
-  },
-  {
-    "v": "1.0.75",
-    "d": "15/06/2026",
-    "type": "Added",
-    "en": "New get_icon_svg tool resolves Material Symbols (ms:<name>) and Font Awesome (fa:<name>) icon-font references to real inline SVG markup via the…",
-    "vi": "Tool mới get_icon_svg resolve tên icon-font Material Symbols (ms:<name>) và Font Awesome (fa:<name>) thành SVG inline thực sự qua Iconify API công…"
   }
 ]

package/dist/http.js

@@ -21,7 +21,7 @@ import { ICON_SVG, ICON_MIME } from "./branding.js";
 import { guideHtml, ogImageSvg, normalizeLang } from "./web-guide.js";
 import { privacyHtml, termsHtml } from "./legal.js";
 import { searchPexels, resolvePexelsKey } from "./persistence/pexels-client.js";
-import { captureWithPlaywright, isAllowedScreenshotUrl } from "./persistence/screenshot-playwright.js";
+import { captureWithPlaywright, captureTilesWithPlaywright, isAllowedScreenshotUrl } from "./persistence/screenshot-playwright.js";
 import { resolveEnv, ENVIRONMENTS, stripTrailingSlash } from "./persistence/config.js";
 import { buildConnectUrl } from "./auth/login.js";
 import { registerClient, startAuthorize, completeAuthorize, exchangeToken, resolveAccessToken, revokeToken, authServerMetadata, protectedResourceMetadata, } from "./auth/oauth-server.js";
@@ -350,13 +350,30 @@ async function handleRenderScreenshot(req, res) {
         return sendErr(400, { ok: false, error: allow.error });
     const fullPage = sp.get("full_page") !== "false";
     const width = sp.get("width") ? Number(sp.get("width")) : undefined;
+    // Tiles mode: split a tall page into horizontal bands, returned as a JSON array
+    // of base64 images (top→bottom) so the model reads each slice at a readable size.
+    if (sp.get("tiles") === "1" || sp.get("tiles") === "true") {
+        const bandHeight = sp.get("band_height") ? Number(sp.get("band_height")) : undefined;
+        const t = await captureTilesWithPlaywright(target, { width, bandHeight });
+        if (!t.ok)
+            return sendErr(t.reason === "not_installed" ? 503 : 502, { ok: false, error: t.error });
+        res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store", ...cors });
+        return res.end(JSON.stringify({
+            ok: true,
+            mimeType: t.mimeType,
+            page_height: t.pageHeight,
+            width: t.width,
+            truncated: t.truncated,
+            tiles: t.tiles.map((b) => ({ y: b.y, height: b.height, data: b.data.toString("base64") })),
+        }));
+    }
     const r = await captureWithPlaywright(target, { fullPage, width });
     if (!r.ok) {
         // 503 when the engine is absent (caller should fall back / skip), 502 otherwise.
         return sendErr(r.reason === "not_installed" ? 503 : 502, { ok: false, error: r.error });
     }
-    res.writeHead(200, { "content-type": "image/png", "cache-control": "no-store", ...cors });
-    return res.end(r.png);
+    res.writeHead(200, { "content-type": r.mimeType, "cache-control": "no-store", ...cors });
+    return res.end(r.data);
 }
 export async function startHttpServer(port) {
     // mcp-session-id -> live transport (each bound to its own McpServer instance).

package/dist/mcp/response.js

@@ -18,6 +18,18 @@ export function image(dataBase64, mimeType = "image/png", note) {
     }
     return { content };
 }
+/**
+ * Like `image()` but returns SEVERAL image blocks (e.g. a tall page tiled into
+ * top→bottom bands), optionally followed by a text note. The model sees each band
+ * at a readable size instead of one over-squished image.
+ */
+export function images(items, note) {
+    const content = items.map((it) => ({ type: "image", data: it.dataBase64, mimeType: it.mimeType ?? "image/png" }));
+    if (note !== undefined) {
+        content.push({ type: "text", text: typeof note === "string" ? note : JSON.stringify(note, null, 2) });
+    }
+    return { content };
+}
 /**
  * Directive shipped alongside every non-empty validation-warnings list.
  * Warnings are design defects the customer WILL see (text overlapping the

package/dist/persistence/screenshot-client.js

@@ -132,6 +132,52 @@ export async function captureViaProxy(base, targetUrl, opts, nonce = 0) {
         return { ok: false, status: 0, via: "proxy", error: `network error calling screenshot proxy ${base}: ${e?.message ?? e}` };
     }
 }
+/**
+ * Capture a tall page as horizontal BANDS via the self-hosted Playwright route
+ * (`?tiles=1`) so the model reads each slice at a readable size. Microlink can't
+ * tile, so this REQUIRES a proxy host (RENDER_SCREENSHOT_BASE); without one it
+ * returns not_supported and the caller should fall back to a single full-page shot.
+ * Never throws.
+ */
+export async function captureScreenshotTiles(targetUrl, opts = {}, resolved = {}, nonce = 0) {
+    if (!resolved.proxyBase) {
+        return { ok: false, status: 0, not_supported: true, error: "tiling needs a Playwright host (RENDER_SCREENSHOT_BASE); Microlink can't tile" };
+    }
+    const q = new URLSearchParams();
+    q.set("url", targetUrl + (targetUrl.includes("?") ? "&" : "?") + "_=" + nonce);
+    q.set("tiles", "1");
+    q.set("full_page", "true");
+    if (opts.width && Number.isFinite(opts.width))
+        q.set("width", String(Math.round(opts.width)));
+    if (opts.bandHeight && Number.isFinite(opts.bandHeight))
+        q.set("band_height", String(Math.round(opts.bandHeight)));
+    const url = `${resolved.proxyBase}${SCREENSHOT_PROXY_PATH}?${q.toString()}`;
+    try {
+        const res = await fetch(url, { method: "GET", headers: { Accept: "application/json" }, signal: AbortSignal.timeout(SCREENSHOT_TIMEOUT_MS) });
+        const ct = (res.headers.get("content-type") ?? "").toLowerCase();
+        if (res.ok && ct.includes("application/json")) {
+            const j = await res.json();
+            return {
+                ok: true,
+                status: res.status,
+                mimeType: j.mimeType,
+                pageHeight: j.page_height,
+                width: j.width,
+                truncated: j.truncated === true,
+                tiles: (j.tiles ?? []).map((t) => ({ y: t.y, height: t.height, dataBase64: t.data })),
+                via: "proxy",
+            };
+        }
+        const body = (await res.text()).slice(0, 300);
+        return { ok: false, status: res.status, quota_exhausted: res.status === 429, error: `tiles proxy returned HTTP ${res.status}${body ? `: ${body}` : ""}` };
+    }
+    catch (e) {
+        if (e?.name === "TimeoutError" || e?.name === "AbortError") {
+            return { ok: false, status: 0, error: `tiles request timed out after ${SCREENSHOT_TIMEOUT_MS}ms` };
+        }
+        return { ok: false, status: 0, error: `network error calling tiles proxy ${resolved.proxyBase}: ${e?.message ?? e}` };
+    }
+}
 /**
  * Capture a screenshot with AUTOMATIC FALLOVER between the two engines:
  *   - Microlink direct (free, zero-config) and

package/dist/persistence/screenshot-playwright.js

@@ -63,8 +63,34 @@ async function getBrowser() {
         return null;
     }
 }
-/** Screenshot a URL with Playwright. Never throws. */
-export async function captureWithPlaywright(url, opts = {}) {
+/**
+ * Output tuning (env-controlled, so the VPS operator picks the size/quality
+ * tradeoff). Default JPEG — a full-page landing screenshot is ~5–10× smaller as
+ * JPEG than PNG with no loss that matters for a layout/colour comparison, which
+ * shrinks the base64 the model receives. `scale` (deviceScaleFactor) renders at a
+ * lower pixel density to cut dimensions too; 1 = crisp, 0.5 = quarter the pixels.
+ */
+function outputOpts() {
+    const fmt = (process.env.RENDER_SCREENSHOT_FORMAT ?? "jpeg").toLowerCase();
+    const type = fmt === "png" ? "png" : "jpeg";
+    const q = parseInt(process.env.RENDER_SCREENSHOT_QUALITY ?? "", 10);
+    const quality = type === "jpeg" ? (Number.isFinite(q) && q >= 1 && q <= 100 ? q : 72) : undefined;
+    const s = parseFloat(process.env.RENDER_SCREENSHOT_SCALE ?? "");
+    const scale = Number.isFinite(s) && s > 0 && s <= 2 ? s : 1;
+    return { type, quality, scale };
+}
+/** Default band height (CSS px) for tiling a tall page; env-tunable. */
+function resolveBandHeight() {
+    const b = parseInt(process.env.RENDER_SCREENSHOT_BAND_HEIGHT ?? "", 10);
+    return Number.isFinite(b) && b >= 200 ? b : 1400;
+}
+/**
+ * Run `fn` against a fresh browser context (viewport width + deviceScaleFactor),
+ * with a single self-heal retry if the cached browser died (crash, or a system
+ * Chrome that closed). Always closes the context. Never throws — the shared
+ * lifecycle for both single-shot and tiled capture.
+ */
+async function withContext(width, scale, fn) {
     const pw = await loadPlaywright();
     if (!pw) {
         return {
@@ -73,13 +99,10 @@ export async function captureWithPlaywright(url, opts = {}) {
             error: "playwright is not installed on this host (run: npm i playwright && npx playwright install chromium)",
         };
     }
-    // One shot, with a single self-heal retry: if the cached browser died (crash,
-    // or a system Chrome that closed), drop it and relaunch once.
     for (let attempt = 0; attempt < 2; attempt++) {
         let browser = await getBrowser();
         if (!browser)
             return { ok: false, error: "failed to launch headless chromium (check CHROME_BIN / playwright install)" };
-        // If the cached handle is already disconnected, force a relaunch.
         if (typeof browser.isConnected === "function" && !browser.isConnected()) {
             browserPromise = null;
             browser = await getBrowser();
@@ -88,19 +111,12 @@ export async function captureWithPlaywright(url, opts = {}) {
         }
         let ctx;
         try {
-            ctx = await browser.newContext({
-                viewport: { width: opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280, height: 900 },
-                deviceScaleFactor: 1,
-            });
-            const page = await ctx.newPage();
-            await page.goto(url, { waitUntil: "load", timeout: 30_000 });
-            await page.waitForTimeout(1200); // let webfonts/lazy images settle
-            const png = await page.screenshot({ fullPage: opts.fullPage !== false, type: "png" });
-            return { ok: true, png: Buffer.from(png) };
+            ctx = await browser.newContext({ viewport: { width, height: 900 }, deviceScaleFactor: scale });
+            const value = await fn(ctx);
+            return { ok: true, value };
         }
         catch (e) {
             const msg = String(e?.message ?? e);
-            // Browser-died errors → reset and retry once; other errors → fail now.
             const dead = /closed|disconnected|crash|Target page, context or browser/i.test(msg);
             if (dead && attempt === 0) {
                 browserPromise = null;
@@ -115,6 +131,73 @@ export async function captureWithPlaywright(url, opts = {}) {
     }
     return { ok: false, error: "playwright capture failed after retry" };
 }
+/** Load a page in `ctx`, wait for it to settle, return the page handle. */
+async function openSettledPage(ctx, url) {
+    const page = await ctx.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 30_000 });
+    await page.waitForTimeout(1200); // let webfonts/lazy images settle
+    return page;
+}
+/** Screenshot a URL with Playwright (one image — full page or viewport). Never throws. */
+export async function captureWithPlaywright(url, opts = {}) {
+    const out = outputOpts();
+    const width = opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280;
+    const r = await withContext(width, out.scale, async (ctx) => {
+        const page = await openSettledPage(ctx, url);
+        return Buffer.from(await page.screenshot({
+            fullPage: opts.fullPage !== false,
+            type: out.type,
+            ...(out.type === "jpeg" ? { quality: out.quality } : {}),
+        }));
+    });
+    if (!r.ok)
+        return r;
+    return { ok: true, data: r.value, mimeType: out.type === "png" ? "image/png" : "image/jpeg" };
+}
+/**
+ * Capture a tall page as a STACK of horizontal bands (top→bottom) via Playwright
+ * `clip` — so the model sees each slice at a readable aspect ratio instead of one
+ * giant image squished (and blurred) to the vision input's long-edge cap. No image
+ * library needed: each band is its own screenshot. Bands are capped at `maxTiles`
+ * (truncated:true when the page is taller than that).
+ */
+export async function captureTilesWithPlaywright(url, opts = {}) {
+    const out = outputOpts();
+    const width = opts.width && Number.isFinite(opts.width) ? Math.round(opts.width) : 1280;
+    const bandH = opts.bandHeight && opts.bandHeight >= 200 ? Math.round(opts.bandHeight) : resolveBandHeight();
+    const maxTiles = opts.maxTiles && opts.maxTiles > 0 ? Math.round(opts.maxTiles) : 8;
+    const r = await withContext(width, out.scale, async (ctx) => {
+        const page = await openSettledPage(ctx, url);
+        // String form so tsc doesn't type-check `document` against the Node libs.
+        const pageHeight = Math.ceil(Number(await page.evaluate("Math.max(document.documentElement.scrollHeight, document.body.scrollHeight)")) || 0);
+        const total = Math.max(1, Math.ceil(pageHeight / bandH));
+        const n = Math.min(total, maxTiles);
+        // `clip` is measured against the VIEWPORT, so grow the viewport to cover the
+        // bands we'll capture before clipping (Chromium caps a single shot at ~16384px).
+        const captureHeight = Math.min(pageHeight, n * bandH, 16000);
+        await page.setViewportSize({ width, height: Math.max(captureHeight, 1) });
+        await page.waitForTimeout(300); // reflow after the resize
+        const tiles = [];
+        for (let i = 0; i < n; i++) {
+            const y = i * bandH;
+            let h = Math.min(bandH, pageHeight - y);
+            if (y + h > captureHeight)
+                h = captureHeight - y; // never clip past the viewport
+            if (h <= 0)
+                break;
+            const shot = await page.screenshot({
+                clip: { x: 0, y, width, height: h },
+                type: out.type,
+                ...(out.type === "jpeg" ? { quality: out.quality } : {}),
+            });
+            tiles.push({ y, height: h, data: Buffer.from(shot) });
+        }
+        return { pageHeight, width, tiles, truncated: total > maxTiles };
+    });
+    if (!r.ok)
+        return r;
+    return { ok: true, mimeType: out.type === "png" ? "image/png" : "image/jpeg", ...r.value };
+}
 // ---------------------------------------------------------------------------
 // SSRF guard — this route fetches an arbitrary `url`, so block private/loopback
 // targets (someone could otherwise screenshot internal services). Pure + exported

package/dist/tools/media.js

@@ -26,9 +26,9 @@ import { z } from "zod";
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { text, image } from "../mcp/response.js";
+import { text, image, images } from "../mcp/response.js";
 import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
-import { captureScreenshot, resolveScreenshotProxyBase, screenshotProxyBaseFromHeaders, resolveMicrolinkKey, microlinkKeyFromHeaders, } from "../persistence/screenshot-client.js";
+import { captureScreenshot, captureScreenshotTiles, resolveScreenshotProxyBase, screenshotProxyBaseFromHeaders, resolveMicrolinkKey, microlinkKeyFromHeaders, } from "../persistence/screenshot-client.js";
 import { uploadImageMultipart } from "../persistence/webcake-client.js";
 import { resolveIconSvg } from "../persistence/icon-client.js";
 import { configFromHeaders, ENVIRONMENTS, stripTrailingSlash } from "../persistence/config.js";
@@ -269,12 +269,13 @@ export function registerMediaTools(server, allowLocalFiles = true) {
         });
     });
     // 13c) Render a page/URL to a screenshot the model can SEE --------------------
-    server.tool("render_preview", "Renders a PUBLIC URL to a PNG and returns it as an image so the model can SEE the result and compare it visually to the reference — the fidelity-check step of the clone loop (build → see → patch_page → re-check). Pass `page_id` to shoot a created page's preview (/preview/<id>) or `url` for any public page (e.g. the reference you're cloning). full_page defaults to true (whole scrollable page). AGENT-FIRST: if YOU already have a screenshot/browser capability (a shell + headless browser, or a screenshot tool), screenshot the preview URL YOURSELF instead — it's fresh and unlimited; use this tool only when you cannot. ENGINE: zero-config via Microlink's free tier (rate-limited ~50/day PER IP, so heavy looping can hit HTTP 429 — then this returns ok:false and you should SKIP the visual check that round, not fail); a host can set RENDER_SCREENSHOT_BASE (or the x-render-screenshot-base header) to a keyed proxy, or MICROLINK_API_KEY / x-microlink-key for a higher quota. NOTE: a no-domain preview only renders for ~10 minutes after the last publish — call this promptly after create_page/publish_page, and re-publish before re-checking a stale page.", {
+    server.tool("render_preview", "Renders a PUBLIC URL to a PNG and returns it as an image so the model can SEE the result and compare it visually to the reference — the fidelity-check step of the clone loop (build → see → patch_page → re-check). Pass `page_id` to shoot a created page's preview (/preview/<id>) or `url` for any public page (e.g. the reference you're cloning). full_page defaults to true (whole scrollable page). AGENT-FIRST: if YOU already have a screenshot/browser capability (a shell + headless browser, or a screenshot tool), screenshot the preview URL YOURSELF instead — it's fresh and unlimited; use this tool only when you cannot. ENGINE: zero-config via Microlink's free tier (rate-limited ~50/day PER IP, so heavy looping can hit HTTP 429 — then this returns ok:false and you should SKIP the visual check that round, not fail); a host can set RENDER_SCREENSHOT_BASE (or the x-render-screenshot-base header) to a keyed proxy, or MICROLINK_API_KEY / x-microlink-key for a higher quota. NOTE: a no-domain preview only renders for ~10 minutes after the last publish — call this promptly after create_page/publish_page, and re-publish before re-checking a stale page. TALL PAGES: pass tiles:true to get the page as a STACK of top→bottom band images (each readable at full detail) instead of one full-page image squished small — needs a self-hosted Playwright host (RENDER_SCREENSHOT_BASE); falls back to a single image otherwise.", {
         page_id: z.string().optional().describe("A created page's id — screenshots its /preview/<id> URL (built from the preview base). Provide page_id OR url."),
         url: z.string().optional().describe("Any public http(s) URL to screenshot (e.g. the reference page being cloned). Wins over page_id."),
         full_page: z.boolean().optional().describe("Capture the whole scrollable page (default true) vs just the viewport."),
         width: z.number().int().min(320).max(2560).optional().describe("Viewport width in px (default 1280; use ~960/1200 to match the page canvas, ~420 for mobile)."),
-    }, { title: "Render Preview Screenshot", readOnlyHint: true, openWorldHint: true }, async ({ page_id, url, full_page, width }, extra) => {
+        tiles: z.boolean().optional().describe("Tall pages: return the page as MULTIPLE top→bottom band images (each readable in detail) instead of one squished full-page image. Requires a Playwright host (RENDER_SCREENSHOT_BASE); without one it falls back to a single image."),
+    }, { title: "Render Preview Screenshot", readOnlyHint: true, openWorldHint: true }, async ({ page_id, url, full_page, width, tiles }, extra) => {
         const headers = extra?.requestInfo?.headers;
         let target = url?.trim();
         if (!target && page_id) {
@@ -287,6 +288,26 @@ export function registerMediaTools(server, allowLocalFiles = true) {
             proxyBase: resolveScreenshotProxyBase(screenshotProxyBaseFromHeaders(headers)),
             microlinkKey: resolveMicrolinkKey(microlinkKeyFromHeaders(headers)),
         };
+        // Tiles mode (tall pages): a stack of readable top→bottom bands. Needs a
+        // Playwright host; if none is configured, fall through to a single image.
+        if (tiles === true) {
+            const t = await captureScreenshotTiles(target, { width }, resolved, Date.now());
+            if (t.ok && t.tiles && t.tiles.length) {
+                return images(t.tiles.map((b) => ({ dataBase64: b.dataBase64, mimeType: t.mimeType })), `Rendered ${target} as ${t.tiles.length} band(s) top→bottom (page ${t.pageHeight}px @ ${t.width}px wide${t.truncated ? ", TRUNCATED — page taller than the band cap" : ""}). Read the bands in order as one page. Compare each to the reference: section order, colors, spacing, image placement, text. For each mismatch, patch_page the element by id, re-publish, then re-check.`);
+            }
+            if (!t.not_supported) {
+                // A real failure (quota/network) — report it; don't silently single-shot.
+                return text({
+                    ok: false,
+                    url: target,
+                    status: t.status,
+                    quota_exhausted: t.quota_exhausted ?? false,
+                    error: t.error,
+                    hint: "Tiled screenshot failed. Retry without tiles for a single image, or skip the visual check this round.",
+                });
+            }
+            // not_supported → fall through to a single full-page image below.
+        }
         const r = await captureScreenshot(target, { fullPage: full_page !== false, width }, resolved, Date.now());
         if (!r.ok) {
             return text({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.80",
+  "version": "1.0.82",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "mcpName": "io.github.vuluu2k/webcake-landing-mcp",
   "type": "module",