webcake-landing-mcp 1.0.66 → 1.0.67

package/README.md

@@ -187,7 +187,7 @@ server, the `login` browser flow (+ backend contract), and how to grab a JWT by
 |-------|-------|-------|
 | **Reference** | `get_generation_guide` · `list_elements` · `get_element` · `get_page_schema` | nothing |
 | **Generation** | `new_element` · `new_page_skeleton` · `validate_page` | nothing |
-| **Media** | `search_images` (real Pexels stock photos) · `upload_images` (re-host external images) | nothing |
+| **Media** | `search_images` (real Pexels stock photos) · `upload_images` (re-host external images, data: URIs, or local file paths from the user's machine) | nothing |
 | **Ingest** | `ingest_html` · `ingest_url` (recreate an existing page) | nothing |
 | **Persistence** | `list_organizations` · `create_page` · `list_pages` · `find_pages` · `get_page` · `update_page` · `add_section` · `patch_page` · `publish_page` | `WEBCAKE_API_BASE` + `WEBCAKE_JWT` |
 

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.0.67",
+    "d": "12/06/2026",
+    "type": "Added",
+    "en": "upload_images now accepts local file paths in the urls parameter — absolute POSIX paths (/…), home-directory paths (~/…), file:// URIs, and Windows…",
+    "vi": "upload_images nay chấp nhận đường dẫn file cục bộ trong tham số urls — đường dẫn POSIX tuyệt đối (/…), đường dẫn thư mục home (~/…), URI file://, và…"
+  },
   {
     "v": "1.0.66",
     "d": "12/06/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "validate_page now warns when a text-block's estimated rendered height overflows onto a sibling element placed directly below its declared box; the…",
     "vi": "validate_page nay cảnh báo khi chiều cao render ước tính của text-block tràn xuống phần tử anh em đặt ngay phía dưới khung khai báo; cảnh báo nêu…"
-  },
-  {
-    "v": "1.0.61",
-    "d": "11/06/2026",
-    "type": "Added",
-    "en": "ingest_html and ingest_url now return a size_hint field ({ height, basis, css? }) on every AST section, providing the desktop section height in px…",
-    "vi": "ingest_html và ingest_url nay trả về trường size_hint ({ height, basis, css? }) trên mỗi section trong AST, cung cấp chiều cao desktop của section…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -114,7 +114,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). borderRadius is a STRING with CSS units ("8px", "50%", "16px 16px 0 0") — a bare number or unit-less string is auto-coerced to px by the server, but write the unit explicitly to avoid surprises.
-- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). SOURCE PRIORITY: (1) images the user supplied or that exist in the reference HTML/URL (ingest AST images/background_images/og_image) → re-host them via upload_images and use those EXACT images in their slots — never swap them for stock photos; (2) only for slots with NO source image → 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); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). NEVER leave src empty — it renders blank on the live page. The server automatically derives styles.background from specials.src on every expand (create/update/validate) using the editor's exact format: 'center center/ cover no-repeat scroll content-box url(<src>) border-box' — you do NOT need to set styles.background manually; if you do hand-write it, it must contain url(...). A SECTION background may layer a gradient overlay over an image: 'linear-gradient(...), center center/ cover no-repeat scroll content-box url(<src>) border-box' — the server canonicalises any url() layer into that exact editor shorthand on expand (other url() formats survive the first save but get mangled to 'undefined/ undefined/ …' the moment the page is edited in the Webcake editor). 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). Do NOT set a flat (no url()) styles.background on a video element — it suppresses the poster image.
+- IMAGES: a real landing page has images (hero/product shot, feature icons, about photo). SOURCE PRIORITY: (1) images the user supplied — including local file paths from their computer (pass the path directly in upload_images 'urls'; NEVER upload a user's local file to a third-party host like catbox or imgur to obtain a URL first) — or that exist in the reference HTML/URL (ingest AST images/background_images/og_image) → re-host them via upload_images and use those EXACT images in their slots — never swap them for stock photos; (2) only for slots with NO source image → 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); (3) if search_images returns ok:false, is unreachable, or has NO photo that fits the slot → find a real image YOURSELF using whatever web search/fetch capability you have (the brand's own site, the product page, a free-to-use source), then re-host it via upload_images and use the returned URL; (4) a PLACEHOLDER is the LAST resort, ONLY after (2) AND (3) both failed — sized to the box: "https://placehold.co/<width>x<height>". Never jump straight from a failed search to a placeholder without trying (3). NEVER leave src empty — it renders blank on the live page. The server automatically derives styles.background from specials.src on every expand (create/update/validate) using the editor's exact format: 'center center/ cover no-repeat scroll content-box url(<src>) border-box' — you do NOT need to set styles.background manually; if you do hand-write it, it must contain url(...). A SECTION background may layer a gradient overlay over an image: 'linear-gradient(...), center center/ cover no-repeat scroll content-box url(<src>) border-box' — the server canonicalises any url() layer into that exact editor shorthand on expand (other url() formats survive the first save but get mangled to 'undefined/ undefined/ …' the moment the page is edited in the Webcake editor). 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). Do NOT set a flat (no url()) styles.background on a video element — it suppresses the poster image.
 - CONTRAST (check EVERY text element against the band it sits on, especially SATURATED / mid-tone bands like yellow, orange, teal, pink — there "light vs dark text" is not obvious, so decide by the band's luminance): light bands → near-black text (e.g. rgba(20,30,25,1)); dark bands → near-white text; a saturated/mid-tone band → whichever of near-black or near-white actually reads (for a bright yellow/amber band that means DARK text, not white/grey). NEVER use muted-grey, low-alpha (alpha < ~0.85), or near-white text on a colored band — that is exactly what makes labels look faded/sunken. Muted-grey is ONLY for secondary text on a white/very-light band. Icons and their captions follow the SAME rule as the text beside them.
 - movable:false for section/slide/grid-item/popup; otherwise true. runtime is always {}.
 - Every form input MUST have a unique specials.field_name.
@@ -146,7 +146,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): if the slot has a source image (user-supplied or from the reference HTML/URL), upload_images it and use the returned Webcake URL; otherwise call search_images and put a returned URL into specials.src / gallery item.link. If search_images fails or has no fitting photo, find a real image yourself (web search/fetch → upload_images). Use placehold.co ONLY as the last resort when both search_images AND your own search failed.
+3b. For every image the page needs (hero, product, about, feature, gallery): if the slot has a source image (user-supplied — including local file paths from their computer, pass the path directly in upload_images 'urls'; NEVER relay the user's local file through a third-party host like catbox or imgur — or from the reference HTML/URL), upload_images it and use the returned Webcake URL; otherwise call search_images and put a returned URL into specials.src / gallery item.link. If search_images fails or has no fitting photo, find a real image yourself (web search/fetch → upload_images). Use placehold.co ONLY as the last resort when both search_images AND your own search failed.
 4. Assemble { page, popup, settings, options, cartConfigs }.
 5. Call validate_page and fix every error AND every warning — warnings are visible defects (text spilling onto the element below, off-canvas boxes, empty bands at a section's bottom, missing field_name, dead event targets), not advisory polish. Re-validate until the warning list is empty; only a demonstrably false positive may remain (tell the user which and why).
 6. To save: call list_organizations. If the account has EXACTLY ONE organization, create_page will auto-select it — no need to ask. If there are MULTIPLE organizations, show them to the user and ask which to use (highlight is_default as the suggested default); pass the chosen organization_id to create_page. If the user explicitly wants to save without any organization, pass organization_id:"personal". Then create_page (dry_run first, then dry_run:false). Note: create_page itself enforces this — it refuses to guess between multiple orgs and returns the org list asking you to pick.

package/dist/domains/landing/instructions.js

@@ -37,7 +37,7 @@ MODEL (essentials):
 - PREMIUM CRAFT (read "sang"): generous whitespace (don't cram; ~48–72px above each band's first element, ≥16–24px between elements); clear type scale (H1 40–56 / body 16–18, big jump); ONE accent used sparingly + neutrals; snap spacing to an 8px grid; reuse the same content width / margin / card+button radius across sections.
 - 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). SOURCE PRIORITY: (1) images the user provided or that exist in the reference HTML/URL → re-host via upload_images and use those exact images; (2) only for slots with NO source image → 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); (3) if search_images returns ok:false / is unreachable / has no fitting photo → find a real image YOURSELF using whatever web search/fetch capability you have (brand site, product page, free-to-use source) and re-host it via upload_images; (4) a PLACEHOLDER sized to the box (https://placehold.co/<width>x<height>) is the LAST resort, only after (2) AND (3) both failed. (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). SOURCE PRIORITY: (1) images the user supplied (including local file paths from their computer — pass the path directly in upload_images urls; NEVER upload a user's local file to a third-party host like catbox or imgur first) or that exist in the reference HTML/URL → re-host via upload_images and use those exact images; (2) only for slots with NO source image → 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); (3) if search_images returns ok:false / is unreachable / has no fitting photo → find a real image YOURSELF using whatever web search/fetch capability you have (brand site, product page, free-to-use source) and re-host it via upload_images; (4) a PLACEHOLDER sized to the box (https://placehold.co/<width>x<height>) is the LAST resort, only after (2) AND (3) both failed. (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.
 
 - PREVIEW vs PUBLISH: for review share the EDITOR url (the builder renders the raw source). The editor_url SIGNS THE BROWSER IN automatically (it routes through the builder's /transport with the account token), so it works even when the user isn't logged in — but for the same reason it must go to the PAGE OWNER ONLY, never into anything public. create_page AUTO-PUBLISHES on success (builds the rendered app + publish_html), so a fresh page's preview_url renders right away — but the preview host (preview.localhost:5800 local / staging.webcake.me staging / www.webcake.me prod) only serves it for ~10 MINUTES after the last publish, then shows "Preview page is expired". The EDIT routes (update_page/add_section/patch_page) store source only — after finishing a round of edits, run publish_page({ page_id, dry_run:false }) to rebuild the rendered app (else the preview shows the STALE pre-edit build). ONLY a custom_domain (publish_page({ page_id, custom_domain, dry_run:false })) gives a permanent public URL; without one the page has just the ephemeral preview link — say so and suggest attaching a domain the user already points at Webcake.
 

package/dist/http.js

@@ -203,7 +203,7 @@ export async function startHttpServer(port) {
                         if (transport.sessionId)
                             transports.delete(transport.sessionId);
                     };
-                    const server = createServer();
+                    const server = createServer({ allowLocalFiles: false });
                     await server.connect(transport);
                     await transport.handleRequest(req, res, body);
                     return;

package/dist/persistence/webcake-client.js

@@ -609,6 +609,60 @@ export async function uploadImageBase64(base, b64, ext, contentType) {
     }
     return { ok: true, url: hostedUrl, status: res.status };
 }
+/** Timeout used for multipart uploads — generous to accommodate large files. */
+const UPLOAD_MULTIPART_TIMEOUT_MS = 120_000;
+/**
+ * Upload an image to the Webcake backend via multipart/form-data.
+ * The /external/upload_file endpoint is public — no JWT required.
+ * The backend derives `ext` from the last dot segment of `filename` and uses
+ * `file.content_type` from the part headers — so `filename` must carry the
+ * correct extension and `contentType` must be set explicitly.
+ * Supports up to 200 MB (the backend's multipart Plug.Parsers limit).
+ * Returns `{ ok: true, url }` on success or `{ ok: false, error }` on failure.
+ */
+export async function uploadImageMultipart(base, bytes, filename, contentType) {
+    const url = `${base.replace(/\/+$/, "")}${UPLOAD_FILE_ENDPOINT}`;
+    const form = new FormData();
+    // Attach the blob with an explicit content type so the backend picks it up
+    // from file.content_type, and a filename so it can derive the extension.
+    form.append("file", new Blob([bytes], { type: contentType }), filename);
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            // Do NOT set Content-Type manually — fetch sets it with the correct
+            // multipart boundary when the body is a FormData instance.
+            headers: { Accept: "application/json" },
+            body: form,
+            signal: timeoutSignal(UPLOAD_MULTIPART_TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        const e2 = timeoutOrNetworkError(url, e);
+        return { ok: false, status: e2.status, error: e2.error };
+    }
+    const rawText = await res.text();
+    let json = null;
+    try {
+        json = JSON.parse(rawText);
+    }
+    catch {
+        /* non-JSON */
+    }
+    if (!res.ok || json?.success === false) {
+        const reason = json?.reason ?? json?.message ?? (json ? undefined : rawText.slice(0, 200));
+        return {
+            ok: false,
+            status: res.status,
+            error: `Backend returned ${res.status}${reason ? `: ${reason}` : ""}`,
+        };
+    }
+    const hostedUrl = typeof json?.data === "string" ? json.data : undefined;
+    if (!hostedUrl) {
+        return { ok: false, status: res.status, error: "Backend returned success but no URL in data field" };
+    }
+    return { ok: true, url: hostedUrl, status: res.status };
+}
 /**
  * POST to a host-scoped route. Node's fetch cannot reach `*.localhost` hosts
  * (browsers special-case .localhost; Node's DNS does not, and undici forbids a

package/dist/server.js

@@ -10,7 +10,13 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { landingDomain } from "./domains/landing/index.js";
 import { registerTools } from "./tools/index.js";
 import { ICON_DATA_URI, ICON_MIME, BRAND } from "./branding.js";
-export function createServer() {
+/**
+ * Create the MCP server.
+ * @param allowLocalFiles Set to false in remote HTTP (serve) mode to prevent
+ *   upload_images from reading arbitrary files off the host filesystem.
+ *   Defaults to true (stdio / single-user mode on the user's own machine).
+ */
+export function createServer({ allowLocalFiles = true } = {}) {
     const server = new McpServer({
         name: "webcake-landing",
         version: "1.0.0",
@@ -20,6 +26,6 @@ export function createServer() {
         websiteUrl: BRAND.websiteUrl,
         icons: [{ src: ICON_DATA_URI, mimeType: ICON_MIME, sizes: ["any"] }],
     }, { instructions: landingDomain.instructions });
-    registerTools(server, landingDomain);
+    registerTools(server, landingDomain, { allowLocalFiles });
     return server;
 }

package/dist/smoke.js

@@ -14,6 +14,7 @@ import { toEditorUrl, toEditorLoginUrl, toPreviewUrl, buildPublishRequestRedacte
 import { normalizePhoto, resolvePexelsKey, pexelsKeyFromHeaders, resolvePexelsProxyBase, buildSearchQuery, PEXELS_PROXY_DEFAULT } from "./persistence/pexels-client.js";
 import { putDraft, getDraft, updateDraft, deleteDraft } from "./persistence/draft-cache.js";
 import { buildConnectUrl, parseCallback } from "./auth/login.js";
+import { isLocalPath, resolveLocalPath, sniffMime, localContentType } from "./tools/media.js";
 let failures = 0;
 const check = (name, cond, extra) => {
     if (cond) {
@@ -1174,5 +1175,67 @@ console.log("== validator: pill/badge label alignment ==");
     const rWide = validatePage(expandSource(badge(108, 330, 300, { fontSize: 16, fontWeight: 700 }, { width: 220, left: 370 }), createElement));
     check("pill: label wider than pill → spill warning", rWide.warnings.some((w) => w.includes("spills past")), rWide.warnings);
 }
+console.log("== upload_images: local-path detector (pure, offline) ==");
+{
+    // isLocalPath: recognised forms
+    check("localPath: absolute POSIX /…", isLocalPath("/home/user/photo.jpg"));
+    check("localPath: home-dir ~/…", isLocalPath("~/Pictures/logo.png"));
+    check("localPath: file:// URI", isLocalPath("file:///tmp/img.png"));
+    check("localPath: Windows drive C:\\…", isLocalPath("C:\\Users\\user\\img.jpg"));
+    check("localPath: Windows drive C:/…", isLocalPath("C:/Users/user/img.jpg"));
+    // isLocalPath: things that must NOT match
+    check("localPath: http URL → false", !isLocalPath("https://example.com/img.jpg"));
+    check("localPath: data URI → false", !isLocalPath("data:image/png;base64,abc"));
+    check("localPath: relative path → false", !isLocalPath("images/photo.jpg"));
+    // resolveLocalPath
+    const home = (await import("node:os")).homedir();
+    check("resolveLocalPath: ~/… expands homedir", resolveLocalPath("~/foo/bar.jpg") === home + "/foo/bar.jpg");
+    check("resolveLocalPath: /abs passes through", resolveLocalPath("/abs/path.jpg") === "/abs/path.jpg");
+    // file:// resolution is handled by fileURLToPath; test the passthrough for absolute paths
+    check("resolveLocalPath: Windows C:\\ passes through", resolveLocalPath("C:\\Users\\x.jpg") === "C:\\Users\\x.jpg");
+}
+console.log("== upload_images: magic-byte sniffer (pure, offline) ==");
+{
+    // JPEG: FF D8 FF
+    const jpegBuf = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]);
+    check("sniff: JPEG magic → image/jpeg", sniffMime(jpegBuf) === "image/jpeg");
+    // PNG: 89 50 4E 47
+    const pngBuf = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d]);
+    check("sniff: PNG magic → image/png", sniffMime(pngBuf) === "image/png");
+    // GIF: 47 49 46 38
+    const gifBuf = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39]);
+    check("sniff: GIF magic → image/gif", sniffMime(gifBuf) === "image/gif");
+    // BMP: 42 4D
+    const bmpBuf = Buffer.from([0x42, 0x4d, 0x00, 0x00, 0x00]);
+    check("sniff: BMP magic → image/bmp", sniffMime(bmpBuf) === "image/bmp");
+    // WEBP: RIFF????WEBP
+    const webpBuf = Buffer.from([
+        0x52, 0x49, 0x46, 0x46, // RIFF
+        0x00, 0x00, 0x00, 0x00, // file size (ignored)
+        0x57, 0x45, 0x42, 0x50, // WEBP
+    ]);
+    check("sniff: WEBP magic → image/webp", sniffMime(webpBuf) === "image/webp");
+    // unknown bytes
+    const unknownBuf = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+    check("sniff: unknown bytes → undefined", sniffMime(unknownBuf) === undefined);
+    // too-short buffer
+    check("sniff: 2-byte buffer → undefined", sniffMime(Buffer.from([0xff, 0xd8])) === undefined);
+}
+console.log("== upload_images: localContentType (ext + magic, pure offline) ==");
+{
+    const jpegBuf = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]);
+    const pngBuf = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d]);
+    const unknownBuf = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+    // magic wins over extension when they agree
+    check("localContentType: .jpg + JPEG magic → image/jpeg", localContentType("jpg", jpegBuf) === "image/jpeg");
+    check("localContentType: .png + PNG magic → image/png", localContentType("png", pngBuf) === "image/png");
+    // magic wins over (wrong) extension
+    check("localContentType: .png ext but JPEG magic → image/jpeg (magic wins)", localContentType("png", jpegBuf) === "image/jpeg");
+    // extension fallback when magic is unknown
+    check("localContentType: unknown magic + .png ext → image/png (ext fallback)", localContentType("png", unknownBuf) === "image/png");
+    check("localContentType: unknown magic + .svg ext → image/svg+xml (ext fallback)", localContentType("svg", unknownBuf) === "image/svg+xml");
+    // both unknown → undefined
+    check("localContentType: unknown magic + unknown ext → undefined", localContentType("xyz", unknownBuf) === undefined);
+}
 console.log(`\n${failures === 0 ? "ALL GOOD" : failures + " FAILURE(S)"}`);
 process.exit(failures === 0 ? 0 : 1);

package/dist/tools/index.js

@@ -3,10 +3,10 @@ import { registerGenerationTools } from "./generation.js";
 import { registerMediaTools } from "./media.js";
 import { registerIngestTools } from "./ingest.js";
 import { registerPersistenceTools } from "./persistence.js";
-export function registerTools(server, domain) {
+export function registerTools(server, domain, { allowLocalFiles = true } = {}) {
     registerReferenceTools(server, domain);
     registerGenerationTools(server, domain);
-    registerMediaTools(server);
+    registerMediaTools(server, allowLocalFiles);
     registerIngestTools(server);
     registerPersistenceTools(server, domain);
 }

package/dist/tools/media.js

@@ -2,8 +2,15 @@
  * 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`).
- * `upload_images` converts external image URLs (or data: URIs) into Webcake-hosted
- * URLs (statics.pancake.vn) so generated pages don't hotlink third-party hosts.
+ * `upload_images` converts external image URLs (or data: URIs) OR LOCAL FILE PATHS
+ * (absolute POSIX, ~/…, file://, Windows drive paths) into Webcake-hosted URLs
+ * (statics.pancake.vn) so generated pages don't hotlink third-party hosts and the
+ * AI never needs to proxy the user's files through a third-party service.
+ * Uses multipart/form-data upload (200 MB backend limit).
+ *
+ * LOCAL FILE PATHS are only allowed on the stdio transport (server running on the
+ * user's own machine). On the remote HTTP transport (serve mode, multi-user) every
+ * local-path entry is rejected per-entry to prevent arbitrary-file-read attacks.
  *
  * 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
@@ -16,9 +23,12 @@
  * public). Defaults to dry_run=true.
  */
 import { z } from "zod";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { text } from "../mcp/response.js";
 import { searchPexels, searchImagesViaProxy, resolvePexelsKey, resolvePexelsProxyBase, pexelsKeyFromHeaders, } from "../persistence/pexels-client.js";
-import { uploadImageBase64 } from "../persistence/webcake-client.js";
+import { uploadImageMultipart } from "../persistence/webcake-client.js";
 import { configFromHeaders, ENVIRONMENTS, stripTrailingSlash } from "../persistence/config.js";
 /** Resolve just the API base (no JWT required) from per-request headers → env → WEBCAKE_ENV preset → prod default. */
 function resolveApiBase(headers) {
@@ -36,8 +46,8 @@ function resolveApiBase(headers) {
     // Default to prod.
     return ENVIRONMENTS.prod.apiBase;
 }
-const UPLOAD_TIMEOUT_MS = 20_000;
-const UPLOAD_MAX_BYTES = 8 * 1024 * 1024; // 8 MB
+const UPLOAD_FETCH_TIMEOUT_MS = 60_000; // 60 s — large bodies can be slow to transfer
+const UPLOAD_MAX_BYTES = 200_000_000; // 200 MB — mirrors the backend multipart Plug.Parsers limit
 /** Map a content_type to its canonical file extension. */
 function extFromContentType(ct) {
     const sub = ct.split(";")[0].trim().toLowerCase();
@@ -67,7 +77,89 @@ function extFromUrl(url) {
     }
     return "jpg";
 }
-export function registerMediaTools(server) {
+// ---------------------------------------------------------------------------
+// Local-path helpers (exported for smoke-test coverage)
+// ---------------------------------------------------------------------------
+/** Windows drive-letter path pattern, e.g. C:\…  or  C:/… */
+const WIN_DRIVE_RE = /^[A-Za-z]:[\\/]/;
+/**
+ * Return true when `entry` looks like a local file path (not a URL / data URI).
+ * Recognised forms: file://, absolute POSIX (/…), home-dir (~/…), Windows drive (C:\…).
+ * Exported so the smoke test can assert the pure logic without a transport.
+ */
+export function isLocalPath(entry) {
+    return (entry.startsWith("file://") ||
+        entry.startsWith("/") ||
+        entry.startsWith("~/") ||
+        WIN_DRIVE_RE.test(entry));
+}
+/**
+ * Resolve a local-path entry to an absolute POSIX path.
+ * - file://… → fileURLToPath
+ * - ~/…      → expand homedir
+ * - /…       → unchanged
+ * - C:\…     → unchanged (Windows absolute)
+ */
+export function resolveLocalPath(entry) {
+    if (entry.startsWith("file://"))
+        return fileURLToPath(entry);
+    if (entry.startsWith("~/"))
+        return homedir() + entry.slice(1);
+    return entry;
+}
+/** Map a file extension (lowercased, no dot) to its MIME type. */
+const EXT_TO_MIME = {
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    png: "image/png",
+    webp: "image/webp",
+    gif: "image/gif",
+    avif: "image/avif",
+    svg: "image/svg+xml",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+};
+/**
+ * Sniff the MIME type of a Buffer from its magic bytes.
+ * Returns undefined when the signature isn't recognised.
+ * Exported for smoke-test coverage.
+ */
+export function sniffMime(buf) {
+    if (buf.length < 4)
+        return undefined;
+    // JPEG: FF D8 FF
+    if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return "image/jpeg";
+    // PNG: 89 50 4E 47
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47)
+        return "image/png";
+    // GIF: 47 49 46 38 (GIF87a / GIF89a)
+    if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38)
+        return "image/gif";
+    // BMP: 42 4D
+    if (buf[0] === 0x42 && buf[1] === 0x4d)
+        return "image/bmp";
+    // WEBP: RIFF????WEBP  (bytes 0-3 = RIFF, bytes 8-11 = WEBP)
+    if (buf.length >= 12 &&
+        buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46 &&
+        buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50) {
+        return "image/webp";
+    }
+    return undefined;
+}
+/**
+ * Derive the content-type for a local file: sniff magic bytes first, then fall
+ * back to the extension. Returns undefined when both fail (unrecognised format).
+ * Exported for smoke-test coverage.
+ */
+export function localContentType(ext, buf) {
+    const sniffed = sniffMime(buf);
+    const fromExt = EXT_TO_MIME[ext.toLowerCase()];
+    // Prefer sniffed (more reliable); fall back to extension when sniff fails.
+    return sniffed ?? fromExt;
+}
+export function registerMediaTools(server, allowLocalFiles = true) {
     // 13) Search images ---------------------------------------------------------
     server.tool("search_images", "Searches Pexels stock photos (see https://www.pexels.com/api/) by short English subject queries. Returns hotlinkable URLs at several sizes (src.large for heroes/banners, src.medium for cards/thumbs), `avg_color` for matching section backgrounds, plus photographer name and attribution URL. BATCH MODE: pass `queries: [...]` to fetch multiple subjects in PARALLEL — e.g. ['fresh coffee cup','barista pouring','interior cafe'] for hero + about + gallery — returns { queries: { [q]: result } } so the caller picks one image per slot in a single round-trip; default `pick='best'` returns only the top photo per query (compact, drop-in for specials.src), `pick='all'` returns the full list. `query` (single) returns the full result like before. Works out of the box via a shared hosted proxy; set PEXELS_API_KEY env or x-pexels-key header to use your own quota. ONLY for image slots with NO source image: when the user supplied images or the reference HTML/URL contains image URLs (ingest AST images/background_images/og_image), re-host THOSE via upload_images instead of searching stock photos.", {
         query: z.string().optional().describe("Single subject query — backward-compat. Prefer `queries` when the page needs 2+ images."),
@@ -130,97 +222,160 @@ export function registerMediaTools(server) {
         return text({ queries: out });
     });
     // 14) Upload images to Webcake -----------------------------------------------
-    server.tool("upload_images", "Converts external image URLs (typically collected from ingest_html/ingest_url results) or data: URIs into Webcake-hosted URLs (statics.pancake.vn) by downloading each image and re-uploading it to the Webcake backend. Use this whenever the page is built from a reference HTML/URL (BOTH intents — adapt AND clone) or the user supplies their own image URLs: reference images are the user's assets, so re-host and reuse them rather than replacing them with stock photos, and never hotlink third-party hosts that may block hotlinking or disappear. The returned URLs go directly into specials.src — same as search_images results. Processes up to 20 URLs per call in parallel, with an 8 MB per-image cap. No Webcake credentials required (the upload endpoint is public). DEFAULTS to dry_run=true (returns a preview of what would be uploaded, no network calls); set dry_run=false to actually upload. Use search_images instead when you need stock photos.", {
+    server.tool("upload_images", "Converts external image URLs (typically collected from ingest_html/ingest_url results), data: URIs, or LOCAL FILE PATHS from the user's computer into Webcake-hosted URLs (statics.pancake.vn) by reading/downloading each image and re-uploading it to the Webcake backend via multipart upload (200 MB backend limit). Use this whenever the page is built from a reference HTML/URL (BOTH intents — adapt AND clone), the user supplies their own image URLs, OR the user provides local image files from their machine — pass the path directly in `urls`; NEVER upload a user's local file to a third-party host (catbox, imgur, transfer.sh…) to obtain a URL first. The returned URLs go directly into specials.src — same as search_images results. Processes up to 20 entries per call in parallel, with a 200 MB per-image cap. No Webcake credentials required (the upload endpoint is public). DEFAULTS to dry_run=true (returns a preview of what would be processed, no network calls); set dry_run=false to actually upload. Use search_images instead when you need stock photos. Local file paths are only permitted when the MCP server runs locally (stdio mode); on the remote HTTP transport they are rejected per-entry.", {
         urls: z
             .array(z.string())
             .min(1)
             .max(20)
-            .describe("External http(s) image URLs or data:image/...;base64,... URIs to upload. 1–20 per call."),
+            .describe("Image sources to upload — 1–20 per call. Accepted formats:\n" +
+            "• http(s) URLs (remote images to download and re-host)\n" +
+            "• data:image/...;base64,... URIs (inline image data)\n" +
+            "• Local file paths from the user's machine: absolute POSIX paths (/home/user/photo.jpg), home-dir paths (~/Pictures/logo.png), file:// URIs, or Windows drive paths (C:\\Users\\…). Local paths are only allowed when the server runs in stdio mode (the user's own machine); they are rejected on the remote HTTP transport.\n" +
+            "Up to 200 MB per image (the backend multipart limit)."),
         dry_run: z
             .boolean()
             .optional()
-            .describe("Default TRUE — return a preview of the endpoint and URLs that WOULD be processed, without any network activity. Set false to actually download and upload."),
+            .describe("Default TRUE — return a preview of the endpoint and entries that WOULD be processed, without any network or filesystem activity (local paths: reports whether the file exists and its size). Set false to actually read/download and upload."),
     }, { title: "Upload Images to Webcake", readOnlyHint: false, openWorldHint: true }, async ({ urls, dry_run }, extra) => {
         const isDry = dry_run !== false;
         const base = resolveApiBase(extra?.requestInfo?.headers);
-        // Deduplicate input URLs.
+        // Stdio transport: extra.requestInfo is undefined (no HTTP request headers).
+        // HTTP transport: extra.requestInfo is always present.
+        // We derive allowLocalFiles from the parameter passed into registerMediaTools
+        // (true for stdio, false for the HTTP serve mode — see registerTools / http.ts).
+        const localAllowed = allowLocalFiles;
+        // Deduplicate input entries while preserving original strings as keys.
         const deduped = [...new Set(urls)];
         if (isDry) {
+            // For local paths: stat the file so the model catches typos before the real call.
+            const urlsInfo = await Promise.all(deduped.map(async (entry) => {
+                if (isLocalPath(entry)) {
+                    if (!localAllowed) {
+                        return { entry, local: true, allowed: false, error: "Local file paths are only supported when the MCP server runs locally (stdio). Send a public URL or data: URI instead." };
+                    }
+                    try {
+                        const resolved = resolveLocalPath(entry);
+                        const st = await fs.stat(resolved);
+                        return { entry, local: true, allowed: true, exists: true, size_bytes: st.size, exceeds_limit: st.size > UPLOAD_MAX_BYTES, limit_bytes: UPLOAD_MAX_BYTES };
+                    }
+                    catch {
+                        return { entry, local: true, allowed: true, exists: false };
+                    }
+                }
+                return { entry, local: false };
+            }));
             return text({
                 ok: true,
                 dry_run: true,
                 endpoint: `${base}/external/upload_file`,
-                urls_to_upload: deduped,
-                hint: "Re-call with dry_run:false to actually download and upload these images.",
+                urls_to_upload: urlsInfo,
+                hint: "Re-call with dry_run:false to actually read/download and upload these images.",
             });
         }
-        // Process each URL in parallel; per-URL failures don't fail the whole call.
-        const results = await Promise.all(deduped.map(async (originalUrl) => {
+        // Process each entry in parallel; per-entry failures don't fail the whole call.
+        const results = await Promise.all(deduped.map(async (originalEntry) => {
             try {
-                let b64;
+                let bytes;
                 let contentType;
-                if (originalUrl.startsWith("data:")) {
-                    // data:image/<subtype>;base64,<data>
-                    const match = originalUrl.match(/^data:(image\/[^;,]+);base64,(.+)$/s);
+                if (isLocalPath(originalEntry)) {
+                    // --- LOCAL FILE PATH ---
+                    if (!localAllowed) {
+                        return [originalEntry, { ok: false, error: "Local file paths are only supported when the MCP server runs locally (stdio). Send a public URL or data: URI instead." }];
+                    }
+                    const resolved = resolveLocalPath(originalEntry);
+                    // Stat first — size check before reading the whole file.
+                    let stat;
+                    try {
+                        stat = await fs.stat(resolved);
+                    }
+                    catch (e) {
+                        const msg = (e?.code === "ENOENT") ? `File not found: ${resolved}` : `Cannot read file: ${e?.message ?? e}`;
+                        return [originalEntry, { ok: false, error: msg }];
+                    }
+                    if (stat.size > UPLOAD_MAX_BYTES) {
+                        return [originalEntry, { ok: false, error: `Image exceeds the 200 MB backend limit (file size: ${stat.size} bytes)` }];
+                    }
+                    // Read file contents.
+                    let fileBuf;
+                    try {
+                        fileBuf = await fs.readFile(resolved);
+                    }
+                    catch (e) {
+                        return [originalEntry, { ok: false, error: `Cannot read file: ${e?.message ?? e}` }];
+                    }
+                    // Derive extension from path, sniff MIME from bytes.
+                    const dotIdx = resolved.lastIndexOf(".");
+                    const extRaw = dotIdx >= 0 ? resolved.slice(dotIdx + 1).replace(/[?#].*$/, "").toLowerCase() : "";
+                    const ct = localContentType(extRaw, fileBuf);
+                    if (!ct) {
+                        return [originalEntry, { ok: false, error: `Not a recognized image file: ${resolved}` }];
+                    }
+                    contentType = ct;
+                    bytes = fileBuf;
+                }
+                else if (originalEntry.startsWith("data:")) {
+                    // --- DATA URI ---
+                    const match = originalEntry.match(/^data:(image\/[^;,]+);base64,(.+)$/s);
                     if (!match) {
-                        return [originalUrl, { ok: false, error: "Malformed data: URI — expected data:image/<type>;base64,<data>" }];
+                        return [originalEntry, { ok: false, error: "Malformed data: URI — expected data:image/<type>;base64,<data>" }];
                     }
                     contentType = match[1].toLowerCase();
-                    b64 = match[2];
+                    bytes = Buffer.from(match[2], "base64");
                 }
                 else {
-                    // Fetch the remote image.
+                    // --- REMOTE HTTP(S) URL ---
                     let res;
                     try {
-                        res = await fetch(originalUrl, {
-                            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+                        res = await fetch(originalEntry, {
+                            signal: AbortSignal.timeout(UPLOAD_FETCH_TIMEOUT_MS),
                             headers: {
                                 "User-Agent": "Mozilla/5.0 (compatible; webcake-landing-mcp/1.0; +https://webcake.io)",
                             },
                         });
                     }
                     catch (e) {
-                        return [originalUrl, { ok: false, error: `Fetch failed: ${e?.message ?? e}` }];
+                        return [originalEntry, { ok: false, error: `Fetch failed: ${e?.message ?? e}` }];
                     }
                     if (!res.ok) {
-                        return [originalUrl, { ok: false, error: `Remote returned HTTP ${res.status}` }];
+                        return [originalEntry, { ok: false, error: `Remote returned HTTP ${res.status}` }];
                     }
                     // Reject oversized images early via Content-Length.
                     const cl = res.headers.get("content-length");
                     if (cl && parseInt(cl, 10) > UPLOAD_MAX_BYTES) {
-                        return [originalUrl, { ok: false, error: `Image exceeds 8 MB limit (Content-Length: ${cl})` }];
+                        return [originalEntry, { ok: false, error: `Image exceeds the 200 MB backend limit (Content-Length: ${cl})` }];
                     }
                     // Determine content-type; reject non-images (also catches html error pages).
                     const rawCt = res.headers.get("content-type") ?? "";
-                    contentType = rawCt.split(";")[0].trim().toLowerCase() || `image/${extFromUrl(originalUrl)}`;
+                    contentType = rawCt.split(";")[0].trim().toLowerCase() || `image/${extFromUrl(originalEntry)}`;
                     if (!contentType.startsWith("image/")) {
-                        return [originalUrl, { ok: false, error: `Not an image — content-type: ${contentType || "(empty)"}` }];
+                        return [originalEntry, { ok: false, error: `Not an image — content-type: ${contentType || "(empty)"}` }];
                     }
                     const buf = await res.arrayBuffer();
                     if (buf.byteLength > UPLOAD_MAX_BYTES) {
-                        return [originalUrl, { ok: false, error: `Image exceeds 8 MB limit (actual: ${buf.byteLength} bytes)` }];
+                        return [originalEntry, { ok: false, error: `Image exceeds the 200 MB backend limit (actual: ${buf.byteLength} bytes)` }];
                     }
-                    b64 = Buffer.from(buf).toString("base64");
+                    bytes = Buffer.from(buf);
                 }
                 if (!contentType.startsWith("image/")) {
-                    return [originalUrl, { ok: false, error: `Not an image — content-type: ${contentType}` }];
+                    return [originalEntry, { ok: false, error: `Not an image — content-type: ${contentType}` }];
                 }
                 const ext = extFromContentType(contentType);
-                const result = await uploadImageBase64(base, b64, ext, contentType);
+                const filename = `upload.${ext}`;
+                const result = await uploadImageMultipart(base, bytes, filename, contentType);
                 if (!result.ok) {
-                    return [originalUrl, { ok: false, error: result.error ?? "Upload failed" }];
+                    return [originalEntry, { ok: false, error: result.error ?? "Upload failed" }];
                 }
-                return [originalUrl, { ok: true, url: result.url }];
+                return [originalEntry, { ok: true, url: result.url }];
             }
             catch (e) {
-                return [originalUrl, { ok: false, error: `Unexpected error: ${e?.message ?? e}` }];
+                return [originalEntry, { ok: false, error: `Unexpected error: ${e?.message ?? e}` }];
             }
         }));
         const images = {};
         let uploaded = 0;
         let failed = 0;
-        for (const [url, result] of results) {
-            images[url] = result;
+        for (const [entry, result] of results) {
+            images[entry] = result;
             if (result.ok)
                 uploaded++;
             else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.66",
+  "version": "1.0.67",
   "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",