sbuilder-mcp 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.37.0] - 2026-09-11
+
+### Added
+- sb_import and sb_import_site now take a `nav_timeout_ms` argument (5,000-120,000ms, default 30,000) to raise how long a capture waits for a slow origin to answer at all.
+
+### Fixed
+- sb_import_site's timeout failure now reports the number of seconds the page actually waited and suggests raising `nav_timeout_ms`, instead of always naming the unmodified default even after a caller had already raised it.
+
+## [0.36.1] - 2026-09-11
+
+- fix(import,api): a capture waited on iframes, and a recovery list was unreadable
+
 ## [0.36.0] - 2026-09-11
 
 ### 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.37.0] - 2026-09-11
+
+### Added
+- sb_import và sb_import_site giờ nhận thêm tham số `nav_timeout_ms` (5.000-120.000ms, mặc định 30.000) để tăng thời gian chờ trang trả lời khi nguồn phản hồi chậm.
+
+### Fixed
+- Lỗi timeout của sb_import_site giờ báo đúng số giây trang thực sự đã chờ và gợi ý tăng `nav_timeout_ms`, thay vì luôn nêu giá trị mặc định chưa đổi ngay cả khi caller đã tự tăng nó.
+
 ## [0.36.0] - 2026-09-11
 
 ### Added

package/dist/tools/api.js

@@ -45,6 +45,33 @@ function pickFields(item, fields) {
  * it would have been and how to narrow the call. A non-list answer is never
  * cut: there is no honest place to stop inside one object.
  */
+/**
+ * LIST OPERATIONS WHOSE EVERY ROW CARRIES A WHOLE PAGE DOCUMENT.
+ *
+ * The page recovery surface answers with the documents themselves — which is
+ * right, since a restore has to have something to restore from — and useless to
+ * read. MEASURED against a live server: one version of a TWO-NODE page is 1,690
+ * bytes, so a realistic 120-node page runs about 70 KB per version and a listing
+ * of twenty is **1.4 MB in one answer**. An agent choosing which version to
+ * restore would be handed a truncated blob and no reliable way to pick.
+ *
+ * `sb_publish` already had this exact problem and the same answer: a published
+ * row carries `document`, `html` and `css` for every page the cascade touched,
+ * so it PROJECTS the rows. This is that, applied where the caller cannot know to
+ * ask — and it is a DEFAULT rather than a rule: an explicit `pick` still wins,
+ * so the document is one argument away for a caller that wants to read one.
+ */
+const LIST_PROJECTIONS = {
+    'get:/api/sites/{siteId}/pages/{pageId}/versions': [
+        'id',
+        'versionNo',
+        'label',
+        'createdBy',
+        'createdAt',
+        'isLive',
+    ],
+    'get:/api/sites/{siteId}/pages/{pageId}/history': ['id', 'createdBy', 'createdAt'],
+};
 export function shapeResponse(raw, opts) {
     const asked = opts.pick !== undefined || opts.max_items !== undefined;
     const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
@@ -271,7 +298,10 @@ export async function callOperation(ctx, args) {
     if (raw === null || raw === undefined) {
         return { ok: true, method: op.method, path, note: 'The platform answered with no content.' };
     }
-    return shapeResponse(raw, { pick: args.pick, max_items: args.max_items });
+    // The caller's own `pick` outranks the default: asking for `document` is how
+    // you read a version rather than merely choose one.
+    const projection = args.pick ?? LIST_PROJECTIONS[op.id];
+    return shapeResponse(raw, { pick: projection, max_items: args.max_items });
 }
 export function registerApiTools(server, ctx) {
     server.registerTool('sb_api_find', {

package/dist/tools/importpage.js

@@ -193,6 +193,13 @@ export function registerImportTools(server, ctx, session) {
                 .max(100)
                 .optional()
                 .describe('Default 24 — every image is an upload'),
+            nav_timeout_ms: z
+                .number()
+                .int()
+                .min(5_000)
+                .max(120_000)
+                .optional()
+                .describe('How long to wait for a page to answer at all. Default 30000; raise it for a slow origin'),
             max_nodes: z
                 .number()
                 .int()
@@ -207,7 +214,7 @@ export function registerImportTools(server, ctx, session) {
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ url, site_id: given, max_sections, max_images, max_nodes, upload_images, dry_run }) => {
+    }, async ({ url, site_id: given, max_sections, max_images, max_nodes, nav_timeout_ms, upload_images, dry_run }) => {
         const siteId = siteFor(ctx, given);
         // THE TARGET PAGE MUST BE OPEN, and not only because that is where the
         // nodes go: its own heading, button and section are where the tokens come
@@ -217,6 +224,7 @@ export function registerImportTools(server, ctx, session) {
             maxSections: max_sections,
             maxImages: max_images,
             maxNodes: max_nodes,
+            navTimeoutMs: nav_timeout_ms,
         });
         const tokens = tokensFromPage(doc.doc);
         const images = imageSources(shot.sections);
@@ -332,13 +340,20 @@ export function registerImportTools(server, ctx, session) {
             exclude: z.array(z.string()).optional(),
             max_images: z.number().int().min(0).max(200).optional().describe('Default 24, whole import'),
             max_nodes: z.number().int().min(1).max(1000).optional().describe('Per page, default 300'),
+            nav_timeout_ms: z
+                .number()
+                .int()
+                .min(5_000)
+                .max(120_000)
+                .optional()
+                .describe('How long to wait for a page to answer at all. Default 30000; raise it for a slow origin'),
             upload_images: z.boolean().optional(),
             homepage: z.boolean().optional().describe("Entry into this site's home page, default true"),
             nav: z.boolean().optional().describe('Shared header linking the new pages, default true'),
             dry_run: z.boolean().optional(),
         },
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ url, site_id: given, max_pages, depth, include, exclude, max_images, max_nodes, upload_images, homepage, nav, dry_run, }) => {
+    }, async ({ url, site_id: given, max_pages, depth, include, exclude, max_images, max_nodes, nav_timeout_ms, upload_images, homepage, nav, dry_run, }) => {
         const siteId = siteFor(ctx, given);
         const entry = normalizeUrl(url);
         if (!entry) {
@@ -470,7 +485,7 @@ export function registerImportTools(server, ctx, session) {
         // 9,829px of catalogue across a dozen collection bands, and 300 cut it
         // off in the middle of the third. A cap is here to stop a runaway page,
         // not to decide how much of an ordinary one survives.
-        { maxImages: max_images ?? 60, maxNodes: max_nodes ?? 900 });
+        { maxImages: max_images ?? 60, maxNodes: max_nodes ?? 900, navTimeoutMs: nav_timeout_ms });
         const byUrl = new Map(shots.map((s) => [s.url, s]));
         // ONE UPLOAD PER IMAGE FOR THE WHOLE SITE, not per page. A logo, a payment
         // strip and a footer badge appear on every page of a real site, and

package/dist/vision/capture.js

@@ -1075,6 +1075,19 @@ function capturePage(limits) {
         }
         restore(bestState);
     }
+    // WHAT FRACTION OF THE PAGE A READER SEES SURVIVED, reported rather than
+    // assumed. Both halves are already computed above for the fallback decision,
+    // so this costs nothing and closes the one failure a capture cannot express:
+    // SETTLING IS NOT FAILING. MEASURED on ttgshop.vn while the origin was taking
+    // 45s to answer — 6 text nodes and 114 characters of a page holding 2,396,
+    // 4.8%, `skipped` empty, no error anywhere. A thin import that says so is one
+    // a caller retries; a silent one ships.
+    //
+    // Against the honest denominator this file already argues for: page chrome is
+    // skipped ON PURPOSE, so counting it would make every correct import of a
+    // nav-heavy site look broken.
+    const kept = textOf(sections);
+    const coverage = contentChars > 0 ? Math.round((kept / contentChars) * 100) : 100;
     const link = Array.from(document.querySelectorAll('link[rel="canonical"]'))[0];
     const canonical = link ? (link.getAttribute('href') ?? '') : '';
     return {
@@ -1084,6 +1097,7 @@ function capturePage(limits) {
         ...(forms.length ? { forms } : {}),
         sections,
         skipped,
+        coverage,
     };
 }
 /**
@@ -1123,18 +1137,49 @@ async function withBrowser(fn) {
  * `shoot.ts` gives: a page with a poller never goes idle, and waiting for that
  * spends the whole budget on a timeout that cannot resolve.
  */
-async function readPage(browser, url, width, work) {
+/**
+ * How long to wait for a page to answer AT ALL, and why it is a knob.
+ *
+ * Thirty seconds is right for the web and wrong for one site on one afternoon.
+ * MEASURED on ttgshop.vn, the same shop this importer was built against: it
+ * answered in 4.6s all morning and then took 45 SECONDS for 151 KB, with the
+ * next request not answering inside 45s at all. Nothing about the page changed
+ * — the origin was simply having a bad day, which is the ordinary condition of
+ * the sites a merchant actually asks to import.
+ *
+ * The default stays 30s, because a caller who says nothing wants a bound rather
+ * than a hang. What was wrong was that the number could not be raised at all:
+ * an import of your OWN slow site had no recourse, and the failure arrives as a
+ * bare Playwright timeout that names the browser rather than the remedy.
+ */
+const NAV_TIMEOUT_MS = 30_000;
+async function readPage(browser, url, width, work, navMs = NAV_TIMEOUT_MS, settleMs) {
     let page;
     try {
         page = await browser.newPage({ viewport: { width, height: 900 } });
-        await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
+        // `domcontentloaded`, NOT `load`, and `settleDom` does the rest.
+        //
+        // `load` waits for every SUBRESOURCE — including third-party iframes, which
+        // an import has no use for: this walk reads the iframe's `src` ATTRIBUTE and
+        // never needs the frame to render. So a page carrying an ad frame, a chat
+        // widget or a slow video embed stalled the whole capture for up to thirty
+        // seconds and then THREW, losing an import whose DOM had been ready the
+        // entire time. Caught by this repo's own test, whose fixture embeds real
+        // YouTube, Vimeo and Google Maps frames: it started failing at exactly 30s
+        // with nothing about the page having changed.
+        //
+        // The same lesson `sb_look` already paid for with `networkidle`, one wait
+        // earlier: the right question is "has the DOM stopped changing", and
+        // `settleDom` answers it directly and bounded. A page that genuinely needs
+        // its images is the SHOOT path's problem, and that one still waits.
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: navMs });
         // THE SAME SETTLE `sb_look` USES, not a flat sleep. A fixed 600ms is wrong
         // at both ends: example.com is finished long before it, and a page that
         // builds itself with scripts is not finished after it — which is exactly the
         // page an import is most likely to be pointed at. `settleDom` asks the
         // question actually being asked (has the page stopped changing) and answers
         // when it becomes true, bounded so a page that never settles is still read.
-        await settleDom(page);
+        await settleDom(page, settleMs);
         return await work(page);
     }
     finally {
@@ -1149,10 +1194,32 @@ function limitsFrom(opts) {
         maxNodes: opts.maxNodes ?? 400,
     };
 }
+/**
+ * A read that failed, said in the caller's terms.
+ *
+ * Playwright's own timeout names the browser and the wait — "page.goto: Timeout
+ * 30000ms exceeded" — which is true and tells a merchant nothing they can act
+ * on. The remedy is a number they can raise, so the message carries it.
+ */
+function readFailure(e) {
+    const msg = e.message ?? String(e);
+    // THE NUMBER COMES OUT OF THE ERROR, never out of the default. The first
+    // version of this printed NAV_TIMEOUT_MS, so a caller who had already raised
+    // the budget to 90s was told the page "did not answer within 30s" — a
+    // confidently wrong number, and one that sends them to change a setting they
+    // had just changed.
+    const hit = /Timeout (\d+)ms exceeded/.exec(msg);
+    if (hit) {
+        const secs = Math.round(Number(hit[1]) / 1000);
+        return (`the page did not answer within ${secs}s. A slow origin is ordinary — raise ` +
+            'nav_timeout_ms and try again, or import fewer pages at once.');
+    }
+    return msg.slice(0, 160);
+}
 /** Open a URL and capture it. */
 export async function capture(url, opts = {}) {
     const limits = limitsFrom(opts);
-    return withBrowser((browser) => readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits)));
+    return withBrowser((browser) => readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits), opts.navTimeoutMs, opts.settleMs));
 }
 /**
  * Capture several pages through one browser.
@@ -1169,11 +1236,11 @@ export async function captureMany(urls, opts = {}) {
         const out = [];
         for (const url of urls) {
             try {
-                const result = (await readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits)));
+                const result = (await readPage(browser, url, opts.width ?? 1440, (page) => page.evaluate(capturePage, limits), opts.navTimeoutMs, opts.settleMs));
                 out.push({ url, ok: true, result });
             }
             catch (e) {
-                out.push({ url, ok: false, why: e.message.slice(0, 160) });
+                out.push({ url, ok: false, why: readFailure(e) });
             }
         }
         return out;

package/dist/vision/shoot.js

@@ -172,7 +172,7 @@ export async function shoot(url, opts = {}) {
  * polling widget from holding the shot forever. A page that never settles is
  * photographed anyway — a late picture beats none.
  */
-export async function settleDom(page) {
+export async function settleDom(page, capMs = 2_000) {
     await page
         .evaluate(({ quiet, cap }) => new Promise((resolve) => {
         const start = Date.now();
@@ -194,7 +194,14 @@ export async function settleDom(page) {
                 resolve();
             }
         }, 50);
-    }), { quiet: 250, cap: 2_000 })
+    }), 
+    // The CAP is a knob because 2,000 ms is right for a healthy origin and
+    // wrong for a struggling one. MEASURED on ttgshop.vn while it was taking
+    // 45s to answer: the capture returned 6 text nodes and 114 characters of
+    // a page that holds 2,396 — 4.8% — and reported NO error, because
+    // settling is not failing. A silent thin import is worse than a refused
+    // one, and the shoot path keeps the default it was tuned for.
+    { quiet: 250, cap: capMs })
         .catch(() => { });
 }
 /**

package/package.json

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