sbuilder-mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.3 — 2026-08-29
+
+check switch quickly site for agent
+
+## 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/install/index.js

@@ -8,6 +8,14 @@ export function buildEntry(opts, pkg = 'sbuilder-mcp') {
         env.SB_API = opts.api;
     if (opts.token)
         env.SB_TOKEN = opts.token;
+    // NAMING THE STORE is what lets a second one join this entry later instead of
+    // replacing it. A key opens exactly one site, so the ring files each key under
+    // the site it belongs to and the call picks by the site it names.
+    if (opts.token && opts.site) {
+        env.SB_SITES = JSON.stringify([
+            { id: opts.site, ...(opts.siteName ? { name: opts.siteName } : {}), token: opts.token },
+        ]);
+    }
     // Only when a key is absent: a key opens everything the agent does day to day,
     // and writing an account password into six config files to buy the handful of
     // account-level calls it adds is a bad trade the installer should not make for
@@ -45,7 +53,7 @@ export function install(opts) {
             return { client: t.label, path: t.path, status: 'skipped', reason: 'dry run', note: t.note };
         }
         try {
-            const out = mergeInto(t, SERVER_NAME, entry);
+            const out = mergeInto(t, opts.name || SERVER_NAME, entry);
             return {
                 client: t.label,
                 path: t.path,
@@ -72,6 +80,11 @@ export function runInstallCli(argv) {
         email: get('--email') ?? process.env.SB_EMAIL,
         password: get('--password') ?? process.env.SB_PASSWORD,
         clients: get('--client')?.split(','),
+        // One key opens ONE store, so a machine driving two stores needs two
+        // entries. Without this the second install silently replaced the first.
+        name: get('--name'),
+        site: get('--site') ?? process.env.SB_SITE,
+        siteName: get('--site-name'),
         dryRun: argv.includes('--dry-run'),
     };
     if (!opts.token && !(opts.email && opts.password)) {

package/dist/install/write.js

@@ -31,6 +31,35 @@ export function mergeJson(target, name, entry) {
     }
     const servers = (doc[target.key] ?? {});
     const before = JSON.stringify(servers[name] ?? null);
+    // ONE KEY OPENS ONE STORE, so a second store cannot quietly take this entry.
+    //
+    // The server name was a constant, and connecting a second store overwrote the
+    // first: same name, different token. Nothing said so. The agent then reached
+    // store B only, store A's connection died, and the machine went on reporting
+    // itself as installed — the platform even kept the old row, last seen an hour
+    // ago, with no way to tell "stopped being used" from "quietly replaced".
+    //
+    // So an existing entry pointing somewhere else is a REFUSAL that names the
+    // fix, not a silent replacement.
+    const clash = pointsElsewhere(servers[name], entry);
+    if (clash) {
+        // MERGE if we can, refuse if we cannot.
+        //
+        // Two stores on one machine do not need two installs: a key opens one site,
+        // but the server holds a ring of them and picks by the site each call names.
+        // So when the incoming install says WHICH site it is for, its key joins the
+        // ring beside the one already there and both stores work from this single
+        // entry. Only an install that cannot name its site is refused — there is no
+        // way to file its key under anything.
+        const merged = combine(servers[name], entry);
+        if (!merged) {
+            return {
+                wrote: false,
+                reason: `"${name}" in ${target.path} already points at another store (${clash}), and this install did not say which site it is for. Re-run with --site, or with --name to keep a separate entry.`,
+            };
+        }
+        entry = merged;
+    }
     servers[name] = entry;
     doc[target.key] = servers;
     // Idempotent: an identical entry is not a write, so re-running the installer
@@ -95,3 +124,79 @@ export function mergeInto(target, name, entry) {
         ? mergeToml(target, name, entry)
         : mergeJson(target, name, entry);
 }
+/**
+ * Whether an existing entry belongs to a DIFFERENT store than the one being
+ * installed.
+ *
+ * Compared on the credential and the host, because those are what bind a config
+ * to a store — the command and args are identical for every install. Returns the
+ * old prefix so the refusal can say WHICH store it would have replaced; the full
+ * token is never echoed, since these messages get pasted into issues.
+ */
+export function pointsElsewhere(existing, entry) {
+    if (!existing || typeof existing !== 'object')
+        return null;
+    const env = (existing.env ?? {});
+    const oldToken = env.SB_TOKEN ?? '';
+    const oldApi = env.SB_API ?? '';
+    const newToken = entry.env.SB_TOKEN ?? '';
+    const newApi = entry.env.SB_API ?? '';
+    if (!oldToken && !oldApi)
+        return null;
+    if (oldToken === newToken && oldApi === newApi)
+        return null;
+    // A key is bound to one site, so a different key is a different store even
+    // when the host matches.
+    // Eight characters: enough to recognise the key on the API-keys screen,
+    // short enough that a message pasted into an issue is not a credential.
+    const hint = oldToken ? oldToken.slice(0, 8) + '…' : oldApi;
+    return hint;
+}
+/**
+ * Fold a second store into an entry that already serves a first.
+ *
+ * The ring lives in `SB_SITES` as JSON rows, with `SB_TOKEN` staying as the
+ * default for any site that has no pair of its own — which is what keeps the
+ * store that was installed first working without ever having named itself.
+ *
+ * Returns null when the incoming install carries no site, because then its key
+ * cannot be filed under anything and the only honest options are a refusal or a
+ * silent overwrite.
+ */
+export function combine(existing, incoming) {
+    const bySite = new Map();
+    for (const src of [existing.env?.SB_SITES, incoming.env?.SB_SITES]) {
+        try {
+            const rows = JSON.parse(src || '[]');
+            if (!Array.isArray(rows))
+                continue;
+            for (const r of rows) {
+                if (r?.id && r?.token) {
+                    // The LATER row wins on name: a store that was renamed should show its
+                    // new name after the next install, not the one it had months ago.
+                    bySite.set(r.id, { id: r.id, token: r.token, ...(r.name ? { name: r.name } : {}) });
+                }
+            }
+        }
+        catch {
+            // A hand-mangled value is skipped, not thrown on: the other store's entry
+            // is still perfectly good and must survive.
+        }
+    }
+    if (bySite.size === 0)
+        return null;
+    return {
+        command: incoming.command,
+        args: incoming.args,
+        env: {
+            ...existing.env,
+            ...incoming.env,
+            // The FIRST store keeps the default slot. Handing it to the newcomer would
+            // silently redirect every call that does not name a site — the same
+            // takeover this exists to prevent, one level down.
+            ...(existing.env?.SB_TOKEN ? { SB_TOKEN: existing.env.SB_TOKEN } : {}),
+            ...(existing.env?.SB_API ? { SB_API: existing.env.SB_API } : {}),
+            SB_SITES: JSON.stringify([...bySite.values()]),
+        },
+    };
+}

package/dist/server.js

@@ -1,3 +1,5 @@
+import { readKeyRing } from './transport/keys.js';
+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';
@@ -47,10 +49,26 @@ export function pkgVersion() {
 }
 export function buildContext() {
     const base = process.env.SB_API ?? 'http://localhost:8080';
-    return { base, session: new Session(base), apiKey: process.env.SB_TOKEN };
+    return {
+        base,
+        session: new Session(base),
+        apiKey: process.env.SB_TOKEN,
+        // Extra stores, if this machine drives more than one. A key opens exactly
+        // one site, so several stores mean several keys — not several installs.
+        keys: readKeyRing(),
+    };
 }
 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/api.js

@@ -1,3 +1,4 @@
+import { keyForSite, siteInPath } from '../transport/keys.js';
 import { z } from 'zod';
 import { API_OPERATIONS } from '../catalog/api.generated.js';
 import { searchOperations, describeOperation } from '../catalog/search.js';
@@ -12,7 +13,7 @@ import { text } from '../mcp/response.js';
  * session carries the whole account. Preferring it is also what lets a merchant
  * connect an agent with one env var and no password.
  */
-export function tokenFor(ctx, credential) {
+export function tokenFor(ctx, credential, siteId) {
     if (credential === 'apiKey') {
         // Naming the env var matters: the alternative is a 401 api_key_required
         // from the platform, which reads like a permissions problem rather than an
@@ -23,6 +24,14 @@ export function tokenFor(ctx, credential) {
         return ctx.apiKey;
     }
     if (credential === 'siteScoped') {
+        // A store with a key of its own always wins. Sending store A's key to store
+        // B is refused by the platform as `api_key_site` — correctly, and in a way
+        // that reads like a permissions bug rather than the wrong credential.
+        if (ctx.keys) {
+            const own = keyForSite(ctx.keys, siteId);
+            if (own)
+                return own;
+        }
         if (ctx.apiKey)
             return ctx.apiKey;
         if (ctx.session.loggedIn())
@@ -47,7 +56,7 @@ export async function callOperation(ctx, args) {
         }
         path = path.replace(`{${name}}`, encodeURIComponent(value));
     }
-    const token = tokenFor(ctx, op.credential);
+    const token = tokenFor(ctx, op.credential, siteInPath(path));
     const dryRun = args.dry_run !== false;
     if (dryRun) {
         return {

package/dist/tools/credentialpick.js

@@ -5,7 +5,12 @@ import { tokenFor } from './api.js';
  * A one-line re-export so `transport/` does not reach into `tools/api.ts` for
  * the rule and quietly grow a second copy of it. There is exactly one answer to
  * "which token opens /api/sites", and it lives in `tokenFor`.
+ *
+ * PASS THE SITE. An install may hold keys for several stores, and the key for
+ * the store being addressed is the only one the platform will accept — omitting
+ * it silently falls back to the default key, which then fails as `api_key_site`
+ * on somebody's second store.
  */
-export function siteToken(ctx) {
-    return tokenFor(ctx, 'siteScoped');
+export function siteToken(ctx, siteId) {
+    return tokenFor(ctx, 'siteScoped', siteId);
 }

package/dist/tools/live.js

@@ -1,3 +1,4 @@
+import { siteRef } from './siteref.js';
 import { randomBytes } from 'node:crypto';
 import { z } from 'zod';
 import { text, images } from '../mcp/response.js';
@@ -6,6 +7,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';
@@ -46,9 +48,9 @@ export function registerLiveTools(server, ctx, session) {
     server.tool('sb_live_join', "Join the editor's live-edit room for this site, as a visible peer. Once joined, every " +
         'sb_add / sb_set / sb_move / sb_remove / sb_bind also goes out as a live op, so anyone ' +
         'with the editor open watches the page assemble. Safe alongside a human: this client ' +
-        'always yields — it never answers a snapshot request and re-pulls on any divergence.', { site_id: z.string() }, async ({ site_id }) => {
+        'always yields — it never answers a snapshot request and re-pulls on any divergence.', { site_id: siteRef(ctx) }, async ({ site_id }) => {
         const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
-        const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, () => siteToken(ctx));
+        const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, () => siteToken(ctx, site_id));
         const live = new LiveSession(socket, {
             onRemote: (patches) => session.applyRemote(patches),
             onDesync: (reason) => session.markStale(reason),
@@ -62,8 +64,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,16 +84,20 @@ 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(),
+        site_id: siteRef(ctx),
         search: z.string().optional(),
         media_type: z.string().optional().describe('e.g. "image"'),
         limit: z.number().int().min(1).max(200).optional(),
@@ -99,14 +106,14 @@ export function registerLiveTools(server, ctx, session) {
         base: ctx.base,
         method: 'GET',
         path: `/api/sites/${encodeURIComponent(site_id)}/media`,
-        token: siteToken(ctx),
+        token: siteToken(ctx, site_id),
         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(),
+        site_id: siteRef(ctx),
         path: z.string().optional().describe('A file on this machine'),
         url: z.string().optional().describe('Fetched, then uploaded'),
         name: z.string().optional(),

package/dist/tools/page.js

@@ -1,3 +1,4 @@
+import { siteRef } from './siteref.js';
 import { z } from 'zod';
 import { text } from '../mcp/response.js';
 import { loadSource, saveSource } from '../transport/pages.js';
@@ -151,7 +152,7 @@ const specSchema = z.lazy(() => z.object({
 export function registerPageTools(server, ctx) {
     const session = new PageSession(ctx);
     server.tool('sb_page_open', 'Open a page for editing and return its outline. Call before any sb_add / sb_set / ' +
-        'sb_move / sb_remove. Find page ids with sb_api_find "list pages".', { site_id: z.string(), page_id: z.string() }, async ({ site_id, page_id }) => {
+        'sb_move / sb_remove. Find page ids with sb_api_find "list pages".', { site_id: siteRef(ctx), page_id: z.string() }, async ({ site_id, page_id }) => {
         const outline = await session.open(site_id, page_id);
         return text({ outline, ...reviewField(session.current()) });
     });
@@ -307,16 +308,16 @@ export function registerPageTools(server, ctx) {
         return text({ duplicated: id, into: ids[0], nodes: ids.length, rev: d.rev });
     });
     server.tool('sb_templates', "The store's saved section templates — designed sections a person starts from rather " +
-        'than assembling one. Use sb_template_use to drop one into the open page.', { site_id: z.string() }, async ({ site_id }) => text(await request({
+        'than assembling one. Use sb_template_use to drop one into the open page.', { site_id: siteRef(ctx) }, async ({ site_id }) => text(await request({
         base: ctx.base,
         method: 'GET',
         path: `/api/sites/${encodeURIComponent(site_id)}/section-templates`,
-        token: siteToken(ctx),
+        token: siteToken(ctx, site_id),
         fetchImpl: ctx.fetchImpl,
     })));
     server.tool('sb_template_use', 'Instantiate a saved section template into a page. The server does the copy, so the ' +
         'section arrives exactly as it was designed — then re-open the page to see it.', {
-        site_id: z.string(),
+        site_id: siteRef(ctx),
         template_id: z.string(),
         page_id: z.string(),
         dry_run: z.boolean().optional(),
@@ -329,7 +330,7 @@ export function registerPageTools(server, ctx) {
             base: ctx.base,
             method: 'POST',
             path,
-            token: siteToken(ctx),
+            token: siteToken(ctx, site_id),
             body: { pageId: page_id },
             fetchImpl: ctx.fetchImpl,
         });
@@ -340,15 +341,15 @@ export function registerPageTools(server, ctx) {
             note: 'Re-open the page with sb_page_open — this session still holds the old tree.',
         });
     });
-    server.tool('sb_page_list', "Every page on the site, with its slug and whether it is live.", { site_id: z.string() }, async ({ site_id }) => text(await request({
+    server.tool('sb_page_list', "Every page on the site, with its slug and whether it is live.", { site_id: siteRef(ctx) }, async ({ site_id }) => text(await request({
         base: ctx.base,
         method: 'GET',
         path: `/api/sites/${encodeURIComponent(site_id)}/pages`,
-        token: siteToken(ctx),
+        token: siteToken(ctx, site_id),
         fetchImpl: ctx.fetchImpl,
     })));
     server.tool('sb_page_create', 'Create a page. It arrives empty; sb_page_open seeds its ROOT so you can build into it.', {
-        site_id: z.string(),
+        site_id: siteRef(ctx),
         name: z.string(),
         settings: z.record(z.unknown()).optional(),
         dry_run: z.boolean().optional(),
@@ -360,14 +361,14 @@ export function registerPageTools(server, ctx) {
             base: ctx.base,
             method: 'POST',
             path,
-            token: siteToken(ctx),
+            token: siteToken(ctx, site_id),
             body: { name, ...(settings ? { settings } : {}) },
             fetchImpl: ctx.fetchImpl,
         }));
     });
     server.tool('sb_publish', 'Compile the draft into the live page. PUBLISH CASCADES: a page sharing a global ' +
         'section with others republishes them too, because a header edited once must not go ' +
-        'live on one page and stay stale on the rest.', { site_id: z.string(), page_id: z.string(), dry_run: z.boolean().optional() }, async ({ site_id, page_id, dry_run }) => {
+        'live on one page and stay stale on the rest.', { site_id: siteRef(ctx), page_id: z.string(), dry_run: z.boolean().optional() }, async ({ site_id, page_id, dry_run }) => {
         const path = `/api/sites/${encodeURIComponent(site_id)}/pages/${encodeURIComponent(page_id)}/publish`;
         if (dry_run !== false)
             return text({ dry_run: true, would_post: path });
@@ -375,7 +376,7 @@ export function registerPageTools(server, ctx) {
             base: ctx.base,
             method: 'POST',
             path,
-            token: siteToken(ctx),
+            token: siteToken(ctx, site_id),
             fetchImpl: ctx.fetchImpl,
         }));
     });

package/dist/tools/session.js

@@ -62,11 +62,114 @@ export function registerSessionTools(server, ctx) {
         email: z.string().optional(),
         password: z.string().optional(),
     }, async (args) => text(await connect(ctx, args)));
-    server.tool('sb_site_list', 'List the sites this account can operate.', {}, async () => text(await request({
+    server.tool('sb_site_list', 'List the stores this install can reach. Switching store is just passing a ' +
+        'different site_id on the next call — no reconnect, no reinstall.', {}, async () => text(await sitesFor(ctx)));
+}
+/**
+ * Which stores this install can reach.
+ *
+ * Extracted from the tool so it can be tested without standing up an MCP server
+ * — and because it answers a question the platform deliberately will not: `GET
+ * /api/sites` refuses an API key (`api_key_scope`, "a key addresses one site's
+ * resources; it cannot list sites"). That refusal is right, and it left the
+ * normal install unable to name the one parameter that switches store.
+ */
+export async function sitesFor(ctx) {
+    /*
+     * TWO SOURCES, and the key one is the source that was missing.
+     *
+     * `GET /api/sites` needs an account session. An API key is refused there on
+     * purpose — `api_key_scope`, "a key addresses one site's resources; it cannot
+     * list sites" — which is correct and left the normal install with NO way to
+     * answer "which stores can I reach". Switching store is one parameter, and the
+     * agent could not discover the parameter.
+     *
+     * Each ring entry is then PROBED, because the config outlives the store. A
+     * deleted site leaves its key in the database (nothing cascades to a Citus
+     * reference table) and leaves its row in SB_SITES forever, so an unchecked
+     * list advertises a store that answers 404 to everything — and it does so on
+     * the one screen whose entire job is to say what is available.
+     */
+    const fromKeys = await Promise.all([...(ctx.keys?.bySite.values() ?? [])].map(async (s) => ({
+        id: s.id,
+        // The NAME is the point: a person says "switch to Áo Thun", never
+        // "switch to site_14675b5a570b248d".
+        name: s.name,
+        // Enough to match the store on its API-keys screen, never the whole key.
+        key: s.token.slice(0, 8) + '…',
+        source: 'key',
+        ...(await probe(ctx, s.id, s.token)),
+    })));
+    if (!ctx.session.loggedIn()) {
+        if (fromKeys.length > 0)
+            return { sites: fromKeys };
+        // An older install: one key, no site recorded beside it. Say what to do
+        // rather than returning an empty list, which reads as "you have no stores".
+        return {
+            sites: [],
+            note: ctx.apiKey
+                ? 'This install holds one key but did not record which store it opens. Re-run the ' +
+                    "install command from the store's Agent app — it now passes --site — or call " +
+                    "sb_connect to list an account's stores."
+                : 'No credential. Set SB_TOKEN, or call sb_connect with SB_EMAIL and SB_PASSWORD.',
+        };
+    }
+    const account = await request({
         base: ctx.base,
         method: 'GET',
         path: '/api/sites',
         token: ctx.session.token(),
         fetchImpl: ctx.fetchImpl,
-    })));
+    });
+    return { ...account, keyed_sites: fromKeys };
+}
+/**
+ * Is this store still there, and does its key still open it?
+ *
+ * One cheap read per store, on the tool whose whole job is to report what is
+ * available — the only place where being right is worth a round trip. Every
+ * other tool takes the store it was given and lets the platform answer.
+ *
+ * The four outcomes are deliberately distinct, because the remedy differs and a
+ * merged one sends people to the wrong screen: a deleted store needs its row
+ * removed from the config, a revoked key needs a new key, a scope problem needs
+ * the key re-minted with more, and an unreachable host needs nothing at all
+ * except trying again later.
+ */
+async function probe(ctx, siteId, token) {
+    try {
+        await request({
+            base: ctx.base,
+            method: 'GET',
+            path: `/api/sites/${encodeURIComponent(siteId)}/pages`,
+            query: { limit: 1 },
+            token,
+            fetchImpl: ctx.fetchImpl,
+        });
+        return { status: 'ok' };
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 404) {
+            return {
+                status: 'gone',
+                fix: 'This store no longer exists. Remove its row from SB_SITES, or re-run the install command for a store that does.',
+            };
+        }
+        if (status === 401) {
+            return {
+                status: 'key_rejected',
+                fix: "The key was revoked or is unknown. Mint a new one from that store's Agent app and re-run the install command.",
+            };
+        }
+        if (status === 403) {
+            return {
+                status: 'key_too_narrow',
+                fix: 'The key authenticates but may not read this store. Re-mint it, or check the role of the member who created it.',
+            };
+        }
+        // A network failure is not a verdict about the store, and reporting it as
+        // one would send somebody to delete a config row over a flaky connection.
+        return { status: 'unreachable' };
+    }
 }

package/dist/tools/siteref.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { resolveSite } from '../transport/keys.js';
+/**
+ * A `site_id` argument that also accepts the store's NAME.
+ *
+ * Because a person switching store says "Áo Thun", never
+ * "site_14675b5a570b248d". The ring already records both for every store this
+ * machine holds a key for, and without this the name reached the URL builder
+ * verbatim and produced `/api/sites/Áo%20Thun/pages` — a 404 that names nothing.
+ *
+ * Resolved in the SCHEMA rather than in each handler, deliberately. Nine tools
+ * take a site id, and a rule applied by hand nine times is a rule that will be
+ * applied eight times the moment a tenth is added — with the tenth silently
+ * being the only one that cannot switch by name.
+ *
+ * Pass-through is the fallback: anything that does not match a known store is
+ * handed on untouched, so ids keep working, and so does a store this install has
+ * no key for (which then fails at the platform, as it should).
+ */
+export function siteRef(ctx) {
+    return z
+        .string()
+        .describe('Store id, or the store name as shown by sb_site_list — "Áo Thun" works as well as ' +
+        'site_14675b5a570b248d.')
+        .transform((given) => {
+        if (!ctx.keys)
+            return given;
+        // An AMBIGUOUS name resolves to nothing and falls through unchanged, so
+        // the platform refuses it rather than this picking one of two stores with
+        // the same name and writing edits into the wrong one.
+        return resolveSite(ctx.keys, given)?.id ?? given;
+    });
+}

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/keys.js

@@ -0,0 +1,73 @@
+/**
+ * Read the ring from the environment.
+ *
+ * A malformed value yields an EMPTY ring rather than throwing. This runs at
+ * startup, before any transport exists to report through, so the failure would
+ * be a server that refuses to start with its reason on a stdout nobody reads —
+ * and `SB_TOKEN` alone still works, which is the single-store case.
+ */
+export function readKeyRing(env = process.env) {
+    const bySite = new Map();
+    try {
+        const parsed = JSON.parse(env.SB_SITES || '[]');
+        if (Array.isArray(parsed)) {
+            for (const row of parsed) {
+                const r = row;
+                if (typeof r?.id === 'string' && r.id && typeof r.token === 'string' && r.token) {
+                    bySite.set(r.id, {
+                        id: r.id,
+                        token: r.token,
+                        ...(typeof r.name === 'string' && r.name ? { name: r.name } : {}),
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // Not valid JSON. Fall through with an empty ring.
+    }
+    return { bySite, fallback: env.SB_TOKEN || undefined };
+}
+export function siteInPath(path) {
+    const m = /^\/api\/sites\/([^/]+)/.exec(path);
+    return m ? decodeURIComponent(m[1]) : undefined;
+}
+/**
+ * The key for one request.
+ *
+ * A named site with a key of its own always wins, so a machine holding three
+ * stores never sends store A's credential to store B — which the platform would
+ * refuse with `api_key_site`, correctly and confusingly.
+ */
+export function keyForSite(ring, siteId) {
+    if (siteId) {
+        const own = ring.bySite.get(siteId);
+        if (own)
+            return own.token;
+    }
+    return ring.fallback;
+}
+/** The same answer, for a caller that holds a path rather than an id. */
+export function keyForPath(ring, path) {
+    return keyForSite(ring, siteInPath(path));
+}
+/** Every store this install holds a key for, freshest information first. */
+export function knownSites(ring) {
+    return [...ring.bySite.values()];
+}
+/**
+ * Find a store by whatever the person said — its id or its name.
+ *
+ * Names are matched case- and space-insensitively because they are typed by
+ * hand into a chat, not copied. An ambiguous name returns nothing rather than
+ * guessing: two stores called "Shop" and a silent pick means edits land in the
+ * wrong one, which is the failure this whole area keeps producing.
+ */
+export function resolveSite(ring, needle) {
+    const want = needle.trim().toLowerCase();
+    const byId = ring.bySite.get(needle.trim());
+    if (byId)
+        return byId;
+    const named = [...ring.bySite.values()].filter((s) => (s.name ?? '').trim().toLowerCase() === want);
+    return named.length === 1 ? named[0] : undefined;
+}

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, siteId)}`,
+            Accept: 'application/json',
+            ...identityHeaders(),
+        },
         body: form,
     });
     const raw = await res.text();

package/dist/transport/pages.js

@@ -19,7 +19,7 @@ export async function loadSource(ctx, siteId, pageId) {
         base: ctx.base,
         method: 'GET',
         path: sourcePath(siteId, pageId),
-        token: siteToken(ctx),
+        token: siteToken(ctx, siteId),
         fetchImpl: ctx.fetchImpl,
     }));
     return out.source;
@@ -43,7 +43,7 @@ export async function saveSource(ctx, siteId, pageId, document) {
         base: ctx.base,
         method: 'PUT',
         path: sourcePath(siteId, pageId),
-        token: siteToken(ctx),
+        token: siteToken(ctx, siteId),
         body: { document, schemaVersion: document.schema_version ?? 1 },
         fetchImpl: ctx.fetchImpl,
     }));

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.3",
   "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",