webcake-landing-mcp 1.0.43 → 1.0.45

package/README.md

@@ -89,7 +89,7 @@ persists it (source-only — the page opens in the editor where re-saving render
 | **npx (local)** — runs on your machine | Personal daily use, full control | browser `login`, a JWT, or none (reference tools) |
 | **Hosted URL** — use our live server, nothing to install | No Node.js, teams, the claude.ai dialog | your personal `?jwt=` link / `x-webcake-jwt` header |
 
-The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `list_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
+The **reference + generation tools** (`get_generation_guide`, `list_elements`, `validate_page`, …) and the **ingest tools** (`ingest_html`, `ingest_url` — turn an existing HTML or URL into a layout anchor so the AI can recreate or adapt it) work with **zero config**; only the **persistence tools** (`create_page`, `update_page`, `add_section`, `list_pages`, `find_pages`, `get_page`, `list_organizations`) need a token. Credentials resolve in order: **per-request header → env var → saved `auth.json`** (`login`).
 
 > 🛠️ Prefer a shell-script installer (`install.sh`/`install.ps1`), a cloned local build, or hand-written per-IDE config? See **[docs/manual-install.md](docs/manual-install.md)**.
 
@@ -464,6 +464,7 @@ Both `create_page` and `update_page` **default to `dry_run=true`** (validate and
 | `list_organizations` | List the account's organizations (id, name, is_default). Default = the `is_default` org. |
 | `create_page` | Persist a generated source as a new page (source-only). **Defaults to `dry_run=true`.** |
 | `list_pages` | List the account's pages (id, name, organization_id, updated_at) to pick one to edit. |
+| `find_pages` | Search the account's pages by name, domain, and/or page id (AND-combined) to locate one to edit; returns id, name, org, custom/default domain, updated_at. |
 | `get_page` | Fetch an existing page's decoded source tree so you can edit it. |
 | `update_page` | Overwrite an existing page's source with an edited tree. **Defaults to `dry_run=true`.** |
 

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.0.45",
+    "d": "09/06/2026",
+    "type": "Changed",
+    "en": "get_generation_guide workflow condensed to four steps: element-type reads and image fetches are now batched into single calls…",
+    "vi": "Workflow trong get_generation_guide được rút gọn xuống còn bốn bước: việc đọc loại phần tử và tìm ảnh nay được gộp thành các lần gọi batch duy nhất…"
+  },
+  {
+    "v": "1.0.44",
+    "d": "09/06/2026",
+    "type": "Added",
+    "en": "New find_pages tool searches the account's pages by name, domain (matches custom_domain or default_domain), and/or page id (filters are…",
+    "vi": "Công cụ find_pages mới tìm kiếm các trang trong tài khoản theo tên, domain (khớp với custom_domain hoặc default_domain), và/hoặc page id (các bộ lọc…"
+  },
   {
     "v": "1.0.43",
     "d": "09/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "New ingest_html tool parses an HTML string into a compact reference AST (~2–5KB) that classifies sections by role (header, hero, features, form,…",
     "vi": "Công cụ ingest_html mới phân tích cú pháp một chuỗi HTML thành AST tham chiếu thu gọn (~2–5KB) phân loại các section theo vai trò (header, hero,…"
-  },
-  {
-    "v": "1.0.39",
-    "d": "08/06/2026",
-    "type": "Internal",
-    "en": "Added server.json MCP Registry manifest (namespace io.github.vuluu2k/webcake-landing-mcp) and the corresponding mcpName field in package.json so the…",
-    "vi": "Thêm manifest MCP Registry server.json (namespace io.github.vuluu2k/webcake-landing-mcp) và trường mcpName tương ứng trong package.json để MCP…"
-  },
-  {
-    "v": "1.0.38",
-    "d": "08/06/2026",
-    "type": "Added",
-    "en": "New add_section tool appends one or more sections to an existing page without re-sending the full source: the server fetches the current page,…",
-    "vi": "Công cụ add_section mới cho phép gắn thêm một hoặc nhiều section vào trang hiện có mà không cần gửi lại toàn bộ source: server lấy trang hiện tại,…"
   }
 ]

package/dist/domains/landing/guide.js

@@ -126,15 +126,12 @@ WORKFLOW (recommended)
 0. INTAKE (never skip — even for a quick/test page): ask the essentials above, WAIT for the answers, restate a short outline (sections + CTA + colors), and get the user's "yes" BEFORE any new_page_skeleton / create_page. Do not generate on the same turn as the request.
 0b. LOCK THE DESIGN SYSTEM (after the customer confirms): commit the exact palette, type scale, spacing scale, and component specs (see DESIGN SYSTEM) — these are your tokens for every element below. Set settings.fontGeneral to the chosen font.
 1. Call get_generation_guide (this) once, then new_page_skeleton for the top-level shape.
-2. For each element type you'll use, call get_element to learn its specials & see an example.
-3. Optionally call new_element to get a correct skeleton, then fill specials + coordinates.
-3b. For every image the page needs (hero, product, about, feature, gallery), call search_images and put a returned URL into specials.src / gallery item.link. Use placehold.co ONLY when search_images returns ok:false.
-4. Assemble { page, popup, settings, options, cartConfigs }.
-5. Call validate_page and fix every error.
-6. To save: call list_organizations, show the orgs to the user and ask which to use (default to is_default). Then create_page (dry_run first, then dry_run:false with the chosen organization_id).
+2. BATCH the reads: call get_element ONCE with every type you'll use ({types:[…]}) to learn their specials + examples, and search_images ONCE with one query per image slot ({queries:[…]}). Don't call them per-type/per-image. (new_element is OPTIONAL — compact authoring (id + type + responsive styles + specials) is enough; skip it unless you want a skeleton.) Use placehold.co ONLY when search_images returns ok:false.
+3. Assemble { page, popup, settings, options, cartConfigs } in one pass.
+4. To save: call list_organizations, show the orgs and ask which to use (default to is_default). Then call create_page directly with dry_run=false (it validates internally and BLOCKS on errors — no separate validate_page round-trip, no dry-run pre-pass). Use dry_run=true / a standalone validate_page only when the request is ambiguous, the user asks to preview, or you assembled a source you are not persisting this turn. Fix every error before the real write.
 
 EDITING an existing page
 - list_pages → let the user pick (or take a page_id from a URL).
 - get_page(page_id) → you get the live { page, popup, settings, ... }. Edit it surgically: change only the elements the user asked for (text/styles/specials/events); keep every other element, its id, and coordinates intact. Never regenerate the whole tree for a small change.
 - To add an element: build it with new_element, give it a unique id, set top/left/width/height inside the right section's children.
-- validate_page → update_page(page_id, source) (dry_run first, then dry_run:false).`;
+- update_page(page_id, source) directly with dry_run=false (it validates + blocks on errors — no separate validate_page or dry-run pre-pass needed). Use dry_run=true only to preview an overwrite of significant existing content.`;

package/dist/domains/landing/instructions.js

@@ -9,11 +9,11 @@ RULES (follow for every request):
 - INTAKE FIRST — do this EVERY time, even for a "quick"/"test" page. Do NOT jump straight to new_page_skeleton/create_page on the same turn as the request: ask the essentials, restate an outline, get a "yes", THEN build. Ask ONE short batch (3–6, with sensible defaults so the user answers fast) enough to understand the page's PURPOSE, name, look and layout: page purpose/goal, brand/page name, what they sell + price (sales/ads pages), primary color + logo/branding, sections & layout in order, primary CTA + destination, desktop+mobile or mobile-only, which organization. CONSULT, don't interrogate: SUGGEST so the user reacts to something concrete — propose a section flow (pick the archetype matching the page type) + a look (hero treatment + color/tone), and when the user is vague offer 2–3 directions to choose from; proactively suggest sections that fit their goal (social-proof, FAQ, countdown), but ask, don't silently add. Then restate the proposed design (section flow + CTA + color/tone) and WAIT for the user's confirmation, iterating until it matches their intent, before generating. Never assume or silently placeholder the page name, product, price, or colors — ask; only placeholder a core fact when the user explicitly declines to give it.
 - ASK for any real data the page will display — never invent it, and don't silently placeholder it. This includes: phone/hotline/Zalo, price (+ original price), address, shop/brand name, links/URLs, email, opening hours, and exact stats/social-proof numbers. If a value the page needs is missing, ASK the user for it (in intake, or pause and ask before generating). Use a clearly-labelled placeholder ONLY when the user explicitly says to skip it — then tell them exactly what to fill in.
 - LANGUAGE: write ALL page copy in the SAME language the user is chatting in, with FULL, CORRECT diacritics/accents. For Vietnamese, every word MUST carry its proper dấu (e.g. "Trân Trọng Kính Mời", "Ngày 15 Tháng 08 Năm 2025") — NEVER emit accent-stripped "không dấu" text. Never romanize or drop accent marks from any language.
-- ALWAYS call validate_page and fix every error before create_page / update_page.
+- VALIDATION IS BUILT IN — create_page / update_page / add_section all validate the source themselves and BLOCK on errors (a dry_run=true call IS the validator: it validates + returns warnings without writing). So do NOT spend a separate validate_page round-trip before persisting — go straight to the persist call. Call validate_page on its own ONLY when you assemble a source you are NOT about to persist this turn (e.g. an intermediate check). Either way, fix every error before the real write.
 - BUILD THE SOURCE IN ONE PASS — gather everything you need BEFORE assembling the source, then build the FULL tree once. BATCH the reads: when a section needs several element types (section + text-block + image-block + button + form + input), call get_element({types:[…]}) ONCE instead of one call per type — same for images, call search_images({queries:[…]}) ONCE with one query per image slot (it dedups + parallelizes and returns one best photo per query). Do NOT interleave get_element calls between create_page previews and rebuild. create_page/update_page take the entire source as input, so each call re-ships the whole page — re-previewing repeatedly wastes the request.
-- create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear AND validate_page already passed (no errors), SKIP the dry-run and call with dry_run=false directly — saves one round-trip. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — validate_page is the validator. Do not run dry-run then dry-run again before the real write.
+- create_page and update_page DEFAULT to dry_run=true (a safety net for ambiguous requests). When the user's intent is clear, call with dry_run=false DIRECTLY (one call): the persist tools validate internally and block on errors, so the dry-run round-trip buys nothing here. Use dry_run=true only when (a) the request is ambiguous about target/content, (b) the user explicitly asks to "preview" or "xem trước", (c) this is an update_page that overwrites significant existing content, or (d) you genuinely need to inspect the redacted payload. Never loop dry-runs to "check" the source — the dry-run is itself the validator. Do not run dry-run then dry-run again before the real write, and do not add a separate validate_page call in front of it.
 - LARGE PAGES (4+ sections) — build INCREMENTALLY to avoid the giant single create_page payload that can drop the connection: create_page with a SMALL skeleton (empty/near-empty page) to get a page_id, then call add_section once per section (each call ships ONLY that section; the backend appends it server-side and rejects duplicate ids — no whole-source get+put). Small pages can still go in one create_page pass.
-- EDIT existing pages surgically: get_page → change ONLY what was asked → keep every other element, its id, and coordinates → validate_page → update_page. Never regenerate the whole tree for a small change.
+- EDIT existing pages surgically: find_pages (locate the page by name/domain/id when you don't already have a page_id) → get_page → change ONLY what was asked → keep every other element, its id, and coordinates → validate_page → update_page. Never regenerate the whole tree for a small change.
 - Organizations: call list_organizations and ask which to use; default to the is_default org. Endpoints are owner-scoped (only the account's own pages).
 - REFERENCE INPUT — if the user provides a layout reference, USE it as the layout anchor (don't ignore it, don't re-invent from scratch). Three input modes: (1) IMAGE/screenshot attached in chat → analyze it natively (no tool call): identify section flow (hero/features/form/cta/footer), heading hierarchy, dominant colors, font feel, then map sections to Webcake elements. (2) HTML string → call ingest_html(html) to get a compact AST. (3) URL → call ingest_url(url) for the same AST. The AST classifies sections by role and lists headings/subheadings/ctas/images/form_fields plus brand hints (colors/fonts) — use it for LAYOUT + HIERARCHY, then generate FRESH content tailored to the user's brand (don't 1:1 copy text). intent='clone' only when the user explicitly asks to mirror the original; default intent='adapt'. The reference workflow PRESERVES craft rules above (centering, page margin, premium spacing, real images) — apply them on top of the reference layout, don't bypass them.
 
@@ -28,4 +28,4 @@ MODEL (essentials):
 - Visible content lives in specials (text, src, field_name…), never in styles. Colors as rgba(). Animation in config.animation={name,delay,duration,repeat}. Form inputs need a unique specials.field_name (use canonical keys: full_name, phone_number, email, address, quantity).
 - IMAGES: include them (hero/product, feature icons, about photo). PREFER REAL PHOTOS — call search_images with a short English subject (e.g. 'fresh coffee cup') and put a returned URL (src.large for a hero/banner, src.medium for a card/thumb) into the image-block specials.src; it works out of the box (a shared proxy supplies images). Only if search_images returns ok:false, FALL BACK to a PLACEHOLDER sized to the box: https://placehold.co/<width>x<height>. (gallery.media = array of OBJECTS {type:'image',link:'<url>',linkVideo:'',typeVideo:'youtube',imageCompression:true} — NOT plain strings, the gallery reads item.link; video.specials.img = poster). NEVER leave src empty (renders blank). Ensure text contrasts with its section background.
 
-Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, get_page, update_page, add_section.`;
+Start by calling get_generation_guide. Tools: get_generation_guide, list_elements, get_element, new_element, new_page_skeleton, get_page_schema, validate_page, search_images, ingest_html, ingest_url, list_organizations, create_page, list_pages, find_pages, get_page, update_page, add_section.`;

package/dist/persistence/webcake-client.js

@@ -1,6 +1,7 @@
 const CREATE_ENDPOINT = "/api/v1/ai/create_page_from_source";
 const ORGS_ENDPOINT = "/api/v1/org/organizations";
 const PAGES_ENDPOINT = "/api/v1/ai/pages";
+const SEARCH_PAGES_ENDPOINT = "/api/v1/ai/search_pages";
 const PAGE_SOURCE_ENDPOINT = "/api/v1/ai/page_source";
 const UPDATE_ENDPOINT = "/api/v1/ai/update_page_source";
 const APPEND_ENDPOINT = "/api/v1/ai/append_section";
@@ -167,6 +168,32 @@ export async function listPages(config) {
     const pages = r.json?.data?.pages ?? r.json?.pages ?? [];
     return { ok: true, status: r.status, pages };
 }
+/**
+ * Search the account's pages by name / domain / id via the dedicated backend
+ * endpoint. Filters are AND-combined server-side; each row carries the page's
+ * `custom_domain` + `default_domain` so the caller can disambiguate by URL.
+ * Returns `endpoint_missing:true` on a 404 so the caller can fall back to
+ * filtering `listPages` client-side against an older backend lacking the route.
+ */
+export async function searchPages(config, filters) {
+    const qs = new URLSearchParams();
+    if (filters.name)
+        qs.set("name", filters.name);
+    if (filters.domain)
+        qs.set("domain", filters.domain);
+    if (filters.id)
+        qs.set("id", filters.id);
+    if (filters.limit != null)
+        qs.set("limit", `${filters.limit}`);
+    const url = `${config.base}${SEARCH_PAGES_ENDPOINT}${qs.toString() ? `?${qs}` : ""}`;
+    const r = await getJson(url, config);
+    if (r.status === 404)
+        return { ok: false, status: 404, endpoint_missing: true, error: "search_pages endpoint not found on backend" };
+    if (!r.ok)
+        return { ok: false, status: r.status, error: r.error };
+    const pages = r.json?.data?.pages ?? r.json?.pages ?? [];
+    return { ok: true, status: r.status, pages };
+}
 /** Read a page's decoded source tree (must be owned by the account). */
 export async function getPageSource(config, pageId) {
     const url = `${config.base}${PAGE_SOURCE_ENDPOINT}?page_id=${encodeURIComponent(pageId)}`;

package/dist/tools/persistence.js

@@ -12,7 +12,7 @@
 import { z } from "zod";
 import { text } from "../mcp/response.js";
 import { readConfig, configFromHeaders } from "../persistence/config.js";
-import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, createPage, listOrganizations, listPages, getPageSource, updatePageSource, appendSection, } from "../persistence/webcake-client.js";
+import { buildRequestRedacted, buildUpdateRequestRedacted, buildAppendRequestRedacted, createPage, listOrganizations, listPages, searchPages, getPageSource, updatePageSource, appendSection, } from "../persistence/webcake-client.js";
 export function registerPersistenceTools(server, domain) {
     // Resolve config from THIS request's headers (remote per-user JWT) first, then env.
     const cfgFor = (extra) => readConfig(configFromHeaders(extra?.requestInfo?.headers));
@@ -107,6 +107,52 @@ export function registerPersistenceTools(server, domain) {
             return text({ ok: false, reason: "missing_env", missing_env: missing });
         return text(await listPages(config));
     });
+    // 10b) Find pages (search by name / domain / id) ----------------------------
+    // The lookup step before an edit: locate the page the user means by name,
+    // domain (custom OR default), and/or page id, then feed its id to get_page →
+    // (edit) → update_page/add_section. Filters are AND-combined server-side and
+    // results carry both domain fields so the model can disambiguate by URL.
+    //
+    // Searches via the dedicated /api/v1/ai/search_pages endpoint (proper DB query,
+    // not limited to the 50 most-recent). If that route is missing (older backend
+    // → 404) it FALLS BACK to listing pages and filtering client-side by name/id
+    // (domain search is unavailable in the fallback — list_pages omits domains).
+    server.tool("find_pages", "Searches the account's pages by name, domain, and/or page id so you can locate the page to edit, then pass its id to get_page → update_page/add_section. Filters are AND-combined (e.g. name='sale' + domain='shop.com'). Each result includes id, name, organization_id, custom_domain, default_domain, updated_at. With no filters it returns the most-recent pages (like list_pages). Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", {
+        name: z.string().optional().describe("Case-insensitive substring of the page name to match."),
+        domain: z
+            .string()
+            .optional()
+            .describe("Case-insensitive substring of the page's domain (matches custom_domain OR default_domain)."),
+        page_id: z.string().optional().describe("Exact page id — narrows to that single page (useful to confirm it exists/owned)."),
+        limit: z.number().int().positive().max(100).optional().describe("Max results (default 50, capped at 100)."),
+    }, { title: "Find Webcake Pages", readOnlyHint: true, openWorldHint: true }, async ({ name, domain, page_id, limit }, extra) => {
+        const { config, missing } = cfgFor(extra);
+        if (!config)
+            return text({ ok: false, reason: "missing_env", missing_env: missing });
+        const res = await searchPages(config, { name, domain, id: page_id, limit });
+        if (!res.endpoint_missing) {
+            return text({ ok: res.ok, pages: res.pages, count: res.pages?.length ?? 0, status: res.status, error: res.error });
+        }
+        // Fallback: older backend without /search_pages — list and filter client-side.
+        const listed = await listPages(config);
+        if (!listed.ok)
+            return text({ ok: false, status: listed.status, error: listed.error });
+        let pages = listed.pages ?? [];
+        const nameQ = name?.toLowerCase();
+        if (nameQ)
+            pages = pages.filter((p) => p.name?.toLowerCase().includes(nameQ));
+        if (page_id)
+            pages = pages.filter((p) => `${p.id}` === page_id);
+        if (limit != null)
+            pages = pages.slice(0, limit);
+        return text({
+            ok: true,
+            pages,
+            count: pages.length,
+            via: "legacy_list_filter_fallback",
+            ...(domain ? { note: "Domain search is unavailable on this backend (list_pages omits domains); the domain filter was ignored." } : {}),
+        });
+    });
     // 11) Get page (read source) ------------------------------------------------
     server.tool("get_page", "Fetches an existing page's decoded source tree { page, popup, settings, options, cartConfigs } plus name and organization_id. Needs WEBCAKE_API_BASE + WEBCAKE_JWT.", { page_id: z.string().describe("The page id (from list_pages or a URL).") }, { title: "Get Webcake Page Source", readOnlyHint: true, openWorldHint: true }, async ({ page_id }, extra) => {
         const { config, missing } = cfgFor(extra);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-landing-mcp",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "description": "MCP server exposing Webcake landing-page element schemas + AI usage hints, and persisting LLM-generated page sources to a Webcake backend.",
   "mcpName": "io.github.vuluu2k/webcake-landing-mcp",
   "type": "module",