sbuilder-mcp 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-09-07
+
+### Fixed
+- sb_live_join now accepts an API key (SB_TOKEN) to join the live-edit room, instead of refusing it and requiring a session; the platform now gates the socket on the key's delegated member permission and its own site, so a key-only install can join like every other tool.
+- sb_media_upload now accepts an API key, instead of refusing it and requiring a session; the platform's upload endpoint moved behind the same gate as sb_sites, and a 401 with a key present now reports that the key lacks the media permission or belongs to another site, rather than telling the caller to switch credentials.
+
 ## [0.2.1] - 2026-09-07
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,12 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-09-07
+
+### Fixed
+- sb_live_join giờ chấp nhận API key (SB_TOKEN) để vào phòng live-edit, thay vì từ chối và bắt buộc dùng session; nền tảng giờ kiểm soát socket dựa trên quyền member được ủy quyền qua key và site của chính key đó, nên một cài đặt chỉ dùng key có thể tham gia như mọi tool khác.
+- sb_media_upload giờ chấp nhận API key, thay vì từ chối và bắt buộc dùng session; endpoint upload của nền tảng giờ nằm sau cùng một cổng chặn với sb_sites, và lỗi 401 khi có key giờ báo rằng key thiếu quyền media hoặc thuộc site khác, thay vì bảo caller đổi sang loại credential khác.
+
 ## [0.2.1] - 2026-09-07
 
 ### Added

package/dist/tools/live.js

@@ -60,30 +60,45 @@ export function bindNode(doc, id, source, field) {
     ];
 }
 /**
- * The live socket takes a session JWT only.
+ * The credential that opens the live-edit room.
  *
- * `server/internal/server/realtime.go:38` refuses API keys, and a rejected
- * socket auth still fires `onopen` — so without this check an API-key-only
- * agent would "join", publish every edit into the void, and never learn why
- * nobody saw them. Every other tool works with the key; this one says so.
+ * AN AGENT KEY NOW WORKS. `server/internal/server/realtime.go:44` gives a `wbk_`
+ * bearer "the same door as a session", decided from the token's own shape, and
+ * gates it on member.read through the key's DELEGATED principal — so the key
+ * sees the room only if the member who minted it may, and only on the site the
+ * key belongs to. This function used to refuse a key-only context outright,
+ * which was true before agent keys landed and now turns away a working setup.
+ *
+ * The peer that appears on the canvas is then the KEY, not a person: the
+ * platform returns `key.ID` and `key.Name` rather than the minter's name,
+ * deliberately — an avatar borrowing a human's name would tell the room a person
+ * is editing when a machine is. So the merchant sees the label they chose for
+ * the key moving around the page.
+ *
+ * Still a GETTER, read per attempt: a session access token lives ~15 minutes and
+ * rotates, and a captured string replays an expired token forever on every
+ * reconnect — silently, because a rejected socket auth still fires `onopen`.
  */
-export function requireSessionForLive(ctx) {
-    if (!ctx.session.loggedIn()) {
-        throw new Error('sbuilder: the live-edit room takes a session token only — an API key cannot join. Set ' +
-            'SB_EMAIL and SB_PASSWORD and call sb_connect, then sb_live_join. Every other tool ' +
-            'works with the key alone.');
+export function liveTokenFor(ctx) {
+    if (!ctx.session.loggedIn() && !ctx.apiKey) {
+        throw new Error('sbuilder: the live-edit room needs a credential. Set SB_TOKEN, or SB_EMAIL and ' +
+            'SB_PASSWORD, and call sb_connect before sb_live_join.');
     }
-    return () => ctx.session.token();
+    // Prefer the key, for the reason `tokenFor` prefers it everywhere: a key is
+    // narrower — one site, its own scopes, revocable on its own — while a session
+    // carries the whole account.
+    return () => (ctx.apiKey ? ctx.apiKey : ctx.session.token());
 }
 export function registerLiveTools(server, ctx, session) {
     server.registerTool('sb_live_join', {
         description: "Join the site's live-edit room as a visible peer: every write then appears in any open " +
-            'editor as it happens. Always yields, so it is safe beside a human. Needs ' +
-            'SB_EMAIL / SB_PASSWORD; the socket refuses API keys.',
+            'editor as it happens, with the agent shown by the API key\'s own name rather than a ' +
+            "person's. Always yields, so it is safe beside a human. Works with SB_TOKEN or with " +
+            'SB_EMAIL / SB_PASSWORD.',
         inputSchema: { site_id: z.string() },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     }, async ({ site_id }) => {
-        const tokenFn = requireSessionForLive(ctx);
+        const tokenFn = liveTokenFor(ctx);
         const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
         const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, tokenFn);
         const live = new LiveSession(socket, {

package/dist/transport/media.js

@@ -66,18 +66,27 @@ export async function uploadMedia(ctx, siteId, source) {
         throw new ApiError(res.status, 'non_json_response', raw.slice(0, 400));
     }
     if (!res.ok) {
-        // THE UPLOAD SURFACE TAKES A SESSION ONLY.
+        // AN API KEY CAN UPLOAD — THE PLATFORM WIDENED THIS.
         //
-        // `/api/media/{siteId}` is mounted behind `RequireAuth` — not the
-        // `RequireAuthOrDefer` that lets a `wbk_` key open `/api/sites`
-        // (server/internal/server/router.go). So a key-only install, which is the
-        // one the store's Agent app hands out and the one the README recommends,
-        // gets a bare "unauthorized" from the ONE tool that cannot be replaced by
-        // sb_api_call, because the body is multipart. Found on a live run.
+        // `/api/media` is now mounted behind `RequireAuthOrDefer`
+        // (server/internal/server/router.go:2821), the same gate `/api/sites` uses,
+        // and `upload_agentkey_test.go` pins the three answers that make it safe:
+        // the key's own site only, the same permission the session path checks, and
+        // no key at all still meaning 401. The platform's own comment gives the
+        // reason it changed — the media LIBRARY already took a key while the UPLOAD
+        // refused one, so a merchant could hand an agent a key that manages every
+        // image the store has and cannot add one.
+        //
+        // This message used to say "an API key cannot upload" and send the caller to
+        // set SB_EMAIL. That is now the wrong instruction: with a key present, a 401
+        // here means the KEY is wrong for this call, not that the wrong KIND of
+        // credential was used, and the old text sent people to fix something that
+        // was never broken.
         if ((res.status === 401 || res.status === 403) && ctx.apiKey && !ctx.session.loggedIn()) {
-            throw new ApiError(res.status, 'media_needs_session', 'sbuilder: the media upload endpoint takes a session token only — an API key cannot ' +
-                'upload. Set SB_EMAIL and SB_PASSWORD and call sb_connect, then retry. Every other ' +
-                'tool works with the key alone.');
+            throw new ApiError(res.status, 'media_key_refused', 'sbuilder: the platform refused this API key for the upload. It accepts a key, so the ' +
+                'cause is the key itself: it needs the media permission, and it must belong to THIS ' +
+                'site — a key minted for another site is refused before the upload is read. Check the ' +
+                "key's scopes and its site, or set SB_EMAIL / SB_PASSWORD to upload as a person.");
         }
         const env = (parsed ?? {});
         const fieldText = env.fields

package/package.json

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