webcake-storefront-mcp 1.0.1

package/dist/tools/builder-extras.js

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { resolvePreviewUrl } from "../config.js";
+import { parse as parseHtml } from "node-html-parser";
+const ALLOWED_IMG = /^image\/(jpe?g|png|webp)$/;
+/** 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" });
+    if (!res.ok)
+        throw new Error(`Fetch failed (${res.status}) for ${url}`);
+    const ct = (res.headers.get("content-type") || "").split(";")[0].trim();
+    const ab = await res.arrayBuffer();
+    if (ab.byteLength > maxBytes)
+        throw new Error(`Image too large (${ab.byteLength} bytes, max ${maxBytes}).`);
+    return { buf: Buffer.from(ab), contentType: ct };
+}
+/** Ensure a buffer is jpeg/png/webp (the only types the CDN base64 endpoint accepts). */
+async function toAllowedImage(buf, contentType) {
+    if (ALLOWED_IMG.test(contentType))
+        return { buf, contentType };
+    const sharp = (await import("sharp")).default;
+    const out = await sharp(buf).jpeg({ quality: 85 }).toBuffer();
+    return { buf: out, contentType: "image/jpeg" };
+}
+export function registerBuilderExtraTools(server, api, handle) {
+    // ── 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.`, {
+        query: z.string().describe("Subject to search, e.g. 'coffee shop interior'"),
+        per_page: z.number().min(1).max(30).default(6).describe("How many results (default 6)"),
+        orientation: z.enum(["landscape", "portrait", "square"]).optional().describe("Preferred orientation"),
+    }, ({ query, per_page, orientation }) => handle(async () => {
+        const key = process.env.PEXELS_API_KEY;
+        if (!key)
+            return { error: "PEXELS_API_KEY env var is not set. Add it to use stock image search." };
+        const url = new URL("https://api.pexels.com/v1/search");
+        url.searchParams.set("query", query);
+        url.searchParams.set("per_page", String(per_page));
+        if (orientation)
+            url.searchParams.set("orientation", orientation);
+        const res = await fetch(url, { headers: { Authorization: key } });
+        if (!res.ok)
+            return { error: `Pexels error ${res.status}` };
+        const json = await res.json();
+        const photos = (json.photos || []).map((p) => ({
+            url: p.src && (p.src.large || p.src.original),
+            thumbnail: p.src && p.src.medium,
+            width: p.width,
+            height: p.height,
+            alt: p.alt || "",
+            credit: p.photographer,
+            source: p.url,
+        }));
+        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));
+        }
+        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 };
+    }));
+    // ── Publish the site ────────────────────────────────────────────────────────
+    server.tool("publish_site", `Publish the whole site live — snapshots all current page sources into the live (published) version.
+Note: BuilderX publishes at the SITE level, not per page; publishing makes every saved page go live.
+Two-step safety: dry_run=true (default) describes what will happen; dry_run=false actually publishes.`, {
+        dry_run: z.boolean().default(true).describe("Preview (true) or publish for real (false)"),
+    }, ({ dry_run }) => handle(async () => {
+        const preview_url = await resolvePreviewUrl(api);
+        if (dry_run) {
+            return {
+                dry_run: true,
+                preview_url,
+                note: "This will publish ALL saved pages of the site live. Call again with dry_run=false to publish.",
+            };
+        }
+        const res = await api.publishSite({ is_publish: true });
+        const data = (res && res.data) || res;
+        return { success: true, published_at: data && data.published_at, site: data && data.name, preview_url };
+    }));
+    // ── Ingest reference HTML / URL into a blueprint ────────────────────────────
+    function blueprintFromHtml(html) {
+        const root = parseHtml(html, { blockTextElements: { script: false, style: false } });
+        const text = (el) => (el ? el.text.replace(/\s+/g, " ").trim() : "");
+        const attr = (sel, name) => {
+            const el = root.querySelector(sel);
+            return el ? el.getAttribute(name) : undefined;
+        };
+        const title = text(root.querySelector("title")) || attr('meta[property="og:title"]', "content");
+        const description = attr('meta[name="description"]', "content") || attr('meta[property="og:description"]', "content");
+        const ogImage = attr('meta[property="og:image"]', "content");
+        const headings = root
+            .querySelectorAll("h1, h2, h3")
+            .map((h) => ({ level: h.tagName.toLowerCase(), text: text(h) }))
+            .filter((h) => h.text)
+            .slice(0, 40);
+        const paragraphs = root
+            .querySelectorAll("p")
+            .map((p) => text(p))
+            .filter((t) => t.length > 20)
+            .slice(0, 40);
+        const images = root
+            .querySelectorAll("img")
+            .map((img) => ({ src: img.getAttribute("src"), alt: img.getAttribute("alt") || "" }))
+            .filter((i) => i.src && /^https?:\/\//.test(i.src))
+            .slice(0, 40);
+        const buttons = root
+            .querySelectorAll("a, button")
+            .map((b) => ({ text: text(b), href: b.getAttribute("href") || null }))
+            .filter((b) => b.text && b.text.length < 40)
+            .slice(0, 30);
+        // Collect colours mentioned in inline styles (rough palette signal).
+        const colors = new Set();
+        for (const el of root.querySelectorAll("[style]")) {
+            const style = el.getAttribute("style") || "";
+            for (const m of style.matchAll(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]+\)/g))
+                colors.add(m[0]);
+            if (colors.size > 24)
+                break;
+        }
+        return {
+            title,
+            description,
+            og_image: ogImage,
+            headings,
+            paragraphs,
+            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.",
+        };
+    }
+    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.", {
+        html: z.string().describe("Raw HTML to analyse"),
+    }, ({ html }) => handle(async () => blueprintFromHtml(html)));
+    server.tool("ingest_url", "Fetch a public URL and parse it into a structural blueprint (see ingest_html). Note: client-rendered (React/Vue) pages may return little content.", {
+        url: z.string().describe("Public page URL to analyse"),
+    }, ({ url }) => handle(async () => {
+        const res = await fetch(url, { redirect: "follow", headers: { "User-Agent": "webcake-storefront-mcp" } });
+        if (!res.ok)
+            return { error: `Fetch failed (${res.status}).` };
+        const html = await res.text();
+        const blueprint = blueprintFromHtml(html);
+        if (!blueprint.headings.length && !blueprint.paragraphs.length) {
+            blueprint.warning = "Little text found — the page may be client-rendered (JS). Consider ingest_html with rendered source.";
+        }
+        return { url, status: res.status, ...blueprint };
+    }));
+}

package/dist/tools/builder.js

@@ -0,0 +1,124 @@
+import { z } from "zod";
+import { BUILD_GUIDE } from "../builder/guide.js";
+import { listElements, getElement, buildElement } from "../builder/catalog.js";
+import { buildSection, newPageSkeleton, validatePage, reassignIds, } from "../builder/page.js";
+// Recursive spec for new_section / build_page children.
+const elementSpec = z.object({
+    type: z.string().describe("Element type (see list_elements)"),
+    opts: z.record(z.any()).optional().describe("Factory opts: { style, config, specials, text, src, width, height, ... }"),
+    children: z.array(z.any()).optional().describe("Nested child specs (same shape) for container types"),
+});
+function parseSource(src) {
+    if (src == null)
+        return null;
+    return typeof src === "string" ? JSON.parse(src) : src;
+}
+function newPageId(res) {
+    return (res && res.data && res.data.id) || (res && res.id) || null;
+}
+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()));
+    server.tool("get_element", "Get the full detail of an element type: category, container flag, summary, and a live skeleton node (the authoritative default shape) you can copy and edit.", {
+        type: z.string().describe("Element type, e.g. 'text', 'button', 'grid-product'"),
+    }, ({ type }) => handle(async () => getElement(type)));
+    server.tool("new_element", "Build a single structurally-valid element node from the real builder factory. Returns the node — edit its specials/style, then place it in a section's children.", {
+        type: z.string().describe("Element type (see list_elements)"),
+        opts: z.record(z.any()).optional().describe("Factory opts: { text, src, width, height, style, config, specials, events }"),
+    }, ({ type, opts }) => handle(async () => buildElement(type, opts || {})));
+    server.tool("new_section", `Build a complete section node with children laid out in the builder's vertical grid.
+Pass an array of element specs; each child is stacked top-to-bottom. Nest containers via the child's own 'children'.
+Example children: [{ "type":"text", "opts":{"text":"Welcome","style":{"fontSize":"40px"}} }, { "type":"button", "opts":{"text":"Shop now"} }]`, {
+        children: z.array(elementSpec).default([]).describe("Child element specs, stacked vertically in the section"),
+        section_opts: z.record(z.any()).optional().describe("Optional factory opts for the section node itself"),
+    }, ({ children, section_opts }) => handle(async () => buildSection(children || [], section_opts || {})));
+    server.tool("new_page_skeleton", "Return an empty but valid page source: { sections: [] }. Add sections built with new_section, then save with build_page.", {}, () => handle(async () => newPageSkeleton()));
+    server.tool("validate_page", "Validate a page source ({ sections: [...] }). Returns errors (block saving: duplicate/missing ids, missing types) and warnings (unknown types, form fields without field_name, dangling event targets) plus stats. Always run this before build_page.", {
+        source: z.any().describe("Page source object or JSON string"),
+    }, ({ source }) => handle(async () => {
+        const parsed = parseSource(source);
+        return validatePage(parsed);
+    }));
+    server.tool("build_page", `Create a brand-new page AND set its full content source in one step.
+Two-step safety: call with dry_run=true (default) to validate and preview, then dry_run=false to actually create + save.
+The source must be { sections: [...] } — build sections with new_section. Validation errors block the real save.`, {
+        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)"),
+        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);
+        if (dry_run) {
+            return {
+                dry_run: true,
+                validation,
+                request: { name, slug, type, is_homepage, sections: (parsed && parsed.sections || []).length },
+                hint: validation.valid
+                    ? "Looks valid. Call again with dry_run=false to create and save the page."
+                    : "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 });
+        const pageId = newPageId(created);
+        if (!pageId) {
+            return { error: "Page created but no id was returned; cannot save source.", created };
+        }
+        const saved = await api.updatePageSource(pageId, { source: parsed });
+        return {
+            success: true,
+            page_id: pageId,
+            name,
+            slug,
+            page_source_id: saved && saved.data && saved.data.id,
+            stats: validation.stats,
+        };
+    }));
+    server.tool("add_section", `Append a section to an EXISTING page's source. Reads the current source, appends your section, validates, and (when dry_run=false) saves.
+The section is re-id'd to avoid collisions. Build it with new_section.
+Two-step safety: dry_run=true (default) previews; dry_run=false saves.`, {
+        page_id: z.string().describe("Target page id"),
+        section: z.any().describe("A section node (from new_section) — object or JSON string"),
+        dry_run: z.boolean().default(true).describe("Preview only (true) or save (false)"),
+    }, ({ page_id, section, dry_run }) => handle(async () => {
+        const pagesRes = await api.listPages();
+        const pages = (pagesRes && pagesRes.data) || pagesRes || [];
+        const page = Array.isArray(pages) ? pages.find((p) => p.id === page_id) : null;
+        if (!page)
+            return { error: `Page "${page_id}" not found.` };
+        const source = parseSource(page.source && page.source.source) || newPageSkeleton();
+        if (!Array.isArray(source.sections))
+            source.sections = [];
+        const sectionNode = reassignIds(parseSource(section));
+        if (!sectionNode || sectionNode.type !== "section") {
+            return { error: "Provided 'section' is not a section node (type must be 'section')." };
+        }
+        source.sections.push(sectionNode);
+        const validation = validatePage(source);
+        if (dry_run) {
+            return {
+                dry_run: true,
+                page_id,
+                section_id: sectionNode.id,
+                validation,
+                total_sections: source.sections.length,
+                hint: validation.valid ? "Call again with dry_run=false to save." : "Fix errors before saving.",
+            };
+        }
+        if (!validation.valid)
+            return { error: "Validation failed — not saving.", validation };
+        const saved = await api.updatePageSource(page_id, { source });
+        return {
+            success: true,
+            page_id,
+            section_id: sectionNode.id,
+            total_sections: source.sections.length,
+            page_source_id: saved && saved.data && saved.data.id,
+        };
+    }));
+}

package/dist/tools/cms-files.js

@@ -0,0 +1,255 @@
+import { z } from "zod";
+import { HTTP_FUNCTION_GUIDE } from "../guides.js";
+// ── HTTP function code parsing utilities ──
+/**
+ * Parse exported functions from http_function code.
+ * Tracks braces properly, handles template literals and strings.
+ */
+function parseExportedFunctions(code) {
+    if (!code)
+        return [];
+    const lines = code.split("\n");
+    const functions = [];
+    const exportRe = /^export\s+const\s+(\w+)\s*=/;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(exportRe);
+        if (!m)
+            continue;
+        const fullName = m[1];
+        const underIdx = fullName.indexOf("_");
+        const method = underIdx > 0 ? fullName.slice(0, underIdx) : "";
+        const funcName = underIdx > 0 ? fullName.slice(underIdx + 1) : fullName;
+        const startLine = i + 1;
+        // Find end by tracking brace depth
+        let depth = 0;
+        let started = false;
+        let endLine = startLine;
+        for (let j = i; j < lines.length; j++) {
+            for (const ch of lines[j]) {
+                if (ch === "{") {
+                    depth++;
+                    started = true;
+                }
+                if (ch === "}")
+                    depth--;
+            }
+            if (started && depth <= 0) {
+                endLine = j + 1;
+                break;
+            }
+            if (j === lines.length - 1)
+                endLine = j + 1;
+        }
+        functions.push({
+            name: fullName,
+            method,
+            function_name: funcName,
+            start_line: startLine,
+            end_line: endLine,
+            code: lines.slice(i, endLine).join("\n"),
+        });
+    }
+    return functions;
+}
+/** Extract import block (lines before first export) */
+function extractImports(code) {
+    if (!code)
+        return "";
+    const lines = code.split("\n");
+    const out = [];
+    for (const line of lines) {
+        if (/^export\s/.test(line))
+            break;
+        out.push(line);
+    }
+    return out.join("\n").trim();
+}
+/** Replace a function in the code by name, returns new full content */
+function replaceFunctionByName(code, funcName, newCode) {
+    const funcs = parseExportedFunctions(code);
+    const target = funcs.find((f) => f.name === funcName || f.function_name === funcName);
+    if (!target)
+        throw new Error(`Function "${funcName}" not found in file`);
+    const lines = code.split("\n");
+    const before = lines.slice(0, target.start_line - 1);
+    const after = lines.slice(target.end_line);
+    return [...before, newCode.trimEnd(), ...after].join("\n");
+}
+/** Remove a function from the code by name */
+function removeFunctionByName(code, funcName) {
+    const funcs = parseExportedFunctions(code);
+    const target = funcs.find((f) => f.name === funcName || f.function_name === funcName);
+    if (!target)
+        throw new Error(`Function "${funcName}" not found in file`);
+    const lines = code.split("\n");
+    let start = target.start_line - 1;
+    while (start > 0 && lines[start - 1].trim() === "")
+        start--;
+    lines.splice(start, target.end_line - start);
+    return lines.join("\n");
+}
+/** Build function overview result */
+function buildOverviewResult(content, fileId, schemas, includeGuide) {
+    const funcs = parseExportedFunctions(content);
+    const imports = extractImports(content);
+    const res = {
+        file_id: fileId,
+        total_lines: content.split("\n").length,
+        imports: imports || undefined,
+        functions: funcs.map((f) => ({
+            name: f.name,
+            method: f.method,
+            function_name: f.function_name,
+            start_line: f.start_line,
+            end_line: f.end_line,
+            lines: f.end_line - f.start_line + 1,
+        })),
+        collections: schemas,
+        hint: "Use get_http_function_snippet to read a specific function, or set overview=false to get full file",
+    };
+    if (includeGuide)
+        res.guide = HTTP_FUNCTION_GUIDE;
+    return res;
+}
+/** Helper to extract content and file_id from API response */
+function extractContent(httpFunc) {
+    const content = (httpFunc?.data?.content) || (httpFunc?.content) || "";
+    const fileId = (httpFunc?.data?.id) || (httpFunc?.id) || undefined;
+    return { content, fileId };
+}
+/** Helper to build collection schemas */
+function buildSchemas(collections) {
+    const raw = collections?.data;
+    const list = Array.isArray(raw) ? raw : Array.isArray(raw?.data) ? raw.data : [];
+    return list.map((c) => ({
+        name: c.name,
+        table_name: c.table_name,
+        fields: (c.schema || []).map((f) => ({
+            name: f.name,
+            type: f.type,
+            is_required: f.is_required,
+            reference: f.reference || undefined,
+        })),
+    }));
+}
+export function registerCmsFileTools(server, api, handle) {
+    server.tool("list_cms_files", "List all CMS files (HTTP functions, cron jobs, ...) for the site", {}, () => handle(() => api.listCmsFiles()));
+    server.tool("create_cms_file", `Create a new CMS file. Types: "http_function", "jobs_config", "default"`, {
+        name: z.string().describe("File name"),
+        content: z.string().describe("Code content (JavaScript or JSON)"),
+        type: z.enum(["http_function", "jobs_config", "default"]).default("default").describe("File type"),
+    }, ({ name, content, type }) => handle(() => api.createCmsFile({ name, content, type_create: "backend", type })));
+    server.tool("update_cms_file", "Update the code content of an existing CMS file", {
+        id: z.string().describe("CMS file ID"),
+        content: z.string().describe("New code content"),
+        name: z.string().optional().describe("Rename file"),
+    }, ({ id, content, name }) => handle(() => api.updateCmsFile(id, { content, ...(name && { name }) })));
+    // ── HTTP function — token-optimized read/write ──
+    server.tool("get_http_function", `Get the main HTTP function file. Choose the right mode for your task:
+- overview=true: function names + line ranges only, NO code body. Use for: browsing, understanding structure, finding which function to read.
+- overview=false (DEFAULT): full code + collection schemas. Use for: writing new features, refactoring, understanding full context.
+Tip: for small fixes, use overview first then get_http_function_snippet to read just that function.
+Add include_guide=true on first call to get the coding guide`, {
+        overview: z.boolean().default(false).describe("true=function list only, false=full code (default)"),
+        include_guide: z.boolean().default(false).describe("Include coding guide (only needed once)"),
+    }, ({ overview, include_guide }) => handle(async () => {
+        const [httpFunc, collections] = await Promise.all([
+            api.getHttpFunction(),
+            api.listCollections({ limit: 100 }).catch(() => null),
+        ]);
+        const { content, fileId } = extractContent(httpFunc);
+        const schemas = buildSchemas(collections);
+        if (overview)
+            return buildOverviewResult(content, fileId, schemas, include_guide);
+        const res = { http_function: httpFunc, collections: schemas };
+        if (include_guide)
+            res.guide = HTTP_FUNCTION_GUIDE;
+        return res;
+    }));
+    server.tool("get_http_function_snippet", "Read specific function(s) by name. Much more token-efficient than reading the full file", {
+        function_names: z.array(z.string()).describe("Function names (e.g. ['get_Products', 'post_CreateOrder'])"),
+    }, ({ function_names }) => handle(async () => {
+        const { content } = extractContent(await api.getHttpFunction());
+        const allFuncs = parseExportedFunctions(content);
+        const nameSet = new Set(function_names);
+        const found = allFuncs.filter((f) => nameSet.has(f.name) || nameSet.has(f.function_name));
+        const notFound = function_names.filter((n) => !found.some((f) => f.name === n || f.function_name === n));
+        return {
+            imports: extractImports(content) || undefined,
+            functions: found.map((f) => ({
+                name: f.name, method: f.method, function_name: f.function_name,
+                start_line: f.start_line, end_line: f.end_line, code: f.code,
+            })),
+            not_found: notFound.length ? notFound : undefined,
+        };
+    }));
+    server.tool("edit_http_function", `Edit the HTTP function file by function name — best for targeted changes (fix a bug, rename, add one function).
+For writing multiple new functions or major refactors, use update_http_function with full content instead.
+Actions:
+- "replace_function": replace an ENTIRE function by name with new code. Server finds function boundaries automatically.
+- "add": append new function code at end of file.
+- "remove": remove a function by name.
+- "update_imports": replace the import block (lines before first export).
+Returns updated function list after edit.`, {
+        action: z.enum(["replace_function", "add", "remove", "update_imports"]).describe("Edit action"),
+        function_name: z.string().optional().describe("Target function name (for replace_function and remove)"),
+        code: z.string().optional().describe("New function code (for replace_function and add) or new import block (for update_imports)"),
+    }, ({ action, function_name, code }) => handle(async () => {
+        const httpFunc = await api.getHttpFunction();
+        let { content, fileId } = extractContent(httpFunc);
+        if (action === "replace_function") {
+            if (!function_name)
+                throw new Error("replace_function requires function_name");
+            if (!code)
+                throw new Error("replace_function requires code (the new function code)");
+            content = replaceFunctionByName(content, function_name, code);
+        }
+        else if (action === "add") {
+            if (!code)
+                throw new Error("add requires code");
+            content = content.trimEnd() + "\n\n" + code.trimEnd() + "\n";
+        }
+        else if (action === "remove") {
+            if (!function_name)
+                throw new Error("remove requires function_name");
+            content = removeFunctionByName(content, function_name);
+        }
+        else if (action === "update_imports") {
+            if (code == null)
+                throw new Error("update_imports requires code (the new import block)");
+            const oldImports = extractImports(content);
+            if (oldImports) {
+                content = content.replace(oldImports, code.trimEnd());
+            }
+            else {
+                content = code.trimEnd() + "\n\n" + content;
+            }
+        }
+        await api.createOrUpdateHttpFunction({ content });
+        const schemas = buildSchemas(null);
+        return buildOverviewResult(content, fileId, schemas, false);
+    }));
+    server.tool("update_http_function", `Write the FULL HTTP function file content. Best for: writing new features, major refactors, or changes that touch multiple functions.
+For small targeted edits (fix one function, add one function), use edit_http_function instead.
+After update, auto-deploys to the bundle service`, {
+        content: z.string().describe("Full JS code content"),
+    }, ({ content }) => handle(() => api.createOrUpdateHttpFunction({ content })));
+    server.tool("run_function", `Run a deployed HTTP function. function_name excludes method prefix.
+Example: "get_Products" → function_name="Products", method="GET"`, {
+        function_name: z.string().describe("Function name without method prefix (e.g. 'Products')"),
+        method: z.enum(["GET", "POST", "PUT", "PATCH"]).default("POST").describe("HTTP method"),
+        params: z.record(z.any()).optional().describe("Parameters"),
+    }, ({ function_name, method, params }) => handle(() => api.runFunction(function_name, method, params)));
+    server.tool("debug_function", "Run JS code in debug mode (without deploying). Returns execution result and console logs", {
+        content: z.string().describe("JS code to debug"),
+        function_name: z.string().describe("Function name to run"),
+        params: z.record(z.any()).optional().describe("Test parameters"),
+    }, ({ content, function_name, params }) => handle(() => api.debugFunction({ content, functionName: function_name, params })));
+    server.tool("save_file_version", "Save a version snapshot of a CMS file for rollback", {
+        cms_file_id: z.string().describe("CMS file ID"),
+        content: z.string().describe("Content to save"),
+        is_public: z.boolean().default(false).describe("Mark as public version"),
+    }, ({ cms_file_id, content, is_public }) => handle(() => api.saveFileVersion({ cms_file_id, content, is_public })));
+    server.tool("get_file_versions", "View version history of a CMS file", { cms_file_id: z.string().describe("CMS file ID") }, ({ cms_file_id }) => handle(() => api.getFileVersions({ cms_file_id })));
+    server.tool("toggle_debug_render", "Toggle debug render mode for a CMS file", { cms_file_id: z.string().describe("CMS file ID") }, ({ cms_file_id }) => handle(() => api.toggleDebugRender({ cms_file_id })));
+}

package/dist/tools/collections.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+export function registerCollectionTools(server, api, handle) {
+    server.tool("list_collections", "List all database collections (tables) for the site. Returns collection names, table names, and field counts. Use get_collection for full schema details", {
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+        term: z.string().optional().describe("Search by collection name"),
+    }, ({ page, limit, term }) => handle(async () => {
+        const res = await api.listCollections({ page, limit, term });
+        const collections = (res && res.data) || res || [];
+        if (!Array.isArray(collections))
+            return res;
+        return {
+            data: collections.map((c) => ({
+                id: c.id || c._id,
+                name: c.name,
+                table_name: c.table_name,
+                fields_count: (c.schema || []).length,
+                records_count: c.records_count || undefined,
+            })),
+            total: res.total || collections.length,
+        };
+    }));
+    server.tool("get_collection", "Get a specific collection's details including full schema (field names, types, constraints, references) and records", {
+        id: z.string().describe("Collection ID"),
+    }, ({ id }) => handle(() => api.getCollection(id)));
+    server.tool("query_collection_records", "Query records from a collection by table name. Use to inspect existing data", {
+        table_name: z.string().describe("Collection table name (e.g. 'subscribers', 'custom_orders')"),
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+    }, ({ table_name, page, limit }) => handle(() => api.queryCollectionRecords(table_name, { page, limit })));
+}

package/dist/tools/combos.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+const COMBO_GUIDE = `
+## Combo Product Types
+
+### By item matching:
+- is_variation=true — Variation-based: combo requires specific product variations
+- is_variation=false — Product-based: combo requires specific products (any variation)
+- is_categories=true — Category-based: combo requires items from specific categories with quantities
+
+### Discount types:
+- discount_amount > 0 — Fixed discount amount off combo price
+- is_use_percent=true — Percentage discount (discount_by_percent %), capped by max_discount_by_percent
+- is_value_combo=true — Fixed total price for combo (value_combo)
+- is_free_shipping=true — Combo includes free shipping
+
+### Key Fields:
+- name: combo display name
+- slug: URL-friendly identifier
+- is_activated: whether combo is currently active
+- start_time / end_time: combo schedule (UTC+7)
+- images: combo images array
+- categories: for category-based combos, array of {id, name, count} specifying required categories and quantities
+- combo_product_variations: items that make up the combo (products/variations with count)
+- bonus_items: free/bonus products included with the combo
+`;
+export function registerComboTools(server, api, handle) {
+    server.tool("list_combos", "List all combo/bundle products of the site. Use get_combo_items for combo composition details", {
+        page: z.number().optional().describe("Page number (default: 1)"),
+        limit: z.number().optional().describe("Items per page (default: 20)"),
+        term: z.string().optional().describe("Search by combo name"),
+        include_guide: z.boolean().optional().describe("Include combo type reference guide"),
+    }, ({ page, limit, term, include_guide }) => handle(async () => {
+        const res = await api.listCombos({ page, limit, term });
+        const combos = (res && res.combo_products) || (res && res.data) || [];
+        const result = {
+            data: Array.isArray(combos)
+                ? combos.map((c) => ({
+                    id: c.id,
+                    name: c.name,
+                    slug: c.slug,
+                    custom_id: c.custom_id || undefined,
+                    is_activated: c.is_activated,
+                    is_variation: c.is_variation,
+                    is_categories: c.is_categories || undefined,
+                    discount_amount: c.discount_amount || undefined,
+                    is_use_percent: c.is_use_percent || undefined,
+                    discount_by_percent: c.discount_by_percent || undefined,
+                    max_discount_by_percent: c.max_discount_by_percent || undefined,
+                    is_value_combo: c.is_value_combo || undefined,
+                    value_combo: c.value_combo || undefined,
+                    is_free_shipping: c.is_free_shipping || undefined,
+                    start_time: c.start_time || undefined,
+                    end_time: c.end_time || undefined,
+                    images: c.images || undefined,
+                    categories: c.categories || undefined,
+                    inserted_at: c.inserted_at,
+                }))
+                : combos,
+            total: res.total || (Array.isArray(combos) ? combos.length : 0),
+        };
+        if (include_guide)
+            result.guide = COMBO_GUIDE.trim();
+        return result;
+    }));
+    server.tool("get_combo_items", "Get items (products/variations) and bonus products that compose a combo. Returns combo_items (required items with count) and bonus_items (free gifts)", {
+        combo_product_id: z.string().describe("Combo product ID"),
+        is_variation_bonus: z.boolean().optional().describe("Whether bonus items are variation-based"),
+    }, ({ combo_product_id, is_variation_bonus }) => handle(async () => {
+        const res = await api.getComboItems(combo_product_id, { is_variation_bonus });
+        return (res && res.data && res.data.data) || (res && res.data) || res;
+    }));
+}