sbuilder-mcp 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -6,6 +6,15 @@ 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.29.0] - 2026-09-10
+
+### Added
+- sb_media_upload's `pick` argument now accepts several ids at once, so stocking a new site's empty library from one search result takes one upload call instead of one per photo; a picked id the search did not return refuses the whole call rather than uploading part of it.
+- A layout pattern now declares how many picture slots it has, and sb_template_use reports how many the site's library could fill and names the sb_media_upload calls (query, then pick with several ids) that fill the rest.
+
+### Changed
+- sb_template_use's result field for a library with too few images is now `pictures`, naming the exact shortfall (slots wanted vs. images offered) instead of the old `images` field, which only ever said the library was completely empty.
+
 ## [0.28.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,15 @@ 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.29.0] - 2026-09-10
+
+### Added
+- Tham số `pick` của sb_media_upload giờ nhận nhiều id cùng lúc, nên việc lấp đầy thư viện trống của một site mới từ một lần tìm kiếm chỉ cần một lệnh upload thay vì một lệnh cho mỗi ảnh; một id được chọn mà kết quả tìm kiếm không trả về sẽ từ chối toàn bộ lệnh thay vì chỉ upload một phần.
+- Một layout dựng sẵn giờ khai báo số ô chứa ảnh nó có, và sb_template_use báo lại thư viện của site lấp được bao nhiêu ô cùng tên các lệnh sb_media_upload (query, rồi pick với nhiều id) để lấp phần còn lại.
+
+### Changed
+- Trường kết quả của sb_template_use khi thư viện thiếu ảnh giờ là `pictures`, nêu đúng phần còn thiếu (số ô cần vs. số ảnh có) thay cho trường `images` cũ, vốn chỉ báo khi thư viện hoàn toàn trống.
+
 ## [0.28.0] - 2026-09-10
 
 ### Added

package/README.md

@@ -101,7 +101,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_publish` | Compile the draft into the live page (cascades to shared globals) |
 | `sb_review` | Every defect a visitor would see, each with its fix, plus the five gaps between this store and a paid order |
 | `sb_media_list` | The site's media library |
-| `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from |
+| `sb_media_upload` | Add an image and get its URL — a local path, a URL the platform fetches, or a SEARCH for real photographs you read and pick from, one or several at a time |
 | `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 and layout defects measured on the render |
 | `sb_event` | Give a node a click action — open the cart, go to a page, open a pop-up |

package/README.vi.md

@@ -98,7 +98,7 @@ nhét ngược lại vào mọi bản cài.
 | `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, và năm khoảng trống chắn giữa cửa hàng với một đơn đã thanh toán |
 | `sb_media_list` | Thư viện ảnh của site |
-| `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn |
+| `sb_media_upload` | Thêm ảnh và lấy URL — file trên máy, một URL để nền tảng tự tải, hoặc TÌM ảnh chụp thật để đọc mô tả rồi chọn, một hoặc nhiều tấm một lượt |
 | `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 node và lỗi bố cục đo trên bản render |
 | `sb_event` | Gắn click action cho một node — mở giỏ, sang trang, mở pop-up |

package/dist/domains/site/patterns.js

@@ -93,6 +93,7 @@ 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',
+        images: 1,
         build: (t, pool) => {
             const used = new Set();
             return section([
@@ -149,6 +150,7 @@ export const LAYOUT_PATTERNS = [
     {
         id: 'sb_gallery',
         name: 'Dải ảnh',
+        images: 6,
         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();

package/dist/tools/live.js

@@ -405,14 +405,18 @@ export function registerLiveTools(server, ctx, session) {
     server.registerTool('sb_media_upload', {
         description: 'Put an image into the media library and get its URL back, ready for sb_set. Takes a ' +
             'local path, a URL, or a SEARCH — `query` returns real photographs with their own ' +
-            'descriptions, and `pick` uploads the one you chose. The only way to add an image.',
+            'descriptions, and `pick` uploads the one you chose, or several at once to stock a ' +
+            'site you just built. The only way to add an image.',
         inputSchema: {
             site_id: z.string().optional(),
             path: z.string().optional().describe('A file on this machine'),
             url: z.string().optional().describe('Fetched, then uploaded'),
             query: z.string().optional().describe('Search real photographs; read the descriptions, then pick'),
             orientation: z.enum(['landscape', 'portrait', 'square']).optional(),
-            pick: z.number().int().optional().describe('The id of the search result to upload'),
+            pick: z
+                .union([z.number().int(), z.array(z.number().int())])
+                .optional()
+                .describe('The id of the search result to upload — or several ids, which stocks a site in one call'),
             name: z.string().optional(),
             folder_id: z.string().optional(),
             dry_run: z.boolean().optional(),
@@ -446,48 +450,106 @@ export function registerLiveTools(server, ctx, session) {
                 }
                 throw e;
             }
-            const chosen = pick !== undefined ? photos.find((p) => p.id === pick) : undefined;
-            if (!chosen) {
+            // STOCKING A SITE IS WHY THIS TAKES SEVERAL. One search answers with
+            // eight photographs and a gallery band wants six of them — and a site
+            // this server has just built has an EMPTY library, so every picture
+            // slot in every pattern is a sentence until somebody fills it. One
+            // pick per call made that twelve round trips for one band, which is
+            // how a correct rule becomes a rule nobody follows.
+            //
+            // It does NOT weaken rule 7. What that rule protects is that somebody
+            // LOOKED: reading eight descriptions and choosing six is the same act
+            // of choosing as reading eight and choosing one. What it forbids is
+            // uploading a hit nobody read, and no `pick` still uploads nothing.
+            const wanted = pick === undefined ? [] : Array.isArray(pick) ? pick : [pick];
+            const chosen = wanted
+                .map((id) => photos.find((p) => p.id === id))
+                .filter((p) => p !== undefined);
+            const absent = wanted.filter((id) => !photos.some((p) => p.id === id));
+            // A PARTIAL PICK IS REFUSED WHOLE rather than half-uploaded. The caller
+            // named a set; delivering some of it and reporting the rest as a note
+            // leaves them to work out which slots they can still fill.
+            if (chosen.length === 0 || absent.length > 0) {
                 return text({
-                    ...(pick !== undefined ? { no_such_pick: pick } : {}),
+                    ...(absent.length === 1 ? { no_such_pick: absent[0] } : {}),
+                    ...(absent.length > 1 ? { no_such_picks: absent } : {}),
                     found: photos.map((p) => ({
                         pick: p.id,
                         shows: p.alt || '(the photographer left no description)',
                         size: `${p.width}x${p.height}`,
                         by: p.photographer,
                     })),
-                    next: 'Read what each one SHOWS, then re-call with pick:<id> and dry_run:false. The photo ' +
-                        "is uploaded into this site's own library, never hotlinked.",
+                    next: 'Read what each one SHOWS, then re-call with pick:<id> and dry_run:false — or ' +
+                        'pick:[<id>,<id>,…] to take several in one call, which is what fills a gallery ' +
+                        "band. Each photo is uploaded into this site's own library, never hotlinked.",
                     licence: ctx.notices.once('stock_licence', 'These are Pexels photographs: free for commercial use, with attribution ' +
                         'appreciated rather than required, so a storefront can carry one without printing ' +
                         'a credit line nobody asked for. The photographer comes back with each result if ' +
                         'you want to credit anyway.'),
                 });
             }
+            // ONE PICK KEEPS THE SHAPE IT HAS ALWAYS HAD. A caller that asked for
+            // one photograph gets one answer about one photograph; only a caller
+            // that asked for several is handed a list to read.
+            const solo = chosen.length === 1 ? chosen[0] : undefined;
             if (dry_run !== false) {
                 return text({
                     dry_run: true,
-                    would_upload: chosen.url,
-                    shows: chosen.alt,
-                    by: chosen.photographer,
+                    would_upload: solo ? solo.url : chosen.map((c) => c.url),
+                    shows: solo ? solo.alt : chosen.map((c) => c.alt),
+                    by: solo ? solo.photographer : chosen.map((c) => c.photographer),
                     into: site_id,
                     note: 'Nothing was sent. Re-call with dry_run:false to upload.',
                 });
             }
-            const asset = await uploadMedia(ctx, site_id, {
-                url: chosen.url,
-                // THE DESCRIPTION BECOMES THE NAME, so the library is searchable by
-                // what the photographs show and the alt on the page means something.
-                name: name ?? chosen.alt ?? undefined,
-                folderId: folder_id,
-            });
+            // NOT ATOMIC, AND IT MUST NOT PRETEND TO BE. Each photo is its own
+            // upload, so the fifth failing does not un-upload the four that
+            // landed — throwing here would leave the caller with four images in
+            // the library, no idea which, and an error that names none of them.
+            // The same reasoning `sb_import_site` records for its per-page report.
+            const uploaded = [];
+            const failed = [];
+            for (const one of chosen) {
+                try {
+                    const asset = await uploadMedia(ctx, site_id, {
+                        url: one.url,
+                        // THE DESCRIPTION BECOMES THE NAME, so the library is searchable
+                        // by what the photographs show and the alt on the page means
+                        // something. A caller-supplied name can only speak for ONE photo,
+                        // so it is honoured only when one was picked.
+                        name: (solo ? name : undefined) ?? one.alt ?? undefined,
+                        folderId: folder_id,
+                    });
+                    uploaded.push({
+                        asset,
+                        shows: one.alt,
+                        credit: { by: one.photographer, profile: one.photographer_url, photo: one.page_url },
+                    });
+                }
+                catch (e) {
+                    failed.push({ pick: one.id, why: e.message });
+                }
+            }
+            if (solo) {
+                const only = uploaded[0];
+                if (!only)
+                    throw new Error(`sbuilder: ${failed[0]?.why ?? 'the upload failed'}`);
+                const asset = only.asset;
+                return text({
+                    asset,
+                    shows: solo.alt,
+                    credit: only.credit,
+                    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.',
+                });
+            }
             return text({
-                asset,
-                shows: chosen.alt,
-                credit: { by: chosen.photographer, profile: chosen.photographer_url, photo: chosen.page_url },
-                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.',
+                uploaded,
+                ...(failed.length ? { failed } : {}),
+                next: `${uploaded.length} in this site's library now. A layout pattern reads the library ` +
+                    'when it builds, so sb_template_use will put these into its picture slots — or set ' +
+                    'one on a node directly with sb_set namespace specials, keys { "src": "<url>" }.',
             });
         }
         if (!path && !url) {

package/dist/tools/page.js

@@ -794,6 +794,7 @@ export function registerPageTools(server, ctx) {
                     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,
+                    ...(pattern.images ? { pictures_wanted: pattern.images } : {}),
                     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.',
                 });
@@ -805,11 +806,19 @@ export function registerPageTools(server, ctx) {
                 nodes: ids.length,
                 into: page_id,
                 rev: doc.rev,
-                ...(pool.length === 0
+                // A SHORT LIBRARY IS THE ORDINARY STATE OF A SITE THIS SERVER BUILT,
+                // not an edge case — nothing has been uploaded yet, so every picture
+                // slot in every pattern is a sentence. Saying "there are no images"
+                // and stopping leaves the agent to rediscover the fix; saying how
+                // many this band wanted and naming the two calls that fill them is
+                // the same fact with the next step attached.
+                ...(pattern.images && pool.length < pattern.images
                     ? {
-                        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.',
+                        pictures: `This band has ${pattern.images} picture slot${pattern.images > 1 ? 's' : ''} and the ` +
+                            `library offered ${pool.length}; the rest say so in words rather than showing a grey ` +
+                            'box. Fill them: sb_media_upload query:"<what the band should show>" reads back real ' +
+                            'photographs with their own descriptions, then pick:[…] uploads the ones you chose in ' +
+                            'one call. Re-run this pattern afterwards and it takes them.',
                     }
                     : {}),
                 ...(fromTheme

package/package.json

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