sbuilder-mcp 0.1.0

package/dist/transport/socket.js

@@ -0,0 +1,85 @@
+/** WebSocket.OPEN per spec, as a literal so this module never reads a global. */
+const OPEN = 1;
+const RETRY_BASE_MS = 500;
+const RETRY_MAX_MS = 15_000;
+export class RealtimeSocket {
+    url;
+    token;
+    factory;
+    ws = null;
+    closed = false;
+    attempt = 0;
+    handlers = [];
+    timer = null;
+    constructor(url, 
+    /**
+     * A GETTER, read per attempt. The access token lives ~15 minutes and
+     * rotates; a socket holding the string it was constructed with replays an
+     * expired token on every reconnect, and the failure is SILENT — a rejected
+     * auth still fires `onopen`, so no error event ever surfaces.
+     */
+    token, factory = (u) => new WebSocket(u)) {
+        this.url = url;
+        this.token = token;
+        this.factory = factory;
+    }
+    get attempts() {
+        return this.attempt;
+    }
+    on(handler) {
+        this.handlers.push(handler);
+    }
+    connect() {
+        if (this.closed)
+            return;
+        const ws = this.factory(this.url);
+        this.ws = ws;
+        this.attempt += 1;
+        ws.onopen = () => {
+            // Auth is the FIRST message, never a header (a browser cannot set one on a
+            // WebSocket) and never a query parameter (a token in a URL lands in logs).
+            // The server enforces a 5s deadline, so it goes out immediately.
+            ws.send(JSON.stringify({ t: 'auth', token: this.token() }));
+        };
+        ws.onmessage = (ev) => {
+            // A frame ARRIVING is the only evidence this connection is usable. An open
+            // proves nothing: a refused auth opens and then closes. Resetting the
+            // counter on open instead produced open → attempt=0 → auth → close →
+            // 500ms → forever: a 2 Hz reconnect storm with the backoff never engaging,
+            // no onerror (a policy close is not an error), and nothing in any UI.
+            this.attempt = 0;
+            let parsed;
+            try {
+                parsed = JSON.parse(String(ev.data));
+            }
+            catch {
+                return; // a malformed frame must never throw into the socket
+            }
+            for (const h of this.handlers)
+                h(parsed);
+        };
+        ws.onclose = () => {
+            if (this.closed)
+                return;
+            const wait = Math.min(RETRY_BASE_MS * 2 ** this.attempt, RETRY_MAX_MS);
+            this.timer = setTimeout(() => this.connect(), wait);
+        };
+        ws.onerror = () => {
+            // Genuinely rare: a policy close is not an error. Nothing to do here —
+            // onclose runs either way and owns the reconnect.
+        };
+    }
+    send(e) {
+        if (this.closed)
+            return;
+        if (this.ws?.readyState !== OPEN)
+            return;
+        this.ws.send(JSON.stringify(e));
+    }
+    close() {
+        this.closed = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.ws?.close();
+    }
+}

package/dist/vision/preview.js

@@ -0,0 +1,30 @@
+import { request } from '../transport/http.js';
+import { siteToken } from '../tools/credentialpick.js';
+/**
+ * Mint a signed link to this page's DRAFT preview.
+ *
+ * The link is short-lived and is the only gate on the public `/_wb/preview`
+ * route, which renders the STORED draft through the Go renderer. So a screenshot
+ * always shows the last SAVED state — save first, or you photograph the past.
+ */
+export async function previewUrl(ctx, siteId, pageId) {
+    const out = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(siteId)}/pages/${encodeURIComponent(pageId)}/preview`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    const link = out?.preview?.url;
+    if (!link) {
+        throw new Error('sbuilder: the server returned no preview url for this page. A page with no saved draft ' +
+            'has no preview — save it first.');
+    }
+    // The server returns a RELATIVE link in dev (`/_wb/preview?t=…`) and an
+    // absolute one in production, where the preview is served from the storefront
+    // origin rather than the API's. Resolving against the API base handles both:
+    // `new URL` leaves an absolute input untouched. Passing the raw value to
+    // Playwright throws "Cannot navigate to invalid URL", which is where this was
+    // found — running it, not reading it.
+    return new URL(link, ctx.base).toString();
+}

package/dist/vision/shoot.js

@@ -0,0 +1,103 @@
+import { chromium } from 'playwright-core';
+/** The three widths the platform's own breakpoints care about. */
+export const DEFAULT_WIDTHS = [1440, 768, 390];
+/**
+ * Launch the SYSTEM Chrome — `channel: 'chrome'`, not a bundled browser.
+ *
+ * `playwright-core` ships no browsers, so installing this package downloads
+ * nothing. When Chrome is absent the launch throws, and this re-throws NAMING
+ * it: a vision loop that quietly returns a blank image is worse than one that
+ * refuses, because the agent would go on to judge a page it never saw.
+ */
+async function launch() {
+    try {
+        return await chromium.launch({ channel: 'chrome', headless: true });
+    }
+    catch (err) {
+        throw new Error('sbuilder: could not launch Google Chrome for the screenshot. sb_look needs Chrome ' +
+            `installed — playwright-core bundles no browser. Underlying error: ${String(err)}`);
+    }
+}
+/**
+ * Photograph a rendered page at several widths, and measure every node.
+ *
+ * The boxes are the load-bearing half. `cursor` frames on the live-edit socket
+ * carry LAYOUT pixels — the canvas is zoomed per viewer, so a screen coordinate
+ * lands somewhere else on a peer with a different window — and nothing else in
+ * this server knows where a node ended up. Measured here, the agent's cursor
+ * moves to the element it is about to change instead of to a made-up number.
+ */
+export async function shoot(url, opts = {}) {
+    const widths = opts.widths ?? DEFAULT_WIDTHS;
+    const browser = await launch();
+    try {
+        const shots = [];
+        for (const width of widths) {
+            const page = await browser.newPage({ viewport: { width, height: 900 } });
+            await page.goto(url, { waitUntil: 'networkidle' });
+            // 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
+            // on every real page, silently: the screenshots looked fine, and the half
+            // of this function that exists to place the presence cursor did nothing.
+            // Found by running it against the Go renderer.
+            //
+            // Ids are filtered by SHAPE (`xx_8hex`, plus ROOT) rather than taken from
+            // every `[id]`, so a wrapper or an anchor target cannot be mistaken for a
+            // node. `type` is read off the leading `wb-` class, which is the only type
+            // signal the render emits; the caller already knows the real types from
+            // sb_outline, so this is a convenience, not a contract.
+            const boxes = (await page.evaluate(() => [...document.querySelectorAll('[id]')]
+                .filter((el) => el.id === 'ROOT' || /^[a-z]{2}_[0-9a-f]{8}$/.test(el.id))
+                .map((el) => {
+                const r = el.getBoundingClientRect();
+                const wb = String(el.className || '')
+                    .split(/\s+/)
+                    .find((c) => c.startsWith('wb-'));
+                return {
+                    id: el.id,
+                    type: wb ? wb.slice(3) : '',
+                    x: Math.round(r.x),
+                    y: Math.round(r.y),
+                    w: Math.round(r.width),
+                    h: Math.round(r.height),
+                };
+            })));
+            // ZOOM. A designer does not judge a card by looking at the whole page, and
+            // a full-page shot of a long storefront makes one card a few pixels tall.
+            // The clip comes from the SAME measurement pass the boxes do, so what is
+            // framed is exactly what `sb_set` addresses.
+            let clip;
+            if (opts.node) {
+                const box = boxes.find((b) => b.id === opts.node);
+                if (!box) {
+                    await page.close();
+                    throw new Error(`sbuilder: node "${opts.node}" is not on the rendered page at ${width}px. It may be ` +
+                        'hidden at this breakpoint, or not saved yet — sb_look renders the STORED draft.');
+                }
+                if (box.w === 0 || box.h === 0) {
+                    await page.close();
+                    throw new Error(`sbuilder: node "${opts.node}" renders with no size at ${width}px (${box.w}×${box.h}) — ` +
+                        'nothing to photograph. It is collapsed or empty; sb_review will say which.');
+                }
+                const pad = opts.pad ?? 16;
+                clip = {
+                    x: Math.max(0, box.x - pad),
+                    y: Math.max(0, box.y - pad),
+                    width: Math.min(width, box.w + pad * 2),
+                    height: box.h + pad * 2,
+                };
+            }
+            const png = await page.screenshot({
+                type: 'png',
+                ...(clip ? { clip } : { fullPage: true }),
+            });
+            shots.push({ width, pngBase64: png.toString('base64'), boxes });
+            await page.close();
+        }
+        return shots;
+    }
+    finally {
+        await browser.close();
+    }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "sbuilder-mcp",
+  "version": "0.1.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",
+  "license": "MIT",
+  "bin": {
+    "sb-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.vi.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "smoke": "node dist/smoke.js",
+    "test": "vitest run",
+    "codegen": "tsx scripts/gen-catalog.ts",
+    "prepublishOnly": "npm run build && npm run smoke",
+    "release": "node scripts/release.mjs",
+    "release:patch": "node scripts/release.mjs patch",
+    "release:minor": "node scripts/release.mjs minor",
+    "release:major": "node scripts/release.mjs major",
+    "release:dry": "node scripts/release.mjs --dry"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright-core": "^1.62.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.0"
+  },
+  "homepage": "https://github.com/vuluu2k/sbuilder-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/vuluu2k/sbuilder-mcp/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vuluu2k/sbuilder-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "store-builder",
+    "sbuilder",
+    "website-builder",
+    "ai-agent",
+    "page-builder"
+  ]
+}