@bettercms-ai/mcp 0.66.6 → 0.67.0

package/dist/index.js

@@ -2695,6 +2695,7 @@ var NEW_TOOL_TEXT = {
 var DELETE_PAGE_RUNTIME_BUNDLE = " Or, with no pageId, `runtimeBundle`: 'report' lists the duplicate pages derived from a server app's own bundle (`app/` folders); 'apply' retires them and their empty folders.";
 var PARAM_TEXT = {
   runtimeBundle: "instead of pageId: the server-app bundle cleanup",
+  pageRef: "page id or path ('/de/about'); a bare slug only when one page has it",
   editorSetupForce: "re-run a setup already ready for the live build",
   editorSetupCheck: "true = only report the state; starts nothing",
   pageDynamic: "a dynamic (collection template) page only",
@@ -2705,7 +2706,7 @@ var PARAM_TEXT = {
   where: "field filters: {field: value} is equality, {field: {op: value}} with op eq|ne|gt|gte|lt|lte|contains|in, and an array means `in`. System fields slug, status, publishedAt, locale work anywhere; a data field needs modelId. Compares the served copy (live for published, working for draft)",
   sort: "comma list, a leading - sorts descending, e.g. '-publishedAt,title'",
   page: "1-based page of `limit` rows; the response's meta says totalPages",
-  locale: "BCP-47 locale, one of the project's locales; null = the default language",
+  locale: "language, a BCP-47 tag (zh-CN \u2192 zh-cn), one of the project's locales; null = the default",
   translationOf: "the SOURCE's id this translates (never another translation); null unlinks. One per locale: set locale on the translation and translationOf to the source",
   pageScheduledAt: "ISO datetime to publish this page's draft at (needs publish permission); null cancels. An edit that omits scheduledAt CANCELS a pending schedule",
   pageUnpublishAt: "ISO datetime at which the published page returns to draft; null cancels; omitting it never cancels it",
@@ -2716,7 +2717,7 @@ var PARAM_TEXT = {
   confirmedInput: "true only after the user explicitly approved adding this custom input (`ui.input`); else setting or changing one is refused input_needs_confirmation. Removing one needs no approval"
 };
 var INPUT_CONFIRMED_HEADER = "x-bcms-confirmed-input";
-var BUTTON_FIELD_NOTE = "'button' is ONE call to action, value {label, href, variant?, size?, arrow?, icon?, newTab?}: never a text field beside a link field.";
+var BUTTON_FIELD_NOTE = "'button' is ONE call to action, value {label, href, variant?, size?, arrow?, icon?, newTab?} (arrow:false, icon:null turn one off): never a text field beside a link field.";
 var UPDATE_FIELD_DESCRIPTION = "Change ONE existing field of a content model (`modelId`) or of a page's schema (`pageId`), addressed by `path`: its key, or dot-separated keys through groups and repeaters ('hero.title'). Set its label, helpText, required, validation `config` (merged by key; null deletes one), showIf, ui or placement (null clears those). The rest of the schema is written back unchanged at the version read; a 409 means it changed since, so read again. `type` changes how every stored value is read and needs allowRetype: true. `key` renames it: stored values stay under the old key, so the route answers 409 with the entry count unless allowFieldRemoval: true discards them \u2014 migrate the values first. Ask the user before a retype or a rename. A page's label + link pair (primaryCtaText + primaryCtaHref) becomes one button with `mergeHref`.";
 var GET_SEO_DESCRIPTION = "Get the connected project's site-wide SEO settings \u2014 every key update_seo writes: seoDefaults (metaTitle, metaDescription, ogImage, twitterHandle, og, twitter, collectionSchemaTypes), siteSchema (the site's JSON-LD), robotsConfig, sitemapConfig, rssConfig, indexnowConfig and searchConfig.";
 var UPDATE_SEO_DESCRIPTION = "Set the connected project's site-wide SEO defaults and config. Each key you send is REPLACED whole (not deep-merged), so read get_seo and send the complete object. `seoDefaults` applies to every page that does not override it, and its `collectionSchemaTypes` maps a collection's model id to the schema.org type of its entries. `siteSchema` is the site's own JSON-LD (Organization/WebSite, emitted on the home page). `robotsConfig`, `sitemapConfig` and `rssConfig` shape robots.txt, sitemap.xml and the feed; `indexnowConfig` pings search engines on publish; `searchConfig` is site search. A key the plan does not include answers 403 FEATURE_LOCKED. Rebuilds the site.";
@@ -3299,6 +3300,7 @@ function buildToolDefs(deps) {
       throw err;
     }
   }
+  const pageIdOf = async (client, ref) => UUID.test(ref) ? ref : (await client.fetchJSON(client.url(`/management/pages/resolve?ref=${encodeURIComponent(ref)}`))).data.id;
   function guard(fn) {
     return async (args) => {
       try {
@@ -3419,10 +3421,10 @@ function buildToolDefs(deps) {
     translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf)
   });
   const getPageInput = z.object({
-    pageId: z.string().min(1).describe("page id (from list_pages / create_page)")
+    pageId: z.string().min(1).describe(PARAM_TEXT.pageRef)
   });
   const setPageContentInput = z.object({
-    pageId: z.string().min(1).describe("id of the page to write values to"),
+    pageId: z.string().min(1).describe(PARAM_TEXT.pageRef),
     data: z.record(z.string(), z.unknown()).describe(
       "field values keyed by field key. A nested 'array' (zone) value is an OBJECT { nonRepeatable: { childKey: value, \u2026 }, repeatable: [ { childKey: value }, \u2026 ] } \u2014 nonRepeatable holds the fixed-block values, repeatable is the list of item objects (omit a zone you didn't define). A primitive 'array' (itemType) is a plain list. An 'image' value is an asset URL or asset id (from upload_asset) \u2014 the server resolves it to { id, url, name, altText }. Read get_page first to see each field's zones."
     ),
@@ -3722,8 +3724,8 @@ function buildToolDefs(deps) {
   const composePagesInput = z.object({
     pages: z.array(
       z.object({
-        pageId: z.string().min(1).optional().describe("page id (from list_pages); or pass `slug`"),
-        slug: z.string().min(1).optional().describe("page slug, resolved against list_pages; or pass `pageId`"),
+        pageId: z.string().min(1).optional().describe(PARAM_TEXT.pageRef),
+        slug: z.string().min(1).optional().describe("a page slug, when one page has it; or pass `pageId`"),
         blockJson: z.array(blockObject).describe("REPLACES this page's whole block composition")
       })
     ).min(1).max(50)
@@ -4333,7 +4335,7 @@ ${d.outline}` : "Proposed Content structure.", d);
         "update_page",
         "Edit a page",
         "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first and send its `optimisticVersion` as `ifMatch`). A `blockJson` that swaps a component block to another component comes back with `warnings` (COMPONENT_SWAP_DROPS_OVERRIDES) naming the overrides the new component does not render; they stay on the block, so swapping back restores them. It does NOT change the field SCHEMA \u2014 use add_field (pageId) / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call \u2014 and on a singleton it publishes the page's content entry too; if the entry's workflow stage refuses, the page still goes live and `warnings` carries ENTRY_STILL_DRAFT with the entry id and the reason. STRUCTURED DATA is native SEO, never a field: leave it out and the page gets Automatic JSON-LD from its content (WebSite on the home page, Blog/CollectionPage on a collection's list page, WebPage otherwise); `schemaType` picks an explicit schema.org type whose properties are filled from the content; `schema` is pasted JSON-LD and wins over both (null clears it). " + PAGE_HEAD_NOTE + " " + SECTION_DOCTRINE,
-        z.object({ ...headPatchShape, noindex: z.boolean().optional().describe("hide this page from search engines and site search"), pageId: z.string().min(1), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional(), scheduledAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageScheduledAt), unpublishAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageUnpublishAt), locale: z.string().nullable().optional().describe(PARAM_TEXT.locale), translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf), ifMatch: z.number().int().min(0).optional().describe(UPDATE_PAGE_IF_MATCH_NOTE), dynamic: z.object({ previewPath: z.string().nullable().optional().describe(PARAM_TEXT.previewPath), modelId: z.string().min(1).optional().describe(PARAM_TEXT.pageModelId) }).optional().describe(PARAM_TEXT.pageDynamic) }).shape,
+        z.object({ ...headPatchShape, noindex: z.boolean().optional().describe("hide this page from search engines and site search"), pageId: z.string().min(1).describe(PARAM_TEXT.pageRef), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional(), scheduledAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageScheduledAt), unpublishAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageUnpublishAt), locale: z.string().nullable().optional().describe(PARAM_TEXT.locale), translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf), ifMatch: z.number().int().min(0).optional().describe(UPDATE_PAGE_IF_MATCH_NOTE), dynamic: z.object({ previewPath: z.string().nullable().optional().describe(PARAM_TEXT.previewPath), modelId: z.string().min(1).optional().describe(PARAM_TEXT.pageModelId) }).optional().describe(PARAM_TEXT.pageDynamic) }).shape,
         async (c, a) => {
           const res = await c.fetchJSON(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
@@ -4723,7 +4725,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Each release scans the built HTML for the element rendering each CMS field value; per slot this returns `mode` ('text-match' = guessed from rendered text, 'declared' = template-declared), what was bound, and `unmatched`: each path with its reason \u2014 not-declared, ambiguous-text, no-element, declared-only, needs-wrap, refused, layout-owned, page-owned, layout-locator-stale, locale-unvarianted, svg-unavailable, partial and unstamped (a page list the content apply left as built: `kind` `list <bound>/<total>`), mismatch (a text-match stamp whose element shows MORE than the value, or no longer the text it was matched on (`data-bcms-from`): never written), report-outdated. DEPLOY FIRST: before any release there is no report (pages 0, mode null, refreshRequired true). `refreshReason`: `never-generated` \u2014 only a release BetterCMS builds and serves writes a report, so a HEADLESS site never gets one, redeploy or not; `outdated` \u2014 the next release rewrites it. It certifies only that every non-empty field has SOME element carrying its path. `unaddressable` is the copy it cannot see: visible live text no field owns, by route and bucket, biggest first (null = unmeasured: diff visible text against entry values). Over `count / visible > 0.02`, fix it in the SOURCE (wrap the run in an element the codemod can bind, or declare `<BcmsField path=\u2026>`), deploy, re-read \u2014 playbook \xA711. `canvas.lane`: the editor's live-preview lane (`bridge`, `draft-route`; `none` \u2192 get_next_steps). `coverage.error` `nothing-bound`: no element of this build is bound, so its percentage describes another site.",
+        "The receipt for 'is this site actually EDITABLE?'. Each release scans the built HTML for the element rendering each CMS field value; per slot this returns `mode` ('text-match' = guessed from rendered text, 'declared' = template-declared), what was bound, and `unmatched`: each path with its reason \u2014 not-declared, ambiguous-text, no-element, declared-only, needs-wrap, refused, layout-owned, page-owned, layout-locator-stale, locale-unvarianted, svg-unavailable, partial and unstamped (a page list the content apply left as built: `kind` `list <bound>/<total>`), mismatch (a text-match stamp whose element shows MORE than the value, or no longer the text it was matched on (`data-bcms-from`): never written), report-outdated. DEPLOY FIRST: before any release there is no report (pages 0, mode null, refreshRequired true). `refreshReason`: `never-generated` \u2014 only a release BetterCMS builds and serves writes a report, so a HEADLESS site never gets one, redeploy or not; `outdated` \u2014 the next release rewrites it. It certifies only that every non-empty field has SOME element carrying its path. Global Sections count only on routes that render them (`layoutRoutes`). `unaddressable` is the copy it cannot see: visible live text no field owns, by route and bucket, biggest first (null = unmeasured: diff visible text against entry values). Over `count / visible > 0.02`, fix it in the SOURCE (wrap the run in an element the codemod can bind, or declare `<BcmsField path=\u2026>`), deploy, re-read \u2014 playbook \xA711. `canvas.lane`: the editor's live-preview lane (`bridge`, `draft-route`; `none` \u2192 get_next_steps). `coverage.error` `nothing-bound`: no element of this build is bound, so its percentage describes another site.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read \u2014 everything here, `unaddressable` included, is measured PER SLOT, so on a promote-gated project pass 'current' to read the tree the editor frames. Defaults to the slot this project's releases land in. The response's `sha` is the build the report describes; `refreshRequired` is true when that is not the build this slot serves. Also per slot: `builtRoutes`: routes the live build has HTML for (null = cannot say). `layoutIncomplete`: Layout paths the last content apply could not write (their publish waits); `layoutUnread`: Layout fields no route reads (`layoutUnreadJudged` false = not judged).") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -4994,7 +4996,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release` is the newest release (id, sha, status, phaseMarks, error, createdAt): while an uploaded build ingests or releases, state is `building`, `release.sha` the new sha and `lastLiveSha` still the old one; a failed deploy shows `release.status` failed with its `error`, and `held` state (`held.by`: staff, archived or no-subdomain) means the release waits until that is cleared. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release` is the newest release (id, sha, status, phaseMarks, error, createdAt): while an uploaded build ingests or releases, state is `building`, `release.sha` the new sha and `lastLiveSha` still the old one (re-sending the live sha is a no-op); a failed deploy shows `release.status` failed with its `error`, and `held` state (`held.by`: staff, archived or no-subdomain) means the release waits until that is cleared. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
         z.object({}).shape,
         // Flat body, no `data` envelope: `data()` read it as undefined.
         async (c) => ok("Deploy status.", await c.fetchJSON(c.url(`/management/projects/deploy-status`), { method: "GET" }))
@@ -5052,7 +5054,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       name: "list_pages",
       config: {
         title: "List pages in the current project",
-        description: "List the pages in the project this MCP key is bound to, each with its full field SCHEMA, pageType (singleton|dynamic), and status. Use it to verify WHERE content lands and to read field keys/types before set_page_content / add_field.",
+        description: "List the pages in the project this MCP key is bound to, each with its id, `path`, `language`, full field SCHEMA, pageType (singleton|dynamic), and status. Use it to verify WHERE content lands and to read field keys/types before set_page_content / add_field.",
         inputSchema: {}
       },
       handler: guard(
@@ -5064,6 +5066,9 @@ ${res.warnings.join("\n")}` : summary, res.data);
               id: p.id,
               title: p.title,
               slug: p.slug,
+              // Its URL and language: slugs are unique per folder, so `about` can be seven pages.
+              path: p.path,
+              language: p.language,
               pageType: p.pageType,
               status: p.status,
               fields: p.fields
@@ -5076,7 +5081,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       name: "get_page",
       config: {
         title: "Get a page (with its field schema)",
-        description: "Get one page by id INCLUDING its full field schema (keys, types, nested group/repeater children) and pageType. Read this before set_page_content so you write correctly-keyed values, or before add_field so you know the existing keys.",
+        description: "Get one page INCLUDING its full field schema (keys, types, nested group/repeater children), pageType, `path` and `language`. Read this before set_page_content so you write correctly-keyed values, or before add_field so you know the existing keys.",
         inputSchema: getPageInput.shape
       },
       handler: guard(
@@ -5643,18 +5648,20 @@ ${notes.join("\n")}` : summary, created);
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const needsSlug = args.pages.some((p) => !p.pageId);
-          const [known, pageList] = await Promise.all([
-            client.listComponents({ select: "summary" }),
-            needsSlug ? client.listPages() : Promise.resolve([])
-          ]);
+          const known = await client.listComponents({ select: "summary" });
           const ids = new Set(known.map((c) => c.id));
-          const bySlug = new Map(pageList.map((p) => [p.slug, p.id]));
           const results = [];
           for (const page of args.pages) {
-            const pageId = page.pageId ?? (page.slug ? bySlug.get(page.slug) : void 0);
-            if (!pageId) {
-              results.push({ ok: false, slug: page.slug, error: `No page with slug '${page.slug}' in this project \u2014 pass a pageId from list_pages.` });
+            const ref = page.pageId ?? page.slug;
+            if (!ref) {
+              results.push({ ok: false, error: "Pass a pageId or path from list_pages." });
+              continue;
+            }
+            let pageId;
+            try {
+              pageId = await pageIdOf(client, ref);
+            } catch (err) {
+              results.push({ ok: false, slug: page.slug, error: errorText(err) });
               continue;
             }
             const unknown = [...new Set(componentIdsIn(page.blockJson))].filter((id) => !ids.has(id));
@@ -5672,7 +5679,7 @@ ${notes.join("\n")}` : summary, created);
                 client.url(`/management/pages/${pageId}/meta`),
                 { method: "PATCH", body: JSON.stringify({ blockJson: page.blockJson }) }
               );
-              results.push({ ok: true, pageId, slug: written.data?.slug ?? page.slug, blocks: page.blockJson.length });
+              results.push({ ok: true, pageId, slug: written.data?.slug ?? page.slug, path: written.data?.path, blocks: page.blockJson.length });
             } catch (err) {
               results.push({ ok: false, pageId, slug: page.slug, error: errorText(err) });
             }
@@ -5924,11 +5931,20 @@ ${lines.join("\n")}`, found);
     // through the client's request plumbing — no bespoke SDK method per endpoint.
     ...lifecycleTools()
   ];
+  const withPageRef = (def) => ({
+    ...def,
+    handler: (args) => {
+      const ref = args?.pageId;
+      if (typeof ref !== "string" || !ref || UUID.test(ref)) return def.handler(args);
+      return guard(async () => def.handler({ ...args, pageId: await withClient((c) => pageIdOf(c, ref)) }))(void 0);
+    }
+  });
   return [
     ...defs.filter((d) => !LISTING_TAIL.has(d.name)),
     ...defs.filter((d) => LISTING_TAIL.has(d.name))
-  ].map(withProjectId);
+  ].map(withPageRef).map(withProjectId);
 }
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function registerTools(server, deps, tools = process.env.BETTERCMS_MCP_TOOLS) {
   const withElicit = {
     ...deps,
@@ -7335,7 +7351,7 @@ the host has a stale cached MCP \u2014 tell the user to \`rm -rf ~/.npm/_npx\` a
 
 ${SCHEMA_PROPOSAL_FLOW}
 
-After creating, report each page's id, slug, type, and field count, and the project it
+After creating, report each page's id, path, type, and field count, and the project it
 landed in. On 409 slug_taken, offer an alternative slug; on 401/403, the MCP key needs
 (re)authorizing.`
           }
@@ -7367,7 +7383,7 @@ ${PAGE_FLOW}
 
 ${STRUCTURE_RULE}
 
-After creating, report the page id, slug, type, field count, and the project it landed in.
+After creating, report the page id, path, type, field count, and the project it landed in.
 On 409 slug_taken, offer an alternative slug; on 401/403, the MCP key needs (re)authorizing.`
           }
         }