webcake-storefront-mcp 1.1.3 → 1.2.0

package/README.md

@@ -149,7 +149,7 @@ Base URLs come from a **named environment** — set `WEBCAKE_ENV` (or `--env`) a
 | **`prod`** (default) | `https://api.storefront.webcake.io` | `https://webcake.io` | `<site_slug>.webcake.me` |
 
 Override a preset with `WEBCAKE_API_URL` / `WEBCAKE_APP_URL`. Optional, configured server-side:
-`PEXELS_API_KEY` (search_images), `MONGO_URI` (image-alt cache). Token / session / site can also be set
+`PEXELS_API_KEY` (search_images). Token / session / site can also be set
 in chat via `update_auth` and `switch_site` — saved to a local config file at `~/.webcake-storefront-mcp/`.
 
 <details>
@@ -171,7 +171,7 @@ in chat via `update_auth` and `switch_site` — saved to a local config file at
 | Group | Tools | Needs |
 |-------|-------|-------|
 | **Build a page** | `get_build_guide` · `list_elements` · `get_element` · `new_element` · `new_section` · `new_page_skeleton` · `validate_page` · `build_page` · `add_section` | catalog tools: nothing |
-| **Media & ingest** | `search_images` (Pexels) · `upload_image` (CDN) · `ingest_html` · `ingest_url` (recreate a reference page) | — |
+| **Media & ingest** | `search_images` (Pexels) · `upload_images` (CDN) · `ingest_html` · `ingest_url` (recreate a reference page) | — |
 | **Pages & code** | `list_pages` · `get_page_source` · `search_page_elements` · `get_page_element` · `update_page_element(s)` · `create_page` · `update_page` · `update_page_source` · custom CSS/JS · page contents · global sections · `publish_site` | token + session |
 | **Commerce** | products · orders · collections · promotions · combos | token + session |
 | **Content & store** | blog articles · themes / site style · apps · customers · `send_mail` | token + session |

package/README.vi.md

@@ -148,7 +148,7 @@ URL gốc lấy theo **môi trường có tên** — đặt `WEBCAKE_ENV` (hoặ
 | **`prod`** (mặc định) | `https://api.storefront.webcake.io` | `https://webcake.io` | `<site_slug>.webcake.me` |
 
 Override bằng `WEBCAKE_API_URL` / `WEBCAKE_APP_URL`. Tuỳ chọn, đặt phía server:
-`PEXELS_API_KEY` (search_images), `MONGO_URI` (cache alt ảnh). Token / session / site cũng có thể đặt
+`PEXELS_API_KEY` (search_images). Token / session / site cũng có thể đặt
 trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình tại `~/.webcake-storefront-mcp/`.
 
 <details>
@@ -170,7 +170,7 @@ trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình
 | Nhóm | Tool | Cần |
 |-------|-------|-------|
 | **Dựng trang** | `get_build_guide` · `list_elements` · `get_element` · `new_element` · `new_section` · `new_page_skeleton` · `validate_page` · `build_page` · `add_section` | tool catalog: không cần |
-| **Media & ingest** | `search_images` (Pexels) · `upload_image` (CDN) · `ingest_html` · `ingest_url` (dựng lại trang tham khảo) | — |
+| **Media & ingest** | `search_images` (Pexels) · `upload_images` (CDN) · `ingest_html` · `ingest_url` (dựng lại trang tham khảo) | — |
 | **Trang & code** | `list_pages` · `get_page_source` · `search_page_elements` · `get_page_element` · `update_page_element(s)` · `create_page` · `update_page` · `update_page_source` · custom CSS/JS · nội dung trang · global section · `publish_site` | token + session |
 | **Thương mại** | sản phẩm · đơn hàng · collection · khuyến mãi · combo | token + session |
 | **Nội dung & store** | bài blog · theme / site style · app · khách hàng · `send_mail` | token + session |

package/dist/api.js

@@ -208,6 +208,32 @@ export class WebcakeCmsApi {
     async updateSiteSettings(newSettings) {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/update_site`, { body: { settings: newSettings }, timeout: 60000 });
     }
+    /** Read the full site.settings object (parsed). Empty object if unset/unparseable. */
+    async getSiteSettings() {
+        const siteRes = await this.request("GET", `/api/v1/site/${this.siteId}/`, { timeout: 60000 });
+        const raw = (siteRes && siteRes.data && siteRes.data.settings) || "";
+        if (raw && typeof raw === "object")
+            return raw;
+        if (typeof raw === "string" && raw.trim()) {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        }
+        return {};
+    }
+    /** Ensure a site data-source flag (use_store/use_member/use_blog/use_error/use_maintain)
+     *  is enabled so special pages' bindings resolve. Merges into existing settings;
+     *  no-op if already on. */
+    async enableSiteFeature(flag) {
+        const settings = await this.getSiteSettings();
+        if (settings[flag] === true)
+            return { changed: false, flag };
+        await this.updateSiteSettings({ ...settings, [flag]: true });
+        return { changed: true, flag };
+    }
     // ── Collections ──
     listCollections(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { query });

package/dist/builder/guide.js

@@ -54,6 +54,23 @@ Breakpoint widths: large_desktop 1920, desktop 1280, laptop 992, tablet 640.
 - Dataset elements (text-dataset, image-dataset, grid-product...) use \`bindings\` to pull
   product/category/blog data — leave bindings to dataset-driven pages.
 
+## Page types & data sources (IMPORTANT for special pages)
+A page's \`type\` decides which live data it can bind to. A SPECIAL page only works if the
+matching site data-source flag (on site.settings) is enabled — otherwise the page renders
+but every product/customer/blog binding resolves to NULL (an empty, broken-looking page).
+\`build_page\` enables the right flag for you when you pass \`type\`:
+- \`main\`    — homepage / normal content. No flag needed.
+- \`store\`   — product detail, category, cart, checkout, thank-you. Needs \`use_store\`.
+            Bindings: \`product::*\`, \`cart_item::*\`.
+- \`member\`  — login, register, profile, order history. Needs \`use_member\`.
+            Bindings: \`customer_address::*\`, \`order_item::*\`.
+- \`blog\`    — blog list, article/post. Needs \`use_blog\`.
+- \`error\` / \`maintain\` — 404 / maintenance. Need \`use_error\` / \`use_maintain\`.
+- \`custom\`  — a free page with no special data. No flag needed.
+Rule of thumb: if the page shows products, a cart, customer/order data, or blog posts,
+set \`type\` accordingly so the binding source is turned on. A binding name like
+\`product::price\` REQUIRES its page to be the matching type.
+
 ## Workflow (do this every time)
 1. Intake: confirm goal, brand, colours, sections wanted (ask 3-5 questions if unclear).
 2. list_elements / get_element to pick the right component types.

package/dist/changelog.json

@@ -0,0 +1,44 @@
+[
+  {
+    "v": "1.2.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "upload_images replaces upload_image with batch support (1–20 sources per call), parallel uploads, and a dry_run mode that previews what would be…",
+    "vi": "upload_images thay thế upload_image với khả năng xử lý hàng loạt (1–20 nguồn mỗi lần gọi), tải song song, và chế độ dry_run cho phép xem trước những…"
+  },
+  {
+    "v": "1.1.4",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "The remote landing page served by the serve command now includes a \"What's new\" section that renders a version timeline loaded from a build-time…",
+    "vi": "Trang landing của lệnh serve nay có thêm mục \"Có gì mới\" hiển thị timeline lịch sử phiên bản được tải từ file changelog.json sinh ra lúc build (từ…"
+  },
+  {
+    "v": "1.1.3",
+    "d": "23/06/2026",
+    "type": "Changed",
+    "en": "The install command's interactive wizard now runs a three-step flow: environment selection (prod / staging / local), authentication, then IDE…",
+    "vi": "Trình hướng dẫn tương tác của lệnh install nay chạy theo 3 bước: chọn môi trường (prod / staging / local), xác thực, rồi cấu hình IDE."
+  },
+  {
+    "v": "1.1.2",
+    "d": "23/06/2026",
+    "type": "Fixed",
+    "en": "The server no longer crashes at startup in container environments built with npm ci --ignore-scripts; the better-sqlite3 native SQLite module has…",
+    "vi": "Server không còn bị crash khi khởi động trong môi trường container được build bằng npm ci --ignore-scripts; module SQLite native better-sqlite3 đã…"
+  },
+  {
+    "v": "1.1.1",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "The serve command's OAuth token store now optionally uses Postgres (via DATABASE_URL) for durable persistence across restarts and shared state…",
+    "vi": "Kho lưu trữ token OAuth của lệnh serve nay hỗ trợ tùy chọn sử dụng Postgres (qua DATABASE_URL) để lưu token bền vững qua các lần khởi động lại và…"
+  },
+  {
+    "v": "1.1.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "The serve (remote Streamable-HTTP) mode now embeds a full OAuth 2.1 Authorization Server at /authorize, /token, /revoke, /register, and…",
+    "vi": "Chế độ serve (remote Streamable-HTTP) nay tích hợp sẵn một Authorization Server OAuth 2.1 đầy đủ tại các endpoint /authorize, /token, /revoke,…"
+  }
+]

package/dist/db.js

@@ -1,8 +1,8 @@
-// Tiny JSON-file persistence (no native deps) for: (1) the saved connection config
-// (token / session / site / api_url / confirm_mode) and (2) the image-alt cache.
+// Tiny JSON-file persistence (no native deps) for the saved connection config
+// (token / session / site / api_url / confirm_mode).
 //
 // Stored under a stable home dir so it survives `npx` (ephemeral package cache) and
-// container restarts. Two flat JSON files instead of SQLite — keeps the package light
+// container restarts. A flat JSON file instead of SQLite — keeps the package light
 // and works in any runtime (Alpine, Docker `--ignore-scripts`, serverless) with no
 // native binding to build. The API is synchronous to match the call sites.
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -11,7 +11,6 @@ import { join } from "node:path";
 const CONFIG_DIR = process.env.WEBCAKE_CONFIG_DIR || join(homedir(), ".webcake-storefront-mcp");
 mkdirSync(CONFIG_DIR, { recursive: true });
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
-const ALT_FILE = join(CONFIG_DIR, "image-alt-cache.json");
 function readJson(file, fallback) {
     try {
         return JSON.parse(readFileSync(file, "utf-8"));
@@ -44,40 +43,3 @@ export function delConfig(key) {
 export function getAllConfig() {
     return { ...config };
 }
-const altCache = readJson(ALT_FILE, {});
-export function getImageAlt(urlKey) {
-    return altCache[urlKey] || null;
-}
-export function getImageAlts(urlKeys) {
-    const out = new Map();
-    for (const k of urlKeys) {
-        const row = altCache[k];
-        if (row)
-            out.set(k, row);
-    }
-    return out;
-}
-export function setImageAlt({ url_key, url, alt, source = "ai" }) {
-    altCache[url_key] = { url_key, url, alt, source, updated_at: Date.now() };
-    writeJson(ALT_FILE, altCache);
-}
-export function setImageAlts(items) {
-    for (const it of items) {
-        altCache[it.url_key] = {
-            url_key: it.url_key,
-            url: it.url,
-            alt: it.alt,
-            source: it.source || "ai",
-            updated_at: Date.now(),
-        };
-    }
-    writeJson(ALT_FILE, altCache);
-}
-export function listImageAlts(limit = 100, offset = 0) {
-    return Object.values(altCache)
-        .sort((a, b) => b.updated_at - a.updated_at)
-        .slice(offset, offset + limit);
-}
-export function countImageAlts() {
-    return Object.keys(altCache).length;
-}

package/dist/http.js

@@ -385,7 +385,7 @@ export async function startHttpServer(port) {
                             transports.delete(transport.sessionId);
                     };
                     const api = apiFromRequest(req);
-                    const server = createServer(api);
+                    const server = createServer(api, { allowLocalFiles: false }); // remote: never read server-side files
                     await server.connect(transport);
                     await transport.handleRequest(req, res, body);
                     return;

package/dist/index.js

@@ -58,7 +58,7 @@ async function main() {
     // no env is required to start — auth (token + session) is set via env or `login`,
     // and the site is chosen at runtime with switch_site.
     const api = makeApi();
-    const server = createServer(api);
+    const server = createServer(api, { allowLocalFiles: true }); // stdio = user's own machine
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error("[webcake-storefront] MCP server ready on stdio.");

package/dist/server.js

@@ -31,7 +31,7 @@ function makeResult(data) {
     return { content: [{ type: "text", text: JSON.stringify(data) }] };
 }
 /** Build a fully-wired MCP server bound to the given API client. */
-export function createServer(api) {
+export function createServer(api, opts = {}) {
     const server = new McpServer({ name: "webcake-storefront", version: "1.0.0" }, { instructions: INSTRUCTIONS });
     const handle = async (fn) => {
         try {
@@ -58,6 +58,6 @@ export function createServer(api) {
     registerGlobalSourceTools(server, api, handle);
     registerImageTools(server, api, handle);
     registerBuilderTools(server, api, handle);
-    registerBuilderExtraTools(server, api, handle);
+    registerBuilderExtraTools(server, api, handle, { allowLocalFiles: opts.allowLocalFiles === true });
     return server;
 }

package/dist/tools/builder-extras.js

@@ -1,7 +1,41 @@
 import { z } from "zod";
 import { resolvePreviewUrl } from "../config.js";
 import { parse as parseHtml } from "node-html-parser";
+import { stat, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 const ALLOWED_IMG = /^image\/(jpe?g|png|webp)$/;
+const LOCAL_MAX = 200 * 1024 * 1024; // 200 MB, matches the backend multipart limit
+/** Is this entry a LOCAL filesystem path (vs an http(s) URL or data: URI)? */
+function isLocalPath(s) {
+    if (s.startsWith("data:") || /^https?:\/\//i.test(s))
+        return false;
+    return s.startsWith("file://") || s.startsWith("/") || s.startsWith("~") || /^[a-zA-Z]:[\\/]/.test(s);
+}
+/** Resolve ~ and file:// to an absolute path. */
+function resolveLocalPath(s) {
+    if (s.startsWith("file://"))
+        return fileURLToPath(s);
+    if (s.startsWith("~"))
+        return join(homedir(), s.slice(1));
+    return s;
+}
+/** Read a local image file into a buffer (with a size cap) + guess its content type. */
+async function readLocalImage(s) {
+    const p = resolveLocalPath(s);
+    const st = await stat(p);
+    if (st.size > LOCAL_MAX)
+        throw new Error(`File too large (${st.size} bytes, max ${LOCAL_MAX}).`);
+    const buf = await readFile(p);
+    const ext = (p.split(".").pop() || "").toLowerCase();
+    const contentType = ext === "png" ? "image/png"
+        : ext === "webp" ? "image/webp"
+            : ext === "gif" ? "image/gif"
+                : ext === "jpg" || ext === "jpeg" ? "image/jpeg"
+                    : "application/octet-stream";
+    return { buf, contentType };
+}
 /** Fetch a URL into a Buffer with a size cap. */
 async function fetchBuffer(url, maxBytes = 15 * 1024 * 1024) {
     const res = await fetch(url, { redirect: "follow" });
@@ -21,7 +55,7 @@ async function toAllowedImage(buf, contentType) {
     const out = await sharp(buf).jpeg({ quality: 85 }).toBuffer();
     return { buf: out, contentType: "image/jpeg" };
 }
-export function registerBuilderExtraTools(server, api, handle) {
+export function registerBuilderExtraTools(server, api, handle, opts = {}) {
     // ── Stock images (Pexels) ──────────────────────────────────────────────────
     server.tool("search_images", `Search stock photos (Pexels) to use on a page. Returns hosted image URLs you can put straight into an image element's runtime.config.src.
 Requires the PEXELS_API_KEY environment variable.`, {
@@ -52,29 +86,78 @@ Requires the PEXELS_API_KEY environment variable.`, {
         }));
         return { query, total_results: json.total_results, photos };
     }));
-    // ── Upload an image to the site CDN ─────────────────────────────────────────
-    server.tool("upload_image", `Upload an image to the site's CDN and get back a hosted URL. Accepts an http(s) URL or a data:image/...;base64 data URI. Non jpeg/png/webp inputs are converted to JPEG.
-Use this for the user's own images; stock photos from search_images are already hosted and don't need uploading.`, {
-        url: z.string().describe("http(s) URL or data:image/...;base64,... data URI"),
-    }, ({ url }) => handle(async () => {
-        let buf, contentType;
-        if (url.startsWith("data:")) {
-            const m = url.match(/^data:([^;]+);base64,(.*)$/s);
-            if (!m)
-                return { error: "Malformed data URI." };
-            contentType = m[1];
-            buf = Buffer.from(m[2], "base64");
-        }
-        else {
-            ({ buf, contentType } = await fetchBuffer(url));
+    // ── Upload images to the site CDN ───────────────────────────────────────────
+    server.tool("upload_images", `Convert external image URLs, data: URIs, or LOCAL FILE PATHS into site-hosted CDN URLs by reading/downloading each image and re-uploading it to the WebCake backend. Use this whenever the user supplies their OWN images (their URLs or files from their machine), or a page is built from a reference HTML/URL. The returned hosted URLs go straight into an image element's specials.src / runtime.config.src — same as search_images results. Stock photos from search_images are already hosted and don't need uploading.
+Processes up to 20 entries per call in parallel; non jpeg/png/webp inputs are converted to JPEG. UPLOADS BY DEFAULT (dry_run defaults to FALSE — this touches no account data): returns an "images" map (original source → hosted URL). Pass dry_run:true to only preview the entries that WOULD be processed (local paths report whether the file exists + its size) without any network/filesystem upload. Local file paths are only permitted when the MCP server runs locally (stdio); on the remote HTTP transport they are rejected per-entry.`, {
+        urls: z
+            .array(z.string())
+            .min(1)
+            .max(20)
+            .describe("Image sources — 1–20 per call. Accepts: http(s) URLs, data:image/...;base64,... URIs, or local file paths (absolute /path, ~/path, file:// — stdio mode only)."),
+        dry_run: z
+            .boolean()
+            .default(false)
+            .describe("Default FALSE — actually reads/downloads and uploads, returning hosted URLs. Set true to only preview what would be processed."),
+    }, ({ urls, dry_run }) => handle(async () => {
+        const deduped = [...new Set(urls)];
+        const localAllowed = opts.allowLocalFiles === true;
+        if (dry_run) {
+            const entries = await Promise.all(deduped.map(async (entry) => {
+                if (entry.startsWith("data:"))
+                    return { entry, kind: "data-uri" };
+                if (isLocalPath(entry)) {
+                    if (!localAllowed)
+                        return { entry, kind: "local", error: "Local file paths are only supported in stdio mode." };
+                    try {
+                        const st = await stat(resolveLocalPath(entry));
+                        return { entry, kind: "local", exists: true, size: st.size };
+                    }
+                    catch (e) {
+                        return { entry, kind: "local", exists: false, error: e?.message ?? String(e) };
+                    }
+                }
+                return { entry, kind: "url" };
+            }));
+            return { dry_run: true, count: deduped.length, entries };
         }
-        const norm = await toAllowedImage(buf, contentType);
-        const dataUri = `data:${norm.contentType};base64,${norm.buf.toString("base64")}`;
-        const res = await api.uploadImageBase64({ base64: dataUri, content_type: norm.contentType });
-        const hosted = (res && res.data) || (res && res.url) || null;
-        if (!hosted)
-            return { error: "Upload returned no URL.", raw: res };
-        return { success: true, url: hosted, content_type: norm.contentType };
+        const images = {};
+        const errors = [];
+        await Promise.all(deduped.map(async (entry) => {
+            try {
+                let buf, contentType;
+                if (entry.startsWith("data:")) {
+                    const m = entry.match(/^data:([^;]+);base64,(.*)$/s);
+                    if (!m)
+                        throw new Error("Malformed data URI.");
+                    contentType = m[1];
+                    buf = Buffer.from(m[2], "base64");
+                }
+                else if (isLocalPath(entry)) {
+                    if (!localAllowed)
+                        throw new Error("Local file paths are only supported when the server runs locally (stdio). Send a public URL or data: URI instead.");
+                    ({ buf, contentType } = await readLocalImage(entry));
+                }
+                else {
+                    ({ buf, contentType } = await fetchBuffer(entry));
+                }
+                const norm = await toAllowedImage(buf, contentType);
+                const dataUri = `data:${norm.contentType};base64,${norm.buf.toString("base64")}`;
+                const res = await api.uploadImageBase64({ base64: dataUri, content_type: norm.contentType });
+                const hosted = (res && res.data) || (res && res.url) || null;
+                if (!hosted)
+                    throw new Error("Upload returned no URL.");
+                images[entry] = hosted;
+            }
+            catch (e) {
+                errors.push({ url: entry, error: e?.message ?? String(e) });
+            }
+        }));
+        return {
+            uploaded: Object.keys(images).length,
+            failed: errors.length,
+            images,
+            ...(errors.length ? { errors } : {}),
+        };
     }));
     // ── Publish the site ────────────────────────────────────────────────────────
     server.tool("publish_site", `Publish the whole site live — snapshots all current page sources into the live (published) version.
@@ -143,7 +226,7 @@ Two-step safety: dry_run=true (default) describes what will happen; dry_run=fals
             images,
             buttons,
             palette: [...colors].slice(0, 24),
-            hint: "Rebuild this as BuilderX sections: map each heading group + its text/image/button into a new_section call. Generate fresh copy where useful; re-host external images with upload_image if you want them on the site CDN. This is a structural blueprint, not a 1:1 clone.",
+            hint: "Rebuild this as BuilderX sections: map each heading group + its text/image/button into a new_section call. Generate fresh copy where useful; re-host external images with upload_images if you want them on the site CDN. This is a structural blueprint, not a 1:1 clone.",
         };
     }
     server.tool("ingest_html", "Parse reference HTML into a structural blueprint (title, headings, paragraphs, images, buttons, colour palette) you can rebuild as BuilderX sections with new_section. Not a 1:1 clone.", {

package/dist/tools/builder.js

@@ -16,6 +16,18 @@ function parseSource(src) {
 function newPageId(res) {
     return (res && res.data && res.data.id) || (res && res.id) || null;
 }
+// BuilderX page kinds. The numeric `type` is what the backend stores (PAGE_TYPE in
+// builderx_spa); SPECIAL kinds also require a site-level data-source flag enabled on
+// site.settings, otherwise components that bind to store/customer/blog data render
+// with null bindings. build_page sets both for you.
+const PAGE_TYPE_NUM = {
+    main: 1, store: 2, member: 3, blog: 4, custom: 5, error: 6, maintain: 7,
+};
+const PAGE_TYPE_FLAG = {
+    store: "use_store", member: "use_member", blog: "use_blog",
+    error: "use_error", maintain: "use_maintain",
+};
+const PAGE_KINDS = ["main", "store", "member", "blog", "custom", "error", "maintain"];
 export function registerBuilderTools(server, api, handle) {
     server.tool("get_build_guide", "Get the BuilderX page authoring guide: page shape, the grid layout model, styling, breakpoints, forms/data, and the build workflow. Read this before building or heavily editing a page.", {}, () => handle(async () => ({ guide: BUILD_GUIDE })));
     server.tool("list_elements", "List all BuilderX element/component types you can place on a page, grouped by category with a one-line summary and whether each is a container.", {}, () => handle(async () => listElements()));
@@ -45,26 +57,45 @@ The source must be { sections: [...] } — build sections with new_section. Vali
         name: z.string().describe("Page name"),
         slug: z.string().describe("URL slug, e.g. '/landing' or '/about'"),
         source: z.any().describe("Full page source { sections: [...] } (object or JSON string)"),
-        type: z.string().optional().describe("Page type (optional)"),
+        type: z
+            .enum(PAGE_KINDS)
+            .optional()
+            .describe("Page kind. SPECIAL pages need a site data-source enabled — build_page does this automatically: store→use_store (product/cart bindings), member→use_member (customer/order bindings), blog→use_blog, error→use_error, maintain→use_maintain. 'main'/'custom' need nothing. Omit for a normal content page (defaults to 'main' for the homepage)."),
         is_homepage: z.boolean().default(false).describe("Set as the site homepage"),
         dry_run: z.boolean().default(true).describe("Preview+validate only (true) or create+save (false)"),
     }, ({ name, slug, source, type, is_homepage, dry_run }) => handle(async () => {
         const parsed = parseSource(source);
         const validation = validatePage(parsed);
+        // Resolve numeric page type + the site data-source flag a special page needs.
+        const kind = type || (is_homepage ? "main" : undefined);
+        const typeNum = kind ? PAGE_TYPE_NUM[kind] : undefined;
+        const requiredFlag = kind ? PAGE_TYPE_FLAG[kind] : undefined;
         if (dry_run) {
             return {
                 dry_run: true,
                 validation,
-                request: { name, slug, type, is_homepage, sections: (parsed && parsed.sections || []).length },
+                request: { name, slug, type: kind ?? null, page_type_num: typeNum ?? null, is_homepage, sections: (parsed && parsed.sections || []).length },
+                will_enable_feature: requiredFlag ?? null,
                 hint: validation.valid
-                    ? "Looks valid. Call again with dry_run=false to create and save the page."
+                    ? `Looks valid. Call again with dry_run=false to create and save the page.${requiredFlag ? ` Will also enable site.settings.${requiredFlag} so its data bindings resolve.` : ""}`
                     : "Fix the errors above before saving.",
             };
         }
         if (!validation.valid) {
             return { error: "Validation failed — not saving.", validation };
         }
-        const created = await api.createPage({ name, slug, type, is_homepage });
+        // A special page is useless if its site data-source flag is off (bindings
+        // return null). Enable it BEFORE creating the page so the page works on first load.
+        let feature = null;
+        if (requiredFlag) {
+            try {
+                feature = await api.enableSiteFeature(requiredFlag);
+            }
+            catch (e) {
+                return { error: `Could not enable site.settings.${requiredFlag} (needed for a '${kind}' page). ${e?.message ?? e}` };
+            }
+        }
+        const created = await api.createPage({ name, slug, ...(typeNum != null ? { type: typeNum } : {}), is_homepage });
         const pageId = newPageId(created);
         if (!pageId) {
             return { error: "Page created but no id was returned; cannot save source.", created };
@@ -75,6 +106,8 @@ The source must be { sections: [...] } — build sections with new_section. Vali
             page_id: pageId,
             name,
             slug,
+            page_type: kind ?? null,
+            ...(feature ? { data_source: { flag: feature.flag, newly_enabled: feature.changed } } : {}),
             page_source_id: saved && saved.data && saved.data.id,
             stats: validation.stats,
         };

package/dist/tools/images.js

@@ -1,6 +1,4 @@
 import { z } from "zod";
-import { getImageAlt, setImageAlts as dbSetImageAlts, listImageAlts, countImageAlts } from "../db.js";
-import { isMongoEnabled, mongoUpsertAlts, mongoFindAlts, mongoListAlts } from "../mongo.js";
 const IMAGE_EXT_RE = /\.(jpe?g|png|gif|webp|svg|avif|bmp|ico)(\?[^"')\s]*)?$/i;
 const URL_IN_CSS_RE = /url\(\s*['"]?([^'")\s]+)['"]?\s*\)/g;
 const HTTP_URL_RE = /https?:\/\/[^\s"'<>)]+/g;
@@ -405,7 +403,6 @@ Note: global_sections are read-only via the API and are not included.`, {
                 const { src, alt, src_path, alt_path } = probeImagePaths(node);
                 if (only_missing_alt && alt && alt.trim())
                     return;
-                const cached = src ? getImageAlt(normalizeUrl(src)) : null;
                 out.push({
                     source_type: meta.source_type,
                     source_id: meta.source_id,
@@ -416,7 +413,6 @@ Note: global_sections are read-only via the API and are not included.`, {
                     alt: alt || "",
                     src_path,
                     alt_path,
-                    ...(cached && { cached_alt: cached.alt, cached_source: cached.source, cached_at: cached.updated_at }),
                 });
             });
         }
@@ -571,30 +567,11 @@ If alt_path is omitted, it is auto-detected via the same probe used by list_imag
             }
             try {
                 await saver(source);
-                // Auto-cache: save alt per src URL so re-runs can skip OCR
-                const cacheBatch = [];
-                for (const u of perItem) {
-                    if (u.error || !u._src)
-                        continue;
-                    if (!/^https?:\/\//i.test(u._src))
-                        continue;
-                    cacheBatch.push({ url_key: normalizeUrl(u._src), url: u._src, alt: u.after, source: "ai" });
-                }
-                if (cacheBatch.length) {
-                    try {
-                        dbSetImageAlts(cacheBatch);
-                    }
-                    catch { /* cache best-effort */ }
-                    if (isMongoEnabled()) {
-                        mongoUpsertAlts(cacheBatch).catch(() => { });
-                    }
-                }
                 results.push({
                     source_type,
                     source_id,
                     success: true,
                     updated: perItem.filter((u) => !u.error).length,
-                    cached: cacheBatch.length,
                     updates: perItem.map(({ _src, ...rest }) => rest),
                 });
             }
@@ -604,137 +581,21 @@ If alt_path is omitted, it is auto-detected via the same probe used by list_imag
         }
         return { dry_run, sources: results.length, results };
     }));
-    // ── Alt cache tools ──
-    server.tool("get_cached_image_alts", `Look up cached alt descriptions for image URLs. URLs are matched by normalized form (query string stripped, lowercase). Use BEFORE running read_image/OCR — skip already-described URLs.
-When MONGO_URI is set, misses are then checked against MongoDB and successful hits are backfilled into the local cache for fast re-lookup.`, {
-        urls: z.array(z.string()).min(1).describe("Image URLs to look up"),
-    }, ({ urls }) => handle(async () => {
-        const hits = [];
-        let misses = [];
-        const keyToUrl = new Map();
-        for (const u of urls) {
-            if (!/^https?:\/\//i.test(u)) {
-                misses.push(u);
-                continue;
-            }
-            const key = normalizeUrl(u);
-            keyToUrl.set(key, u);
-            const row = getImageAlt(key);
-            if (row)
-                hits.push({ url: u, url_key: key, alt: row.alt, source: row.source, updated_at: row.updated_at });
-            else
-                misses.push(u);
-        }
-        let mongo_hits = 0;
-        if (isMongoEnabled() && misses.length) {
-            const missKeys = misses
-                .filter((u) => /^https?:\/\//i.test(u))
-                .map((u) => normalizeUrl(u));
-            try {
-                const found = await mongoFindAlts(missKeys);
-                if (found.size) {
-                    const backfill = [];
-                    const stillMissing = [];
-                    for (const u of misses) {
-                        const k = /^https?:\/\//i.test(u) ? normalizeUrl(u) : null;
-                        if (k && found.has(k)) {
-                            const doc = found.get(k);
-                            hits.push({ url: u, url_key: k, alt: doc.alt, source: doc.source || "mongo", updated_at: doc.updated_at, origin: "mongo" });
-                            backfill.push({ url_key: k, url: doc.url || u, alt: doc.alt, source: doc.source || "mongo" });
-                            mongo_hits++;
-                        }
-                        else {
-                            stillMissing.push(u);
-                        }
-                    }
-                    if (backfill.length) {
-                        try {
-                            dbSetImageAlts(backfill);
-                        }
-                        catch { /* best-effort */ }
-                    }
-                    misses = stillMissing;
-                }
-            }
-            catch { /* fall through with original misses */ }
-        }
-        return { hits_count: hits.length, miss_count: misses.length, mongo_hits, hits, misses };
-    }));
-    server.tool("save_image_alts_cache", `Manually save image URL → alt entries to the local cache. Useful for bulk import or saving descriptions generated outside the set_image_alts flow.`, {
-        items: z.array(z.object({
-            url: z.string().describe("Image URL"),
-            alt: z.string().describe("Alt/description text"),
-            source: z.string().optional().describe("Origin tag (e.g. 'ai', 'manual', 'imported'). Default 'manual'"),
-        })).min(1),
-    }, ({ items }) => handle(async () => {
-        const batch = [];
-        const skipped = [];
-        for (const it of items) {
-            if (!/^https?:\/\//i.test(it.url)) {
-                skipped.push({ url: it.url, reason: "non-http URL" });
-                continue;
-            }
-            batch.push({ url_key: normalizeUrl(it.url), url: it.url, alt: it.alt, source: it.source || "manual" });
-        }
-        if (batch.length) {
-            dbSetImageAlts(batch);
-            if (isMongoEnabled()) {
-                mongoUpsertAlts(batch).catch(() => { });
-            }
-        }
-        return { saved: batch.length, skipped, mongo: isMongoEnabled() ? "queued" : "disabled" };
-    }));
-    server.tool("list_image_alts_cache", `List entries in the alt cache, most recently updated first.`, {
-        limit: z.number().default(100).describe("Max entries (default 100)"),
-        offset: z.number().default(0).describe("Pagination offset"),
-    }, ({ limit, offset }) => handle(async () => {
-        const total = countImageAlts();
-        const rows = listImageAlts(limit, offset);
-        return { total, count: rows.length, entries: rows };
-    }));
-    // ── Mongo sync (active when MONGO_URI is set) ──
-    server.tool("sync_image_alts_to_mongo", `Push local alt cache entries up to MongoDB. Bulk upsert keyed by url_key. Use when you want to back up local-only entries to the shared central store, or after a session of heavy AI describes.
-Requires MONGO_URI env var.`, {
-        limit: z.number().default(1000).describe("Max entries to push per call"),
-        offset: z.number().default(0).describe("Offset into local cache"),
-    }, ({ limit, offset }) => handle(async () => {
-        if (!isMongoEnabled())
-            return { error: "MONGO_URI not configured" };
-        const rows = listImageAlts(limit, offset);
-        if (!rows.length)
-            return { pushed: 0, total_local: countImageAlts() };
-        const res = await mongoUpsertAlts(rows.map((r) => ({ url_key: r.url_key, url: r.url, alt: r.alt, source: r.source })));
-        return { pushed: rows.length, ...res, total_local: countImageAlts() };
-    }));
-    server.tool("sync_image_alts_from_mongo", `Pull MongoDB alt entries down into local cache. Useful when starting on a new machine/site to warm the local cache from the central store.
-Requires MONGO_URI env var.`, {
-        limit: z.number().default(1000).describe("Max entries to pull"),
-        offset: z.number().default(0).describe("Offset into Mongo collection"),
-    }, ({ limit, offset }) => handle(async () => {
-        if (!isMongoEnabled())
-            return { error: "MONGO_URI not configured" };
-        const { total, entries } = await mongoListAlts(limit, offset);
-        if (entries.length) {
-            dbSetImageAlts(entries.map((e) => ({ url_key: e.url_key, url: e.url, alt: e.alt, source: e.source || "mongo" })));
-        }
-        return { pulled: entries.length, total_remote: total, total_local: countImageAlts() };
-    }));
     // ── Combo: fetch images + metadata in one call so Claude can describe + call set_image_alts once ──
     server.tool("fetch_images_for_alt_fill", `One-shot helper for filling image_alt across the site. Returns image bytes + element metadata in a single response so Claude can describe everything in one pass, then call set_image_alts once.
 
 Workflow:
 1. Call this tool with scope/limit.
-2. Tool returns each image inline with its element_id + source_type + source_id (and skips URLs already in cache).
+2. Tool returns each image inline with its element_id + source_type + source_id.
 3. Claude reads images, drafts an alt for each, then calls set_image_alts(items) once with the template at the end of the response.
 
 The pre-built "items" template at the end contains placeholders — fill in "alt" and call set_image_alts.`, {
         scope: z.enum(["all", "pages", "global_sources"]).default("all"),
         page_id: z.string().optional(),
         only_missing_alt: z.boolean().default(true).describe("Default true — skip elements that already have alt"),
-        skip_cached: z.boolean().default(true).describe("Skip URLs already in alt cache (Claude doesn't need to describe again)"),
         limit: z.number().default(10).describe("Max images per call (cap 20)"),
         max_size_mb: z.number().default(8),
-    }, async ({ scope, page_id, only_missing_alt, skip_cached, limit, max_size_mb }) => {
+    }, async ({ scope, page_id, only_missing_alt, limit, max_size_mb }) => {
         try {
             const cap = Math.min(Math.max(limit, 1), 20);
             // 1. Collect candidate elements
@@ -790,17 +651,9 @@ The pre-built "items" template at the end contains placeholders — fill in "alt
                         });
                 }
             }
-            // 2. Resolve cache hits → auto-prepare items; misses → need vision
-            const autoItems = [];
+            // 2. Take up to `cap` candidates that need a vision-generated description
             const needVision = [];
             for (const c of candidates) {
-                if (skip_cached) {
-                    const cached = getImageAlt(normalizeUrl(c.src));
-                    if (cached && cached.alt) {
-                        autoItems.push({ source_type: c.source_type, source_id: c.source_id, element_id: c.element_id, alt: cached.alt });
-                        continue;
-                    }
-                }
                 needVision.push(c);
                 if (needVision.length >= cap)
                     break;
@@ -812,7 +665,7 @@ The pre-built "items" template at the end contains placeholders — fill in "alt
             const content = [];
             content.push({
                 type: "text",
-                text: `Fetched ${needVision.length} image(s) needing description. ${autoItems.length} auto-filled from cache. ${candidates.length - needVision.length - autoItems.length} skipped.
+                text: `Fetched ${needVision.length} image(s) needing description. ${Math.max(0, candidates.length - needVision.length)} more candidate(s) not included in this batch.
 
 For each image below, write a short alt description in the language of the site (Vietnamese unless content suggests otherwise). Focus on the SUBJECT visible — avoid generic phrases like "image of...".
 
@@ -838,9 +691,8 @@ When done, call set_image_alts with the items array. The template is at the bott
                 }
             }
             const template = {
-                auto_from_cache: autoItems,
                 to_describe: visionItems,
-                next_step: "Replace each <FILL_ALT_FOR_#N> with your description, then call set_image_alts with items = [...auto_from_cache, ...to_describe].",
+                next_step: "Replace each <FILL_ALT_FOR_#N> with your description, then call set_image_alts with items = to_describe.",
             };
             content.push({ type: "text", text: JSON.stringify(template, null, 2) });
             return { content };

package/dist/web-guide.js

@@ -14,6 +14,7 @@
  *
  * Self-contained (inline CSS + JS, no external fonts/trackers) so it loads instantly.
  */
+import { readFileSync } from "node:fs";
 // The SPA page (on the builder app) that shows the user their personal remote
 // connector link with login already built in — see builderx_spa McpRemoteStore.vue
 // (/mcp-remote-store). The raw MCP endpoint itself is {ENDPOINT} = <origin>/mcp.
@@ -281,6 +282,9 @@ const T = {
         promptSub: "Bạn có thể nói tự nhiên bằng tiếng Việt. Ví dụ:",
         promptEx: "Tạo cho tôi một trang sản phẩm trên WebCake cho thương hiệu [tên thương hiệu].\nTrang cần có: ảnh sản phẩm lớn, tên và giá, mô tả ngắn, nút \"Mua ngay\".\nKiểm tra kỹ trước khi lưu, rồi xuất bản lên cửa hàng của tôi.",
         faqH2: "Câu hỏi thường gặp",
+        newH2: "Có gì mới",
+        newBadge: "MỚI",
+        clMore: "Xem tất cả thay đổi",
         starH2: "Thấy hữu ích? Tặng dự án một ngôi sao nhé",
         starP: "Đây là dự án miễn phí, mã nguồn mở — mỗi ngôi sao là một lời động viên để dự án tiếp tục phát triển và giúp nhiều người tìm ra nó hơn.",
         starBtn: "Tặng sao trên GitHub",
@@ -292,6 +296,7 @@ const T = {
             { href: "#build", label: "Tạo được gì" },
             { href: "#connect", label: "Kết nối" },
             { href: "#tools", label: "Trợ lý làm gì" },
+            { href: "#new", label: "Có gì mới" },
             { href: "#faq", label: "Hỏi đáp" },
         ],
     },
@@ -439,6 +444,9 @@ const T = {
         promptSub: "You can speak naturally. For example:",
         promptEx: "Create a product page on my WebCake store for [brand name].\nThe page should have: a large product image, name and price, a short description, and a \"Buy Now\" button.\nPlease check everything looks right before saving, then publish it to my store.",
         faqH2: "Frequently asked questions",
+        newH2: "What's new",
+        newBadge: "NEW",
+        clMore: "See all changes",
         starH2: "Find it useful? Give the project a star",
         starP: "It's a free, open-source project — every star is a little encouragement to keep it growing and helps more people find it.",
         starBtn: "Star on GitHub",
@@ -450,10 +458,38 @@ const T = {
             { href: "#build", label: "What you build" },
             { href: "#connect", label: "Connect" },
             { href: "#tools", label: "What it does" },
+            { href: "#new", label: "What's new" },
             { href: "#faq", label: "FAQ" },
         ],
     },
 };
+const CHANGELOG = loadChangelog();
+function loadChangelog() {
+    try {
+        const raw = readFileSync(new URL("./changelog.json", import.meta.url), "utf8");
+        const data = JSON.parse(raw);
+        return Array.isArray(data) ? data : [];
+    }
+    catch {
+        return [];
+    }
+}
+// English Keep-a-Changelog section names → short Vietnamese tags (en uses the raw name).
+const CL_TYPE_VI = {
+    Added: "Thêm mới",
+    Changed: "Cải tiến",
+    Fixed: "Sửa lỗi",
+    Removed: "Gỡ bỏ",
+    Deprecated: "Ngừng dùng",
+    Security: "Bảo mật",
+    Internal: "Nội bộ",
+};
+function clTag(type, lang) {
+    if (!type)
+        return "";
+    const label = lang === "vi" ? (CL_TYPE_VI[type] ?? "") : type;
+    return label ? ` <span class="cl-tag">${label}</span>` : "";
+}
 function steps(items) {
     return items
         .map((body, i) => `<li><span class="n">${i + 1}</span><div class="body">${body}</div></li>`)
@@ -704,6 +740,26 @@ export function guideHtml(origin, lang = "vi") {
     display:flex;gap:18px;flex-wrap:wrap;align-items:center}
   footer a{color:var(--g7);font-weight:600;text-decoration:none;display:inline-flex;align-items:center;gap:6px}
   footer a:hover{text-decoration:underline}
+  .cl-wrap{padding:24px 26px 12px}
+  .cl{position:relative;margin:0;padding:0 0 0 24px;list-style:none}
+  .cl::before{content:"";position:absolute;left:6px;top:8px;bottom:14px;width:2px;
+    background:linear-gradient(var(--g),rgba(16,139,103,.08))}
+  .cl li{position:relative;padding:0 0 18px}
+  .cl li:last-child{padding-bottom:0}
+  .cl li::before{content:"";position:absolute;left:-24px;top:4px;width:12px;height:12px;border-radius:50%;
+    background:var(--card);border:2.5px solid var(--g);box-sizing:border-box}
+  .cl li.is-new::before{box-shadow:0 0 0 0 rgba(16,139,103,.5);animation:ring 2s infinite}
+  @keyframes ring{70%{box-shadow:0 0 0 8px rgba(16,139,103,0)}100%{box-shadow:0 0 0 0 rgba(16,139,103,0)}}
+  .cl .v{display:inline-flex;align-items:center;gap:8px;font-weight:800;font-size:.97rem;flex-wrap:wrap}
+  .cl-tag{font-size:.68rem;font-weight:700;color:var(--g7);background:rgba(16,139,103,.12);
+    border:1px solid var(--line);padding:1px 8px;border-radius:999px;margin-left:8px}
+  .cl .date{color:var(--mut);font-size:.79rem;margin-left:8px;font-weight:500}
+  .cl .t{color:var(--mut);font-size:.91rem;margin:3px 0 0;max-width:62ch}
+  .new{font-size:.64rem;font-weight:800;letter-spacing:.06em;color:#fff;background:var(--g);
+    padding:2px 7px;border-radius:999px;animation:blink 1.8s ease-in-out infinite}
+  @keyframes blink{50%{opacity:.55}}
+  .cl-more{display:inline-flex;align-items:center;gap:6px;margin-top:6px;font-size:.86rem;font-weight:600;color:var(--g7);text-decoration:none}
+  .cl-more:hover{gap:9px}
   @media(max-width:640px){
     .wrap{padding:30px 15px 56px}
     header{flex-wrap:wrap;gap:12px}
@@ -714,6 +770,7 @@ export function guideHtml(origin, lang = "vi") {
     .method{padding:18px 15px}
     .card{padding:18px}
     .tip{padding:11px 12px}
+    .cl-wrap{padding:18px 16px 10px}
     .langsw{padding:6px 10px}
     .uses li,.feat li{padding:14px}
     .flow{flex-direction:column;align-items:stretch;overflow:visible;padding:16px}
@@ -751,7 +808,7 @@ export function guideHtml(origin, lang = "vi") {
     </div>
   </header>
 
-  <p class="hero-in" style="display:flex;gap:9px;flex-wrap:wrap"><span class="pill"><span class="dot"></span> ${t.running}</span><span class="pill">WebCake · StoreCake</span></p>
+  <p class="hero-in" style="display:flex;gap:9px;flex-wrap:wrap"><span class="pill"><span class="dot"></span> ${t.running}</span><span class="pill">WebCake · StoreCake</span>${CHANGELOG[0] ? `<span class="pill">v${CHANGELOG[0].v}</span>` : ""}</p>
 
   <p class="lead hero-in">${t.leadPre}<b class="grad">${t.leadGrad}</b>${t.leadPost}</p>
 
@@ -828,6 +885,16 @@ export function guideHtml(origin, lang = "vi") {
     <li class="glass reveal">${tile("wand")} <span><pre style="background:transparent;color:inherit;border:none;padding:0;font-size:.88rem;white-space:pre-wrap">${t.promptEx}</pre></span></li>
   </ul>
 
+  ${CHANGELOG.length
+        ? `<h2 id="new" class="reveal">${t.newH2}</h2>
+  <div class="glass cl-wrap reveal">
+    <ul class="cl">
+      ${CHANGELOG.map((c, i) => `<li class="${i === 0 ? "is-new" : ""}"><span class="v">v${c.v}${i === 0 ? ` <span class="new">${t.newBadge}</span>` : ""}${clTag(c.type, L)}<span class="date">${c.d}</span></span><p class="t">${L === "en" ? c.en : c.vi}</p></li>`).join("\n      ")}
+    </ul>
+    <a class="cl-more" href="${GITHUB_URL}/blob/main/${L === "en" ? "CHANGELOG.md" : "CHANGELOG.vi.md"}">${t.clMore} ${icon("arrow")}</a>
+  </div>`
+        : ""}
+
   <h2 id="faq" class="reveal">${t.faqH2}</h2>
   ${faq.map((f) => `<details class="glass reveal"><summary>${f.q}</summary><p>${f.a}</p></details>`).join("\n  ")}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",
@@ -24,7 +24,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsc && node scripts/copy-assets.mjs",
+    "build": "node scripts/gen-changelog.mjs && tsc && node scripts/copy-assets.mjs",
     "start": "node dist/index.js",
     "serve": "node dist/index.js serve",
     "dev": "tsc --watch",
@@ -35,7 +35,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
-    "mongodb": "^6.21.0",
     "node-html-parser": "^8.0.2",
     "sharp": "^0.34.5",
     "zod": "^3.25.0"

package/dist/mongo.js

@@ -1,102 +0,0 @@
-// Optional MongoDB sync layer for the image alt cache.
-// Activates when MONGO_URI env var is set. Silently no-op when absent.
-const MONGO_URI = process.env.MONGO_URI || "";
-const MONGO_DB = process.env.MONGO_DB || "webcake_mcp";
-const MONGO_COLLECTION = process.env.MONGO_COLLECTION || "image_alt_cache";
-let _client = null;
-let _collection = null;
-let _connecting = null;
-async function connect() {
-    if (!MONGO_URI)
-        return null;
-    if (_collection)
-        return _collection;
-    if (_connecting)
-        return _connecting;
-    _connecting = (async () => {
-        try {
-            const { MongoClient } = await import("mongodb");
-            _client = new MongoClient(MONGO_URI, { serverSelectionTimeoutMS: 5000 });
-            await _client.connect();
-            const db = _client.db(MONGO_DB);
-            _collection = db.collection(MONGO_COLLECTION);
-            await _collection.createIndex({ url_key: 1 }, { unique: true });
-            return _collection;
-        }
-        catch (e) {
-            _connecting = null;
-            throw e;
-        }
-    })();
-    return _connecting;
-}
-export function isMongoEnabled() {
-    return !!MONGO_URI;
-}
-export async function mongoUpsertAlts(items) {
-    if (!isMongoEnabled())
-        return { ok: false, reason: "MONGO_URI not set" };
-    const col = await connect();
-    if (!col)
-        return { ok: false, reason: "no collection" };
-    if (!items.length)
-        return { ok: true, upserted: 0 };
-    const now = Date.now();
-    const ops = items.map((it) => ({
-        updateOne: {
-            filter: { url_key: it.url_key },
-            update: {
-                $set: {
-                    url_key: it.url_key,
-                    url: it.url,
-                    alt: it.alt,
-                    source: it.source || "ai",
-                    updated_at: now,
-                },
-                $setOnInsert: { created_at: now },
-            },
-            upsert: true,
-        },
-    }));
-    const res = await col.bulkWrite(ops, { ordered: false });
-    return { ok: true, upserted: res.upsertedCount, modified: res.modifiedCount };
-}
-export async function mongoFindAlts(urlKeys) {
-    if (!isMongoEnabled() || !urlKeys.length)
-        return new Map();
-    const col = await connect();
-    if (!col)
-        return new Map();
-    const cursor = col.find({ url_key: { $in: urlKeys } });
-    const map = new Map();
-    for await (const doc of cursor) {
-        map.set(doc.url_key, doc);
-    }
-    return map;
-}
-export async function mongoListAlts(limit = 100, offset = 0) {
-    if (!isMongoEnabled())
-        return { total: 0, entries: [] };
-    const col = await connect();
-    if (!col)
-        return { total: 0, entries: [] };
-    const total = await col.countDocuments();
-    const entries = await col
-        .find({}, { projection: { _id: 0 } })
-        .sort({ updated_at: -1 })
-        .skip(offset)
-        .limit(limit)
-        .toArray();
-    return { total, entries };
-}
-export async function mongoCloseQuietly() {
-    if (_client) {
-        try {
-            await _client.close();
-        }
-        catch { /* ignore */ }
-        _client = null;
-        _collection = null;
-        _connecting = null;
-    }
-}