webcake-storefront-mcp 1.31.2 → 1.31.4

package/dist/api.js

@@ -353,25 +353,29 @@ export class WebcakeCmsApi {
         const headers = await this.cmsApiHeader();
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { query, headers });
     }
-    /** Insert a record into a collection. Body = the record fields. CMS-api-key authed. */
-    async insertCollectionRecord(tableName, record) {
+    /** Create a collection (TABLE). VERIFIED body: { name, table_name } — the table starts with
+     *  only the system columns (id/inserted_at/updated_at/creator_id). Add custom columns after
+     *  with updateCollectionSchema(). (Sending a schema in the create body 500s.) */
+    async createCollection(params) {
         const headers = await this.cmsApiHeader();
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { body: record, headers });
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
     }
-    /** Update a record by id. Body = the changed fields. CMS-api-key authed. */
-    async updateCollectionRecord(tableName, recordId, record) {
+    /** Get one collection by id (includes its full `schema`). */
+    async getCollectionById(id) {
         const headers = await this.cmsApiHeader();
-        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { body: record, headers });
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { headers });
     }
-    /** Delete a record by id. CMS-api-key authed. */
-    async deleteCollectionRecord(tableName, recordId) {
+    /** Add/edit columns: PATCH the collection's FULL schema array. NOTE: this REPLACES the schema,
+     *  so it MUST include the existing system columns + your custom ones. Each custom column =
+     *  { name, type, display_name?, create_type:"custom", is_required?, is_unique? }. */
+    async updateCollectionSchema(id, schema) {
         const headers = await this.cmsApiHeader();
-        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { headers });
+        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { body: { schema }, headers, timeout: 60000 });
     }
-    /** Create a collection (table). Body: { name, schema:[{name,type,...}], ... }. */
-    async createCollection(params) {
+    /** Delete a collection (table) by id. */
+    async deleteCollection(id) {
         const headers = await this.cmsApiHeader();
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
+        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { headers });
     }
     // ── Blog Articles ──
     listArticles(query) {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "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",
+    "type": "Added",
+    "en": "New update_collection_columns tool reads the current collection schema and PATCHes it with the system columns plus the provided custom columns,…",
+    "vi": "Tool mới update_collection_columns đọc schema hiện tại của collection rồi PATCH lại với các cột hệ thống cộng các cột tùy chỉnh được cung cấp, cho…"
+  },
   {
     "v": "1.31.2",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "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."
-  },
-  {
-    "v": "1.28.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New scaffold_popup tool builds and saves a designed newsletter/promo popup (heading + subtext + email subscribe form + close button, centred modal)…",
-    "vi": "Tool mới scaffold_popup xây dựng và lưu một popup newsletter/promo được thiết kế sẵn (tiêu đề + phụ đề + form đăng ký email + nút đóng, dạng modal…"
   }
 ]

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/tools/collections.js

@@ -39,26 +39,52 @@ export function registerCollectionTools(server, api, handle) {
             query.order_by = order_by;
         return api.queryCollectionRecords(table_name, query);
     }));
-    // ── Write tools (custom data CRUD). Endpoints follow the same /db_collections/collections/
-    //    {table}/records[/{id}] REST pattern as the verified read endpoint, with the CMS api-key
-    //    header. They mutate live data — run a small test first to confirm your field shape. ──
-    server.tool("create_collection", "Create a new collection (custom data TABLE) so you can store/query arbitrary data. Pass a name + the field schema. The backend adds id/inserted_at/updated_at automatically.", {
-        name: z.string().describe("Collection / table name (e.g. 'subscribers')."),
-        schema: z
-            .array(z.object({ name: z.string(), type: z.string().describe("Field type: string | text | integer | float | boolean | naive_datetime | binary_id | map | array"), required: z.boolean().optional() }))
-            .describe("Field definitions, e.g. [{name:'email',type:'string',required:true},{name:'joined_at',type:'naive_datetime'}]."),
-    }, ({ name, schema }) => handle(() => api.createCollection({ name, schema })));
-    server.tool("insert_collection_record", "Insert a record into a collection (custom data table). `record` is a field→value object matching the table schema.", {
-        table_name: z.string().describe("Collection table name."),
-        record: z.record(z.any()).describe("Record fields, e.g. { email:'a@b.com', joined_at:'2026-06-26T10:00:00' }."),
-    }, ({ table_name, record }) => handle(() => api.insertCollectionRecord(table_name, record)));
-    server.tool("update_collection_record", "Update a record in a collection by id. `record` carries only the changed fields.", {
-        table_name: z.string().describe("Collection table name."),
-        record_id: z.string().describe("Record id to update."),
-        record: z.record(z.any()).describe("Changed fields."),
-    }, ({ table_name, record_id, record }) => handle(() => api.updateCollectionRecord(table_name, record_id, record)));
-    server.tool("delete_collection_record", "Delete a record from a collection by id.", {
-        table_name: z.string().describe("Collection table name."),
-        record_id: z.string().describe("Record id to delete."),
-    }, ({ table_name, record_id }) => handle(() => api.deleteCollectionRecord(table_name, record_id)));
+    // ── Table-management tools (VERIFIED live: create table, edit columns, delete table). ──
+    // Field type ∈ string | text | integer | float | boolean | naive_datetime | binary_id | map | array.
+    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"),
+        display_name: z.string().optional(),
+        is_required: z.boolean().optional(),
+        is_unique: z.boolean().optional(),
+    });
+    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'}]."),
+    }, ({ name, table_name, columns }) => handle(async () => {
+        const tn = (table_name || name).trim();
+        const created = await api.createCollection({ name, table_name: tn });
+        const col = (created && (created.data || created)) || {};
+        const id = col.id;
+        if (!id)
+            return { error: "Collection created but no id returned.", raw: created };
+        let schema = col.schema || [];
+        if (columns && columns.length) {
+            // PATCH the FULL schema = existing system columns + the new custom ones.
+            const custom = columns.map((c) => ({ ...c, display_name: c.display_name || c.name, create_type: "custom" }));
+            const res = await api.updateCollectionSchema(id, [...schema, ...custom]);
+            schema = (res && (res.data || res) || {}).schema || [...schema, ...custom];
+        }
+        return {
+            success: true,
+            collection_id: id,
+            table_name: col.table_name || tn,
+            columns: schema.map((f) => ({ name: f.name, type: f.type, kind: f.create_type || "system" })),
+            note: "Write rows via an HTTP function (db.model('" + (col.table_name || tn) + "').create({...})); query them with query_collection_records.",
+        };
+    }));
+    server.tool("update_collection_columns", "Add or change a collection's custom columns. Reads the current schema, then PATCHes it with the system columns + your custom columns (the PATCH replaces the whole schema, so omitting a column drops it).", {
+        collection_id: z.string().describe("Collection id (from list_collections / get_collection)."),
+        columns: z.array(COLUMN).describe("The FULL set of custom columns the table should have."),
+    }, ({ collection_id, columns }) => handle(async () => {
+        const cur = await api.getCollectionById(collection_id);
+        const schema = ((cur && (cur.data || cur)) || {}).schema || [];
+        const system = schema.filter((f) => (f.create_type || "system") === "system");
+        const custom = columns.map((c) => ({ ...c, display_name: c.display_name || c.name, create_type: "custom" }));
+        const res = await api.updateCollectionSchema(collection_id, [...system, ...custom]);
+        const newSchema = ((res && (res.data || res)) || {}).schema || [...system, ...custom];
+        return { success: true, collection_id, columns: newSchema.map((f) => ({ name: f.name, type: f.type, kind: f.create_type || "system" })) };
+    }));
+    server.tool("delete_collection", "Delete a collection (table) and all its records by id. Irreversible.", { collection_id: z.string().describe("Collection id.") }, ({ collection_id }) => handle(() => api.deleteCollection(collection_id)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.31.2",
+  "version": "1.31.4",
   "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",