sbuilder-mcp 0.60.4 → 0.61.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.61.1] - 2026-09-17
+
+### Added
+- `sb_connect` now reports how old the generated catalog's platform knowledge is, in words (e.g. "45 days old"), along with the web_builder commit it was generated from, so a stale install reads as staleness instead of as a missing element or key.
+- `sb_set`'s precondition warning now also covers `filterMatch: "all"` on filter elements, which only takes effect where a product can hold several of a source's values.
+
+### Fixed
+- `sb_set`'s precondition warning no longer reports a false positive when a sibling `specials` key is simply unset, since a `null` clause now correctly means "not set" instead of being compared as a literal value.
+
+## [0.61.0] - 2026-09-16
+
+### Added
+- `sb_set` now warns when a write on a `specials` key is legal on its own but does nothing because a sibling key it depends on is missing or set to the wrong value, naming both keys, what the node renders as meanwhile, and which value would fix it, read from the platform's own precondition declarations rather than a list kept in this repo.
+- `sb_set` now separately warns when a `specials` key is not honored by the target element's renderer at all, naming the element types that do honor it, so the write is not mistaken for a fixable missing-neighbour case.
+
+### Internal
+- The generated catalog is refreshed against a current platform checkout (a new tool-results API route); operation count moves from 530 to 531 (179 of 238 writes now carrying a body shape read off the handler).
+
 ## [0.60.4] - 2026-09-16
 
 ### Internal

package/CHANGELOG.vi.md

@@ -6,6 +6,24 @@ 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.61.1] - 2026-09-17
+
+### Added
+- `sb_connect` giờ báo cáo kiến thức nền tảng của catalog được sinh ra đã cũ đến mức nào, bằng lời (ví dụ "45 days old"), cùng với commit web_builder mà nó được sinh ra từ đó, để một bản cài đặt lỗi thời được đọc đúng là lỗi thời thay vì bị hiểu nhầm là thiếu element hay key.
+- Cảnh báo tiền điều kiện của `sb_set` giờ bao phủ thêm `filterMatch: "all"` trên các element bộ lọc, giá trị này chỉ có tác dụng ở nơi một sản phẩm có thể mang nhiều giá trị của một nguồn.
+
+### Fixed
+- Cảnh báo tiền điều kiện của `sb_set` không còn báo sai (false positive) khi một key `specials` liền kề đơn giản là chưa được thiết lập, vì một clause `null` giờ được hiểu đúng là "chưa thiết lập" thay vì bị so sánh như một giá trị literal.
+
+## [0.61.0] - 2026-09-16
+
+### Added
+- `sb_set` giờ cảnh báo khi một lệnh ghi lên key `specials` tự nó hợp lệ nhưng không làm gì cả vì một key liền kề mà nó phụ thuộc vào đang thiếu hoặc sai giá trị — nêu rõ cả hai key, node sẽ render ra sao trong lúc đó, và giá trị nào sẽ khắc phục, được đọc từ chính khai báo tiền điều kiện của nền tảng thay vì một danh sách tự giữ trong repo này.
+- `sb_set` giờ cảnh báo riêng khi một key `specials` hoàn toàn không được renderer của element đích đọc tới, nêu rõ những element type nào thực sự đọc key đó, để tránh bị nhầm thành trường hợp thiếu key liền kề có thể sửa được.
+
+### Internal
+- Catalog được sinh ra giờ được làm mới dựa trên một bản checkout hiện tại của nền tảng (route API tool-results mới); số operation tăng từ 530 lên 531 (179 trong 238 lệnh ghi giờ mang hình dạng body đọc thẳng từ handler).
+
 ## [0.60.4] - 2026-09-16
 
 ### Internal

package/README.md

@@ -112,7 +112,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_store` | Run a store flow that must happen in a fixed order — the four writes that make a working checkout, or any of the platform's 17 form templates (login, register, forgot, contact, subscribe …) with its own field document |
 | `sb_undo` | Put back what a PUT replaced. The SECOND answer for a page, not the only one: the platform has versions, history and restore (`sb_api_find` "page versions"), which outlive this process — reach for those first and use this for every other shaped PUT |
 
-Twenty-eight tools, **530 API operations** (178 of the 237 writes carrying a body shape read
+Twenty-eight tools, **531 API operations** (179 of the 238 writes carrying a body shape read
 off the handler), 113 elements, 79 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything
 the platform can do stays reachable — and operations added to the platform arrive with the

package/README.vi.md

@@ -109,7 +109,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — bốn lệnh ghi tạo nên trang thanh toán, hoặc gieo bất kỳ template nào trong 17 form của nền tảng (login, register, forgot, contact, subscribe …) kèm field document của nó |
 | `sb_undo` | Trả lại thứ mà một lệnh PUT đã ghi đè. Với TRANG thì đây là đường về thứ hai chứ không phải duy nhất: nền tảng có version, history và restore (`sb_api_find` "page versions"), và chúng sống lâu hơn tiến trình này — hãy dùng chúng trước, còn tool này cho mọi PUT có hình dạng khác |
 
-Hai mươi tám tool, **530 operation API** (178 trong 237 lệnh ghi có hình dạng body đọc thẳng
+Hai mươi tám tool, **531 operation API** (179 trong 238 lệnh ghi có hình dạng body đọc thẳng
 từ handler), 113 element, 79 nguồn binding. `sb_api_find` là
 một chỉ mục chứ không phải mỗi endpoint một tool, nên danh sách tool vẫn ngắn trong khi mọi
 thứ nền tảng làm được vẫn với tới — và operation mới thêm bên nền tảng sẽ tự có sau lần

package/dist/catalog/api.generated.js

@@ -1,8 +1,8 @@
 export const SWAGGER_SOURCE = {
-    "operations": 530,
+    "operations": 531,
     "definitions": 107,
-    "bodyCarrying": 196,
-    "bodyUndescribed": 77,
+    "bodyCarrying": 197,
+    "bodyUndescribed": 78,
     "generatedFrom": "server/docs/swagger.json"
 };
 export const API_OPERATIONS = [
@@ -3489,6 +3489,34 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "siteScoped"
     },
+    {
+        "id": "post:/api/sites/{siteId}/ai/tool-results",
+        "method": "POST",
+        "path": "/api/sites/{siteId}/ai/tool-results",
+        "tags": [
+            "sites"
+        ],
+        "summary": "Deliver the result of a client-side tool call",
+        "params": [
+            {
+                "name": "siteId",
+                "in": "path",
+                "required": true,
+                "type": "string",
+                "description": "Site ID"
+            },
+            {
+                "name": "result",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "id (the tool_request's own id, from the SSE event) and result (what the tool answered, as a string)"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "siteScoped"
+    },
     {
         "id": "get:/api/sites/{siteId}/api-keys",
         "method": "GET",

package/dist/catalog/deadkeys.generated.js

@@ -1,6 +1,6 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 4063,
-    "identifiers": 77938,
+    "files": 4065,
+    "identifiers": 77979,
     "seededKeys": 388,
     "dead": 0
 };

package/dist/catalog/elements.generated.js

@@ -36830,6 +36830,115 @@ export const ELEMENT_SEEDS = {
 export const FIRST_CHILD_ONLY = [
     "list-dataset"
 ];
+/**
+ * What a setting needs from its NEIGHBOURS before it does anything.
+ *
+ * Every other table here publishes one key's legal values, which cannot express
+ * "these two are legal apart and meaningless together" — and that is a real
+ * write: filterValueMode "auto" with filterSource "blog_category" stores,
+ * saves, publishes and renders an empty filter.
+ *
+ * Declared by the platform (schema/src/filters/preconditions.ts) and pinned
+ * there against both Go renderers.
+ */
+export const WRITE_PRECONDITIONS = [
+    {
+        "key": "filterValueMode",
+        "value": "auto",
+        "types": [
+            "filter-checkbox",
+            "filter-radio",
+            "filter-color",
+            "filter-tag"
+        ],
+        "requires": [
+            {
+                "key": "filterSource",
+                "anyOf": [
+                    "category"
+                ]
+            }
+        ],
+        "otherwise": "the filter offers NOTHING and renders nothing at all. What this mode follows is the page's own PRODUCT collection (`/collections/{slug}`), so the blog's taxonomy — a tree too, which is why it looks like it should work — has nothing here to follow."
+    },
+    {
+        "key": "filterBehavior",
+        "value": "navigate",
+        "types": [
+            "filter-checkbox",
+            "filter-radio",
+            "filter-color",
+            "filter-tag"
+        ],
+        "requires": [
+            {
+                "key": "filterSource",
+                "anyOf": [
+                    "category",
+                    "blog_category"
+                ]
+            }
+        ],
+        "otherwise": "every row renders as an ordinary filtering label instead of a link. A row becomes an `<a href>` only where its value HAS a page, and both renderers decide that from the source's link kind — a brand, a tag or a price band is a way of narrowing a shelf, not a place."
+    },
+    {
+        "key": "filterShowAll",
+        "value": true,
+        "types": [
+            "filter-checkbox",
+            "filter-radio",
+            "filter-color",
+            "filter-tag"
+        ],
+        "requires": [
+            {
+                "key": "filterValueMode",
+                "anyOf": [
+                    "auto"
+                ]
+            },
+            {
+                "key": "filterBehavior",
+                "anyOf": [
+                    "navigate"
+                ]
+            }
+        ],
+        "otherwise": "no extra row is drawn. It is the way BACK OUT of a browse tree — a link to the category the page is serving — so it needs the page to be followed and the rows to be links. Under in-place filtering, \"everything\" is already what an untouched filter shows."
+    },
+    {
+        "key": "filterMatch",
+        "value": "all",
+        "types": [
+            "filter-checkbox",
+            "filter-radio",
+            "filter-color",
+            "filter-tag"
+        ],
+        "requires": [
+            {
+                "key": "filterSource",
+                "anyOf": [
+                    "category",
+                    "attribute",
+                    "tag",
+                    "blog_category",
+                    "course_tag"
+                ]
+            },
+            {
+                "key": "filterBehavior",
+                "anyOf": [
+                    "filter",
+                    "navigate",
+                    "",
+                    null
+                ]
+            }
+        ],
+        "otherwise": "the filter combines ticked values with OR, as it always did. Both predicates IGNORE the mode outside these cases rather than honouring it — a product holds ONE brand, one price and one stock state, so \"match all\" on two ticked values could only return an empty shelf, and a stale URL degrades to the ordinary OR instead of to a blank page."
+    }
+];
 export const HOVER_HOMES = {
     "button": {
         "home": "legacy"

package/dist/catalog/shapes.generated.js

@@ -1,7 +1,7 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 237,
-    "shaped": 178,
-    "fromHandlers": 178,
+    "writeOperations": 238,
+    "shaped": 179,
+    "fromHandlers": 179,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
     "structsRead": 1726
@@ -3038,6 +3038,20 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "post:/api/sites/{siteId}/ai/tool-results": {
+        "fields": [
+            {
+                "name": "id",
+                "type": "string"
+            },
+            {
+                "name": "result",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "put:/api/sites/{siteId}/ai/settings": {
         "fields": [
             {

package/dist/catalog/source.generated.js

@@ -0,0 +1,7 @@
+// GENERATED by scripts/gen-catalog.ts — do not edit by hand.
+// The platform commit every other generated file here describes.
+export const PLATFORM_SOURCE = {
+    "commit": "d6a68b77a7a00a6a9ca66da5161d57e845aae628",
+    "committedAt": "2026-09-17T00:01:02+07:00",
+    "dirty": false
+};

package/dist/domains/site/vocabulary.js

@@ -1,5 +1,5 @@
 import { DEAD_KEYS } from '../../catalog/deadkeys.generated.js';
-import { ANIMATION, CONFIG_VALUES, ELEMENT_VALUES } from '../../catalog/elements.generated.js';
+import { ANIMATION, CONFIG_VALUES, ELEMENT_VALUES, WRITE_PRECONDITIONS, } from '../../catalog/elements.generated.js';
 /** The vocabulary for a config key, or null when the key has no fixed one. */
 export function vocabularyFor(key) {
     return CONFIG_VALUES[key] ?? null;
@@ -395,3 +395,91 @@ export function deadKeyNote(namespace, key) {
         'draws no row for it either, so only an agent can reach it. Nothing here can fix that — the ' +
         `fix is upstream, in schema/src/elements/${dead.seededBy[0]}/meta.ts.`);
 }
+/**
+ * THE WARNING A PER-KEY VOCABULARY CANNOT GIVE.
+ *
+ * Every table above publishes ONE key's legal values, so a write whose values
+ * are each legal passes in silence — and several combinations in this platform
+ * are legal apart and meaningless together. `filterValueMode: "auto"` with
+ * `filterSource: "blog_category"` is the one that prompted this: both values
+ * are real, the pair stores, saves, publishes, and renders an empty filter,
+ * with no error at any layer. A caller had no way to see it coming.
+ *
+ * Takes the node AS IT WILL BE — the caller merges its write in first — because
+ * these are questions about the finished node. Asking about one key alone is
+ * exactly the blindness being fixed.
+ *
+ * A WARNING AND NEVER A REFUSAL, the rule its siblings above already follow:
+ * the platform stores what it is given, so refusing would invent a rule it does
+ * not have, and a newer deployment may honour a combination this catalog was
+ * generated before. The sentence says what the PAGE does, never "invalid".
+ */
+/**
+ * One clause against one stored value — a MIRROR of `holds` in
+ * schema/src/filters/preconditions.ts, and the two must agree.
+ *
+ * `null` in a clause means NOT SET, which is a real state rather than a hole:
+ * a node written before a key existed does not carry it, and both renderers
+ * then read their own fallback. Without this mapping the two copies disagreed
+ * within an hour of being written — this one called a perfectly good tag filter
+ * broken, which is a FALSE POSITIVE and worse than the silence the whole
+ * mechanism replaced, because a caller warned about correct work stops reading
+ * the warnings.
+ *
+ * It is a copy because this package has no runtime dependency on the schema —
+ * the table arrives as generated data. The cases that separate the two are
+ * asserted on both sides (`test/write-preconditions.test.ts` here,
+ * `schema/test/filter-preconditions.test.ts` there) rather than left to the
+ * reading.
+ */
+function holdsClause(c, stored) {
+    return c.anyOf.includes(stored === undefined ? null : stored);
+}
+export function preconditionNotes(type, specials) {
+    const out = [];
+    for (const p of WRITE_PRECONDITIONS) {
+        if (!p.types.includes(type))
+            continue;
+        if (specials[p.key] !== p.value)
+            continue;
+        const missing = p.requires.filter((c) => !holdsClause(c, specials[c.key]));
+        if (missing.length === 0)
+            continue;
+        const held = missing
+            .map((c) => {
+            const now = specials[c.key];
+            const want = c.anyOf
+                .map((v) => (v === null ? 'to be left unset' : JSON.stringify(v)))
+                .join(' or ');
+            // An ABSENT key is not `null`, and saying so would send a caller looking
+            // for a null they never wrote. The platform's own default applies here,
+            // which is a different thing to fix than a wrong value.
+            const has = now === undefined ? 'is not set' : `is ${JSON.stringify(now)}`;
+            return `${c.key} ${has}, and this needs ${want}`;
+        })
+            .join('; ');
+        out.push(`specials.${p.key} = ${JSON.stringify(p.value)} does nothing on this node: ${held}. ` +
+            `Left as it is, ${p.otherwise}`);
+    }
+    return out;
+}
+/**
+ * The same question for a shape that does not honour the setting AT ALL.
+ *
+ * Split from the clause check because the answer is different in kind: a
+ * missing neighbour is something the caller can fix with another write, while a
+ * `select` will never read the auto value mode however the rest of the node is
+ * arranged.
+ */
+export function unsupportedSettingNote(type, key, value) {
+    const p = WRITE_PRECONDITIONS.find((x) => x.key === key && x.value === value);
+    if (!p || p.types.includes(type))
+        return null;
+    // NOT `p.otherwise`. That sentence explains what a node MISSING A NEIGHBOUR
+    // renders as, and borrowing it here would hand a caller the wrong diagnosis —
+    // it would send them to fix a sibling key on a shape that will never read
+    // this one however the rest of the node is arranged.
+    return (`specials.${key} = ${JSON.stringify(value)} is not a setting ${type} reads — ` +
+        `only ${p.types.join(', ')} honour it. It stores, saves and publishes with no error, ` +
+        `and this element's renderer never looks at it.`);
+}

package/dist/tools/page.js

@@ -9,7 +9,7 @@ import { detachNote, presetIdOf, presetLayer } from '../domains/site/theme.js';
 import { inertHintsFor } from '../domains/site/inert.js';
 import { hasSeed, layoutDocument, seedDocument, seedSummary, seededTypes, } from '../domains/site/storepage.js';
 import { PAGE_TYPES } from '../catalog/storepages.generated.js';
-import { animationNote, deadKeyNote, unknownValueNote, unknownWriteNote, } from '../domains/site/vocabulary.js';
+import { animationNote, deadKeyNote, unknownValueNote, unknownWriteNote, preconditionNotes, unsupportedSettingNote, } from '../domains/site/vocabulary.js';
 import { skinLevelNote } from '../domains/site/fieldskin.js';
 import { siteTheme } from '../domains/site/theme-fetch.js';
 import { request, redact } from '../transport/http.js';
@@ -787,6 +787,31 @@ export function registerPageTools(server, ctx) {
                     if (once)
                         valueNotes.push(once);
                 }
+                // …AND THE ONE A PER-KEY TABLE CANNOT GIVE: values that are each legal
+                // and mean nothing TOGETHER. `filterValueMode: "auto"` with
+                // `filterSource: "blog_category"` passed every check above and
+                // published a filter that renders nothing.
+                //
+                // Asked of the node AS IT WILL BE, not of the write: the node may
+                // already carry the neighbour this write needs, and the write may
+                // supply the neighbour a stored value was missing — so a question
+                // about one key alone answers the wrong thing in both directions.
+                if (e.namespace === 'specials') {
+                    const after = { ...(d.doc.nodes[e.id]?.specials ?? {}), ...e.keys };
+                    for (const [k, v] of Object.entries(e.keys)) {
+                        const un = unsupportedSettingNote(type, k, v);
+                        if (!un)
+                            continue;
+                        const once = ctx.notices.once(`unsupported:${type}.${k}=${JSON.stringify(v)}`, un);
+                        if (once)
+                            valueNotes.push(once);
+                    }
+                    for (const n of preconditionNotes(type, after)) {
+                        const once = ctx.notices.once(`precondition:${type}:${n.slice(0, 60)}`, n);
+                        if (once)
+                            valueNotes.push(once);
+                    }
+                }
             }
             // AND THE QUIETER ONE: a key an element SEEDS that no renderer anywhere
             // reads. The vocabularies above answer "this value means something other

package/dist/tools/session.js

@@ -2,6 +2,26 @@ import { z } from 'zod';
 import { request } from '../transport/http.js';
 import { text } from '../mcp/response.js';
 import { API_OPERATIONS } from '../catalog/api.generated.js';
+import { PLATFORM_SOURCE } from '../catalog/source.generated.js';
+/**
+ * The provenance line, or '' when the generator had no git to ask.
+ *
+ * Reads as an AGE rather than a commit id, because the age is the actionable
+ * half — nobody can tell whether `d6a68b7` is recent, and everybody can tell
+ * whether four months is. The id rides along for the person who then has to
+ * find it.
+ */
+export function catalogAge(now = new Date()) {
+    const { commit, committedAt, dirty } = PLATFORM_SOURCE;
+    if (!commit || !committedAt)
+        return '';
+    const days = Math.floor((now.getTime() - new Date(committedAt).getTime()) / 86_400_000);
+    const age = days <= 1 ? 'today' : days < 45 ? `${days} days old` : `${Math.floor(days / 30)} months old`;
+    return (`Built from web_builder ${commit.slice(0, 9)} (${committedAt.slice(0, 10)}, ${age})` +
+        (dirty ? ', from an UNCOMMITTED tree — it may describe work no deployment has' : '') +
+        `. The platform reports no version of its own, so nothing here can compare the two: if an ` +
+        `element or key you expect is missing, regenerate rather than working around it.`);
+}
 /**
  * Log in and report what this server can actually reach.
  *
@@ -26,6 +46,7 @@ export async function connect(ctx, args) {
             ...(ctx.siteId ? { site: ctx.siteId } : {}),
             ...(ctx.siteId && ctx.siteName ? { site_name: ctx.siteName } : {}),
             operations: API_OPERATIONS.length,
+            ...(catalogAge() ? { catalog: catalogAge() } : {}),
             note: ctx.siteId
                 ? `Connected with an API key alone, on site ${ctx.siteId} (SB_SITE)${ctx.siteName ? `, the store called ${JSON.stringify(ctx.siteName)}` : ''}. Every tool ` +
                     'defaults to it, so site_id is optional. Set SB_EMAIL and SB_PASSWORD as well if ' +
@@ -71,6 +92,7 @@ export async function connect(ctx, args) {
         sites: (listed?.sites ?? []).map((s) => ({ id: s.id, name: s.name })),
         api_key: ctx.apiKey ? 'present' : 'missing',
         operations: API_OPERATIONS.length,
+        ...(catalogAge() ? { catalog: catalogAge() } : {}),
     };
     if (!ctx.apiKey) {
         result.note =

package/package.json

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