webcake-storefront-mcp 1.30.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) {

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "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",
@@ -33,12 +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…"
   }
 ]

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/package.json

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