sbuilder-mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.3 — 2026-08-29
+
+check switch quickly site for agent
+
 ## 0.1.2 — 2026-08-29
 
 244625

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,4 @@
+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';
@@ -48,7 +49,14 @@ 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 });

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';
@@ -47,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),
@@ -96,7 +97,7 @@ export function registerLiveTools(server, ctx, session) {
     });
     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(),
@@ -105,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/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

@@ -51,7 +51,7 @@ export async function uploadMedia(ctx, siteId, source) {
         // 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)}`,
+            Authorization: `Bearer ${siteToken(ctx, siteId)}`,
             Accept: 'application/json',
             ...identityHeaders(),
         },

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/package.json

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