webcake-storefront-mcp 1.31.3 → 1.31.5

package/README.md

@@ -1,4 +1,8 @@
-# 🏪 WebCake Storefront MCP
+<p align="center">
+  <img src="./assets/logo.svg" alt="WebCake Storefront MCP" width="96" height="96">
+</p>
+
+<h1 align="center">WebCake Storefront MCP</h1>
 
 **English** · [Tiếng Việt](./README.vi.md)
 
@@ -78,7 +82,7 @@ An MCP (Model Context Protocol) server that teaches AI agents the **WebCake/Stor
 page source; `build_page` creates the page and saves it, and `publish_site` makes the whole site live.
 
 Beyond page authoring, it exposes your real store: pages & custom code, products, orders, collections,
-blog articles, promotions, combos, themes, customers, and automation — **~101 tools** in total.
+blog articles, promotions, combos, themes, customers, and automation — **~280 tools** in total.
 
 | Method | Best for | Auth |
 |--------|----------|------|
@@ -166,7 +170,7 @@ in chat via `update_auth` and `switch_site` — saved to a local config file at
 
 ## 🧰 The tools at a glance
 
-~101 tools. The headline group **builds pages**; the rest read and edit your live store.
+~280 tools. The headline group **builds pages**; the rest read and edit your live store.
 
 | Group | Tools | Needs |
 |-------|-------|-------|

package/README.vi.md

@@ -1,4 +1,8 @@
-# 🏪 WebCake Storefront MCP
+<p align="center">
+  <img src="./assets/logo.svg" alt="WebCake Storefront MCP" width="96" height="96">
+</p>
+
+<h1 align="center">WebCake Storefront MCP</h1>
 
 [English](./README.md) · **Tiếng Việt**
 
@@ -78,7 +82,7 @@ WebCake/StoreCake (BuilderX)** và kết nối tới backend. AI tạo nguồn t
 `build_page` tạo + lưu trang, `publish_site` đưa cả site lên live.
 
 Ngoài dựng trang, nó mở ra cả store thật: trang & custom code, sản phẩm, đơn hàng, collection,
-bài blog, khuyến mãi, combo, theme, khách hàng, automation — **~101 tool** tổng cộng.
+bài blog, khuyến mãi, combo, theme, khách hàng, automation — **~280 tool** tổng cộng.
 
 | Cách | Hợp cho | Auth |
 |--------|----------|------|
@@ -165,7 +169,7 @@ trong chat bằng `update_auth` và `switch_site` — lưu vào file cấu hình
 
 ## 🧰 Bộ công cụ tổng quan
 
-~101 tool. Nhóm chủ lực **dựng trang**; phần còn lại đọc và sửa store thật của bạn.
+~280 tool. Nhóm chủ lực **dựng trang**; phần còn lại đọc và sửa store thật của bạn.
 
 | Nhóm | Tool | Cần |
 |-------|-------|-------|

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.5",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "Column definitions accepted by create_collection and update_collection_columns now support five new optional fields: note (help text for the…",
+    "vi": "Định nghĩa cột được chấp nhận bởi create_collection và update_collection_columns nay hỗ trợ thêm năm trường tùy chọn mới: note (ghi chú/mô tả cho…"
+  },
+  {
+    "v": "1.31.4",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "The guide returned by get_http_function and get_site_custom_code now includes a verified end-to-end \"Custom data TABLES (collections)\" section…",
+    "vi": "Hướng dẫn trả về bởi get_http_function và get_site_custom_code nay bổ sung phần \"Custom data TABLES (collections)\" đã được xác minh thực tế, ghi lại…"
+  },
   {
     "v": "1.31.3",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New create_collection tool creates a custom data table by accepting a name and a schema array of field definitions (with types such as string,…",
     "vi": "Tool mới create_collection tạo bảng dữ liệu tùy chỉnh bằng cách nhận tham số name và mảng schema chứa định nghĩa các trường (với các kiểu dữ liệu…"
-  },
-  {
-    "v": "1.30.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New list_customers tool browses or searches the site's customer list; accepts page, limit, and term (name/phone/email keyword) and returns a compact…",
-    "vi": "Tool mới list_customers duyệt hoặc tìm kiếm danh sách khách hàng của site; nhận các tham số page, limit và term (từ khóa tên/điện thoại/email) và…"
-  },
-  {
-    "v": "1.29.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "scaffold_global_sections now accepts a logo parameter (hosted image URL) that renders an image element in the header instead of the brand-name text…",
-    "vi": "scaffold_global_sections nay nhận thêm tham số logo (URL hình ảnh được host) để hiển thị phần tử image trong header thay vì node text tên thương hiệu."
   }
 ]

package/dist/guides.js

@@ -101,6 +101,21 @@ await Members.updateOne({ id: created.id }, { tien_con_lai: 100000 });
     const userId = request.customer?.id ?? ""; if (!userId) return { mess: "NO_ACCOUNT_CALL" };
     try { /* … */ return { mess: "OK", ...data }; } catch (err) { console.error(err?.message || err); return { mess: "SYSTEM_ERROR" }; }
 
+## Custom data TABLES (collections) — end-to-end (VERIFIED flow)
+A "collection" is a custom DB table. To stand one up and use it from a function:
+1. Create the table + columns with the MCP tools: create_collection({ name, columns:[{name,type},…] })
+   then update_collection_columns to change them. (Types: string|text|integer|float|boolean|
+   naive_datetime|binary_id|map|array.) The table always has id/inserted_at/updated_at/creator_id.
+2. READ rows directly with the MCP tool query_collection_records({ table_name, where, order_by }).
+3. WRITE rows from an HTTP function via webcake-data — db.model(table) gives full CRUD on it:
+   const T = db.model("my_table");
+   const row = await T.create({ email: "a@b.com" });          // insert
+   await T.updateOne({ id: row.id }, { email: "c@d.com" });    // update
+   await T.deleteMany({ email: "a@b.com" });                   // delete
+   const rows = await T.find({ … }).select([…]).limit(50);     // query
+   (There is NO direct dashboard record-INSERT API — record writes MUST go through a function.
+    Deploy the function with the update_http_function MCP tool, then call it with run_function.)
+
 ## Built-in @webcake/* modules (first arg is always request; they auth via global.token — these run
 ## INSIDE the function sandbox, so they reach the /cms_function endpoints the dashboard JWT can't)
 Thin wrappers over the backend's /cms_function/{site_id}/... endpoints. Pass request so

package/dist/server.js

@@ -1,5 +1,16 @@
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { installTools, buildToolGroupIndex } from "./tools/registry.js";
+/** Server version, read from package.json so it always tracks the published release. */
+export const SERVER_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
 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.
@@ -25,7 +36,7 @@ function makeResult(data) {
 /** Build a fully-wired MCP server bound to the given API client. */
 export function createServer(api, opts = {}) {
     const toolsSpec = opts.tools ?? process.env.WEBCAKE_TOOLS;
-    const server = new McpServer({ name: "webcake-storefront", version: "1.0.0" }, { instructions: `${INSTRUCTIONS}\n\n${buildToolGroupIndex(toolsSpec)}` });
+    const server = new McpServer({ name: "webcake-storefront", version: SERVER_VERSION }, { instructions: `${INSTRUCTIONS}\n\n${buildToolGroupIndex(toolsSpec)}` });
     const handle = async (fn) => {
         try {
             return makeResult(await fn());

package/dist/tools/collections.js

@@ -40,18 +40,39 @@ export function registerCollectionTools(server, api, handle) {
         return api.queryCollectionRecords(table_name, query);
     }));
     // ── Table-management tools (VERIFIED live: create table, edit columns, delete table). ──
-    // Field type ∈ string | text | integer | float | boolean | naive_datetime | binary_id | map | array.
+    // Custom-column types (matches the builderx_spa column editor; backend accepts these + more):
+    //   text | rich_text | url | integer | float | decimal | boolean | reference | color |
+    //   image | media_gallery | video | audio | document | date | naive_datetime | time |
+    //   address | object | array.
+    // (string/binary_id/map are backend aliases of text/reference/object; binary_id & naive_datetime
+    //  are reserved for SYSTEM columns like id/inserted_at — don't pick them for custom fields.)
     const COLUMN = z.object({
         name: z.string().describe("Column name (snake_case)."),
-        type: z.string().describe("string | text | integer | float | boolean | naive_datetime | binary_id | map | array"),
+        type: z
+            .string()
+            .describe("text | rich_text | url | integer | float | decimal | boolean | reference | color | image | media_gallery | video | audio | document | date | naive_datetime | time | address | object | array"),
         display_name: z.string().optional(),
         is_required: z.boolean().optional(),
         is_unique: z.boolean().optional(),
+        note: z.string().optional().describe("Help text / description for the column."),
+        default: z.any().optional().describe("Default value for the column."),
+        reference: z
+            .string()
+            .optional()
+            .describe("For type 'reference' only: the referenced table_name, or a system entity (customer | product | article | blog | variation)."),
+        reference_type: z
+            .enum(["system", "collection"])
+            .optional()
+            .describe("For type 'reference' only: 'system' (built-in entity) or 'collection' (another custom table)."),
+        date_default_type: z
+            .enum(["empty", "added", "specific"])
+            .optional()
+            .describe("For type 'date'/'naive_datetime' only: how the default date is set."),
     });
     server.tool("create_collection", "Create a new collection (custom data TABLE). It starts with the system columns (id/inserted_at/updated_at/creator_id); pass `columns` to add custom fields. NOTE: to WRITE records into it, use an HTTP function (webcake-data: db.model(table).create({...})) — the dashboard has no direct record-insert API. See get_http_function for the SDK guide.", {
         name: z.string().describe("Display name."),
         table_name: z.string().optional().describe("Table name (snake_case, unique). Defaults to name."),
-        columns: z.array(COLUMN).optional().describe("Custom columns to add, e.g. [{name:'email',type:'string'},{name:'amount',type:'integer'}]."),
+        columns: z.array(COLUMN).optional().describe("Custom columns to add, e.g. [{name:'email',type:'text'},{name:'amount',type:'integer'}]."),
     }, ({ name, table_name, columns }) => handle(async () => {
         const tn = (table_name || name).trim();
         const created = await api.createCollection({ name, table_name: tn });

package/dist/web-guide.js

@@ -872,7 +872,7 @@ export function guideHtml(origin, lang = "vi") {
     <details style="margin-top:18px;padding:0">
       <summary>${L === "vi" ? "Dành cho người dùng nâng cao / lập trình viên" : "For advanced users / developers"}</summary>
       <p>${L === "vi" ? "Danh sách đầy đủ các công cụ và lệnh kỹ thuật:" : "Full list of tools and technical commands:"}</p>
-      <pre>${L === "vi" ? "~101 tool: get_build_guide · list_elements · get_element · new_element · new_section · new_page_skeleton · validate_page · build_page · add_section · list_pages · get_page_source · search_page_elements · update_page_element · create_page · update_page · update_page_source · publish_site · list_cms_files · get_http_function · edit_http_function · run_function · debug_function · get_current_context · list_my_sites · switch_site · update_auth · toggle_confirm_mode · send_mail · …và nhiều hơn nữa" : "~101 tools: get_build_guide · list_elements · get_element · new_element · new_section · new_page_skeleton · validate_page · build_page · add_section · list_pages · get_page_source · search_page_elements · update_page_element · create_page · update_page · update_page_source · publish_site · list_cms_files · get_http_function · edit_http_function · run_function · debug_function · get_current_context · list_my_sites · switch_site · update_auth · toggle_confirm_mode · send_mail · …and more"}</pre>
+      <pre>${L === "vi" ? "~280 tool: get_build_guide · list_elements · get_element · new_element · new_section · new_page_skeleton · validate_page · build_page · add_section · list_pages · get_page_source · search_page_elements · update_page_element · create_page · update_page · update_page_source · publish_site · list_cms_files · get_http_function · edit_http_function · run_function · debug_function · get_current_context · list_my_sites · switch_site · update_auth · toggle_confirm_mode · send_mail · …và nhiều hơn nữa" : "~280 tools: get_build_guide · list_elements · get_element · new_element · new_section · new_page_skeleton · validate_page · build_page · add_section · list_pages · get_page_source · search_page_elements · update_page_element · create_page · update_page · update_page_source · publish_site · list_cms_files · get_http_function · edit_http_function · run_function · debug_function · get_current_context · list_my_sites · switch_site · update_auth · toggle_confirm_mode · send_mail · …and more"}</pre>
     </details>
   </div>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.31.3",
+  "version": "1.31.5",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",