sbuilder-mcp 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 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/tools/live.js

@@ -3,6 +3,8 @@ 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 { RealtimeSocket } from '../transport/socket.js';
 import { LiveSession } from '../live/session.js';
@@ -86,6 +88,49 @@ export function registerLiveTools(server, ctx, session) {
             ...(findings.length > 0 ? { findings, findings_notice: REVIEW_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 " +
         'placeholder text.', {
         id: z.string(),

package/dist/transport/media.js

@@ -0,0 +1,66 @@
+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',
+        headers: { Authorization: `Bearer ${siteToken(ctx)}`, Accept: 'application/json' },
+        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/package.json

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