sbuilder-mcp 0.23.0 → 0.24.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.24.0] - 2026-09-10
+
+### Added
+- sb_template_use now fills a picture slot in a built-in layout with a real image from the site's own media library, preferring a landscape image where the layout wants one, instead of leaving a placeholder note asking the caller to add one by hand.
+- sb_templates gained a new built-in layout, sb_gallery, a row of up to six images pulled from the site's media library.
+- The API catalog gained three operations: `POST /api/media/{siteId}/from-url` (reachable through sb_api_call as well as sb_media_upload), `GET /api/sites/{siteId}/forms/submissions`, and `POST /api/sites/{siteId}/translations/review/bulk`.
+
+### Changed
+- sb_template_use no longer repeats a photo already placed on the page: each picture slot it fills draws only from images the page is not already showing, so a hero added first and a gallery added second no longer show the same image twice.
+- sb_template_use now reports `images_available` (the count of unused images in the site's library) in its dry-run preview, and names sb_media_upload in its result when the site's library has no images to draw from.
+
+## [0.23.1] - 2026-09-10
+
+### Added
+- sb_media_upload now asks the platform to fetch a URL source itself (`POST /api/media/{siteId}/from-url`) before falling back to downloading and re-uploading the bytes, so the file makes one network hop instead of two and its content type comes from the origin's own answer instead of being guessed from a header or extension.
+
+### Changed
+- sb_media_upload now raises rather than working around it when the platform refuses a URL source as `remote_blocked` (an address outside the public internet, such as a private range or the cloud metadata endpoint), since fetching that same URL from this server's own machine would defeat the platform's guard rather than respect it.
+
+### Fixed
+- sb_media_upload now reports the platform's own reason when it cannot reach a URL source (for example, "www.blender.org answered 404") instead of the generic "the platform could not read it".
+
 ## [0.23.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,28 @@ 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.24.0] - 2026-09-10
+
+### Added
+- sb_template_use giờ lấp ô chứa ảnh trong một layout dựng sẵn bằng ảnh thật từ thư viện media của chính site, ưu tiên ảnh nằm ngang khi layout cần, thay vì để lại một ghi chú yêu cầu người gọi tự thêm ảnh.
+- sb_templates có thêm một layout dựng sẵn mới, sb_gallery, một hàng tối đa sáu ảnh lấy từ thư viện media của site.
+- Catalog API có thêm ba operation: `POST /api/media/{siteId}/from-url` (gọi được qua sb_api_call cũng như qua sb_media_upload), `GET /api/sites/{siteId}/forms/submissions`, và `POST /api/sites/{siteId}/translations/review/bulk`.
+
+### Changed
+- sb_template_use giờ không còn lặp lại một ảnh đã đặt trên trang: mỗi ô chứa ảnh nó lấp chỉ lấy từ những ảnh trang chưa hiển thị, nên một hero thêm trước và một dải ảnh thêm sau không còn hiện cùng một ảnh hai lần.
+- sb_template_use giờ báo `images_available` (số ảnh chưa dùng trong thư viện site) trong bản xem trước dry-run, và nêu tên sb_media_upload trong kết quả khi thư viện site không có ảnh nào để lấy.
+
+## [0.23.1] - 2026-09-10
+
+### Added
+- sb_media_upload giờ yêu cầu chính nền tảng tải nguồn URL trước (`POST /api/media/{siteId}/from-url`) rồi mới lùi về cách cũ là tải xuống rồi upload lại, nên file chỉ đi một chặng mạng thay vì hai, và content type được lấy từ câu trả lời của chính nguồn thay vì đoán từ header hay phần mở rộng.
+
+### Changed
+- sb_media_upload giờ báo lỗi thay vì tìm cách lách khi nền tảng từ chối một nguồn URL với mã `remote_blocked` (địa chỉ không thuộc internet công khai, như dải private hoặc endpoint metadata của cloud), vì việc tự tải URL đó từ máy chạy server này sẽ phá vỡ lớp bảo vệ của nền tảng thay vì tuân theo nó.
+
+### Fixed
+- sb_media_upload giờ báo đúng lý do của chính nền tảng khi không tải được một nguồn URL (ví dụ "www.blender.org answered 404") thay vì thông báo chung "the platform could not read it".
+
 ## [0.23.0] - 2026-09-10
 
 ### Added

package/dist/catalog/api.generated.js

@@ -1,8 +1,8 @@
 export const SWAGGER_SOURCE = {
-    "operations": 495,
+    "operations": 498,
     "definitions": 104,
-    "bodyCarrying": 177,
-    "bodyUndescribed": 63,
+    "bodyCarrying": 178,
+    "bodyUndescribed": 64,
     "generatedFrom": "server/docs/swagger.json"
 };
 export const API_OPERATIONS = [
@@ -1882,6 +1882,34 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "post:/api/media/{siteId}/from-url",
+        "method": "POST",
+        "path": "/api/media/{siteId}/from-url",
+        "tags": [
+            "media"
+        ],
+        "summary": "Upload media by URL, fetched server-side",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "url, and optionally folderId and name"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/notifications",
         "method": "GET",
@@ -6653,6 +6681,41 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/forms/submissions",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/forms/submissions",
+        "tags": [
+            "forms"
+        ],
+        "summary": "Search a site's responses across all of its forms",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site id"
+            },
+            {
+                "name": "q",
+                "in": "query",
+                "required": false,
+                "type": "string",
+                "description": "Folded substring over every answer"
+            },
+            {
+                "name": "limit",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "Page size (max 200)"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/forms/{id}",
         "method": "GET",
@@ -12500,6 +12563,19 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "post:/api/sites/{siteId}/translations/review/bulk",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/translations/review/bulk",
+        "tags": [
+            "translations"
+        ],
+        "summary": "Approve many machine-written values at once",
+        "params": [],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "delete:/api/sites/{siteId}/trash",
         "method": "DELETE",

package/dist/catalog/elements.generated.js

@@ -18195,8 +18195,7 @@ export const ELEMENTS = {
                 "overflow": "hidden"
             },
             "config": {
-                "defaultNum": 1,
-                "activeButton": ""
+                "defaultNum": 1
             },
             "specials": {
                 "button": true
@@ -19100,7 +19099,6 @@ export const ELEMENTS = {
                             "quantity_default",
                             "toggle_button",
                             "defaultNum",
-                            "activeButton",
                             "quantityButtonId",
                             "quantityInputId"
                         ]
@@ -19179,7 +19177,6 @@ export const ELEMENTS = {
             "quantity_default",
             "toggle_button",
             "defaultNum",
-            "activeButton",
             "quantityButtonId",
             "quantityInputId",
             "width_select",

package/dist/catalog/shapes.generated.js

@@ -1,10 +1,10 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 216,
-    "shaped": 166,
-    "fromHandlers": 166,
+    "writeOperations": 218,
+    "shaped": 168,
+    "fromHandlers": 168,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
-    "structsRead": 1647
+    "structsRead": 1649
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{siteId}/api-keys": {
@@ -3669,6 +3669,24 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "post:/api/media/{siteId}/from-url": {
+        "fields": [
+            {
+                "name": "url",
+                "type": "string"
+            },
+            {
+                "name": "folderId",
+                "type": "string"
+            },
+            {
+                "name": "name",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "fromURLRequest"
+    },
     "put:/api/sites/{siteId}/media/assets/{assetId}": {
         "fields": [
             {
@@ -6785,6 +6803,33 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "post:/api/sites/{siteId}/translations/review/bulk": {
+        "fields": [
+            {
+                "name": "locale",
+                "type": "string"
+            },
+            {
+                "name": "Entries",
+                "type": "object"
+            },
+            {
+                "name": "all",
+                "type": "boolean",
+                "note": "All asks for the whole match set instead of a list."
+            },
+            {
+                "name": "search",
+                "type": "string"
+            },
+            {
+                "name": "entity",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/sites/{siteId}/translations/auto": {
         "fields": [
             {

package/dist/domains/site/patterns.js

@@ -1,4 +1,29 @@
 import { toSpecs } from './importmap.js';
+/**
+ * A REAL IMAGE, from the site's own library, or nothing.
+ *
+ * The instinct a pattern library invites is a placeholder — a grey box, a stock
+ * photo keyed off a word — and both are worse than an empty slot. This repo
+ * already records why stock is not a source: `loremflickr` answered
+ * "kids,clothing" with a cat statue and a photo of an adult, and ten photos from
+ * ten sources read as a scrape. A grey box reads as unfinished, which it is.
+ *
+ * The library is the honest source: those are the merchant's own images, already
+ * uploaded, already the right subject. Measured on a live store: 164 assets, 50
+ * of them images. A `want` of "landscape" is a shape request, not a subject one —
+ * a hero panel filled with a portrait crop is the aspect-ratio mistake rule 6 is
+ * about — and it degrades to any unused image rather than to none.
+ */
+function pick(pool, used, want) {
+    if (!pool?.length)
+        return null;
+    const free = pool.filter((m) => m.url && !used.has(m.url));
+    const wide = free.filter((m) => (m.width ?? 0) > (m.height ?? 0));
+    const chosen = (want === 'landscape' && wide[0]) || free[0] || null;
+    if (chosen)
+        used.add(chosen.url);
+    return chosen;
+}
 /**
  * THE LOOK A PAGE HAS BEFORE IT HAS ANYTHING, and it is not nothing.
  *
@@ -47,15 +72,17 @@ const row = (children, wrap = false) => ({
 const h = (text, level = 2) => ({ kind: 'heading', level, text });
 const p = (text) => ({ kind: 'text', text });
 const cta = (text, href = '#') => ({ kind: 'button', variant: 'cta', text, href });
-const img = (alt) => ({
-    // A PLACEHOLDER WITH NO SRC IS DROPPED by the mapper, which is right — an
-    // empty frame is not content. So a pattern that wants a picture says so in
-    // words and the caller points sb_set at it, rather than the page shipping a
-    // grey box nobody chose.
-    kind: 'image',
-    src: '',
-    alt,
-});
+/**
+ * The picture slot: a real image when the site has one, and WORDS when it does
+ * not.
+ *
+ * An image with no src is dropped by the mapper, which is right — an empty frame
+ * is not content — so the fallback is a sentence naming the call that fills it,
+ * not a grey box. A grey box reads as unfinished because it is.
+ */
+const img = (m, alt, hint) => m
+    ? { kind: 'image', src: m.url, alt: m.name ?? alt }
+    : { kind: 'text', text: hint };
 /**
  * The set. Deliberately small and deliberately ordinary: these are the bands
  * every commercial page is built from, and a library that tried to be clever
@@ -66,12 +93,21 @@ export const LAYOUT_PATTERNS = [
         id: 'sb_hero_split',
         name: 'Hero — hai cột',
         use: 'Mở đầu trang: tiêu đề, một câu, nút hành động bên trái; chỗ cho ảnh bên phải',
-        build: (t) => section([
-            row([
-                { kind: 'group', direction: 'column', children: [h('Tiêu đề chính', 1), p('Một câu nói rõ bạn bán gì và cho ai.'), cta('Mua ngay')] },
-                { kind: 'group', direction: 'column', children: [p('Đặt ảnh vào đây — sb_add một image, hoặc sb_set src lên khối này.')] },
-            ]),
-        ], t),
+        build: (t, pool) => {
+            const used = new Set();
+            return section([
+                row([
+                    { kind: 'group', direction: 'column', children: [h('Tiêu đề chính', 1), p('Một câu nói rõ bạn bán gì và cho ai.'), cta('Mua ngay')] },
+                    {
+                        kind: 'group',
+                        direction: 'column',
+                        children: [
+                            img(pick(pool, used, 'landscape'), 'Ảnh mở đầu', 'Chưa có ảnh nào trong thư viện — sb_media_upload một URL, rồi sb_set src lên khối này.'),
+                        ],
+                    },
+                ]),
+            ], t);
+        },
     },
     {
         id: 'sb_hero_centered',
@@ -110,6 +146,31 @@ export const LAYOUT_PATTERNS = [
         use: 'Một câu và một nút, đặt cuối trang hoặc giữa hai band nội dung',
         build: (t) => section([h('Sẵn sàng bắt đầu?'), p('Một câu nhắc lại lời hứa chính.'), cta('Mua ngay')], t, { alignItems: 'center', textAlign: 'center' }, { alignItems: 'center' }),
     },
+    {
+        id: 'sb_gallery',
+        name: 'Dải ảnh',
+        use: 'Một hàng ảnh cuốn dòng, lấy từ thư viện ảnh của chính site',
+        build: (t, pool) => {
+            const used = new Set();
+            const shots = [];
+            // SIX IS A WALL, THREE IS A ROW. Bounded because a gallery is a design
+            // decision and not a dump of the library — a merchant with 164 assets does
+            // not want 164 of them in one band.
+            for (let i = 0; i < 6; i += 1) {
+                const m = pick(pool, used, 'any');
+                if (!m)
+                    break;
+                shots.push({ kind: 'image', src: m.url, alt: m.name ?? 'Ảnh' });
+            }
+            if (shots.length === 0) {
+                return section([
+                    h('Thư viện ảnh'),
+                    p('Chưa có ảnh nào trong thư viện — sb_media_upload một URL rồi dựng lại dải này.'),
+                ], t);
+            }
+            return section([h('Thư viện ảnh'), row(shots, true)], t);
+        },
+    },
     {
         id: 'sb_faq',
         name: 'Câu hỏi thường gặp',

package/dist/tools/page.js

@@ -20,7 +20,7 @@ import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
 import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
 import { catalogMatches, traitsFor } from '../catalog/element-search.js';
-import { LAYOUT_PATTERNS, PATTERN_BY_ID, THEME_TOKENS } from '../domains/site/patterns.js';
+import { LAYOUT_PATTERNS, PATTERN_BY_ID, THEME_TOKENS, } from '../domains/site/patterns.js';
 import { tokensFromPage } from '../domains/site/importmap.js';
 import { middleEnd } from '../domains/site/traps.js';
 import { applyPatches } from '../core/patch.js';
@@ -703,7 +703,42 @@ export function registerPageTools(server, ctx) {
             // goes on following the theme instead of freezing today's hex into it.
             const fromTheme = Object.keys(read).length === 0;
             const tokens = fromTheme ? THEME_TOKENS : read;
-            const spec = pattern.build(tokens);
+            // REAL IMAGES, from the site's own library. The instinct a pattern
+            // library invites is a placeholder — a grey box or a stock photo keyed
+            // off a word — and this repo already records why the second is not a
+            // source (`loremflickr` answered "kids,clothing" with a cat statue). The
+            // merchant's own uploads are the honest answer, and a failure to read
+            // them costs the picture, never the band.
+            let pool = [];
+            try {
+                const listed = (await request({
+                    base: ctx.base,
+                    method: 'GET',
+                    path: `/api/sites/${encodeURIComponent(site_id)}/media?limit=50`,
+                    token: siteToken(ctx),
+                    fetchImpl: ctx.fetchImpl,
+                }));
+                const rows = listed.media ?? listed.assets ?? [];
+                pool = rows
+                    .filter((m) => m.mediaType === 'image' && typeof m.url === 'string' && m.state !== 'deleted')
+                    .map((m) => ({
+                    url: String(m.url),
+                    name: typeof m.name === 'string' ? m.name : undefined,
+                    width: typeof m.width === 'number' ? m.width : undefined,
+                    height: typeof m.height === 'number' ? m.height : undefined,
+                }));
+            }
+            catch {
+                // A library that cannot be read leaves the picture slot saying so.
+            }
+            // WHAT THE PAGE IS ALREADY SHOWING comes out of the pool. Each call
+            // starts its own selection, so a hero added first and a gallery added
+            // second both reached for the same best landscape — and the page then
+            // showed one photo twice, which reads as a mistake because it is one.
+            const onPage = new Set(Object.values(doc.doc.nodes)
+                .map((n) => n.specials?.src)
+                .filter((v) => typeof v === 'string' && v.length > 0));
+            const spec = pattern.build(tokens, pool.filter((m) => !onPage.has(m.url)));
             if (!spec) {
                 throw new Error(`sbuilder: the built-in "${template_id}" produced nothing to add.`);
             }
@@ -715,6 +750,7 @@ export function registerPageTools(server, ctx) {
                     nodes: ids.length,
                     into: page_id,
                     tokens_from: fromTheme ? "this site's theme — the page has no look of its own yet" : 'this page',
+                    images_available: pool.length,
                     note: 'Composed against THIS page\'s tokens, not copied — the same heading ink, button ' +
                         'fill and section padding the page already uses. Pass dry_run:false to add it.',
                 });
@@ -726,6 +762,13 @@ export function registerPageTools(server, ctx) {
                 nodes: ids.length,
                 into: page_id,
                 rev: doc.rev,
+                ...(pool.length === 0
+                    ? {
+                        images: 'This site has no images in its library, so any picture slot in this band says ' +
+                            'so in words rather than showing a grey box. sb_media_upload takes a URL and ' +
+                            'the platform fetches it server-side.',
+                    }
+                    : {}),
                 ...(fromTheme
                     ? {
                         tokens_from: "this site's theme — the page had no heading, button or section to read a look " +

package/dist/transport/media.js

@@ -41,8 +41,87 @@ function typeForName(name) {
     const dot = name.lastIndexOf('.');
     return dot < 0 ? '' : (TYPE_BY_EXT[name.slice(dot).toLowerCase()] ?? '');
 }
+/**
+ * Ask the platform to fetch the URL itself.
+ *
+ * Returns the asset when the server took it, or null when the ROUTE is not
+ * there — an older deployment — which is the one case the caller may answer by
+ * downloading the bytes and posting them the old way.
+ *
+ * A REFUSAL IS TERMINAL, and that is a security rule rather than tidiness. The
+ * server refuses an address that is not on the public internet (`remote_blocked`
+ * — loopback, private ranges, the cloud metadata endpoint), and a client that
+ * answered by fetching that same URL from its OWN machine and uploading the
+ * bytes would walk straight around the guard. The agent's network is not the
+ * server's, but "the caller does it instead" is exactly the bypass the check
+ * exists to prevent, so the error is raised rather than worked around.
+ */
+async function fromUrl(ctx, siteId, url, source) {
+    const doFetch = ctx.fetchImpl ?? fetch;
+    const res = await doFetch(`${ctx.base.replace(/\/$/, '')}/api/media/${encodeURIComponent(siteId)}/from-url`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${siteToken(ctx)}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+            ...identityHeaders(),
+        },
+        body: JSON.stringify({
+            url,
+            ...(source.name ? { name: source.name } : {}),
+            ...(source.folderId ? { folderId: source.folderId } : {}),
+        }),
+    });
+    // 404/405 is "this build has no such route". Anything else is an answer.
+    if (res.status === 404 || res.status === 405)
+        return null;
+    const raw = await res.text();
+    let parsed = {};
+    try {
+        parsed = raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        // A build that routes this path to something else entirely. Fall back rather
+        // than reporting a parse error the caller cannot act on.
+        return null;
+    }
+    if (!res.ok) {
+        const env = (parsed ?? {});
+        if (env.code === 'remote_blocked') {
+            throw new ApiError(res.status, 'remote_blocked', `sbuilder: the platform refuses to fetch ${url} — it is not an address on the public ` +
+                'internet. This server will not fetch it on the platform\'s behalf either: that would ' +
+                'walk around the check rather than satisfy it. Give a public URL, or upload the file ' +
+                'with a local path.');
+        }
+        if (env.code === 'remote_unreachable') {
+            // THE PLATFORM'S OWN REASON, not a sentence of ours over the top of it. It
+            // says which host answered what — a 404 is a wrong URL, a 403 is an origin
+            // refusing this fetcher, a timeout is worth retrying — and replacing that
+            // with "could not read it" sends all of them to check their network.
+            throw new ApiError(res.status, 'remote_unreachable', `sbuilder: the platform could not fetch ${url} — ${env.error ?? 'no reason given'}.`);
+        }
+        // Any OTHER refusal — 401, 403, 413, an unsupported type — is one the older
+        // path answers with its own, better-worded diagnosis. Let it try.
+        return null;
+    }
+    const body = (parsed ?? {});
+    return body.asset ?? parsed;
+}
 export async function uploadMedia(ctx, siteId, source) {
     const doFetch = ctx.fetchImpl ?? fetch;
+    // THE SERVER'S OWN DOOR FIRST, when the source is a URL.
+    //
+    // `POST /api/media/{siteId}/from-url` fetches it where the platform already
+    // guards outbound requests, so the bytes make ONE hop instead of two and the
+    // content type is decided by the origin's own answer rather than reconstructed
+    // here. Everything below this is the older path, kept because a deployment
+    // without that route must still be able to upload — the same shape the partner
+    // -surface retry below has, and for the same reason.
+    if (source.url) {
+        const viaServer = await fromUrl(ctx, siteId, source.url, source);
+        if (viaServer)
+            return viaServer;
+    }
     let bytes;
     let filename;
     let declared = '';

package/package.json

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