webcake-storefront-mcp 1.29.0 → 1.31.0

package/dist/api.js

@@ -29,7 +29,7 @@ export class WebcakeCmsApi {
     getBundleParams() {
         return { token: this._adminToken, x_cms_api_key: this._cmsApiKey };
     }
-    async request(method, path, { body, query, timeout } = {}) {
+    async request(method, path, { body, query, timeout, headers: extraHeaders } = {}) {
         const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             for (const [k, v] of Object.entries(query)) {
@@ -41,6 +41,7 @@ export class WebcakeCmsApi {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.token}`,
             ...(this.sessionId && { "x-session-id": this.sessionId }),
+            ...(extraHeaders || {}),
         };
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeout || DEFAULT_TIMEOUT);
@@ -340,8 +341,37 @@ export class WebcakeCmsApi {
     getCollection(id) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`);
     }
-    queryCollectionRecords(tableName, query) {
-        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { query });
+    /** Header carrying the CMS api key — collection-data endpoints (records) need it on top of
+     *  the dashboard JWT (without it they 401). Fetches the key once and caches it. */
+    async cmsApiHeader() {
+        await this.fetchCmsTokens();
+        return this._cmsApiKey ? { "x-cms-api-key": this._cmsApiKey } : {};
+    }
+    /** Query a collection's records. Needs the CMS api-key header (else 401). The records
+     *  endpoint accepts page/limit plus `where` (a filter object/JSON) and `order_by`. */
+    async queryCollectionRecords(tableName, query) {
+        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) {
+        const headers = await this.cmsApiHeader();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { body: record, headers });
+    }
+    /** Update a record by id. Body = the changed fields. CMS-api-key authed. */
+    async updateCollectionRecord(tableName, recordId, record) {
+        const headers = await this.cmsApiHeader();
+        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { body: record, headers });
+    }
+    /** Delete a record by id. CMS-api-key authed. */
+    async deleteCollectionRecord(tableName, recordId) {
+        const headers = await this.cmsApiHeader();
+        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { headers });
+    }
+    /** Create a collection (table). Body: { name, schema:[{name,type,...}], ... }. */
+    async createCollection(params) {
+        const headers = await this.cmsApiHeader();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
     }
     // ── Blog Articles ──
     listArticles(query) {
@@ -505,6 +535,11 @@ export class WebcakeCmsApi {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/combo_product/items`, { query: { combo_product_id: comboProductId, ...query } });
     }
     // ── Customers ──
+    /** List/search customers. Real shape: { customers: { data:[…], total_entries } }. Accepts
+     *  page/limit and a `term` keyword (name/phone/email). Endpoint is /customer/all (singular). */
+    listCustomers(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/customer/all`, { query });
+    }
     findCustomerById(id) {
         return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/identity/${id}`);
     }

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.0",
+    "d": "26/06/2026",
+    "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",
@@ -26,19 +40,5 @@
     "type": "Fixed",
     "en": "list_products now correctly unwraps the { products, total_product } API response shape, returning a product array and accurate total instead of…",
     "vi": "list_products nay giải nén đúng kiểu phản hồi { products, total_product } từ API, trả về mảng sản phẩm và tổng chính xác thay vì trả thẳng đối tượng…"
-  },
-  {
-    "v": "1.26.0",
-    "d": "26/06/2026",
-    "type": "Fixed",
-    "en": "create_product now accepts a short_description parameter and sends it to the backend as [{description}] — the array shape the real product schema…",
-    "vi": "create_product nay nhận thêm tham số short_description và gửi lên backend dưới dạng [{description}] — đúng kiểu mảng mà schema sản phẩm thực tế yêu…"
-  },
-  {
-    "v": "1.25.0",
-    "d": "26/06/2026",
-    "type": "Changed",
-    "en": "list_elements now documents 16 previously-uncovered element types, completing curated attribute coverage across all 132 factory types: popup…",
-    "vi": "list_elements nay tài liệu hóa 16 kiểu phần tử trước đây chưa được ghi lại, hoàn thiện độ phủ thuộc tính curated cho toàn bộ 132 kiểu factory: popup…"
   }
 ]

package/dist/tools/collections.js

@@ -25,9 +25,40 @@ export function registerCollectionTools(server, api, handle) {
     server.tool("get_collection", "Get a specific collection's details including full schema (field names, types, constraints, references) and records", {
         id: z.string().describe("Collection ID"),
     }, ({ id }) => handle(() => api.getCollection(id)));
-    server.tool("query_collection_records", "Query records from a collection by table name. Use to inspect existing data", {
-        table_name: z.string().describe("Collection table name (e.g. 'subscribers', 'custom_orders')"),
+    server.tool("query_collection_records", "Query records from a collection (custom data table) by table name. Supports paging + an optional `where` filter and `order_by` sort. (Uses the CMS api-key auth the records endpoint requires.)", {
+        table_name: z.string().describe("Collection table name (e.g. 'subscribers', 'custom_orders') — from get_collection.table_name"),
         page: z.number().optional().describe("Page number"),
         limit: z.number().optional().describe("Items per page"),
-    }, ({ table_name, page, limit }) => handle(() => api.queryCollectionRecords(table_name, { page, limit })));
+        where: z.record(z.any()).optional().describe("Filter object, e.g. { status: 'active' } — matches records by field value."),
+        order_by: z.string().optional().describe("Field to sort by (e.g. 'inserted_at')."),
+    }, ({ table_name, page, limit, where, order_by }) => handle(() => {
+        const query = { page: page ?? 1, limit: limit ?? 50 };
+        if (where && Object.keys(where).length)
+            query.where = JSON.stringify(where);
+        if (order_by)
+            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)));
 }

package/dist/tools/customers.js

@@ -1,5 +1,35 @@
 import { z } from "zod";
 export function registerCustomerTools(server, api, handle) {
+    server.tool("list_customers", "List/search the site's customers (browse or segment). Pass `term` to search by name/phone/email. Returns name, phone, email, order_count, purchased_amount, reward_point, tags, last_order_at. Use find_customer for an exact id/phone/email lookup.", {
+        page: z.number().optional().describe("Page number (default 1)"),
+        limit: z.number().optional().describe("Items per page (default 50)"),
+        term: z.string().optional().describe("Keyword — searches name / phone / email"),
+    }, ({ page, limit, term }) => handle(async () => {
+        const query = { page: page ?? 1, limit: limit ?? 50 };
+        if (term && term.trim())
+            query.term = term.trim();
+        const res = await api.listCustomers(query);
+        // Real shape: { customers: { data:[…], total_entries } }.
+        const box = (res && res.customers) || res || {};
+        const list = (Array.isArray(box) ? box : box.data) || [];
+        if (!Array.isArray(list))
+            return res;
+        return {
+            data: list.map((c) => ({
+                id: c.id,
+                name: c.name,
+                phone_number: c.phone_number || c.recent_phone_number || undefined,
+                email: c.email || undefined,
+                order_count: c.order_count ?? undefined,
+                succeed_order_count: c.succeed_order_count ?? undefined,
+                purchased_amount: c.purchased_amount ?? undefined,
+                reward_point: c.reward_point ?? undefined,
+                tags: c.tags && c.tags.length ? c.tags : undefined,
+                last_order_at: c.last_order_at || undefined,
+            })),
+            total: (box.total_entries ?? res.total) || list.length,
+        };
+    }));
     server.tool("find_customer", "Find a customer by ID, phone number, or email", {
         by: z.enum(["id", "phone", "email"]).describe("Search field"),
         value: z.string().describe("Search value"),

package/package.json

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