sbuilder-mcp 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -6,6 +6,14 @@ 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.26.0] - 2026-09-10
+
+### Added
+- sb_media_upload can now search for a real photograph: `query` returns real photographs with the description each photographer wrote, and `pick` uploads the chosen one into the site's own library instead of hotlinking it.
+- sb_media_upload's search takes `orientation` (landscape, portrait, square) to ask the search itself for the right shape instead of cropping the result afterward.
+- sb_media_upload's search results carry photographer credit (name, profile, photo page), and the uploaded asset's name defaults to the photograph's own description so the library stays searchable by what each image shows.
+- An optional `PEXELS_API_KEY` calls Pexels directly for the image search; without one it falls back to a shared proxy, so an `npx` install with no configuration still finds real images.
+
 ## [0.25.0] - 2026-09-10
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,14 @@ 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.26.0] - 2026-09-10
+
+### Added
+- sb_media_upload giờ có thể tìm ảnh chụp thật: `query` trả về ảnh chụp thật kèm mô tả do chính người chụp viết, và `pick` upload đúng tấm được chọn vào thư viện của site thay vì hotlink.
+- Phần tìm ảnh của sb_media_upload nhận `orientation` (landscape, portrait, square) để hỏi thẳng bộ tìm kiếm về hình dạng phù hợp thay vì cắt ảnh lại sau đó.
+- Kết quả tìm ảnh của sb_media_upload mang theo thông tin ghi công (tên người chụp, trang cá nhân, trang ảnh), và tên của asset sau khi upload mặc định lấy theo mô tả của bức ảnh để thư viện tìm được theo nội dung ảnh.
+- `PEXELS_API_KEY` là tuỳ chọn, dùng để gọi thẳng Pexels cho phần tìm ảnh; không có key thì dùng một proxy chung, nên một bản cài `npx` không cấu hình gì vẫn tìm được ảnh thật.
+
 ## [0.25.0] - 2026-09-10
 
 ### Added

package/README.md

@@ -93,7 +93,7 @@ make, because those mean "this person's account".
 | `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 — the only route, the upload is multipart |
+| `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_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

@@ -65,6 +65,12 @@ là "tài khoản của người này".
 
 `SB_API` mặc định `http://localhost:8080`. Bí mật chỉ đọc từ biến môi trường.
 
+`PEXELS_API_KEY` là **tuỳ chọn**, chỉ ảnh hưởng phần tìm ảnh của `sb_media_upload`: có key thì gọi
+thẳng Pexels (key miễn phí ở <https://www.pexels.com/api/>), không có thì dùng proxy chung mà nhà
+mình đang chạy (`PEXELS_PROXY_BASE`, mặc định `https://mcp.toolvn.io.vn`) — nên bản cài không cấu
+hình gì vẫn tìm được ảnh. Proxy giữ key của chính nó và không bao giờ gửi key về client; đó là ưu
+ái chứ không phải cam kết, và kết quả nói rõ cửa nào đã trả lời.
+
 ## Bộ tool
 
 | Tool | Làm gì |
@@ -90,7 +96,7 @@ là "tài khoản của người này".
 | `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 — đường duy nhất, vì upload là multipart |
+| `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_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/tools/live.js

@@ -27,6 +27,7 @@ import { LiveSession } from '../live/session.js';
 import { refuseAppBlockInterior } from '../domains/site/builder.js';
 import { childrenOf, isOverlay, overlayRoot, subtreeIds } from '../core/tree.js';
 import { siteToken } from './credentialpick.js';
+import { searchStock } from '../transport/stock.js';
 import { siteFor } from './context.js';
 import { projectList, MEDIA_FIELDS } from './project.js';
 /**
@@ -403,21 +404,88 @@ export function registerLiveTools(server, ctx, session) {
     }), 'assets', MEDIA_FIELDS)));
     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 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.',
+            '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.',
         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'),
             name: z.string().optional(),
             folder_id: z.string().optional(),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false },
-    }, async ({ site_id: given, path, url, name, folder_id, dry_run }) => {
+    }, async ({ site_id: given, path, url, name, folder_id, query, orientation, pick, dry_run }) => {
         const site_id = siteFor(ctx, given);
-        if (!path && !url)
-            throw new Error('sbuilder: give sb_media_upload either a path or a url');
+        // A SEARCH IS NOT A GUESS, and the difference is the whole reason this is
+        // two steps. Rule 7 records what a keyword glued into a URL returns —
+        // `loremflickr` answered "kids,clothing" with a cat statue — and the fault
+        // was never stock photography, it was that nobody looked. Every result
+        // here carries what it actually SHOWS, so the caller reads the
+        // descriptions and CHOOSES; uploading the first hit unread would rebuild
+        // the cat statue with better plumbing.
+        if (query) {
+            const found = await searchStock(ctx.fetchImpl ?? fetch, query, {
+                perPage: 8,
+                orientation,
+            });
+            const chosen = pick !== undefined ? found.photos.find((p) => p.id === pick) : undefined;
+            if (!chosen) {
+                return text({
+                    ...(pick !== undefined ? { no_such_pick: pick } : {}),
+                    found: found.photos.map((p) => ({
+                        pick: p.id,
+                        shows: p.alt || '(the photographer left no description)',
+                        size: `${p.width}x${p.height}`,
+                        by: p.photographer,
+                    })),
+                    via: found.via,
+                    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.",
+                    ...(found.via === 'proxy'
+                        ? {
+                            key: 'No PEXELS_API_KEY, so this used the shared proxy — a courtesy, not a ' +
+                                'guarantee. A free key at https://www.pexels.com/api/ calls Pexels directly.',
+                        }
+                        : {}),
+                    licence: ctx.notices.once('stock_licence', 'Pexels photographs are free for commercial use and attribution is appreciated ' +
+                        'rather than required, so a storefront can carry one without printing a credit ' +
+                        'line. The photographer and the photo page come back with each result if you ' +
+                        'want to credit anyway.'),
+                });
+            }
+            if (dry_run !== false) {
+                return text({
+                    dry_run: true,
+                    would_upload: chosen.url,
+                    shows: chosen.alt,
+                    by: chosen.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,
+            });
+            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.',
+            });
+        }
+        if (!path && !url) {
+            throw new Error('sbuilder: give sb_media_upload a path, a url, or a query to search');
+        }
         if (dry_run !== false) {
             return text({
                 dry_run: true,

package/dist/transport/stock.js

@@ -0,0 +1,95 @@
+/**
+ * REAL PHOTOGRAPHS, WITH REAL DESCRIPTIONS.
+ *
+ * Rule 7 of the design skill is the reason this exists and the reason it is
+ * shaped the way it is: "keyword stock imagery is not a source — `loremflickr`
+ * answered 'kids,clothing' with a cat statue and a photo of an adult." That
+ * failure is not about stock photography, it is about GUESSING: a keyword glued
+ * into a URL returns something nobody looked at.
+ *
+ * A search API is a different thing entirely, because every result carries what
+ * it actually SHOWS. Pexels answers "coffee shop" with
+ * "Three young adults engage at a cafe counter, using mobile devices" — so the
+ * caller can read the descriptions and CHOOSE, which is what a person does and
+ * what the cat statue proves nobody was doing.
+ *
+ * PEXELS, because it is already this family's answer: `webcake-landing-mcp`
+ * ships the same client, down to the shared proxy below, and a second house
+ * standard for the same job is a second place for it to drift. Its licence is
+ * free for commercial use with attribution appreciated rather than required,
+ * which is what makes an image usable on a merchant's storefront without
+ * printing a credit line they did not ask for.
+ *
+ * THE KEY IS OPTIONAL, and that is deliberate: with `PEXELS_API_KEY` this calls
+ * Pexels directly, and without one it calls the shared proxy the sibling repo
+ * already runs (`https://mcp.toolvn.io.vn/api/images/search`), which holds a key
+ * and answers the same shape. An `npx` install with no configuration at all
+ * still finds images.
+ */
+const PEXELS_SEARCH = 'https://api.pexels.com/v1/search';
+const PROXY_DEFAULT = 'https://mcp.toolvn.io.vn';
+const PROXY_PATH = '/api/images/search';
+const TIMEOUT_MS = 20_000;
+/** The shape both doors answer, normalised here so the caller cannot tell them apart. */
+function normalise(p) {
+    const src = (p.src ?? {});
+    // `large2x` is ~1880px wide, which is a hero at 1440 and still a few hundred
+    // KB; `original` is the native file and on a 3800px photograph that is tens of
+    // megabytes for a band nobody will view above 1440.
+    const url = src.large2x || src.large || src.original || '';
+    if (!url)
+        return null;
+    return {
+        id: Number(p.id ?? 0),
+        alt: typeof p.alt === 'string' ? p.alt : '',
+        width: Number(p.width ?? 0),
+        height: Number(p.height ?? 0),
+        photographer: typeof p.photographer === 'string' ? p.photographer : '',
+        photographer_url: typeof p.photographer_url === 'string' ? p.photographer_url : '',
+        page_url: typeof p.url === 'string' ? p.url : '',
+        url,
+    };
+}
+/**
+ * Search for photographs.
+ *
+ * `orientation` 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 is far
+ * cheaper to ask the search than to crop afterwards.
+ */
+export async function searchStock(fetchImpl, query, opts = {}) {
+    const q = new URLSearchParams({
+        query,
+        per_page: String(Math.min(Math.max(opts.perPage ?? 8, 1), 30)),
+    });
+    if (opts.orientation)
+        q.set('orientation', opts.orientation);
+    const key = (process.env.PEXELS_API_KEY ?? '').trim();
+    const proxy = (process.env.PEXELS_PROXY_BASE ?? PROXY_DEFAULT).replace(/\/+$/, '');
+    const [url, headers, via] = key
+        ? [`${PEXELS_SEARCH}?${q}`, { Authorization: key }, 'pexels']
+        : [`${proxy}${PROXY_PATH}?${q}`, {}, 'proxy'];
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            headers: { Accept: 'application/json', ...headers },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch (e) {
+        throw new Error(`sbuilder: could not reach the image search (${via}) — ${e.message}. ` +
+            'Set PEXELS_API_KEY for a direct connection, or PEXELS_PROXY_BASE to another host.');
+    }
+    if (!res.ok) {
+        throw new Error(`sbuilder: the image search (${via}) answered ${res.status}. ` +
+            (via === 'proxy'
+                ? 'The shared proxy is a courtesy, not a guarantee — set PEXELS_API_KEY (free at ' +
+                    'https://www.pexels.com/api/) to call Pexels directly.'
+                : 'Check PEXELS_API_KEY.'));
+    }
+    const body = (await res.json());
+    const photos = (body.photos ?? [])
+        .map(normalise)
+        .filter((p) => p !== null);
+    return { photos, via };
+}

package/package.json

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