webcake-storefront-mcp 1.0.1

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { makeApi, resolveSettings } from "./config.js";
+const HELP = `webcake-storefront-mcp — MCP server for the WebCake/StoreCake storefront builder
+
+Usage: npx -y webcake-storefront-mcp [command] [options]
+
+Commands:
+  (none)             start the stdio MCP server (use this in IDE configs)
+  install            configure the server in your IDE(s) — interactive or via flags
+  uninstall          remove the server from your IDE configs
+  login              grab your token via the browser (saved to the local config db)
+  serve [--port N]   run the remote Streamable-HTTP server (default 8787; or PORT env)
+  help, --help, -h   show this help
+
+Global options:
+  --env <local|staging|prod>   pick the API + app base URLs (default prod)
+`;
+/** Read a global `--env <name>` / `--env=<name>` flag and expose it via WEBCAKE_ENV
+ * so every subcommand (stdio, install, login, serve) resolves the same endpoints. */
+function applyEnvFlag(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--env" && argv[i + 1])
+            process.env.WEBCAKE_ENV = argv[i + 1];
+        else if (a.startsWith("--env="))
+            process.env.WEBCAKE_ENV = a.slice("--env=".length);
+    }
+}
+async function main() {
+    applyEnvFlag(process.argv);
+    const sub = process.argv[2];
+    if (sub === "help" || sub === "--help" || sub === "-h") {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (sub === "install" || sub === "uninstall") {
+        const { runInstaller } = await import("./install.js");
+        const rest = sub === "uninstall" ? ["--uninstall", ...process.argv.slice(3)] : process.argv.slice(3);
+        await runInstaller(rest);
+        return;
+    }
+    if (sub === "login") {
+        const { runLogin } = await import("./auth/login.js");
+        await runLogin(process.argv.slice(3));
+        return;
+    }
+    if (sub === "serve" || sub === "http" || sub === "serve-http") {
+        const { startHttpServer } = await import("./http.js");
+        const flagIdx = process.argv.indexOf("--port");
+        const raw = (flagIdx !== -1 ? process.argv[flagIdx + 1] : undefined) ?? process.env.PORT;
+        const port = Number(raw);
+        await startHttpServer(Number.isFinite(port) && port > 0 ? port : 8787);
+        return;
+    }
+    // Default: stdio MCP server.
+    const settings = resolveSettings();
+    if (!settings.apiUrl) {
+        console.error("Required: WEBCAKE_API_URL (env var or saved via `login` / update_auth tool).");
+        console.error("Run `npx -y webcake-storefront-mcp install` to set things up.");
+        process.exit(1);
+    }
+    const api = makeApi();
+    const server = createServer(api);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[webcake-storefront] MCP server ready on stdio.");
+}
+main().catch((err) => {
+    console.error("[webcake-storefront] fatal:", err);
+    process.exit(1);
+});

package/dist/install.js

@@ -0,0 +1,140 @@
+// Installer: writes (or removes) this MCP server's entry in the config files of the
+// supported IDEs. Flag-driven; falls back to a couple of interactive prompts on a TTY.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline/promises";
+const SERVER_KEY = "webcake-storefront";
+function parseArgs(argv) {
+    const o = { uninstall: false, ides: [] };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--uninstall")
+            o.uninstall = true;
+        else if (a === "--ide")
+            o.ides.push(...(argv[++i] || "").split(",").map((s) => s.trim()).filter(Boolean));
+        else if (a === "--env")
+            o.env = argv[++i];
+        else if (a === "--token" || a === "--jwt")
+            o.token = argv[++i];
+        else if (a === "--session" || a === "--session-id" || a === "--wsid")
+            o.sessionId = argv[++i];
+        else if (a === "--site" || a === "--site-id")
+            o.siteId = argv[++i];
+        else if (a === "--api-url" || a === "--api-base")
+            o.apiUrl = argv[++i];
+        else if (a === "--npx")
+            o.launch = "npx";
+        else if (a === "--local")
+            o.launch = "local";
+    }
+    return o;
+}
+const HOME = homedir();
+const APP_SUPPORT = process.platform === "darwin" ? join(HOME, "Library", "Application Support") : join(HOME, ".config");
+// IDE -> config file + whether it nests under "mcpServers" (vs "mcp").
+const IDE_CONFIGS = {
+    "claude-desktop": { path: join(APP_SUPPORT, "Claude", "claude_desktop_config.json"), key: "mcpServers" },
+    "claude-code": { path: join(HOME, ".claude.json"), key: "mcpServers" },
+    cursor: { path: join(HOME, ".cursor", "mcp.json"), key: "mcpServers" },
+    windsurf: { path: join(HOME, ".codeium", "windsurf", "mcp_config.json"), key: "mcpServers" },
+    vscode: { path: join(APP_SUPPORT, "Code", "User", "mcp.json"), key: "mcpServers" },
+};
+const ALL_IDES = Object.keys(IDE_CONFIGS);
+function resolveLaunch(opts) {
+    const self = fileURLToPath(import.meta.url);
+    const ranViaNpx = self.includes("/_npx/") || self.includes("\\_npx\\");
+    const useNpx = opts.launch === "npx" || (opts.launch !== "local" && ranViaNpx);
+    if (useNpx)
+        return { command: "npx", args: ["-y", "webcake-storefront-mcp"] };
+    const entry = join(dirname(self), "index.js");
+    return { command: "node", args: [entry] };
+}
+function buildEnv(opts) {
+    const env = {};
+    if (opts.env)
+        env.WEBCAKE_ENV = opts.env;
+    if (opts.apiUrl)
+        env.WEBCAKE_API_URL = opts.apiUrl;
+    if (opts.token)
+        env.WEBCAKE_TOKEN = opts.token;
+    if (opts.sessionId)
+        env.WEBCAKE_SESSION_ID = opts.sessionId;
+    if (opts.siteId)
+        env.WEBCAKE_SITE_ID = opts.siteId;
+    return env;
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJson(path, data) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+function applyToIde(ide, opts, launch, env) {
+    const cfg = IDE_CONFIGS[ide];
+    if (!cfg)
+        return `skip ${ide} (unknown)`;
+    const json = readJson(cfg.path);
+    const bag = (json[cfg.key] ||= {});
+    if (opts.uninstall) {
+        if (!(SERVER_KEY in bag))
+            return `${ide}: nothing to remove`;
+        delete bag[SERVER_KEY];
+        writeJson(cfg.path, json);
+        return `${ide}: removed (${cfg.path})`;
+    }
+    bag[SERVER_KEY] = {
+        command: launch.command,
+        args: launch.args,
+        ...(Object.keys(env).length ? { env } : {}),
+    };
+    writeJson(cfg.path, json);
+    return `${ide}: configured (${cfg.path})`;
+}
+async function promptMissing(opts) {
+    if (!process.stdin.isTTY)
+        return;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        if (!opts.ides.length) {
+            const ans = (await rl.question(`IDE(s) [${ALL_IDES.join(", ")}, all]: `)).trim();
+            opts.ides = ans === "all" || ans === "" ? ALL_IDES : ans.split(",").map((s) => s.trim());
+        }
+        if (!opts.uninstall && !opts.token && !process.env.WEBCAKE_TOKEN) {
+            const t = (await rl.question("Token (paste JWT, or leave blank to set later): ")).trim();
+            if (t)
+                opts.token = t;
+        }
+        if (!opts.uninstall && !opts.siteId && !process.env.WEBCAKE_SITE_ID) {
+            const s = (await rl.question("Site ID (optional): ")).trim();
+            if (s)
+                opts.siteId = s;
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runInstaller(argv) {
+    const opts = parseArgs(argv);
+    await promptMissing(opts);
+    let ides = opts.ides.length ? opts.ides : ALL_IDES;
+    if (ides.includes("all"))
+        ides = ALL_IDES;
+    const launch = resolveLaunch(opts);
+    const env = buildEnv(opts);
+    console.error(opts.uninstall ? "Removing webcake-storefront MCP…" : "Configuring webcake-storefront MCP…");
+    for (const ide of ides)
+        console.error("  " + applyToIde(ide, opts, launch, env));
+    if (!opts.uninstall)
+        console.error("\nDone. Restart your IDE to pick up the new MCP server.");
+}

package/dist/mongo.js

@@ -0,0 +1,102 @@
+// 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;
+    }
+}

package/dist/server.js

@@ -0,0 +1,63 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerContextTools } from "./tools/context.js";
+import { registerCmsFileTools } from "./tools/cms-files.js";
+import { registerPageTools } from "./tools/pages.js";
+import { registerCollectionTools } from "./tools/collections.js";
+import { registerArticleTools } from "./tools/articles.js";
+import { registerCustomerTools } from "./tools/customers.js";
+import { registerAutomationTools } from "./tools/automation.js";
+import { registerProductTools } from "./tools/products.js";
+import { registerOrderTools } from "./tools/orders.js";
+import { registerSiteStyleTools } from "./tools/site-style.js";
+import { registerAppTools } from "./tools/apps.js";
+import { registerPromotionTools } from "./tools/promotions.js";
+import { registerComboTools } from "./tools/combos.js";
+import { registerGlobalSourceTools } from "./tools/global-sources.js";
+import { registerImageTools } from "./tools/images.js";
+import { registerBuilderTools } from "./tools/builder.js";
+import { registerBuilderExtraTools } from "./tools/builder-extras.js";
+const INSTRUCTIONS = `You are an AI assistant connected to the WebCake/StoreCake storefront platform via MCP tools.
+
+IMPORTANT: When the user asks ANY question about their website, store, products, orders, pages, or code — you MUST use the available tools to look up real data before answering. Never guess.
+
+You can also BUILD pages: use get_build_guide, list_elements, get_element to learn the BuilderX component model, new_section/new_element to compose, validate_page to check, then build_page (dry_run first) to create. Publishing is site-level via publish_site.
+
+Workflow:
+1. On first interaction, call get_current_context to confirm the connected site.
+2. Before answering a site-specific question, query the relevant tool.
+3. When building a page, read get_build_guide first and validate before saving.
+4. Always reply in the user's language; keep Vietnamese with full diacritics.`;
+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) {
+    const server = new McpServer({ name: "webcake-storefront", version: "1.0.0" }, { instructions: INSTRUCTIONS });
+    const handle = async (fn) => {
+        try {
+            return makeResult(await fn());
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+        }
+    };
+    registerContextTools(server, api, handle);
+    registerCmsFileTools(server, api, handle);
+    registerPageTools(server, api, handle);
+    registerCollectionTools(server, api, handle);
+    registerArticleTools(server, api, handle);
+    registerCustomerTools(server, api, handle);
+    registerAutomationTools(server, api, handle);
+    registerProductTools(server, api, handle);
+    registerOrderTools(server, api, handle);
+    registerSiteStyleTools(server, api, handle);
+    registerAppTools(server, api, handle);
+    registerPromotionTools(server, api, handle);
+    registerComboTools(server, api, handle);
+    registerGlobalSourceTools(server, api, handle);
+    registerImageTools(server, api, handle);
+    registerBuilderTools(server, api, handle);
+    registerBuilderExtraTools(server, api, handle);
+    return server;
+}

package/dist/smoke.js

@@ -0,0 +1,81 @@
+/**
+ * Offline smoke test (no MCP transport, no DB/native deps): exercises the page-builder
+ * building blocks so a release can verify them without a client. Run: npm run smoke
+ */
+import { listElements, getElement, buildElement, ELEMENT_TYPES, isKnownType } from "./builder/catalog.js";
+import { newPageSkeleton, buildSection, validatePage, reassignIds, walk, } from "./builder/page.js";
+let failures = 0;
+const check = (name, cond, extra) => {
+    if (cond) {
+        console.log(`  ok  ${name}`);
+    }
+    else {
+        failures++;
+        console.log(`FAIL  ${name}`, extra ?? "");
+    }
+};
+console.log("== catalog: factory registry is well-formed ==");
+{
+    check("element types are non-empty", ELEMENT_TYPES.length > 0, ELEMENT_TYPES.length);
+    check("no duplicate element types", new Set(ELEMENT_TYPES).size === ELEMENT_TYPES.length);
+    const cat = listElements();
+    check("listElements total matches type count", cat.total === ELEMENT_TYPES.length);
+    check("listElements has categories", Object.keys(cat.categories).length > 0);
+    check("getElement('section') is a container", getElement("section").container === true);
+    check("isKnownType('button')", isKnownType("button"));
+    check("isKnownType('nope') is false", !isKnownType("nope"));
+}
+console.log("== factory: nodes are structurally valid ==");
+{
+    const section = buildElement("section");
+    check("section has type + children[]", section.type === "section" && Array.isArray(section.children));
+    const text = buildElement("text", { text: "Hello" });
+    check("text carries specials.text", text.specials?.text === "Hello");
+    check("ids are prefixed by type", /^TEXT-/.test(text.id));
+    let threw = false;
+    try {
+        buildElement("definitely-not-a-type");
+    }
+    catch (e) {
+        threw = e?.code === "UNKNOWN_TYPE";
+    }
+    check("buildElement throws UNKNOWN_TYPE for bad type", threw);
+}
+console.log("== page: grid composition + validation ==");
+{
+    const skeleton = newPageSkeleton();
+    check("skeleton is { sections: [] }", Array.isArray(skeleton.sections) && skeleton.sections.length === 0);
+    const hero = buildSection([
+        { type: "text", opts: { text: "Welcome" } },
+        { type: "button", opts: { text: "Buy" } },
+    ]);
+    check("section grid is 1xN", hero.runtime.config.grid === "1x2", hero.runtime.config.grid);
+    check("children get grid positions", hero.children.every((c) => c.runtime.config.columnStart === 1));
+    const src = newPageSkeleton();
+    src.sections.push(hero);
+    const v = validatePage(src);
+    check("built page validates", v.valid === true, v.errors);
+    check("stats count elements", v.stats.total_elements === 3, v.stats);
+    // duplicate ids must fail validation
+    const dup = newPageSkeleton();
+    const a = buildElement("section");
+    const b = buildElement("section");
+    b.id = a.id;
+    dup.sections.push(a, b);
+    check("duplicate ids fail validation", validatePage(dup).valid === false);
+    // reassignIds gives a fresh id
+    const before = a.id;
+    reassignIds(a);
+    check("reassignIds changes the id", a.id !== before);
+    // walk visits every node
+    let count = 0;
+    walk(src, () => {
+        count += 1;
+    });
+    check("walk visits all nodes", count === 3, count);
+}
+if (failures > 0) {
+    console.error(`\n${failures} smoke check(s) failed.`);
+    process.exit(1);
+}
+console.log("\nAll smoke checks passed.");

package/dist/tools/apps.js

@@ -0,0 +1,7 @@
+import { z } from "zod";
+export function registerAppTools(server, api, handle) {
+    server.tool("list_apps", "List all installed applications/subscriptions of the site. Returns app type, status, and settings", {}, () => handle(() => api.listApps()));
+    server.tool("get_app", "Get a specific installed app by type ID. Common types: 1=CMS, 2=Product Design, 10=Multilingual, etc.", {
+        type: z.string().describe("App type ID"),
+    }, ({ type }) => handle(() => api.getApp(type)));
+}

package/dist/tools/articles.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export function registerArticleTools(server, api, handle) {
+    server.tool("list_articles", "List blog articles (metadata only, without HTML content). Use get_article to get full content", {
+        page: z.number().optional().describe("Page number"),
+        limit: z.number().optional().describe("Items per page"),
+        category_id: z.string().optional().describe("Filter by category"),
+    }, ({ page, limit, category_id }) => handle(async () => {
+        const res = await api.listArticles({ page, limit, category_id });
+        const articles = (res && res.data) || res || [];
+        if (!Array.isArray(articles))
+            return res;
+        return {
+            data: articles.map((a) => ({
+                id: a.id || a._id,
+                name: a.name,
+                slug: a.slug,
+                summary: a.summary || undefined,
+                category_id: a.category_id || undefined,
+                tags: a.tags || undefined,
+                is_hidden: a.is_hidden,
+                created_at: a.created_at,
+                updated_at: a.updated_at,
+            })),
+            total: res.total || articles.length,
+        };
+    }));
+    server.tool("get_article", "Get article details by ID", {
+        id: z.string().describe("Article ID"),
+    }, ({ id }) => handle(() => api.getArticle(id)));
+    server.tool("create_article", "Create a new blog article", {
+        name: z.string().describe("Article title"),
+        slug: z.string().describe("URL slug"),
+        content: z.string().describe("HTML content"),
+        summary: z.string().optional().describe("Summary"),
+        category_id: z.string().optional().describe("Category ID"),
+        tags: z.array(z.string()).optional().describe("Tags"),
+        images: z.array(z.string()).optional().describe("Image URLs"),
+        is_hidden: z.boolean().default(false).describe("Hide from public"),
+    }, (params) => handle(() => api.createArticle(params)));
+    server.tool("update_article", "Update a blog article", {
+        id: z.string().describe("Article ID"),
+        name: z.string().optional().describe("New title"),
+        slug: z.string().optional().describe("New slug"),
+        content: z.string().optional().describe("New HTML content"),
+        summary: z.string().optional().describe("New summary"),
+        category_id: z.string().optional().describe("Category ID"),
+        tags: z.array(z.string()).optional().describe("Tags"),
+        is_hidden: z.boolean().optional().describe("Hide from public"),
+    }, ({ id, ...params }) => handle(() => api.updateArticle(id, params)));
+    server.tool("delete_article", "Delete a blog article", {
+        id: z.string().describe("Article ID"),
+    }, ({ id }) => handle(() => api.deleteArticle(id)));
+}

package/dist/tools/automation.js

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export function registerAutomationTools(server, api, handle) {
+    server.tool("send_mail", "Send email via CMS automation", {
+        to: z.string().describe("Recipient email"),
+        subject: z.string().describe("Email subject"),
+        body: z.string().describe("Email body (supports HTML)"),
+    }, (params) => handle(() => api.sendMail(params)));
+}