WebCake Storefront

WebCake Storefront MCP

英语 · Tiếng Việt

用日常语言描述商店页面——AI 会为你构建、验证页面，并将其发布到你的 WebCake 店面。

⭐ 如果这为你省下了一个下午拖动模块的时间，点个星标吧——每个星标都能让一个独立项目继续运营。

“为我的咖啡店构建一个页面——包含带有‘立即选购’按钮的主视觉区、商品网格和订单表单。保存并发布。”

……随后，你的 WebCake/StoreCake 网站上就会出现一个真正可编辑的页面。无需拖动模块，无需学习架构，也无需手写 JSON。

---

🧩 工作原理

此服务是 AI 助手与店面之间的桥梁。AI 不会猜测页面应该是什么样子——它会向此 MCP 询问。此 MCP 熟悉完整的 BuilderX 组件模型，会验证结果并保存页面。

   You              AI assistant          webcake-storefront MCP          WebCake / StoreCake
  ┌──────┐  prompt  ┌────────────┐  tools ┌───────────────────────┐  API ┌──────────┐
  │ idea │ ───────► │  Claude /  │ ─────► │ • knows the BuilderX  │ ───► │  a real  │
  │      │          │  Cursor /  │        │   component model     │      │ editable │
  │      │ ◄─────── │  Windsurf  │ ◄───── │ • builds + validates  │ ◄─── │  page on │
  └──────┘ live URL └────────────┘ result │ • saves + publishes   │      │ your site│
                                          └───────────────────────┘      └──────────┘

1. 你提出需求：用日常语言说明目标、品牌、版块、商品和表单字段。
2. AI 从 MCP 学习模型：了解元素目录、CSS 网格布局和断点——从而构建出真正的店面页面，而不是凭空猜测。
3. AI 组装并验证 { sections: [...] } 页面源代码。validate_page 会在保存前检查重复 id、错误的网格布局，以及缺少名称的表单字段。
4. AI 将页面保存到你的网站——先进行空运行预览，再正式保存；publish_site 会将页面上线。
5. 你会获得预览 URL——打开页面，在编辑器中调整，完成。

为什么它可靠

📚 了解真实模型	提供 130 多种 BuilderX 组件类型（文本、图片、按钮、表单、商品网格、购物车、倒计时、图库……），直接移植自构建器自身的工厂——与编辑器生成的结构完全相同。
✅ 保存前进行验证	执行结构检查（唯一 id、有效网格、带名称的表单字段、可用的事件目标），确保页面保存后不会出错。
🛡️ 默认安全	每次写入都先进行空运行——预览更改；只有在你确认后才会修改网站。
✏️ 精确编辑	提出一项更改（“把 CTA 改成绿色”），它就只会编辑那个元素——其他所有 id、样式和模块都保持原样。

💡 销售货到付款（COD）或在线支付？它也支持完整的电商模型——商品、变体、购物车、订单、促销和组合商品。

---

✨ 你可以构建

对 AI 说一句话 → 获得一个完整且可编辑的店铺页面：

	只需说……
🛒 产品页	“为我的护肤精华制作一个单品页面——图片库、价格、带购物车的订单表单。”
🏬 店铺首页	“一个首页——主视觉横幅、精选产品网格、订阅简报表单。”
⚡ 限时抢购	“一个限时抢购页面——醒目的倒计时、折扣产品网格、固定的购买按钮。”
🎟️ 活动 / 网络研讨会	“一个注册页面——倒计时、活动日程、注册表单。”
💌 邀请函	“一份婚礼邀请函——姓名、日期、地图、RSVP 表单。”
📰 博客 / 内容	“一个博客索引页，包含精选文章和订阅框。”
🔗 个人简介链接页	“一个个人简介链接页——头像、简短简介、5 个链接按钮、社交账号。”

……然后说**“把 CTA 改成绿色”或“添加第 4 个特色项”**，它只会编辑对应的区块。

🤖 可在 Claude Desktop、Claude Code、Cursor、Windsurf、VS Code 或任何支持 MCP 的客户端中使用——而且构建指南 + 元素目录工具无需调用后端，因此你可以先探索模型，再粘贴令牌。

---

底层原理

这是一个 MCP（Model Context Protocol）服务，用于向 AI Agent 介绍 WebCake/StoreCake 店铺构建器 （BuilderX）的组件模型，并将它们连接到后端。AI 会生成完整的 { sections: [...] } 页面源代码；build_page 用于创建并保存页面，publish_site 则会将整个网站上线。

除了页面创作，它还能访问你的真实店铺：页面和自定义代码、产品、订单、系列、 博客文章、促销活动、组合商品、主题、客户和自动化——总计约 280 个工具。

方式	适用场景	身份验证
npx（本地）——在你的电脑上运行	个人日常使用，完全掌控	浏览器 login，或令牌 + 会话
远程（serve）——自托管 Streamable-HTTP	团队、claude.ai 对话、持续运行	?jwt= 链接 / x-webcake-jwt 标头

构建 + 目录工具（get_build_guide、list_elements、get_element、new_section、 validate_page）无需任何配置；所有读取或写入你网站的操作都需要令牌 + 会话。

---

🚀 连接

任选一种方式。两种方式都会将完整的店铺工具包交给你的 AI 工具。无需编写代码。

① npx——在你的电脑上运行（推荐）

无需安装，始终使用最新版本，需要 Node.js 18+。一行命令即可配置 IDE：

# Interactive — pick your IDE(s) and paste your credentials
npx -y webcake-storefront-mcp install

# Non-interactive — configure every supported IDE at once
npx -y webcake-storefront-mcp install --ide all --token <token> --session <session-id>

# Remove the server from every IDE config
npx -y webcake-storefront-mcp uninstall

支持的目标：claude-desktop、claude-code、cursor、windsurf、vscode 或 all。 只想运行服务（手动配置）？npx -y webcake-storefront-mcp。

② 浏览器登录——无需复制/粘贴令牌

npx -y webcake-storefront-mcp login

这会打开构建器的连接页面；点击 Connect 后，你的令牌 + 会话会保存在本地，并自动加载。

远程 URL——自托管，无需在每个客户端上安装

npx -y webcake-storefront-mcp serve --port 8787

然后让任意客户端连接到 http://<host>:8787/mcp?jwt=<TOKEN>（支持标头的客户端可以改为发送 x-webcake-jwt；在聊天中使用 switch_site 选择网站）。PEXELS_API_KEY 等服务端密钥 保存在主机上——在 VPS 上使用很方便。

⚠️ ?jwt= 链接包含你的个人令牌——请像对待密码一样保护它，并在生产环境中使用 HTTPS。

---

⚙️ 配置

需要提供两个值：WEBCAKE_TOKEN（Bearer JWT）和 WEBCAKE_SESSION_ID（作为 x-session-id 发送）。你可以在运行时选择站点——只需在聊天中提出，AI 就会调用 list_my_sites / switch_site（你的选择会保存并在下次会话中沿用），因此无需设置 WEBCAKE_SITE_ID。

基础 URL 来自一个命名环境——设置 WEBCAKE_ENV（或 --env），就无需手动输入 URL：

WEBCAKE_ENV	api	app（登录）	preview
local	http://localhost:24679	http://localhost:5173	demo.localhost:24679/<siteId>
staging	https://api.staging.storecake.io	https://staging.webcake.io	staging2.webcake.me/<siteId>
prod（默认）	https://api.storefront.webcake.io	https://webcake.io	<site_slug>.webcake.me

使用 WEBCAKE_API_URL / WEBCAKE_APP_URL 覆盖预设值。可选，在服务端配置： PEXELS_API_KEY（search_images）。也可以在聊天中通过 update_auth 和 switch_site 设置令牌 / 会话 / 站点——这些值会保存到本地配置文件 ~/.webcake-storefront-mcp/。

如何获取令牌和会话 ID

1. 打开 WebCake 构建器并登录。
2. 打开 DevTools（F12）→ Network 标签页 → 点击任意 API 请求。
3. 在 Request Headers 中：Authorization: Bearer … → WEBCAKE_TOKEN；x-session-id: … → WEBCAKE_SESSION_ID。
4. 无需预先提供站点 ID——在聊天中运行 list_my_sites，然后运行 switch_site 选择站点（下次会自动沿用）。

---

🧰 工具一览

约 280 个工具。核心工具组用于构建页面；其余工具用于读取和编辑你的线上店铺。

分组	工具	所需信息
构建页面	get_build_guide · list_elements · get_element · new_element · new_section · new_page_skeleton · validate_page · build_page · add_section	目录工具：无需信息
媒体与导入	search_images（Pexels）· upload_images（CDN）· ingest_html · ingest_url（重建参考页面）	—
页面与代码	list_pages · get_page_source · search_page_elements · get_page_element · update_page_element(s) · create_page · update_page · update_page_source · 自定义 CSS/JS · 页面内容 · 全局分区 · publish_site	令牌 + 会话
电商	商品 · 订单 · 集合 · 促销 · 组合	令牌 + 会话
内容与店铺	博客文章 · 主题 / 站点样式 · 应用 · 客户 · send_mail	令牌 + 会话
后端代码	HTTP 函数的增删改查（get_http_function、edit_http_function、run_function、debug_function……）	令牌 + 会话
上下文	get_current_context · list_my_sites · switch_site · update_auth · toggle_confirm_mode	令牌
站点方案	get_site_subscription（当前方案、状态、剩余天数）· count_my_sites（按方案 / 自定义域名 / 回收站统计）· list_plans	令牌

所有写入操作默认使用 dry_run=true——它会预览确切变更，只有使用 dry_run=false 重新运行时才会修改你的站点。

💬 推荐提示词

为我构建一个 WebCake 店铺页面，内容为 <品牌/优惠>。使用 webcake-storefront MCP： 调用 get_build_guide、list_elements，使用 new_section 构建各个分区， 反复运行 validate_page，直到错误数为零，然后运行 build_page（先进行试运行），再运行 publish_site。

---

⭐ 喜欢这个想法？点个星标

这是一个由个人维护的开源项目，每一个 ⭐ 都能切实推动项目发展，也能帮助其他开发者发现它。

• ⭐ 给仓库点个星标 — 只需 2 秒，却能带来巨大动力。
• 🐛 提交问题 — 无论是 Bug、缺少组件，还是一个想法，都欢迎提出。
• 🔁 分享给还在逐块搭建店铺页面的朋友。

为 WebCake 社区倾注 ❤️ 打造。感谢你的支持。