sbuilder-mcp 0.2.2 → 0.3.0

package/dist/tools/session.js

@@ -23,10 +23,16 @@ export async function connect(ctx, args) {
             user: 'api key',
             sites: [],
             api_key: 'present',
+            ...(ctx.siteId ? { site: ctx.siteId } : {}),
             operations: API_OPERATIONS.length,
-            note: 'Connected with an API key alone. It is bound to one site, so there is no site list — ' +
-                'pass that site id to sb_page_open. Set SB_EMAIL and SB_PASSWORD as well if you want ' +
-                'account-level calls (listing sites, members, roles), which a key cannot make.',
+            note: ctx.siteId
+                ? `Connected with an API key alone, on site ${ctx.siteId} (SB_SITE). Every tool ` +
+                    'defaults to it, so site_id is optional. Set SB_EMAIL and SB_PASSWORD as well if ' +
+                    'you want account-level calls (listing sites, members, roles), which a key cannot make.'
+                : 'Connected with an API key alone. It is bound to one site, so there is no site list — ' +
+                    'pass that site id to sb_page_open, or set SB_SITE once and leave site_id out. Set ' +
+                    'SB_EMAIL and SB_PASSWORD as well if you want account-level calls (listing sites, ' +
+                    'members, roles), which a key cannot make.',
         };
     }
     if (!email || !password) {
@@ -70,11 +76,30 @@ export function registerSessionTools(server, ctx) {
         description: 'List the sites this account can operate.',
         inputSchema: {},
         annotations: { readOnlyHint: true },
-    }, async () => text(await request({
-        base: ctx.base,
-        method: 'GET',
-        path: '/api/sites',
-        token: ctx.session.token(),
-        fetchImpl: ctx.fetchImpl,
-    })));
+    }, async () => {
+        // A KEY CANNOT ANSWER THIS, and saying "not logged in — call sb_connect
+        // first" was the wrong instruction: sb_connect SUCCEEDS on a key-only
+        // install and this call still fails, so the caller retries the thing that
+        // already worked. `GET /api/sites` means "this human's account", which a
+        // key is deliberately not.
+        if (!ctx.session.loggedIn()) {
+            if (ctx.apiKey) {
+                throw new Error('sbuilder: listing sites is an ACCOUNT call and an API key addresses one site, so ' +
+                    'the platform refuses it by design — sb_connect will not change that. ' +
+                    (ctx.siteId
+                        ? `This install works on ${ctx.siteId} (SB_SITE).`
+                        : 'Set SB_SITE to the site you mean.') +
+                    ' Set SB_EMAIL and SB_PASSWORD if you genuinely need the account-level list.');
+            }
+            throw new Error('sbuilder: no credential. Set SB_TOKEN to an API key, or SB_EMAIL and SB_PASSWORD ' +
+                'and call sb_connect.');
+        }
+        return text(await request({
+            base: ctx.base,
+            method: 'GET',
+            path: '/api/sites',
+            token: ctx.session.token(),
+            fetchImpl: ctx.fetchImpl,
+        }));
+    });
 }

package/dist/transport/media.js

@@ -45,7 +45,7 @@ export async function uploadMedia(ctx, siteId, source) {
     // No Content-Type header: fetch must set it itself so the multipart boundary
     // matches the body it just built. Setting it by hand is the classic way to
     // make a valid upload unparseable at the other end.
-    const res = await doFetch(`${ctx.base.replace(/\/$/, '')}/api/media/${encodeURIComponent(siteId)}`, {
+    const post = (path) => doFetch(`${ctx.base.replace(/\/$/, '')}${path}`, {
         method: 'POST',
         // Content-Type stays ABSENT — fetch writes it with the boundary it just
         // built — but the identity headers belong here as much as on any other call:
@@ -57,6 +57,25 @@ export async function uploadMedia(ctx, siteId, source) {
         },
         body: form,
     });
+    let res = await post(`/api/media/${encodeURIComponent(siteId)}`);
+    // THE PARTNER SURFACE IS A SECOND DOOR, and it is the key's own.
+    //
+    // `/api/media` takes a key only since `feat(media): a wbk_ API key may upload`
+    // — so against a deployment older than that commit it answers 401 to a key
+    // that is perfectly valid, and the message below then blamed the key's scopes.
+    // Measured: a key holding media.read + media.write, on its own site, refused
+    // by a server binary 26 minutes older than the fix, while `POST /api/v1/media`
+    // — multipart too, and keyed BY DEFINITION, since /api/v1 accepts nothing else
+    // — answered 201 for the same bytes.
+    //
+    // So a refusal here is not the end of the road, and retrying costs one request
+    // on a path that was failing anyway. Only when BOTH doors refuse is the key
+    // itself the suspect.
+    if ((res.status === 401 || res.status === 403) && ctx.apiKey) {
+        const viaPartner = await post('/api/v1/media');
+        if (viaPartner.ok)
+            res = viaPartner;
+    }
     const raw = await res.text();
     let parsed;
     try {
@@ -83,10 +102,12 @@ export async function uploadMedia(ctx, siteId, source) {
         // credential was used, and the old text sent people to fix something that
         // was never broken.
         if ((res.status === 401 || res.status === 403) && ctx.apiKey && !ctx.session.loggedIn()) {
-            throw new ApiError(res.status, 'media_key_refused', 'sbuilder: the platform refused this API key for the upload. It accepts a key, so the ' +
-                'cause is the key itself: it needs the media permission, and it must belong to THIS ' +
-                'site — a key minted for another site is refused before the upload is read. Check the ' +
-                "key's scopes and its site, or set SB_EMAIL / SB_PASSWORD to upload as a person.");
+            throw new ApiError(res.status, 'media_key_refused', 'sbuilder: both upload doors refused this API key — /api/media and the partner surface ' +
+                '/api/v1/media. Two causes fit. The key: it needs media.write and must belong to THIS ' +
+                'site, since a key minted for another one is refused before the upload is read. Or the ' +
+                'DEPLOYMENT: /api/media took keys only from "feat(media): a wbk_ API key may upload", ' +
+                'so a server older than that refuses a perfectly good key — check the running build ' +
+                "before changing the key. Failing both, set SB_EMAIL / SB_PASSWORD to upload as a person.");
         }
         const env = (parsed ?? {});
         const fieldText = env.fields

package/dist/vision/measure.js

@@ -16,13 +16,22 @@ function overlaps(a, b) {
  * 1440 and spills at 390 is the ordinary responsive failure, and saying which
  * width it happened at is most of the fix.
  */
-export function measureShot(shot) {
+export function measureShot(shot, skip = new Set()) {
     const out = [];
     const byId = new Map(shot.boxes.map((b) => [b.id, b]));
     const seen = new Set();
     for (const b of shot.boxes) {
         if (b.id === 'ROOT')
             continue;
+        // AN OVERLAY IS OFF-SCREEN ON PURPOSE. The cart drawer is parked outside
+        // the viewport until a shopper opens it, so every node inside it measures
+        // as off-canvas — 24 findings on one page, on every page carrying the
+        // drawer, at every width. They are also not this page's to fix: an overlay
+        // is composed onto ROOT on read and stripped on write (trap 1), which is
+        // why `reviewDesign` already skips them and this had to as well. A list
+        // that is two dozen false positives long is a list nobody reads.
+        if (skip.has(b.id))
+            continue;
         // OFF-CANVAS. A negative x, or a right edge past the viewport, is content
         // the visitor cannot reach — and on a phone it also drags a horizontal
         // scrollbar across the whole page.
@@ -52,9 +61,16 @@ export function measureShot(shot) {
     // choice — but two elements in the same flow row sitting on top of each other
     // is one of them being unreadable.
     for (const a of shot.boxes) {
+        if (skip.has(a.id))
+            continue;
         for (const b of shot.boxes) {
             if (a.id >= b.id || a.id === 'ROOT' || b.id === 'ROOT')
                 continue;
+            // Same reason as above, and it needs saying twice because the pair loop is
+            // its own pass: a drawer parked off-screen overlaps whatever the page has
+            // at those coordinates, and neither half of that pair is a defect.
+            if (skip.has(b.id))
+                continue;
             if (a.w === 0 || a.h === 0 || b.w === 0 || b.h === 0)
                 continue;
             const pairKey = `${a.id}|${b.id}`;
@@ -91,10 +107,10 @@ function contains(outer, inner) {
  * widths it spills at is the useful part, so the widths are collected onto the
  * single finding rather than repeated as separate ones.
  */
-export function measure(shots) {
+export function measure(shots, skip = new Set()) {
     const merged = new Map();
     for (const shot of shots) {
-        for (const f of measureShot(shot)) {
+        for (const f of measureShot(shot, skip)) {
             const key = `${f.code}|${f.nodeId}`;
             const existing = merged.get(key);
             if (existing)

package/dist/vision/shoot.js

@@ -138,6 +138,44 @@ export async function shoot(url, opts = {}) {
         }
     }));
 }
+/**
+ * WALK THE PAGE so its lazy images load, then come back to the top.
+ *
+ * `fullPage: true` does NOT scroll: Playwright resizes the capture, and an
+ * `<img loading="lazy">` below the fold never enters the viewport, never
+ * fetches, and photographs as an empty box. The renderer marks every image
+ * below the first screen lazy, so this hit the one thing the vision loop exists
+ * to judge — measured on a real storefront: 4 of the page's images unloaded
+ * before the walk, 0 after. The agent saw four blank product cards on a page a
+ * shopper sees four photos on, and the honest reading of that picture is "the
+ * images are broken", which would send it to fix something that works.
+ *
+ * BOUNDED at every step, because a shot that never happens is worse than one
+ * taken a beat early: the walk is capped, and the wait for decoding gives up
+ * rather than hanging on an image the server will never send.
+ */
+async function settleLazyImages(page) {
+    await page
+        .evaluate(async () => {
+        const step = window.innerHeight || 900;
+        const end = document.body.scrollHeight;
+        // A very long page is walked in bigger strides rather than not at all.
+        const stride = Math.max(step, Math.ceil(end / 40));
+        for (let y = 0; y < end; y += stride) {
+            window.scrollTo(0, y);
+            await new Promise((r) => setTimeout(() => r(undefined), 60));
+        }
+        window.scrollTo(0, 0);
+    })
+        .catch(() => { });
+    // Give what the walk started a chance to arrive. `complete` is false while a
+    // fetch is in flight; a decoded-but-broken image reports complete with a zero
+    // natural width, and that is a REAL defect the shot should show, so it is not
+    // waited on.
+    await page
+        .waitForFunction(() => [...document.querySelectorAll('img')].every((i) => i.complete === true), undefined, { timeout: 3_000 })
+        .catch(() => { });
+}
 async function shootOne(page, url, width, format, opts) {
     // LOAD, then a BOUNDED settle — never `networkidle` alone.
     //
@@ -150,6 +188,7 @@ async function shootOne(page, url, width, format, opts) {
     // waits for it; if it never does, the shot happens anyway.
     await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
     await page.waitForLoadState('networkidle', { timeout: 2_500 }).catch(() => { });
+    await settleLazyImages(page);
     // A RENDERED page carries its node ids as the HTML `id` attribute — not as
     // `data-node-id`, which is the editor CANVAS's hook and never reaches the
     // renderer. Selecting the canvas attribute here returned an empty box list

package/package.json

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