sbuilder-mcp 0.50.0 → 0.52.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ 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.52.0] - 2026-09-15
+
+### Added
+- `sb_page_list`'s `usually_also` advisory now names a missing `faq` page.
+- `sb_page_list`'s `usually_also` advisory now names a missing blog listing page, but only on a site that already has a `post` (article) template to list — a site with no articles is no longer told to build one.
+
+### Changed
+- `sb_page_list`'s `usually_also` advisory splits the single `policy` entry into `policy-delivery` (shipping and returns) and `policy-privacy` (privacy and terms of use), so a site carrying only one of the two no longer reads as having both.
+
+## [0.51.0] - 2026-09-15
+
+### Added
+- `sb_page_list` now reports which of the pages most sites carry — login, register, forgot-password, contact, about, and policy pages — this site appears to be missing, matched by name against untyped `page` rows since none of them has a page type of its own, alongside a note naming the suggestion as advice rather than a defect.
+
 ## [0.50.0] - 2026-09-15
 
 ### Changed

package/CHANGELOG.vi.md

@@ -6,6 +6,20 @@ 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.52.0] - 2026-09-15
+
+### Added
+- Gợi ý `usually_also` của `sb_page_list` giờ nêu tên trang `faq` nếu site còn thiếu.
+- Gợi ý `usually_also` của `sb_page_list` giờ nêu tên trang danh sách blog nếu site còn thiếu, nhưng chỉ khi site đã có template bài viết (`post`) để liệt kê — site chưa có bài viết nào thì không còn bị nhắc xây trang này.
+
+### Changed
+- Gợi ý `usually_also` của `sb_page_list` tách mục `policy` duy nhất thành `policy-delivery` (giao hàng và đổi trả) và `policy-privacy` (bảo mật và điều khoản sử dụng), để một site chỉ có một trong hai trang không còn bị đọc nhầm là đã có đủ cả hai.
+
+## [0.51.0] - 2026-09-15
+
+### Added
+- `sb_page_list` giờ báo cáo site này có vẻ đang thiếu những trang mà hầu hết các site thường có — đăng nhập, đăng ký, quên mật khẩu, liên hệ, giới thiệu và các trang chính sách — bằng cách so khớp theo tên với các trang loại `page` không có kiểu riêng, kèm ghi chú nói rõ đây là gợi ý chứ không phải lỗi.
+
 ## [0.50.0] - 2026-09-15
 
 ### Changed

package/dist/domains/site/inventory.js

@@ -0,0 +1,115 @@
+/**
+ * THE PAGES A SITE HAS THAT THE PLATFORM CANNOT NAME.
+ *
+ * `readinessGaps` already reports every page the storefront ROUTES BY TYPE —
+ * product, category, search, checkout, complete, account, error. Each of those
+ * has a named consequence when it is absent, which is what makes it a defect.
+ *
+ * The rest of a website has no type at all. Login, register, forgot-password,
+ * contact, about and the policies are ordinary pages of type "page", so nothing
+ * anywhere can tell a site that has them from a site that does not — and an
+ * agent building a store therefore ships whatever it happened to think of. A
+ * store built with these tools came out with a home page, a product list and a
+ * category grid, and no way to contact the shop, no policy a shopper could
+ * read, and no /login for its own header to link to.
+ *
+ * ADVICE, NOT A DEFECT, AND IT SAYS SO. `readinessGaps` is a list of things
+ * that are broken; this is a list of things that are usually there. They are
+ * kept apart deliberately: a check that reports a judgement as a defect is one
+ * an author learns to ignore, and readiness.ts's own header says exactly that.
+ *
+ * MATCHED BY NAME, WHICH IS A GUESS, AND THE RESULT SAYS SO. There is no type,
+ * no flag and no API that identifies a contact page, so the only signal is what
+ * the merchant called it. A page under an unusual name therefore reads as
+ * absent. That fails in the safe direction — a line of advice about a page you
+ * already have costs a sentence; the reverse ships a shop nobody can reach.
+ */
+export const USUAL_PAGES = [
+    {
+        key: 'login',
+        match: ['login', 'signin', 'sign-in', 'dang-nhap', 'đăng nhập'],
+        why: 'Nothing for a header, an order email or /account\'s signed-out state to link to. ' +
+            'Seed it with sb_store action:"form" template "login" on a page of type "page".',
+    },
+    {
+        key: 'register',
+        match: ['register', 'signup', 'sign-up', 'dang-ky', 'đăng ký'],
+        why: 'A shopper cannot open an account, so order history, addresses and any member-gated ' +
+            'page are unreachable. Template "register".',
+    },
+    {
+        key: 'forgot',
+        match: ['forgot', 'reset', 'quen-mat-khau', 'quên mật khẩu', 'doi-mat-khau'],
+        why: 'A customer who forgets a password has no way back in and writes to support instead. ' +
+            'Template "forgot".',
+    },
+    {
+        key: 'contact',
+        match: ['contact', 'lien-he', 'liên hệ'],
+        why: 'No address, phone or form anywhere, so a shopper with a question about an order has ' +
+            'nowhere to put it. Template "contact".',
+    },
+    {
+        key: 'about',
+        match: ['about', 'gioi-thieu', 'giới thiệu', 've-chung-toi'],
+        why: 'Nothing says who the shop is, which is the page a first-time buyer opens before paying.',
+    },
+    // TWO POLICIES, NOT ONE BUCKET. These were a single entry, and it read a shop
+    // carrying only "Chính sách giao hàng & đổi trả" as complete — which is
+    // exactly the shop that was measured, and it had no privacy terms at all. One
+    // policy page satisfying a check about all of them is the check answering a
+    // question it was not asked.
+    {
+        key: 'policy-delivery',
+        match: [
+            'doi-tra', 'đổi trả', 'return', 'refund', 'hoan-tien', 'hoàn tiền',
+            'shipping', 'van-chuyen', 'vận chuyển', 'giao-hang', 'giao hàng', 'delivery',
+        ],
+        why: 'No delivery or return terms a shopper can read before paying. This is the page a buyer ' +
+            'looks for when the parcel is late and the one a dispute is settled against.',
+    },
+    {
+        key: 'policy-privacy',
+        match: [
+            'privacy', 'bao-mat', 'bảo mật', 'dieu-khoan', 'điều khoản', 'terms',
+            'quy-dinh', 'quy định',
+        ],
+        why: 'No privacy policy or terms of use. Payment providers and marketplaces ask for both ' +
+            'before they will list a shop, and a checkout form collects personal data either way.',
+    },
+    {
+        key: 'faq',
+        match: ['faq', 'cau-hoi', 'câu hỏi', 'hoi-dap', 'hỏi đáp', 'help', 'tro-giup', 'trợ giúp'],
+        why: 'The same handful of questions reach support one message at a time, with no page to link ' +
+            'an answer to. The accordion element is what this page is built from.',
+    },
+    {
+        key: 'blog',
+        // ONLY ONCE THERE IS SOMETHING TO LIST. `post` is the ARTICLE template —
+        // it answers /blog/{slug} and has no address of its own — so a site with
+        // one can publish articles that nothing on the site links to. A site
+        // without one has no articles, and telling it to build a listing page is
+        // advice about a section it never asked for.
+        when: (pages) => pages.some((x) => x.type === 'post'),
+        match: ['blog', 'tin-tuc', 'tin tức', 'news', 'bai-viet', 'bài viết', 'kien-thuc', 'cẩm nang'],
+        why: 'This site has an article template, so /blog/{slug} works — but no page LISTS the ' +
+            'articles, so each one is reachable only by someone who already has its URL.',
+    },
+];
+/**
+ * Which of the usual pages this site appears not to have.
+ *
+ * Only `page`-typed rows are searched: a product TEMPLATE named "Chi tiết sản
+ * phẩm" is not an about page, and letting a template satisfy one of these would
+ * report a site as complete on the strength of a page that answers a different
+ * address entirely.
+ */
+export function missingUsualPages(pages) {
+    if (!pages)
+        return [];
+    const hay = pages
+        .filter((p) => (typeof p.type === 'string' ? p.type === 'page' : true))
+        .map((p) => `${typeof p.slug === 'string' ? p.slug : ''} ${typeof p.name === 'string' ? p.name : ''}`.toLowerCase())
+        .join('\n');
+    return USUAL_PAGES.filter((u) => (u.when ? u.when(pages) : true) && !u.match.some((m) => hay.includes(m)));
+}

package/dist/tools/page.js

@@ -20,6 +20,7 @@ import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
 import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
 import { catalogBrowse, catalogMatches, traitsFor } from '../catalog/element-search.js';
+import { missingUsualPages } from '../domains/site/inventory.js';
 import { LAYOUT_PATTERNS, PATTERN_BY_ID, THEME_TOKENS, } from '../domains/site/patterns.js';
 import { tokensFromPage } from '../domains/site/importmap.js';
 import { middleEnd } from '../domains/site/traps.js';
@@ -1159,13 +1160,33 @@ export function registerPageTools(server, ctx) {
         description: "Every page on the site, with its slug and whether it is live.",
         inputSchema: { site_id: z.string().optional() },
         annotations: { readOnlyHint: true },
-    }, async ({ site_id: given }) => text(projectList(await request({
-        base: ctx.base,
-        method: 'GET',
-        path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/pages`,
-        token: siteToken(ctx),
-        fetchImpl: ctx.fetchImpl,
-    }), 'pages', PAGE_FIELDS)));
+    }, async ({ site_id: given }) => {
+        const raw = (await request({
+            base: ctx.base,
+            method: 'GET',
+            path: `/api/sites/${encodeURIComponent(siteFor(ctx, given))}/pages`,
+            token: siteToken(ctx),
+            fetchImpl: ctx.fetchImpl,
+        }));
+        // WHAT A SITE USUALLY ALSO HAS, said where an agent is orienting rather
+        // than after it has finished. sb_review reports the pages the storefront
+        // ROUTES BY TYPE; these have no type at all — login, register, forgot,
+        // contact, about, the policies are ordinary "page" rows — so nothing else
+        // in this server can tell a site that has them from one that does not.
+        // See ./inventory.ts: advice, matched by name, and the note says both.
+        const missing = missingUsualPages(raw.pages ?? null);
+        return text({
+            ...projectList(raw, 'pages', PAGE_FIELDS),
+            ...(missing.length
+                ? {
+                    usually_also: Object.fromEntries(missing.map((m) => [m.key, m.why])),
+                    usually_also_note: 'Pages most sites have that this one appears not to, found by NAME because they ' +
+                        'have no type — one you named unusually will show here anyway. Advice, not ' +
+                        'defects: sb_review reports the pages the storefront routes by type.',
+                }
+                : {}),
+        });
+    });
     server.registerTool('sb_page_create', {
         description: `A store type (${seededTypes().join(', ')}) arrives with the document the editor ` +
             'gives a merchant — product carries the whole bound buy box; seed:false for blank. ' +

package/package.json

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