\n\n**English** · [Tiếng Việt](./README.vi.md)\n\n[](https://www.npmjs.com/package/webcake-storefront-mcp)\n[](https://www.npmjs.com/package/webcake-storefront-mcp)\n[](https://github.com/vuluu2k/webcake-storefront-mcp/stargazers)\n[](https://modelcontextprotocol.io)\n\n> **Describe a store page in plain words — your AI builds it, validates it, and publishes it to your WebCake storefront.**\n\n> ⭐ **If this saves you an afternoon of dragging blocks around, [give it a star](https://github.com/vuluu2k/webcake-storefront-mcp) — every star keeps a solo project alive.**\n\n> *\"Build a page for my coffee shop — a hero with a Shop Now button, a product grid, and an order form. Save it and publish.\"*\n\n…and a real, **editable** page appears on your WebCake/StoreCake site. No dragging blocks, no learning the schema, no hand-writing JSON.\n\n---\n\n## 🧩 How it works\n\nThis server is the **bridge** between your AI assistant and your storefront. The AI never *guesses* what a\npage looks like — it asks this MCP, which knows the entire BuilderX component model, validates the result, and saves it.\n\n```text\n You AI assistant webcake-storefront MCP WebCake / StoreCake\n ┌──────┐ prompt ┌────────────┐ tools ┌───────────────────────┐ API ┌──────────┐\n │ idea │ ───────► │ Claude / │ ─────► │ • knows the BuilderX │ ───► │ a real │\n │ │ │ Cursor / │ │ component model │ │ editable │\n │ │ ◄─────── │ Windsurf │ ◄───── │ • builds + validates │ ◄─── │ page on │\n └──────┘ live URL └────────────┘ result │ • saves + publishes │ │ your site│\n └───────────────────────┘ └──────────┘\n```\n\n1. **You ask** in plain language — goal, brand, sections, products, form fields.\n2. **The AI learns the model** from the MCP: the element catalog, the CSS-grid layout, the breakpoints — so it builds a *real* storefront page, not a guess.\n3. **It assembles + validates** the `{ sections: [...] }` page source. `validate_page` catches duplicate ids, broken grids, and form fields without a name **before** anything is saved.\n4. **It saves** to your site — dry-run preview first, then for real — and `publish_site` makes it live.\n5. **You get the preview URL** — open it, tweak in the editor, done.\n\n### Why it's reliable\n\n| | |\n|---|---|\n| 📚 **Knows the real model** | Serves 130+ BuilderX component types (text, image, button, form, product grid, cart, countdown, gallery…) ported **straight from the builder's own factory** — the exact same shapes the editor produces. |\n| ✅ **Validates before saving** | Structural checks (unique ids, valid grid, form fields with names, working event targets) so the page isn't broken when it lands. |\n| 🛡️ **Safe by default** | Every write is **dry-run first** — preview the change, nothing touches your site until you confirm. |\n| ✏️ **Edits surgically** | Ask for one change (\"make the CTA green\") and it edits *only* that element — every other id, style, and block stays exactly as it was. |\n\n> 💡 Selling **COD or online**? It speaks the full commerce model too — products, variations, cart, orders, promotions, combos.\n\n---\n\n## ✨ What you can build\n\nOne sentence to your AI → a finished, **editable** storefront page:\n\n| | Just say… |\n|---|---|\n| 🛒 **Product page** | *\"A one-product page for my skincare serum — gallery, price, an order form with cart.\"* |\n| 🏬 **Storefront home** | *\"A homepage — hero banner, featured product grid, a newsletter form.\"* |\n| ⚡ **Flash sale** | *\"A flash-sale page — big countdown, discounted product grid, a sticky Buy button.\"* |\n| 🎟️ **Event / webinar** | *\"A registration page — countdown, agenda, a sign-up form.\"* |\n| 💌 **Invitation** | *\"A wedding invite — names, date, a map, an RSVP form.\"* |\n| 📰 **Blog / content** | *\"A blog index with featured posts and a subscribe box.\"* |\n| 🔗 **Link-in-bio** | *\"A link-in-bio — avatar, short bio, 5 link buttons, socials.\"* |\n\n…then **\"make the CTA green\"** or **\"add a 4th feature\"** and it edits *only* that block.\n\n> 🤖 Works in **Claude Desktop, Claude Code, Cursor, Windsurf, VS Code**, or any MCP-capable client — and the **build guide + element catalog tools need zero backend calls**, so you can explore the model before pasting a token.\n\n---\n\n## Under the hood\n\nAn MCP (Model Context Protocol) server that teaches AI agents the **WebCake/StoreCake storefront builder\n(BuilderX) component model** and connects them to the backend. The AI produces the full `{ sections: [...] }`\npage source; `build_page` creates the page and saves it, and `publish_site` makes the whole site live.\n\nBeyond page authoring, it exposes your real store: pages & custom code, products, orders, collections,\nblog articles, promotions, combos, themes, customers, and automation — **~280 tools** in total.\n\n| Method | Best for | Auth |\n|--------|----------|------|\n| **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, or a token + session |\n| **Remote (`serve`)** — self-host Streamable-HTTP | Teams, the claude.ai dialog, always-on | `?jwt=` link / `x-webcake-jwt` header |\n\nThe **build + catalog tools** (`get_build_guide`, `list_elements`, `get_element`, `new_section`,\n`validate_page`) work with **zero config**; everything that reads or writes your site needs a token + session.\n\n---\n\n## 🚀 Get connected\n\nPick **one**. Both hand your AI tool the full storefront toolkit. No coding.\n\n### ① `npx` — runs on your machine (recommended)\n\nZero install, always the latest version, needs Node.js 18+. **One line** configures your IDE:\n\n```bash\n# Interactive — pick your IDE(s) and paste your credentials\nnpx -y webcake-storefront-mcp install\n\n# Non-interactive — configure every supported IDE at once\nnpx -y webcake-storefront-mcp install --ide all --token --session \n\n# Remove the server from every IDE config\nnpx -y webcake-storefront-mcp uninstall\n```\n\nTargets: `claude-desktop`, `claude-code`, `cursor`, `windsurf`, `vscode`, or `all`.\nJust want to run the server (configure by hand)? `npx -y webcake-storefront-mcp`.\n\n### ② Browser login — no token copy/paste\n\n```bash\nnpx -y webcake-storefront-mcp login\n```\n\nOpens the builder's **connect page**; click *Connect* and your token + session are saved locally and picked up automatically.\n\n### Remote URL — self-hosted, nothing per-client to install\n\n```bash\nnpx -y webcake-storefront-mcp serve --port 8787\n```\n\nThen point any client at `http://:8787/mcp?jwt=` (clients that support headers can send\n`x-webcake-jwt` instead; pick the site in chat with `switch_site`). Server-side secrets like `PEXELS_API_KEY`\nlive on the host — handy on a VPS.\n\n> ⚠️ A `?jwt=` link contains your personal token — treat it like a password and use **HTTPS** in production.\n\n---\n\n## ⚙️ Configuration\n\nTwo values are required: **`WEBCAKE_TOKEN`** (Bearer JWT) and **`WEBCAKE_SESSION_ID`** (sent as\n`x-session-id`). You pick the **site at runtime** — just ask in chat and the AI calls `list_my_sites` /\n`switch_site` (your choice is saved and reused next session), so no `WEBCAKE_SITE_ID` is needed.\n\nBase URLs come from a **named environment** — set `WEBCAKE_ENV` (or `--env`) and you never type a URL:\n\n| `WEBCAKE_ENV` | api | app (login) | preview |\n|---|---|---|---|\n| `local` | `http://localhost:24679` | `http://localhost:5173` | `demo.localhost:24679/` |\n| `staging` | `https://api.staging.storecake.io` | `https://staging.webcake.io` | `staging2.webcake.me/` |\n| **`prod`** (default) | `https://api.storefront.webcake.io` | `https://webcake.io` | `.webcake.me` |\n\nOverride a preset with `WEBCAKE_API_URL` / `WEBCAKE_APP_URL`. Optional, configured server-side:\n`PEXELS_API_KEY` (search_images). Token / session / site can also be set\nin chat via `update_auth` and `switch_site` — saved to a local config file at `~/.webcake-storefront-mcp/`.\n\n\nHow to get your token + session\n\n1. Open the WebCake builder and log in.\n2. Open DevTools (`F12`) → **Network** tab → click any API request.\n3. In **Request Headers**: `Authorization: Bearer …` → `WEBCAKE_TOKEN`; `x-session-id: …` → `WEBCAKE_SESSION_ID`.\n4. No site id needed up front — in chat, run `list_my_sites` then `switch_site` to choose the site (remembered next time).\n\n\n\n---\n\n## 🧰 The tools at a glance\n\n~280 tools. The headline group **builds pages**; the rest read and edit your live store.\n\n| Group | Tools | Needs |\n|-------|-------|-------|\n| **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 |\n| **Media & ingest** | `search_images` (Pexels) · `upload_images` (CDN) · `ingest_html` · `ingest_url` (recreate a reference page) | — |\n| **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 |\n| **Commerce** | products · orders · collections · promotions · combos | token + session |\n| **Content & store** | blog articles · themes / site style · apps · customers · `send_mail` | token + session |\n| **Backend code** | HTTP-function CRUD (`get_http_function`, `edit_http_function`, `run_function`, `debug_function`…) | token + session |\n| **Context** | `get_current_context` · `list_my_sites` · `switch_site` · `update_auth` · `toggle_confirm_mode` | token |\n\nEvery write **defaults to `dry_run=true`** — it previews the exact change and only touches your site when you re-run with `dry_run=false`.\n\n## 💬 Suggested prompt\n\n> Build me a WebCake storefront page for <brand/offer>. Use the webcake-storefront MCP:\n> call `get_build_guide`, `list_elements`, build the sections with `new_section`,\n> `validate_page` until zero errors, then `build_page` (dry-run first) and `publish_site`.\n\n---\n\n## ⭐ Like the idea? Drop a star\n\nThis is a solo, open-source project — every ⭐ genuinely keeps it moving and helps other builders find it.\n\n- ⭐ **[Star the repo](https://github.com/vuluu2k/webcake-storefront-mcp)** — 2 seconds, huge motivation.\n- 🐛 **[Open an issue](https://github.com/vuluu2k/webcake-storefront-mcp/issues)** — a bug, a missing component, or just an idea.\n- 🔁 **Share it** with anyone still building store pages block by block.\n\n[](https://star-history.com/#vuluu2k/webcake-storefront-mcp&Date)\n\n> Built with ❤️ for the WebCake community. Thanks for being here.\n",
"bytes": 11205,
"sha": "22face9c76e69326e813f1c7f34afedb6dc8016df670158b17d95095024ee854",
"repo_slug": "vuluu2k/webcake-storefront-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_vuluu2k_webcake_storefront_mcp_ffedba31/readme"
}
![\"WebCake](\"./assets/logo.svg\"){kind=logo}
\n