sbuilder-mcp 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -6,6 +6,25 @@ 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.27.0] - 2026-09-10
+
+### Changed
+- sb_media_upload's photo search now runs through the platform (`GET /api/sites/{siteId}/images/search`) instead of calling Pexels or a shared proxy directly, so the provider key lives in one place and no install shares its quota with another product.
+
+### Removed
+- sb_media_upload no longer reads a `PEXELS_API_KEY` or a proxy base from the environment; this client keeps no stock-photo key of its own.
+
+### Added
+- sb_media_upload now reports `search_unavailable` with an explicit next step (pass a URL to sb_media_upload instead) when the platform has no image search configured, rather than raising an error.
+
+## [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,25 @@ 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.27.0] - 2026-09-10
+
+### Changed
+- Phần tìm ảnh của sb_media_upload giờ chạy qua platform (`GET /api/sites/{siteId}/images/search`) thay vì gọi thẳng Pexels hay một proxy chung, nên key của nhà cung cấp nằm ở một nơi duy nhất và không bản cài nào phải chia sẻ quota với sản phẩm khác.
+
+### Removed
+- sb_media_upload không còn đọc `PEXELS_API_KEY` hay proxy base từ biến môi trường; client này không giữ key ảnh stock nào của riêng nó nữa.
+
+### Added
+- sb_media_upload giờ trả về `search_unavailable` kèm bước tiếp theo rõ ràng (truyền URL cho sb_media_upload thay vì tìm) khi platform chưa cấu hình tìm ảnh, thay vì báo lỗi.
+
+## [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

@@ -68,6 +68,14 @@ make, because those mean "this person's account".
 
 `SB_API` defaults to `http://localhost:8080`. Secrets are read from the environment only.
 
+`sb_media_upload`'s photo search needs **no key here**: it calls the platform's own
+`GET /api/sites/{siteId}/images/search`, which runs a rotated pool of provider keys behind the
+credential this server already holds. An operator enables it by setting `PEXELS_API_KEYS` on the
+SERVER (comma separated; free keys at <https://www.pexels.com/api/>). With none configured the
+search answers "unavailable" and tells the caller to find a photograph by its own means and pass
+the URL — which the platform then fetches server-side. There is deliberately no fallback provider
+in this client: one would put the very key the platform exists to hold back into every install.
+
 ## Tools
 
 | Tool | What it does |
@@ -93,7 +101,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,14 @@ 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.
 
+Phần tìm ảnh của `sb_media_upload` **không cần key ở đây**: nó gọi route của chính nền tảng,
+`GET /api/sites/{siteId}/images/search`, nơi có một pool key xoay vòng nằm sau đúng credential mà
+server này đang cầm. Operator bật nó bằng cách đặt `PEXELS_API_KEYS` **trên SERVER** (ngăn cách
+bằng dấu phẩy; key miễn phí ở <https://www.pexels.com/api/>). Không cấu hình gì thì tìm kiếm trả
+lời "không khả dụng" và bảo người gọi tự tìm ảnh rồi đưa URL — nền tảng sẽ tự tải về. Client này
+cố ý **không có nhà cung cấp dự phòng**: có nó là đem đúng cái key mà nền tảng sinh ra để giữ,
+nhét ngược lại vào mọi bản cài.
+
 ## Bộ tool
 
 | Tool | Làm gì |
@@ -90,7 +98,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, SearchUnavailable, NO_SEARCH_NEXT } from '../transport/stock.js';
 import { siteFor } from './context.js';
 import { projectList, MEDIA_FIELDS } from './project.js';
 /**
@@ -403,21 +404,95 @@ 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) {
+            let photos;
+            try {
+                photos = await searchStock(ctx, site_id, query, { perPage: 8, orientation });
+            }
+            catch (e) {
+                if (e instanceof SearchUnavailable) {
+                    // NOT AN ERROR, AN INSTRUCTION. There is deliberately no fallback
+                    // provider here: one would put the very key the platform exists to
+                    // hold back into every install. An agent with a web search of its
+                    // own loses nothing — it finds a photograph and passes the URL, and
+                    // the platform fetches it server-side exactly as it would have.
+                    return text({
+                        search_unavailable: e.why,
+                        next: NO_SEARCH_NEXT,
+                    });
+                }
+                throw e;
+            }
+            const chosen = pick !== undefined ? photos.find((p) => p.id === pick) : undefined;
+            if (!chosen) {
+                return text({
+                    ...(pick !== undefined ? { no_such_pick: pick } : {}),
+                    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.",
+                    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.'),
+                });
+            }
+            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,51 @@
+import { request } from './http.js';
+import { siteToken } from '../tools/credentialpick.js';
+/** The platform has no usable provider key, which is not the same as no results. */
+export class SearchUnavailable extends Error {
+    why;
+    constructor(why) {
+        super(why);
+        this.why = why;
+        this.name = 'SearchUnavailable';
+    }
+}
+export const NO_SEARCH_NEXT = 'This platform has no image search available, so find a photograph by your own means and pass ' +
+    'its URL to sb_media_upload — the platform fetches it server-side and it lands in this site\'s ' +
+    'own library, never hotlinked. An operator enables the search by setting PEXELS_API_KEYS on the ' +
+    'server; the key belongs there rather than here, so one place holds it and one quota is spent.';
+export async function searchStock(ctx, siteId, query, opts = {}) {
+    const q = new URLSearchParams({ query, per_page: String(opts.perPage ?? 8) });
+    if (opts.orientation)
+        q.set('orientation', opts.orientation);
+    try {
+        const out = (await request({
+            base: ctx.base,
+            method: 'GET',
+            path: `/api/sites/${encodeURIComponent(siteId)}/images/search?${q}`,
+            token: siteToken(ctx),
+            fetchImpl: ctx.fetchImpl,
+        }));
+        return (out.photos ?? []).map((p) => ({
+            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.photographerUrl === 'string' ? p.photographerUrl : '',
+            page_url: typeof p.pageUrl === 'string' ? p.pageUrl : '',
+            url: typeof p.url === 'string' ? p.url : '',
+        })).filter((p) => p.url);
+    }
+    catch (e) {
+        // 503 is the platform saying it has no usable key; 404 is a deployment older
+        // than the route. Both mean the same thing to the caller — no search here —
+        // and both deserve the same answer, which is not an error but an instruction.
+        const err = e;
+        if (err?.status === 503 || err?.status === 404 || err?.code === 'image_search_unavailable') {
+            throw new SearchUnavailable(err?.status === 404
+                ? 'this deployment has no image-search route yet'
+                : 'no image provider key is configured or usable on this platform');
+        }
+        throw e;
+    }
+}

package/package.json

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