sbuilder-mcp 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.2 — 2026-08-29
+
+244625
+
 ## 0.1.1 — 2026-08-28
 
 - fix(release): ask for the one-time password instead of dying on it

package/dist/server.js

@@ -1,3 +1,4 @@
+import { setAgentClient } from './transport/identity.js';
 import { readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Session } from './transport/auth.js';
@@ -51,6 +52,15 @@ export function buildContext() {
 }
 export function createServer(ctx = buildContext()) {
     const server = new McpServer({ name: 'sbuilder', version: pkgVersion(), title: 'Store Builder' }, { instructions: INSTRUCTIONS });
+    // LEARN WHO LAUNCHED US, at the handshake, before any tool runs.
+    //
+    // Set here rather than after connect() because the handshake happens DURING
+    // connect: a hook attached afterwards is attached to an event that has already
+    // fired, and every call would then report an anonymous machine — the exact
+    // blindness this exists to remove.
+    server.server.oninitialized = () => {
+        setAgentClient(server.server.getClientVersion(), pkgVersion());
+    };
     registerSessionTools(server, ctx);
     registerApiTools(server, ctx);
     const pageSession = registerPageTools(server, ctx);

package/dist/tools/live.js

@@ -6,6 +6,7 @@ import { previewUrl } from '../vision/preview.js';
 import { uploadMedia } from '../transport/media.js';
 import { request } from '../transport/http.js';
 import { shoot, DEFAULT_WIDTHS } from '../vision/shoot.js';
+import { measure, MEASURE_NOTICE } from '../vision/measure.js';
 import { RealtimeSocket } from '../transport/socket.js';
 import { LiveSession } from '../live/session.js';
 import { siteToken } from './credentialpick.js';
@@ -62,8 +63,9 @@ export function registerLiveTools(server, ctx, session) {
     });
     server.tool('sb_look', "Save the open page, render it through the platform's own renderer, and return " +
         'screenshots at desktop, tablet and mobile widths — plus the measured bounding box of ' +
-        'every node. Pass node_id to frame ONE element instead of the whole page. Judge your ' +
-        'own work from these rather than guessing.', {
+        'every node — plus any LAYOUT defect measured on the render: content past the ' +
+        'viewport, elements overlapping, text too small to read. Pass node_id to frame ONE ' +
+        'element instead of the whole page. Judge your own work from these rather than guessing.', {
         widths: z.array(z.number().int().min(320).max(2560)).optional(),
         with_boxes: z.boolean().optional(),
         node_id: z
@@ -81,11 +83,15 @@ export function registerLiveTools(server, ctx, session) {
         // by rule are the same act, and separating them is how the second one gets
         // skipped.
         const findings = reviewDesign(session.current());
+        // Measured on the render, not read off the document — a card that spills
+        // at 390px is invisible to every check that only reads the tree.
+        const visual = node_id ? [] : measure(shots);
         return images(shots.map((s) => ({ dataBase64: s.pngBase64 })), {
             widths: shots.map((s) => s.width),
             ...(node_id ? { framed: node_id } : {}),
             ...(with_boxes === false ? {} : { boxes: shots[0]?.boxes ?? [] }),
             ...(findings.length > 0 ? { findings, findings_notice: REVIEW_NOTICE } : {}),
+            ...(visual.length > 0 ? { layout: visual, layout_notice: MEASURE_NOTICE } : {}),
         });
     });
     server.tool('sb_media_list', "The site's media library — reuse an image that is already there before adding another. " +

package/dist/transport/http.js

@@ -1,3 +1,13 @@
+/**
+ * The one HTTP path to the platform.
+ *
+ * The platform writes exactly ONE error shape — {"error": "...", "code": "..."} —
+ * through httpx.WriteError, and never plain text. So an error is parsed, not
+ * stringified: `code` is the branchable half, and reading `res.statusText`
+ * instead throws it away. A bare "Conflict" reaching the model is the failure
+ * this file exists to prevent.
+ */
+import { identityHeaders } from './identity.js';
 export class ApiError extends Error {
     status;
     code;
@@ -44,7 +54,12 @@ export function buildUrl(base, path, query) {
 }
 export async function request(opts) {
     const doFetch = opts.fetchImpl ?? fetch;
-    const headers = { Accept: 'application/json' };
+    // Identity rides on EVERY call rather than on a handshake of its own. There is
+    // no "connect" request to hang it off — the first thing this server does is
+    // whatever the agent asked for — and a separate announcement call would be one
+    // more thing that can fail while the real work succeeds, leaving a working
+    // install invisible on the operator's screen.
+    const headers = { Accept: 'application/json', ...identityHeaders() };
     if (opts.token)
         headers.Authorization = `Bearer ${opts.token}`;
     if (opts.body !== undefined)

package/dist/transport/identity.js

@@ -0,0 +1,58 @@
+import { hostname } from 'node:os';
+let current = { client: '', clientVersion: '', host: '', server: '' };
+/**
+ * Record who launched this server.
+ *
+ * Called once, after the MCP handshake, with the `clientInfo` the client sent.
+ * Before that — and if a client sends nothing, which is legal — the identity
+ * stays empty and the platform records an anonymous connection rather than
+ * inventing a name. An invented name would be worse than no name: it would look
+ * like a machine somebody could go and check.
+ */
+export function setAgentClient(info, serverVersion) {
+    current = {
+        client: info?.name ?? '',
+        clientVersion: info?.version ?? '',
+        host: machineName(),
+        server: serverVersion ? `sbuilder-mcp/${serverVersion}` : '',
+    };
+}
+/** The current identity, for tests and for the smoke check. */
+export function agentIdentity() {
+    return current;
+}
+/**
+ * The machine's name.
+ *
+ * `os.hostname()` throws on some locked-down sandboxes rather than returning
+ * something useless, and a telemetry label is never worth failing a request
+ * over.
+ */
+function machineName() {
+    try {
+        return hostname();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The headers that carry it.
+ *
+ * Empty fields are OMITTED rather than sent blank, so the platform's
+ * "identified itself / did not" distinction survives the wire. A header set to
+ * the empty string and a header that is absent must not mean different things
+ * here and there.
+ */
+export function identityHeaders(id = current) {
+    const out = {};
+    if (id.client)
+        out['X-Agent-Client'] = id.client;
+    if (id.clientVersion)
+        out['X-Agent-Client-Version'] = id.clientVersion;
+    if (id.host)
+        out['X-Agent-Host'] = id.host;
+    if (id.server)
+        out['X-Agent-Server'] = id.server;
+    return out;
+}

package/dist/transport/media.js

@@ -1,3 +1,4 @@
+import { identityHeaders } from './identity.js';
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { ApiError } from './http.js';
@@ -46,7 +47,14 @@ export async function uploadMedia(ctx, siteId, source) {
     // make a valid upload unparseable at the other end.
     const res = await doFetch(`${ctx.base.replace(/\/$/, '')}/api/media/${encodeURIComponent(siteId)}`, {
         method: 'POST',
-        headers: { Authorization: `Bearer ${siteToken(ctx)}`, Accept: 'application/json' },
+        // 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:
+        // an install whose only traffic is image uploads is still an install.
+        headers: {
+            Authorization: `Bearer ${siteToken(ctx)}`,
+            Accept: 'application/json',
+            ...identityHeaders(),
+        },
         body: form,
     });
     const raw = await res.text();

package/dist/vision/measure.js

@@ -0,0 +1,109 @@
+/** Below this, body text is uncomfortable on a phone. */
+const MIN_BODY_PX = 12;
+/** A few pixels of overlap is a rounding artefact, not a defect. */
+const SLOP = 2;
+function overlaps(a, b) {
+    return (a.x < b.x + b.w - SLOP &&
+        b.x < a.x + a.w - SLOP &&
+        a.y < b.y + b.h - SLOP &&
+        b.y < a.y + a.h - SLOP);
+}
+/**
+ * Everything measurably wrong with how one shot laid out.
+ *
+ * Reported per width, because these defects are per width: a card that fits at
+ * 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) {
+    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;
+        // 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.
+        if (b.x < -SLOP || b.x + b.w > shot.width + SLOP) {
+            out.push({
+                code: 'off_canvas',
+                nodeId: b.id,
+                width: shot.width,
+                problem: `Extends past the ${shot.width}px viewport (${b.x} → ${b.x + b.w}).`,
+                fix: `Give it a width that can shrink — sb_set id "${b.id}", namespace style, keys { "maxWidth": "100%" } at this breakpoint.`,
+            });
+        }
+        // TEXT TOO SMALL. Only where text actually renders: a container inherits a
+        // font size it never shows, and reporting that would be noise.
+        if (b.hasText && b.fontPx && b.fontPx < MIN_BODY_PX) {
+            out.push({
+                code: 'text_too_small',
+                nodeId: b.id,
+                width: shot.width,
+                problem: `Renders at ${b.fontPx}px at ${shot.width}px wide — below the ${MIN_BODY_PX}px a phone can read comfortably.`,
+                fix: `Raise it for this breakpoint: sb_set id "${b.id}", namespace style, keys { "fontSize": "16px" }.`,
+            });
+        }
+    }
+    // OVERLAP, between siblings only. Any parent overlaps its children by
+    // definition, and an absolutely-positioned decoration over a band is a design
+    // 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) {
+        for (const b of shot.boxes) {
+            if (a.id >= b.id || a.id === 'ROOT' || b.id === 'ROOT')
+                continue;
+            if (a.w === 0 || a.h === 0 || b.w === 0 || b.h === 0)
+                continue;
+            const pairKey = `${a.id}|${b.id}`;
+            if (seen.has(pairKey))
+                continue;
+            // Skip ancestry: a box containing another is nesting, not collision.
+            if (contains(a, b) || contains(b, a))
+                continue;
+            if (!overlaps(a, b))
+                continue;
+            seen.add(pairKey);
+            out.push({
+                code: 'overlap',
+                nodeId: a.id,
+                width: shot.width,
+                problem: `Overlaps ${b.id} at ${shot.width}px wide — one of them is unreadable.`,
+                fix: 'Check the two for a fixed height or a negative margin at this breakpoint; sb_look with node_id on each shows which one is out of place.',
+            });
+        }
+    }
+    void byId;
+    return out;
+}
+function contains(outer, inner) {
+    return (outer.x - SLOP <= inner.x &&
+        outer.y - SLOP <= inner.y &&
+        outer.x + outer.w + SLOP >= inner.x + inner.w &&
+        outer.y + outer.h + SLOP >= inner.y + inner.h);
+}
+/**
+ * Measure every width, and report each defect once.
+ *
+ * A card that spills at three widths is one problem, not three — but WHICH
+ * 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) {
+    const merged = new Map();
+    for (const shot of shots) {
+        for (const f of measureShot(shot)) {
+            const key = `${f.code}|${f.nodeId}`;
+            const existing = merged.get(key);
+            if (existing)
+                existing.widths.push(f.width);
+            else
+                merged.set(key, { ...f, widths: [f.width] });
+        }
+    }
+    return [...merged.values()];
+}
+export const MEASURE_NOTICE = 'These were MEASURED on the rendered page, not read off the document — they are what a ' +
+    'visitor meets at those widths. Fix them at the breakpoint named; a defect at 390px and ' +
+    'not at 1440px is a responsive failure, not a broken element.';

package/dist/vision/shoot.js

@@ -54,6 +54,8 @@ export async function shoot(url, opts = {}) {
                 const wb = String(el.className || '')
                     .split(/\s+/)
                     .find((c) => c.startsWith('wb-'));
+                const cs = getComputedStyle(el);
+                const own = (el.textContent ?? '').trim();
                 return {
                     id: el.id,
                     type: wb ? wb.slice(3) : '',
@@ -61,6 +63,8 @@ export async function shoot(url, opts = {}) {
                     y: Math.round(r.y),
                     w: Math.round(r.width),
                     h: Math.round(r.height),
+                    fontPx: Math.round(parseFloat(cs.fontSize) || 0),
+                    hasText: own.length > 0,
                 };
             })));
             // ZOOM. A designer does not judge a card by looking at the whole page, and

package/package.json

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