sbuilder-mcp 0.34.0 → 0.36.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.36.0] - 2026-09-11
+
+### Added
+- The `/apps` call sheet now explains marketplace app installation as two separate questions: suggesting one is always possible on any credential (`GET /api/sites/{siteId}/apps` plus `GET /oauth/authorize-info` for the app's publisher, privacy policy, scopes, and price), while installing one requires a session (`POST /oauth/authorize`) because an agent key is not an access token and the platform refuses it by design. It also documents that a paid app is refused without an explicit `acceptedPrice`, so this server can never commit a merchant to a subscription on its own.
+- The catalog now carries the two `/oauth` operations behind that flow, `GET /oauth/authorize-info` and `POST /oauth/authorize`, including the request shape for the latter.
+
+### Changed
+- The `builtin-apps` call sheet no longer tells the caller that a marketplace app "cannot be installed from here at all"; that line was stricter than the platform actually enforces.
+
+## [0.35.0] - 2026-09-11
+
+### Added
+- The catalog now carries five page-history operations that reached the platform's own browser and swagger.json but had never carried an `@Router` annotation, so they were invisible to this server: `GET`/`POST .../pages/{pageId}/versions` (list and label a snapshot of the current draft), `POST .../pages/{pageId}/versions/{versionId}/restore`, `GET .../pages/{pageId}/history` (the autosave checkpoints written on every draft save), and `POST .../pages/{pageId}/history/{historyId}/restore`.
+
+### Changed
+- sb_undo's description now points to this page history and restore surface as the better way to recover a page, since it survives process exit while sb_undo's own undo stack is in-process, capped, and gone on exit; it no longer claims the platform has no page history at all.
+
 ## [0.34.0] - 2026-09-11
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,23 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.36.0] - 2026-09-11
+
+### Added
+- Call sheet của `/apps` giờ giải thích việc cài một app từ marketplace như hai câu hỏi tách biệt: gợi ý một app luôn khả thi với bất kỳ credential nào (`GET /api/sites/{siteId}/apps` cùng `GET /oauth/authorize-info` để lấy nhà phát hành, chính sách riêng tư, scope và giá của app), còn cài đặt thì cần một session (`POST /oauth/authorize`) vì agent key không phải access token và nền tảng cố tình từ chối nó. Call sheet cũng ghi rõ một app trả phí sẽ bị từ chối nếu thiếu `acceptedPrice` tường minh, nên server này không bao giờ tự ý khiến merchant phải trả tiền cho một gói đăng ký.
+- Catalog giờ mang theo hai operation `/oauth` phía sau luồng đó, `GET /oauth/authorize-info` và `POST /oauth/authorize`, kèm request shape cho operation thứ hai.
+
+### Changed
+- Call sheet của `builtin-apps` không còn nói với caller rằng một app marketplace "không thể cài từ đây được"; câu đó khắt khe hơn mức nền tảng thực sự yêu cầu.
+
+## [0.35.0] - 2026-09-11
+
+### Added
+- Catalog giờ mang theo năm operation lịch sử trang từng có mặt trên trình duyệt của nền tảng và trong swagger.json nhưng chưa từng được gắn annotation `@Router`, nên trước đây server này không thể thấy chúng: `GET`/`POST .../pages/{pageId}/versions` (liệt kê và gắn nhãn một bản chụp của bản nháp hiện tại), `POST .../pages/{pageId}/versions/{versionId}/restore`, `GET .../pages/{pageId}/history` (các checkpoint autosave được ghi ở mỗi lần lưu bản nháp), và `POST .../pages/{pageId}/history/{historyId}/restore`.
+
+### Changed
+- Mô tả của sb_undo giờ trỏ tới bề mặt lịch sử và khôi phục trang này như cách tốt hơn để phục hồi một trang, vì nó tồn tại qua cả khi tiến trình thoát, trong khi ngăn xếp undo của chính sb_undo chỉ nằm trong tiến trình, có giới hạn, và mất đi khi thoát; nó không còn khẳng định nền tảng hoàn toàn không có lịch sử trang.
+
 ## [0.34.0] - 2026-09-11
 
 ### Added

package/dist/catalog/api.generated.js

@@ -1,8 +1,8 @@
 export const SWAGGER_SOURCE = {
-    "operations": 501,
+    "operations": 508,
     "definitions": 105,
-    "bodyCarrying": 179,
-    "bodyUndescribed": 64,
+    "bodyCarrying": 183,
+    "bodyUndescribed": 68,
     "generatedFrom": "server/docs/swagger.json"
 };
 export const API_OPERATIONS = [
@@ -9532,6 +9532,113 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/pages/{pageId}/history",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/pages/{pageId}/history",
+        "tags": [
+            "pages",
+            "pages"
+        ],
+        "summary": "Restore a page's draft from an autosave checkpoint",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-… , default 50"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/pages/{pageId}/history/{historyId}/restore",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/pages/{pageId}/history/{historyId}/restore",
+        "tags": [
+            "pages",
+            "pages"
+        ],
+        "summary": "Restore a page's draft from an autosave checkpoint",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-… , default 50"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "historyId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "History ID from the list"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/pages/{pageId}/preview",
         "method": "GET",
@@ -9616,6 +9723,250 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/pages/{pageId}/versions",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/pages/{pageId}/versions",
+        "tags": [
+            "pages",
+            "pages",
+            "pages"
+        ],
+        "summary": "Restore a page's draft from a version snapshot",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-… , default 50"
+            },
+            {
+                "name": "offset",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "default 0"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "{label, document?}"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/pages/{pageId}/versions",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/pages/{pageId}/versions",
+        "tags": [
+            "pages",
+            "pages",
+            "pages"
+        ],
+        "summary": "Restore a page's draft from a version snapshot",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-… , default 50"
+            },
+            {
+                "name": "offset",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "default 0"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "{label, document?}"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/sites/{siteId}/pages/{pageId}/versions/{versionId}/restore",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/pages/{pageId}/versions/{versionId}/restore",
+        "tags": [
+            "pages",
+            "pages",
+            "pages"
+        ],
+        "summary": "Restore a page's draft from a version snapshot",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-… , default 50"
+            },
+            {
+                "name": "offset",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "default 0"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "{label, document?}"
+            },
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "pageId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Page ID"
+            },
+            {
+                "name": "versionId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Version ID from the list"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/payment-gateways",
         "method": "GET",
@@ -14888,6 +15239,62 @@ export const API_OPERATIONS = [
         "bodyDescribed": false,
         "bodyRef": null,
         "credential": "apiKey"
+    },
+    {
+        "id": "post:/oauth/authorize",
+        "method": "POST",
+        "path": "/oauth/authorize",
+        "tags": [
+            "apps"
+        ],
+        "summary": "Agree to an app's scopes and install it on a site",
+        "params": [
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "{siteId, clientId, versionId, redirectUri, scopes, state, acceptedPrice?}"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "get:/oauth/authorize-info",
+        "method": "GET",
+        "path": "/oauth/authorize-info",
+        "tags": [
+            "apps"
+        ],
+        "summary": "What an app is asking for, before anyone agrees to it",
+        "params": [
+            {
+                "name": "client_id",
+                "in": "query",
+                "required": true,
+                "type": "string",
+                "description": "The app's client id"
+            },
+            {
+                "name": "version_id",
+                "in": "query",
+                "required": false,
+                "type": "string",
+                "description": "A specific version; the current one otherwise"
+            },
+            {
+                "name": "redirect_uri",
+                "in": "query",
+                "required": true,
+                "type": "string",
+                "description": "Must match one the app registered"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
     }
 ];
 export const API_DEFINITIONS = {

package/dist/catalog/search.js

@@ -114,9 +114,29 @@ export function describeOperation(op) {
                 'reduces the subtree back to the reference. Configure the block through its own ' +
                 'props/slots, never by editing what it rendered.',
             installing: 'A BUILT-IN app installs with POST /api/sites/{siteId}/builtin-apps/{key} and that key ' +
-                "parameter's description names every installable one. A MARKETPLACE app cannot be " +
-                'installed from here at all: it goes through an OAuth consent screen a person has to ' +
-                'approve, so ask the merchant to install it and then read /apps/blocks again.',
+                "parameter's description names every installable one.",
+            // A MARKETPLACE APP IS A PERMISSION GRANT, and who may make it is the
+            // platform's line rather than this client's caution. `consent`
+            // authenticates as a USER — the platform parses an ACCESS TOKEN, so a
+            // session reaches it and a `wbk_` key does not — because an installed app
+            // holds SCOPES against the store. And `acceptedPrice` is a pointer:
+            // omitting it means a free app, and omitting it for a paid one is REFUSED
+            // rather than assumed, so nothing automated can commit a merchant to a
+            // subscription.
+            //
+            // So the honest answer is neither "ask a human" nor "just install it". It
+            // is: always be able to SUGGEST, and install only what the credential in
+            // hand is allowed to install, having shown what it grants.
+            marketplace: 'SUGGESTING one is always available: GET /api/sites/{siteId}/apps lists what this store ' +
+                'can install, and GET /oauth/authorize-info?client_id=… answers with the app, its ' +
+                'publisher, its privacy policy, the SCOPES it would hold and whether it is paid. Show ' +
+                'that to whoever is accountable for it. INSTALLING is POST /oauth/authorize with ' +
+                '{siteId, clientId, versionId, redirectUri, scopes} — it needs a SESSION ' +
+                '(SB_EMAIL/SB_PASSWORD), because an agent key is not an access token and the platform ' +
+                'refuses it by design: the app holds scopes against the store. A FREE app installs with ' +
+                'no acceptedPrice; a PAID one is refused without it rather than having a price assumed ' +
+                'on the merchant\'s behalf, so never send one they have not seen. Then read ' +
+                '/apps/blocks again for what it contributed.',
         };
     }
     const shape = REQUEST_SHAPES[op.id];

package/dist/catalog/shapes.generated.js

@@ -1,7 +1,7 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 219,
-    "shaped": 169,
-    "fromHandlers": 169,
+    "writeOperations": 223,
+    "shaped": 170,
+    "fromHandlers": 170,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
     "structsRead": 1658
@@ -31,6 +31,41 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "versionChoice"
     },
+    "post:/oauth/authorize": {
+        "fields": [
+            {
+                "name": "siteId",
+                "type": "string"
+            },
+            {
+                "name": "clientId",
+                "type": "string"
+            },
+            {
+                "name": "versionId",
+                "type": "string"
+            },
+            {
+                "name": "redirectUri",
+                "type": "string"
+            },
+            {
+                "name": "scopes",
+                "type": "string[]"
+            },
+            {
+                "name": "state",
+                "type": "string"
+            },
+            {
+                "name": "AcceptedPrice",
+                "type": "object",
+                "note": "AcceptedPrice is the amount the merchant was LOOKING AT when they pressed the button, echoed back from the authorize response above."
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/orgs/{orgId}/apps": {
         "fields": [
             {

package/dist/tools/undo.js

@@ -113,8 +113,12 @@ export class UndoLog {
  */
 export function registerUndoTools(server, ctx) {
     server.registerTool('sb_undo', {
-        description: 'Put back what a PUT through sb_api_call replaced. The platform has no page history ' +
-            'or restore, so this is the only way back. No argument lists what is undoable.',
+        description: 'Put back what a PUT through sb_api_call replaced — settings, a product, a form, ' +
+            'anything with a shape. IN THIS PROCESS ONLY, capped, and gone when it exits. For a ' +
+            'PAGE the platform keeps its own: GET .../pages/{pageId}/history lists the autosave ' +
+            'checkpoint it writes on every draft save, versions lists the labelled snapshots, and ' +
+            'either restores. That one survives everything and is the better answer whenever the ' +
+            'thing to recover is a page. No argument lists what is undoable here.',
         inputSchema: {
             index: z.number().int().min(1).optional().describe('1 is the most recent write'),
             dry_run: z.boolean().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",