sbuilder-mcp 0.26.0 → 0.28.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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.28.0] - 2026-09-10
+
+### Added
+- The API catalog gained the platform's own image-search route, `GET /api/sites/{siteId}/images/search`, reachable through sb_api_call as well as through sb_media_upload.
+- The API catalog gained the admin key-pool pair, `GET/POST /api/admin/image-keys`, for managing the platform's Pexels credentials.
+
+### Changed
+- sb_media_upload's "search unavailable" instruction now names the admin Settings area's Pexels keys screen as the way to turn image search on, alongside the PEXELS_API_KEYS server variable, and notes that several keys are walked round-robin because the provider rate-limits per key.
+
+## [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

package/CHANGELOG.vi.md

@@ -6,6 +6,26 @@ 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.28.0] - 2026-09-10
+
+### Added
+- Catalog API có thêm route tìm ảnh của chính nền tảng, `GET /api/sites/{siteId}/images/search`, gọi được qua sb_api_call cũng như qua sb_media_upload.
+- Catalog API có thêm cặp quản lý pool key phía admin, `GET/POST /api/admin/image-keys`, để quản lý key Pexels của nền tảng.
+
+### Changed
+- Chỉ dẫn "chưa cấu hình tìm ảnh" của sb_media_upload giờ nêu tên màn Cài đặt phía admin (khoá Pexels) như một cách bật tìm ảnh, bên cạnh biến môi trường PEXELS_API_KEYS trên server, và ghi chú rằng nhiều khoá được xoay vòng vì nhà cung cấp giới hạn theo từng khoá.
+
+## [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

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 |

package/README.vi.md

@@ -65,11 +65,13 @@ 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.
+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
 

package/dist/catalog/api.generated.js

@@ -1,5 +1,5 @@
 export const SWAGGER_SOURCE = {
-    "operations": 498,
+    "operations": 501,
     "definitions": 104,
     "bodyCarrying": 178,
     "bodyUndescribed": 64,
@@ -1211,6 +1211,32 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/admin/image-keys",
+        "method": "GET",
+        "path": "/api/admin/image-keys",
+        "tags": [
+            "admin"
+        ],
+        "summary": "Manage the platform's Pexels credentials",
+        "params": [],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
+    {
+        "id": "post:/api/admin/image-keys",
+        "method": "POST",
+        "path": "/api/admin/image-keys",
+        "tags": [
+            "admin"
+        ],
+        "summary": "Manage the platform's Pexels credentials",
+        "params": [],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/admin/plans/export",
         "method": "GET",
@@ -7542,6 +7568,55 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "get:/api/sites/{siteId}/images/search",
+        "method": "GET",
+        "path": "/api/sites/{siteId}/images/search",
+        "tags": [
+            "images"
+        ],
+        "summary": "Search stock photographs",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "query",
+                "in": "query",
+                "required": true,
+                "type": "string",
+                "description": "What to search for"
+            },
+            {
+                "name": "per_page",
+                "in": "query",
+                "required": false,
+                "type": "integer",
+                "description": "1-30, default 8"
+            },
+            {
+                "name": "orientation",
+                "in": "query",
+                "required": false,
+                "type": "string",
+                "description": "landscape, portrait or square"
+            },
+            {
+                "name": "locale",
+                "in": "query",
+                "required": false,
+                "type": "string",
+                "description": "Provider locale, e.g. vi-VN"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/integrations",
         "method": "GET",

package/dist/catalog/shapes.generated.js

@@ -1,10 +1,10 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 218,
-    "shaped": 168,
-    "fromHandlers": 168,
+    "writeOperations": 219,
+    "shaped": 169,
+    "fromHandlers": 169,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
-    "structsRead": 1649
+    "structsRead": 1658
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{siteId}/api-keys": {
@@ -4672,6 +4672,21 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "post:/api/admin/image-keys": {
+        "fields": [
+            {
+                "name": "label",
+                "type": "string"
+            },
+            {
+                "name": "key",
+                "type": "string",
+                "note": "`key`, not `secret`: it is what Pexels's own dashboard calls the value the operator is copying, and a form field named for the thing you are pasting is one less thing to guess at."
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/admin/translation-keys": {
         "fields": [
             {

package/dist/tools/live.js

@@ -27,7 +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 { searchStock, SearchUnavailable, NO_SEARCH_NEXT } from '../transport/stock.js';
 import { siteFor } from './context.js';
 import { projectList, MEDIA_FIELDS } from './project.js';
 /**
@@ -428,33 +428,40 @@ export function registerLiveTools(server, ctx, session) {
         // 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;
+            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: found.photos.map((p) => ({
+                    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.'),
+                    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) {

package/dist/transport/stock.js

@@ -1,95 +1,53 @@
-/**
- * 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,
-    };
+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';
+    }
 }
-/**
- * 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)),
-    });
+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 turns the search on by adding a Pexels key in the ' +
+    'admin Settings area (Pexels keys), or by setting PEXELS_API_KEYS on the server; several keys ' +
+    'are walked round-robin, because that provider rate-limits per key. Either way the key lives ' +
+    '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);
-    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),
-        });
+        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) {
-        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.'));
+        // 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;
     }
-    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.26.0",
+  "version": "0.28.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",