sbuilder-mcp 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # 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
+- feat: sb_media_upload — the agent can add images
+- feat(vision): sb_look frames one element
+- feat: sb_review — the defects a visitor sees, not the ones a save catches
+- fix: base style is the cascade's fallback layer, not a trap
+- docs: one install section per README, not two
+- feat: sbuilder-mcp install — one command, six clients
+- feat: close the gap with a human designer — 22 tools
+- docs: phase-6 plan — close the gap with a human designer
+- fix: three defects a live run found that no unit test could
+- docs: point the setup at the store's Agent app, which hands over the config
+- feat(transport): one credential — an API key now opens the private surface too
+- docs: phase 3 tools, the yield rule, and the wire-protocol facts
+- feat(tools): sb_live_join, sb_look and sb_bind; writes publish to the room
+- feat(catalog): generate the renderer's 22 binding source keys
+- feat(vision): preview links and Chrome screenshots with real node bounding boxes
+- feat(live): the live-edit session, with the yield rule as its organising decision
+- feat(transport): the live-edit socket, with the editor's two reconnect bugs designed out
+- docs: phase-3 plan (live editing and sight)
+- docs: phase 2 tools, traps, and an end-to-end smoke check
+- feat(tools): the page tools - open, outline, catalog search, add, set, move, remove
+- feat(transport): load and save a page's draft document
+- feat(site): pre-save validation mirroring the platform's own refusals
+- feat(site): the builder - nested subtrees, per-breakpoint writes, containment rules
+- feat(site): the in-memory page document with a compressed outline
+- feat(site): node ids and catalog-seeded node construction
+- feat(site): encode the four silent-failure traps as tested code
+- feat(core): overlay-aware tree walking, with pageChildren as the safe default
+- feat(core): the document patch primitive and its three admission rules
+- feat(catalog): generate the 85-element catalog with its AI hints
+- docs: phase-2 plan (the page document) and corrected element count
+- docs: mark phase-1 plan steps complete
+- docs: repo kit, bilingual docs, and the tool-authoring skill
+- feat(tools): sb_connect and sb_site_list; wire the server end to end
+- feat(tools): sb_api_find and sb_api_call - full 310-operation reach in two tools
+- feat(catalog): intent search over the API index, with three honest body verdicts
+- feat(catalog): generate the 310-operation API index from the platform OpenAPI doc
+- feat(transport): route credentials by path prefix, which the OpenAPI doc cannot
+- feat(transport): session login/refresh with a per-use token getter
+- feat(transport): shared HTTP client with the platform error envelope and redaction
+- feat: repo skeleton, response helpers, and a green build/test/smoke gate
+- docs: design spec and phase-1 implementation plan for @sbuilder/mcp
+
 ## 0.1.0
 
 First release.

package/README.md

@@ -81,11 +81,13 @@ make, because those mean "this person's account".
 | `sb_page_create` | Create a page |
 | `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
 | `sb_review` | Every defect a visitor would see, each with the command that fixes it |
+| `sb_media_list` | The site's media library |
+| `sb_media_upload` | Add an image and get its URL — the only route, the upload is multipart |
 | `sb_live_join` | Join the editor's live-edit room as a visible peer — edits then appear live |
 | `sb_look` | Save, render, and return screenshots plus measured node boxes |
 | `sb_bind` | Bind a node's content to real store data |
 
-Twenty-three tools, **310 API operations**. `sb_api_find` is an index rather than a tool per endpoint,
+Twenty-five tools, **310 API operations**. `sb_api_find` is an index rather than a tool per endpoint,
 so the tool list stays short while everything the platform can do stays reachable — and
 operations added to the platform arrive with the next `npm run codegen`.
 

package/README.vi.md

@@ -78,11 +78,13 @@ là "tài khoản của người này".
 | `sb_page_create` | Tạo một trang |
 | `sb_publish` | Biên dịch bản nháp thành trang live (lan sang global dùng chung) |
 | `sb_review` | Mọi khiếm khuyết người xem sẽ thấy, kèm lệnh sửa từng cái |
+| `sb_media_list` | Thư viện ảnh của site |
+| `sb_media_upload` | Thêm ảnh và lấy URL — đường duy nhất, vì upload là multipart |
 | `sb_live_join` | Vào phòng live-edit của editor như một peer nhìn thấy được — sửa gì hiện ngay |
 | `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của từng node |
 | `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật |
 
-Hai mươi ba tool, **310 operation API**. `sb_api_find` là một chỉ mục chứ không phải mỗi endpoint một
+Hai mươi lăm tool, **310 operation API**. `sb_api_find` là một chỉ mục chứ không phải mỗi endpoint một
 tool, nên danh sách tool vẫn ngắn trong khi mọi thứ nền tảng làm được vẫn với tới — và
 operation mới thêm bên nền tảng sẽ tự có sau lần `npm run codegen` kế tiếp.
 

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

@@ -3,7 +3,10 @@ import { z } from 'zod';
 import { text, images } from '../mcp/response.js';
 import { BINDING_SOURCES } from '../catalog/elements.generated.js';
 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';
@@ -60,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
@@ -79,11 +83,58 @@ 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. " +
+        'Search by name, filter by type, page with limit/offset.', {
+        site_id: z.string(),
+        search: z.string().optional(),
+        media_type: z.string().optional().describe('e.g. "image"'),
+        limit: z.number().int().min(1).max(200).optional(),
+        offset: z.number().int().min(0).optional(),
+    }, async ({ site_id, search, media_type, limit, offset }) => text(await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(site_id)}/media`,
+        token: siteToken(ctx),
+        query: { search, mediaType: media_type, limit, offset },
+        fetchImpl: ctx.fetchImpl,
+    })));
+    server.tool('sb_media_upload', 'Put an image into the media library and get its URL back, ready for sb_set. Takes a ' +
+        'local file path or a URL to fetch. This is the ONLY way to add an image: the upload ' +
+        'is multipart, which sb_api_call cannot send.', {
+        site_id: z.string(),
+        path: z.string().optional().describe('A file on this machine'),
+        url: z.string().optional().describe('Fetched, then uploaded'),
+        name: z.string().optional(),
+        folder_id: z.string().optional(),
+        dry_run: z.boolean().optional(),
+    }, async ({ site_id, path, url, name, folder_id, dry_run }) => {
+        if (!path && !url)
+            throw new Error('sbuilder: give sb_media_upload either a path or a url');
+        if (dry_run !== false) {
+            return text({
+                dry_run: true,
+                would_upload: path ?? url,
+                into: site_id,
+                note: 'Nothing was sent. Re-call with dry_run:false to upload.',
+            });
+        }
+        const asset = await uploadMedia(ctx, site_id, { path, url, name, folderId: folder_id });
+        return text({
+            asset,
+            next: asset.url
+                ? `Use it: sb_set id "<node>", namespace specials, keys { "src": ${JSON.stringify(asset.url)} }`
+                : 'Uploaded, but the server returned no url — read it back with sb_media_list.',
         });
     });
     server.tool('sb_bind', "Bind a node's content to real store data, so the page shows actual products rather than " +

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

@@ -0,0 +1,74 @@
+import { identityHeaders } from './identity.js';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { ApiError } from './http.js';
+import { siteToken } from '../tools/credentialpick.js';
+/**
+ * Put an image into the site's media library.
+ *
+ * MULTIPART, which is why this does not go through `request()`. That helper
+ * JSON-encodes every body, and `POST /api/media/{siteId}` takes
+ * `file:formData/file` — so an agent reaching this endpoint through sb_api_call
+ * sent JSON to a multipart handler and got a rejection it could not act on. A
+ * page with no images is not a designed page, so this was the gap between
+ * "the agent can lay out a page" and "the agent can finish one".
+ *
+ * Node ≥22 has FormData, Blob and fetch as globals, so this needs no dependency.
+ */
+export async function uploadMedia(ctx, siteId, source) {
+    const doFetch = ctx.fetchImpl ?? fetch;
+    let bytes;
+    let filename;
+    if (source.path) {
+        bytes = await readFile(source.path);
+        filename = source.name ?? basename(source.path);
+    }
+    else if (source.url) {
+        const res = await doFetch(source.url);
+        if (!res.ok) {
+            throw new ApiError(res.status, 'source_unreachable', `could not fetch ${source.url}`);
+        }
+        bytes = new Uint8Array(await res.arrayBuffer());
+        // A URL's last segment is usually the filename; when it is not (a query-only
+        // CDN link), name it rather than uploading something called "".
+        filename = source.name ?? (new URL(source.url).pathname.split('/').pop() || 'image');
+    }
+    else {
+        throw new Error('sbuilder: give sb_media_upload either a local path or a url');
+    }
+    const form = new FormData();
+    form.set('file', new Blob([bytes]), filename);
+    if (source.name)
+        form.set('name', source.name);
+    if (source.folderId)
+        form.set('folderId', source.folderId);
+    // 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)}`, {
+        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:
+        // 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();
+    let parsed;
+    try {
+        parsed = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        throw new ApiError(res.status, 'non_json_response', raw.slice(0, 400));
+    }
+    if (!res.ok) {
+        const env = (parsed ?? {});
+        throw new ApiError(res.status, env.code ?? 'unknown', env.error ?? `HTTP ${res.status}`);
+    }
+    const body = parsed;
+    return body.asset ?? parsed;
+}

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.0",
+  "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",