webcake-storefront-mcp 1.0.1

package/dist/tools/products.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export function registerProductTools(server, api, handle) {
+    server.tool("list_products", "List products of the site (metadata only: id, name, slug, price, image, status). Use get_product for full details", {
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+        term: z.string().optional().describe("Search by product name"),
+    }, ({ page, limit, term }) => handle(async () => {
+        const res = await api.listProducts({ page, limit, term });
+        const products = (res && res.data) || res || [];
+        if (!Array.isArray(products))
+            return res;
+        return {
+            data: products.map((p) => ({
+                id: p.id,
+                name: p.name,
+                slug: p.slug,
+                custom_id: p.custom_id || undefined,
+                image: p.image || undefined,
+                price: p.price || undefined,
+                is_published: p.is_published,
+                total_sold: p.total_sold || 0,
+                rating: p.rating || undefined,
+                categories: p.categories || undefined,
+                updated_at: p.updated_at,
+            })),
+            total: res.total || products.length,
+        };
+    }));
+    server.tool("get_product", "Get full product details by ID: name, description, price, variations, images, attributes, SEO, etc.", {
+        id: z.string().describe("Product ID"),
+    }, ({ id }) => handle(() => api.getProduct(id)));
+    server.tool("search_products", "Search products by keyword. Returns matching products with basic info", {
+        term: z.string().describe("Search keyword"),
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+    }, ({ term, page, limit }) => handle(() => api.searchProducts({ term, page, limit })));
+    server.tool("list_categories", "List all product categories of the site", {}, () => handle(() => api.listCategories()));
+}

package/dist/tools/promotions.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+const PROMOTION_TYPES = `
+## Promotion Types (type field)
+- "normal" — Standard product discount (fixed price or level-based)
+- "same_price" — Fixed price for all items (đồng giá)
+- "coupon" — Coupon/voucher code discount
+- "coupon_id_multiple_times" — Reusable coupon code
+- "discount_by_coupon_id" — Discount by coupon ID
+- "promotion_order" — Order-level discount (by total amount)
+- "promotion_category" — Category-level discount
+- "x_get_y_prod" — Buy X get Y products free
+- "x_get_y_category" — Buy X get Y from category free
+
+## Promotion Classify (promotion_classify)
+- "product" — Apply to specific products/variations
+- "order" — Apply to entire order
+- "category" — Apply to product categories
+- "shipping" — Free shipping promotion
+
+## Key Fields
+- is_activated: whether promotion is currently active
+- start_time / end_time: promotion schedule (UTC+7)
+- priority_level: higher = applied first when conflicts
+- coupon_info: coupon settings (code, max_uses, min_order, etc.)
+- promo_code_info: promo code settings
+- is_free_shipping: whether promotion gives free shipping
+- level_order_prices: tiered discounts by order amount
+- arr_level_promotion: tiered discount levels
+- arr_price_promotion: tiered price discounts
+- payment_methods: restrict to specific payment methods
+- warehouse_ids: restrict to specific warehouses
+- customer_tags: restrict to specific customer tags
+- is_detail_time: has specific day/time scheduling
+- is_hidden: hidden from storefront but still active
+`;
+export function registerPromotionTools(server, api, handle) {
+    server.tool("list_promotions", "List all promotions/discounts of the site (metadata only). Use get_promotion for full details", {
+        page: z.number().optional().describe("Page number (default: 1)"),
+        limit: z.number().optional().describe("Items per page (default: 20)"),
+        include_guide: z.boolean().optional().describe("Include promotion type reference guide"),
+    }, ({ page, limit, include_guide }) => handle(async () => {
+        const res = await api.listPromotions({ page, limit });
+        const promotions = (res && res.data) || [];
+        const result = {
+            data: Array.isArray(promotions)
+                ? promotions.map((p) => ({
+                    id: p.id,
+                    name: p.name,
+                    type: p.type,
+                    promotion_classify: p.promotion_classify || undefined,
+                    is_activated: p.is_activated,
+                    start_time: p.start_time || undefined,
+                    end_time: p.end_time || undefined,
+                    priority_level: p.priority_level,
+                    is_free_shipping: p.is_free_shipping || undefined,
+                    is_hidden: p.is_hidden || undefined,
+                    coupon_info: p.coupon_info || undefined,
+                    used_count: p.used_count || 0,
+                    inserted_at: p.inserted_at,
+                }))
+                : promotions,
+            total: res.total_entries || res.total || (Array.isArray(promotions) ? promotions.length : 0),
+        };
+        if (include_guide)
+            result.guide = PROMOTION_TYPES.trim();
+        return result;
+    }));
+    server.tool("get_promotion", "Get full promotion details by ID: name, type, schedule, discount rules, coupon settings, items, bonus products, etc.", {
+        id: z.string().describe("Promotion ID"),
+    }, ({ id }) => handle(async () => {
+        const res = await api.getPromotion(id);
+        return (res && res.data && res.data.promotion) || (res && res.data) || res;
+    }));
+    server.tool("get_promotion_items", "Get products/variations/categories attached to a promotion. Returns items with discount details (fixed_prices, level_info, coupon_item_info)", {
+        id: z.string().describe("Promotion ID"),
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+    }, ({ id, page, limit }) => handle(async () => {
+        const res = await api.getPromotionItems(id, { page, limit });
+        return (res && res.data && res.data.result) || (res && res.data) || res;
+    }));
+    server.tool("get_active_promotions", "Get all currently active promotions (is_activated=true and within start_time/end_time range)", {}, () => handle(async () => {
+        const res = await api.getActivePromotions();
+        const promotions = (res && res.data && res.data.promotions) || (res && res.data) || [];
+        return {
+            data: Array.isArray(promotions)
+                ? promotions.map((p) => ({
+                    id: p.id,
+                    name: p.name,
+                    type: p.type,
+                    promotion_classify: p.promotion_classify || undefined,
+                    is_activated: p.is_activated,
+                    start_time: p.start_time || undefined,
+                    end_time: p.end_time || undefined,
+                    priority_level: p.priority_level,
+                    is_free_shipping: p.is_free_shipping || undefined,
+                    coupon_info: p.coupon_info || undefined,
+                    level_order_prices: p.level_order_prices || undefined,
+                    arr_level_promotion: p.arr_level_promotion || undefined,
+                    arr_price_promotion: p.arr_price_promotion || undefined,
+                }))
+                : promotions,
+            total: Array.isArray(promotions) ? promotions.length : 0,
+        };
+    }));
+    server.tool("search_promotions", "Search/filter promotions with advanced filters: by type, status (coming_soon/in_progress/finished), keyword, date range", {
+        term: z.string().optional().describe("Search by promotion name"),
+        type: z.string().optional().describe("Filter by type: normal, same_price, coupon, coupon_id_multiple_times, discount_by_coupon_id, promotion_order, promotion_category, x_get_y_prod, x_get_y_category"),
+        status: z.number().optional().describe("Filter by time status: 1=coming_soon, 2=in_progress, 3=finished"),
+        is_activated: z.boolean().optional().describe("Filter by active status"),
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+    }, ({ term, type, status, is_activated, page, limit }) => handle(async () => {
+        const query = {};
+        if (term)
+            query.term = term;
+        if (type)
+            query.type = type;
+        if (status != null)
+            query.status = status;
+        if (is_activated != null)
+            query.is_activated = is_activated;
+        if (page)
+            query.page = page;
+        if (limit)
+            query.limit = limit;
+        const res = await api.searchPromotions(query);
+        const data = (res && res.data && res.data.result) || (res && res.data) || res;
+        return data;
+    }));
+}

package/dist/tools/site-style.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+const TEMPLATE_THEMES_URL = "https://api.storecake.io/api/v1/templates/list_themes";
+const THEME_CATALOG_TTL_MS = 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 15000;
+let _themeCatalogCache = null;
+async function fetchTemplateThemes({ page = 1, limit = 12, lang = "vi", q = "" } = {}) {
+    const url = new URL(TEMPLATE_THEMES_URL);
+    url.searchParams.set("page", String(page));
+    url.searchParams.set("limit", String(limit));
+    url.searchParams.set("lang", lang);
+    if (q)
+        url.searchParams.set("q", q);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch(url, {
+            headers: {
+                accept: "application/json, text/plain, */*",
+                "accept-language": lang,
+                authorization: "Bearer null",
+                origin: "https://webcake.io",
+                referer: "https://webcake.io/",
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            const body = await res.text().catch(() => "");
+            throw new Error(`list_template_themes ${res.status}: ${body}`);
+        }
+        return await res.json();
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function getThemeCatalog(force = false) {
+    if (!force && _themeCatalogCache && Date.now() - _themeCatalogCache.at < THEME_CATALOG_TTL_MS) {
+        return _themeCatalogCache.map;
+    }
+    const map = new Map();
+    let page = 1;
+    const limit = 100;
+    for (let i = 0; i < 5; i++) {
+        const res = await fetchTemplateThemes({ page, limit });
+        const themes = (res && res.themes) || [];
+        for (const t of themes) {
+            map.set(t.id, {
+                id: t.id,
+                name: t.name,
+                preview_url: t.preview_url || "",
+                thumbnail: t.thumbnail || "",
+                categories: (t.categories || []).map((c) => c.name).filter(Boolean),
+            });
+        }
+        if (themes.length < limit)
+            break;
+        page += 1;
+    }
+    _themeCatalogCache = { at: Date.now(), map };
+    return map;
+}
+function parseThemeDescription(d) {
+    if (typeof d !== "string")
+        return { description_vi: "", description_en: "" };
+    try {
+        const j = JSON.parse(d);
+        return {
+            description_vi: (j.description_vi || "").slice(0, 600),
+            description_en: (j.description_en || "").slice(0, 300),
+        };
+    }
+    catch {
+        return { description_vi: d.slice(0, 600), description_en: "" };
+    }
+}
+export function registerSiteStyleTools(server, api, handle) {
+    server.tool("get_site_info", "Get full site information: name, domain, settings (colors, typography, layout, language, payment methods, etc.)", {}, () => handle(async () => {
+        const res = await api.getSite();
+        const site = (res && res.data) || res;
+        if (!site)
+            return { error: "Site not found" };
+        return {
+            id: site.id,
+            name: site.name,
+            domain: site.domain,
+            custom_domain: site.custom_domain || undefined,
+            logo: site.logo || undefined,
+            favicon: site.favicon || undefined,
+            settings: site.settings || {},
+            created_at: site.created_at,
+        };
+    }));
+    server.tool("list_themes", "List all custom themes of the site. Returns theme name, colors, typographies, transitions, and which one is active", {}, () => handle(() => api.listThemes()));
+    server.tool("list_template_themes", "Search/list the public Webcake template marketplace (api.storecake.io). Use to match customer brief against existing templates by keyword. Returns id, name, preview_url, thumbnail, categories", {
+        q: z.string().optional().describe("Keyword to search themes"),
+        page: z.number().optional().describe("Page number (default 1)"),
+        limit: z.number().optional().describe("Items per page (default 12)"),
+        lang: z.string().optional().describe("Language code (default 'vi')"),
+    }, ({ q, page, limit, lang }) => handle(async () => {
+        const res = await fetchTemplateThemes({
+            q: q || "",
+            page: page || 1,
+            limit: limit || 12,
+            lang: lang || "vi",
+        });
+        const themes = ((res && res.themes) || []).map((t) => ({
+            id: t.id,
+            name: t.name,
+            preview_url: t.preview_url,
+            thumbnail: t.thumbnail,
+            categories: (t.categories || []).map((c) => c.name),
+            preview_img: (t.site && t.site.preview_img && (t.site.preview_img["1920_1080"] || t.site.preview_img["430_932"])) ||
+                null,
+        }));
+        return {
+            page: res && res.page,
+            limit: res && res.limit,
+            total: res && res.total_entries,
+            count: themes.length,
+            themes,
+        };
+    }));
+    server.tool("semantic_search_themes", "Semantic search across the theme marketplace using bge-m3 embeddings (cosine similarity). Use when the brief is a natural-language description of industry + features (e.g. 'website mỹ phẩm có popup minigame và loyalty'), not just keywords. Returns top matches with theme_id, score, name, preview_url, thumbnail, description_vi/en", {
+        query: z.string().describe("Natural-language description of the desired website (industry + features)"),
+        limit: z.number().optional().describe("Number of matches to return (default 5, max 10)"),
+    }, ({ query, limit }) => handle(async () => {
+        const q = (query || "").trim();
+        if (!q)
+            return { error: "query is required" };
+        const cap = Math.min(Math.max(limit || 5, 1), 10);
+        const raw = await api.semanticSearchThemes(q);
+        const pairs = Array.isArray(raw && raw.results) ? raw.results : [];
+        let catalog;
+        try {
+            catalog = await getThemeCatalog();
+        }
+        catch {
+            catalog = new Map();
+        }
+        const matches = pairs.slice(0, cap).map(([te, score]) => {
+            const themeId = te && te.theme_id;
+            const info = catalog.get(themeId) || {};
+            const desc = parseThemeDescription(te && te.description);
+            return {
+                theme_id: themeId,
+                score: typeof score === "number" ? Number(score.toFixed(4)) : null,
+                name: info.name || null,
+                preview_url: info.preview_url || null,
+                thumbnail: info.thumbnail || null,
+                categories: info.categories || [],
+                description_vi: desc.description_vi,
+                description_en: desc.description_en,
+            };
+        });
+        return { query: q, count: matches.length, matches };
+    }));
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "webcake-storefront-mcp",
+  "version": "1.0.1",
+  "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
+  "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
+  "type": "module",
+  "bin": {
+    "webcake-storefront-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-assets.mjs",
+    "start": "node dist/index.js",
+    "serve": "node dist/index.js serve",
+    "dev": "tsc --watch",
+    "smoke": "node dist/smoke.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm run smoke"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "better-sqlite3": "^12.8.0",
+    "mongodb": "^6.21.0",
+    "node-html-parser": "^8.0.2",
+    "sharp": "^0.34.5",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}