sbuilder-mcp 0.35.0 → 0.36.1

package/CHANGELOG.md

@@ -6,6 +6,19 @@ 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.1] - 2026-09-11
+
+- fix(import,api): a capture waited on iframes, and a recovery list was unreadable
+
+## [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

package/CHANGELOG.vi.md

@@ -6,6 +6,15 @@ 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

package/dist/catalog/api.generated.js

@@ -1,8 +1,8 @@
 export const SWAGGER_SOURCE = {
-    "operations": 506,
+    "operations": 508,
     "definitions": 105,
-    "bodyCarrying": 182,
-    "bodyUndescribed": 67,
+    "bodyCarrying": 183,
+    "bodyUndescribed": 68,
     "generatedFrom": "server/docs/swagger.json"
 };
 export const API_OPERATIONS = [
@@ -15239,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": 222,
-    "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/api.js

@@ -45,6 +45,33 @@ function pickFields(item, fields) {
  * it would have been and how to narrow the call. A non-list answer is never
  * cut: there is no honest place to stop inside one object.
  */
+/**
+ * LIST OPERATIONS WHOSE EVERY ROW CARRIES A WHOLE PAGE DOCUMENT.
+ *
+ * The page recovery surface answers with the documents themselves — which is
+ * right, since a restore has to have something to restore from — and useless to
+ * read. MEASURED against a live server: one version of a TWO-NODE page is 1,690
+ * bytes, so a realistic 120-node page runs about 70 KB per version and a listing
+ * of twenty is **1.4 MB in one answer**. An agent choosing which version to
+ * restore would be handed a truncated blob and no reliable way to pick.
+ *
+ * `sb_publish` already had this exact problem and the same answer: a published
+ * row carries `document`, `html` and `css` for every page the cascade touched,
+ * so it PROJECTS the rows. This is that, applied where the caller cannot know to
+ * ask — and it is a DEFAULT rather than a rule: an explicit `pick` still wins,
+ * so the document is one argument away for a caller that wants to read one.
+ */
+const LIST_PROJECTIONS = {
+    'get:/api/sites/{siteId}/pages/{pageId}/versions': [
+        'id',
+        'versionNo',
+        'label',
+        'createdBy',
+        'createdAt',
+        'isLive',
+    ],
+    'get:/api/sites/{siteId}/pages/{pageId}/history': ['id', 'createdBy', 'createdAt'],
+};
 export function shapeResponse(raw, opts) {
     const asked = opts.pick !== undefined || opts.max_items !== undefined;
     const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -271,7 +298,10 @@ export async function callOperation(ctx, args) {
     if (raw === null || raw === undefined) {
         return { ok: true, method: op.method, path, note: 'The platform answered with no content.' };
     }
-    return shapeResponse(raw, { pick: args.pick, max_items: args.max_items });
+    // The caller's own `pick` outranks the default: asking for `document` is how
+    // you read a version rather than merely choose one.
+    const projection = args.pick ?? LIST_PROJECTIONS[op.id];
+    return shapeResponse(raw, { pick: projection, max_items: args.max_items });
 }
 export function registerApiTools(server, ctx) {
     server.registerTool('sb_api_find', {

package/dist/vision/capture.js

@@ -1127,7 +1127,22 @@ async function readPage(browser, url, width, work) {
     let page;
     try {
         page = await browser.newPage({ viewport: { width, height: 900 } });
-        await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
+        // `domcontentloaded`, NOT `load`, and `settleDom` does the rest.
+        //
+        // `load` waits for every SUBRESOURCE — including third-party iframes, which
+        // an import has no use for: this walk reads the iframe's `src` ATTRIBUTE and
+        // never needs the frame to render. So a page carrying an ad frame, a chat
+        // widget or a slow video embed stalled the whole capture for up to thirty
+        // seconds and then THREW, losing an import whose DOM had been ready the
+        // entire time. Caught by this repo's own test, whose fixture embeds real
+        // YouTube, Vimeo and Google Maps frames: it started failing at exactly 30s
+        // with nothing about the page having changed.
+        //
+        // The same lesson `sb_look` already paid for with `networkidle`, one wait
+        // earlier: the right question is "has the DOM stopped changing", and
+        // `settleDom` answers it directly and bounded. A page that genuinely needs
+        // its images is the SHOOT path's problem, and that one still waits.
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
         // THE SAME SETTLE `sb_look` USES, not a flat sleep. A fixed 600ms is wrong
         // at both ends: example.com is finished long before it, and a page that
         // builds itself with scripts is not finished after it — which is exactly the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "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",