@bettercms-ai/mcp 0.72.1 → 0.72.2

package/dist/index.js

@@ -2540,6 +2540,7 @@ var STRUCTURE_PLAYBOOK_URI = "bettercms://playbook/structure";
 var STRUCTURE_DEFAULT_INSTRUCTION = `After you create collections or pages, organise them per the structure playbook: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure (read-only), show the user its outline, then apply it with set_content_structure and the version it returned (the If-Match). A project that already has a structure keeps it: file only what you created, with move_to_folder, unless the user asks for a full re-organisation.`;
 var SKILLS_ROUTING_INSTRUCTION = "Before writing code in a repo that uses BetterCMS, explore the repo, then read the installed `bettercms` skill (`npx @bettercms-ai/install --project -y` adds it if missing): its table turns what you found into the one reference the task needs \u2014 read only that. Without the skill installed, read the same files as resources: bettercms://skill/bettercms, then bettercms://skill/<reference>.";
 var DOCK_UI_ROUTING_INSTRUCTION = "How fields and props look in the editor (groups, tabs, rows, icons, item names) is playbook \xA714 or the `field-ui` prompt: write it with update_content_model field* or update_component prop* plus ifMatch, read it back, and finish when get_next_steps reports no dock-* step.";
+var PUBLISH_HOLD_INSTRUCTION = "An item an author held back from site publishes (`publishHeldAt` set) stays out of whole-site publishes: do not publish it unless the user names it; publish_entries `release` includes it again.";
 var RECEIPT_FIRST_INSTRUCTION = "Start every project with get_next_steps: its `receipt` lists what is already done (`done`), what is still missing (`missing`, each item citing the count it reacted to) and the one `nextAction`. Work from that receipt instead of re-reading the site, call get_next_steps again after each batch of edits, and before you tell the user you are finished. On an imported site the gate is the definition of done: run `receipt.gate.nextAction`, read again, and repeat until `receipt.complete` is true. Record a gap you cannot close with editor_setup `exempt` only for an allowed reason that is true, with a note, never in prose.";
 var NEXT_STEPS_DESCRIPTION = `Call this FIRST on a project. Returns \`receipt\` \u2014 \`done\` (live release, bound elements, conversion coverage, composed pages, published components and Layout), \`missing\`, \`nextAction\` and \`notes\` (unjudged: unknown, not done) \u2014 plus \`data\`, the unfinished items by \`ruleId\` (skill finish-site lists them). Each item cites its count and may carry \`payload\` {rows, total}, at most 20 rows. \`receipt.complete\` is the setup gate's verdict and \`receipt.gate\` its numbers per built route. Run \`receipt.gate.nextAction\`, call it again after each batch; you are finished only when \`complete\` is true. \`organise-content\`: pages and collections are in no folder \u2014 read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure and, once the user agrees, set_content_structure.`;
 var LAYOUT_CHROME_INSTRUCTION = 'When the user asks to make the navigation, footer or other site chrome editable, or get_next_steps lists a `layout-*` or `chrome-duplicated` item: this is playbook \xA711 item 3. Chrome is the project Layout, never page fields: in the source, wrap each Section in `data-bcms-layout-section` (the slot, its base slug) and mark each value `data-bcms-layout-field="layout:<sections[slug].id>:<fieldId>"`, never `data-bcms-field` inside it, then push; the strip removes the page copies, never delete them by hand. On a site BetterCMS serves, publish_layout writes Layout VALUES into the live pages; a structure change waits for a Rebuild. Never place nav, footer or modal blocks or fields on a page: the Layout (or the site\'s own layout) draws chrome, so a page copy either duplicates it or renders nowhere (get_componentize_plan reports one as LAYOUT_CHROME).';
@@ -2898,6 +2899,7 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "apply_branch",
   "generate_image",
   "transform_image",
+  "write_alt_text",
   // The ABM campaign lane — also hidden from the default listing (ABM_TOOLS below).
   "research_account",
   "build_abm_page",
@@ -2950,10 +2952,11 @@ var WEBHOOK_EVENTS = [
   "deployment.triggered"
 ];
 var NEW_TOOL_TEXT = {
+  save_reusable_block: "Copy a page section (its layout, values and design) into Saved blocks in the section library, under `name`. The page is not changed; a block placed from Saved blocks is an independent section.",
   search_content: "Full-text search over the project's PUBLISHED pages and entries (the site-search index). Returns id, type ('page'|'entry'), title, slug and a snippet per hit; `type` narrows to one kind. Drafts are not indexed: find those with list_content_entries `where`. `meta.unavailable` means site search is off for this project.",
   discard_draft: "Throw away unpublished edits to an entry (`entryId`) or a page (`pageId`) \u2014 exactly one: the draft returns to exactly what is live and `pendingChanges` becomes false. A page resets its blockJson and its published Layout overrides. 409 no_published_version means it was never published (delete it instead). Pass ifMatch (optimisticVersion) to refuse if it changed since you read it.",
   give_feedback: "Tell the BetterCMS team about a tool that failed, a capability you needed and did not have, or docs that misled you. Opens a ticket for the team; nothing in the project changes. Name the `tool`, and paste the request and response into `context`. Never include secrets or personal data.",
-  publish_entries: "Publish or unpublish many entries and pages in ONE call (up to 100 ids of each; pages publish only). Needs a publish-enabled connection, and each item still passes its own gates (editorial stage, required fields). Nothing stops the run: the result lists what changed (`published` or `unpublished`) and every refusal in `failed` with its reason. A publish answers 202 with the routes being rebuilt.",
+  publish_entries: "Publish or unpublish many entries and pages in ONE call (up to 100 ids of each; no page unpublish). Needs a publish-enabled connection, and each item still passes its own gates (editorial stage, required fields). Nothing stops the run: the result lists what changed (`published` or `unpublished`) and every refusal in `failed` with its reason. A publish answers 202 with the routes being rebuilt. `hold` keeps a live item's edits out of whole-site publishes, `release` includes them again; publishing a held item here ends its hold.",
   create_content_entries: "Create up to 200 DRAFT entries of one collection in ONE call, each {slug?, data} as create_content_entry takes it. Every row reports `created` (with id and slug) or `failed` (with the error), a failure does not stop the others, and `meta` counts them. A row with `externalKey` is safe to send again: its entry is `updated` (draft only), or `unchanged` when the row is the same. A row setting a developer-locked field fails (FIELD_LOCKED). Publish afterwards with publish_entries.",
   translate_entry: "Create an entry's `targetLocale` translation with AI (uses AI credits: 402/403 when out or not on the plan). Text and longtext fields are translated; rich text and documents are copied for you to translate; the rest is copied. The new entry is a DRAFT with `locale` set and `translationOf` = the source; `meta` lists translated and copied keys. `targetLocale` must be one of the project's locales; 409 locale_conflict means that translation exists, so edit it instead.",
   list_webhooks: "List the project's outgoing webhooks: name, url, events, whether active, and delivery health (total, failed, last attempt). Signing secrets are never returned.",
@@ -2966,7 +2969,8 @@ var NEW_TOOL_TEXT = {
   refresh_search_index: "Tell search engines and site search about published changes; costs nothing. action 'indexnow' submits `urls` (this site's own, up to 1000) to IndexNow, or every change since the last submission when omitted. action 'reindex' rebuilds the project's site-search index. 503 means the index is unreachable: try again later.",
   import_redirects: "Bulk-create redirects for a migration, from `rows` or from `text` in `format` (our CSV export, a Netlify `_redirects` file, or a vercel.json). Call it with `dryRun: true` FIRST: nothing is written and each row comes back `would-create`, `existing` or `skipped` with a reason. Rows get create_redirect's rules. Max 5000.",
   editor_setup: "Make the live build editable. A build imports only SEO/meta, media, brand and the models bcms-content.json declares; this derives the rest from the live release: pages, collections, forms, bindings, button and section components (when the authoring preference is components), Component Groups and the Content sidebar. Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true` or get_deploy_status `editorSetup`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
-  transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText)."
+  transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText).",
+  write_alt_text: "Alt text for a Media Library image (mediaId) or an https image URL (url), written from its pixels (1 AI credit). A suggestion: save it with update_media."
 };
 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 FIELD_LOCKED_NOTE = "A readOnly 'developer' field keeps its stored value: changing or omitting it without schema access is 403 FIELD_LOCKED.";
@@ -3025,7 +3029,8 @@ var SEO_KEY_TEXT = {
   indexnowConfig: "IndexNow on publish, minus URL patterns to leave out",
   searchConfig: "site search: on/off, the box's placeholder, AI answers"
 };
-var VARIANT_GROUP_NOTE = "When the component belongs to a family of looks, `variantGroup` names the family and lists its looks.";
+var VARIANT_GROUP_NOTE = "`variantGroup`: the family of looks it belongs to, if any, and its looks.";
+var DETACHED_COPY_NOTE = "{overrides?}: a rich-text embed's separate-copy `fields` (playbook \xA75)";
 var UNPROPPED_COPY_NOTE = "A `warnings` entry UNPROPPED_COPY names copy no prop targets, which nobody can edit: add a prop with a `target` for each leaf it lists.";
 var UPDATE_PAGE_IF_MATCH_NOTE = "get_page's `optimisticVersion`: the write applies only at that version, and a 409 means the page changed since, so read it again. Send it whenever you pass blockJson, which REPLACES the whole composition.";
 var SLOT_MULTIPLE_NOTE = "'slot' with config.multiple holds a list [{componentId, overrides?}] (config.maxItems, default 12, at most 50): target.path 'props.children' on a section. V2 slots, 'table' mode 'types': playbook \xA75.";
@@ -3713,7 +3718,7 @@ function buildToolDefs(deps) {
       "per-type props: heading {text, level}; text/richtext {html} (NOT {text}), and both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only) \u2014 use it for a title that carries a styled span; image {src, alt}; button {text, href, variant? (hosted pages; else a Button component), size? sm|md|lg, fullWidth?, arrow? boolean, icon? ui.icon name, newTab? boolean, rel? nofollow|sponsored|ugc}; spacer {height}; video {url}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns, copyright?}; section {children: block[]}; columns {columns: block[][], gap} \u2014 a column may hold ANY block; slider {slides:[{id,children}]}; tabs {tabs:[{id,label,children}]}; collection {cardComponentId?, source? {modelId}, limit?, filters?, sort?, pinnedIds?, excludeCurrent?}: a collection's published entries as cards (every prop: skill content-modeling)"
     ),
     style: z.record(z.string(), z.unknown()).optional().describe(
-      "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop], never all three. A real marketing band is a `section` block carrying bg + padding + contentWidth."
+      "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop] (all three hides it on the page: kept in the draft, never published). A real marketing band is a `section` block carrying bg + padding + contentWidth."
     ),
     window: windowArg.nullable().optional().describe(WINDOW_NOTE)
   });
@@ -4120,7 +4125,8 @@ function buildToolDefs(deps) {
     componentId: z.string().min(1).describe("component id (from list_components)")
   });
   const getComponentInput = z.object({
-    componentId: z.string().min(1).describe("component id (from list_components)")
+    componentId: z.string().min(1).describe("component id (from list_components)"),
+    detachedCopy: z.object({ overrides: z.record(z.string(), z.unknown()).optional() }).optional().describe(DETACHED_COPY_NOTE)
   });
   const publishComponentsInput = z.object({
     componentIds: z.array(z.string().min(1)).min(1).max(100).describe("component ids (from list_components)")
@@ -4428,6 +4434,13 @@ ${d.outline}` : "Proposed Content structure.", d);
         z.object({ redirectId: z.string().min(1) }).shape,
         async (c, a) => ok("Deleted redirect.", await data(c, "DELETE", `/management/redirects/${s(a.redirectId)}`))
       ),
+      def(
+        "save_reusable_block",
+        "Save a section as a reusable block",
+        NEW_TOOL_TEXT.save_reusable_block,
+        z.object({ pageId: z.string().min(1), blockId: z.string().min(1).describe("a top-level section id (get_page)"), name: z.string().min(1).describe("80 characters at most; a longer one is refused as SAVED_BLOCK_NAME_TOO_LONG") }).shape,
+        async (c, a) => ok("Saved the section as a reusable block.", await data(c, "POST", `/management/saved-blocks`, { pageId: a.pageId, blockId: a.blockId, name: a.name }))
+      ),
       def(
         "get_seo",
         "Get site SEO",
@@ -5022,14 +5035,14 @@ ${d.outline}` : "Proposed Content structure.", d);
         "Publish or unpublish many entries and pages",
         NEW_TOOL_TEXT.publish_entries,
         z.object({
-          action: z.enum(["publish", "unpublish"]).describe("take the items live, or back to draft"),
+          action: z.enum(["publish", "unpublish", "hold", "release"]).describe("live, back to draft, or hold/release from site publishes"),
           entryIds: z.array(z.string().min(1)).max(100).optional().describe("entry ids (from list_content_entries)"),
-          pageIds: z.array(z.string().min(1)).max(100).optional().describe("page ids (from list_pages); publish only")
+          pageIds: z.array(z.string().min(1)).max(100).optional().describe("page ids (from list_pages); not for unpublish")
         }).shape,
         async (c, a) => {
           const receipt = await data(c, "POST", `/management/publish`, { action: a.action, entryIds: a.entryIds, pageIds: a.pageIds });
           const outcome = receipt?.outcome;
-          return ok(a.action === "publish" ? publishedLines(outcome, "Publish receipt.").join("\n") : "Unpublish receipt.", receipt);
+          return ok(a.action === "publish" ? publishedLines(outcome, "Publish receipt.").join("\n") : a.action === "unpublish" ? "Unpublish receipt." : "Hold receipt.", receipt);
         }
       ),
       def(
@@ -5141,6 +5154,13 @@ ${d.outline}` : "Proposed Content structure.", d);
         }).shape,
         async (c, a) => ok("Edited image (a new asset).", await data(c, "POST", `/management/ai/image/transform`, { mediaId: a.mediaId, prompt: a.prompt, altText: a.altText, folderId: a.folderId }))
       ),
+      def(
+        "write_alt_text",
+        "Write alt text with AI",
+        NEW_TOOL_TEXT.write_alt_text,
+        z.object({ mediaId: z.string().min(1).optional().describe("the image (from list_media)"), url: z.string().optional().describe("or an https image URL") }).shape,
+        async (c, a) => ok("Alt text suggestion.", await data(c, "POST", `/management/ai/alt-text`, a.url ? { url: a.url } : { mediaId: a.mediaId }))
+      ),
       def(
         "list_activity",
         "List project activity",
@@ -5509,6 +5529,8 @@ ${d.outline}` : "Proposed Content structure.", d);
               language: p.language,
               pageType: p.pageType,
               status: p.status,
+              // Held back from whole-site publishes: only when set, so an unheld list stays the same size.
+              ...p.publishHeldAt ? { publishHeldAt: p.publishHeldAt } : {},
               fields: p.fields
             }))
           );
@@ -6019,11 +6041,18 @@ ${notes.join("\n")}` : summary, created);
       name: "get_component",
       config: {
         title: "Get a component (with its blockJson)",
-        description: "Get one component by id INCLUDING its blockJson tree and props (with any stored `ui` authoring chrome on them; `stale: true` = no placement renders it). Read this before update_component so you keep the existing blocks, and after declaring field UI as the receipt that it landed \u2014 a prop absent here was not stored. " + VARIANT_GROUP_NOTE,
+        description: "One component with its blockJson and props (stored `ui` on them; `stale: true` = no placement renders it). Read it before update_component to keep its blocks, and after declaring field UI: a prop absent here was not stored. " + VARIANT_GROUP_NOTE,
         inputSchema: getComponentInput.shape
       },
       handler: guard(
         async (args) => withClient(async (client) => {
+          if (args.detachedCopy) {
+            const res = await client.fetchJSON(
+              client.url(`/management/components/${encodeURIComponent(args.componentId)}/detached-copy`),
+              { method: "POST", body: JSON.stringify(args.detachedCopy) }
+            );
+            return ok(`A separate copy of '${res.data.name}': store \`fields\` on the embed.`, res.data);
+          }
           const cmp = await client.getComponent(args.componentId);
           return ok(`Component '${cmp.name}' (${cmp.blockJson.length} block(s)).`, cmp);
         })
@@ -6549,6 +6578,16 @@ component). A list of several item shapes on a component is a \`table\` prop wit
 \`config.mode: 'types'\` and \`config.itemTypes: [{ name, label?, fields }]\`, rows
 \`[{ _key?, _type: '<name>', ...values }]\`.
 
+A component inside a \`richtext\` value is \`{ _type: 'bcmsBlock', _key, schemaKey: 'component',
+schemaLabel?, fields: { componentId, overrides?, variant? } }\` and FOLLOWS the component: publishing
+it changes this place. A SEPARATE COPY stops following it: \`fields: { componentId, detached: true,
+props, blocks, sourcePublishedAt, variant? }\`, exactly as \`get_component { componentId,
+detachedCopy: { overrides } }\` returns them. It renders its own \`blocks\`; \`componentId\` stays so
+it can be linked again (write the linked shape), and a \`sourcePublishedAt\` older than the
+component's \`lastPublishedAt\` (every publish; \`publishedAt\` is the first) means the shared
+version changed since. Refused by name:
+\`component_copy_invalid\`, \`component_copy_not_frozen\`.
+
 ## 5b. NEVER MODEL SEO. It is native.
 
 Do not create \`seoTitle\`, \`metaTitle\`, \`metaDescription\`, \`ogImage\`, \`canonicalUrl\`,
@@ -7187,8 +7226,11 @@ conversion is yours to write.
    markup inside a \`text\` field.
    **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
    this platform stores \u2014 \`block\`, \`table\` (\`{_type:"table", rows:[{_key, cells:[{_key,
-   content:[...blocks], header?}]}]}\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
-   is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, or \`bcmsBlock\` carrying a
+   content:[...blocks], header?, group?}], group?}], caption?, notes?, rowGroups?, columnGroups?}\`,
+   groups \`[{_key, label}]\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
+   is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, \`pullQuote\`
+   (\`{quote, name, role?, link?}\`), \`keyTakeaways\` (\`{title?, points:[...strings]}\`,
+   title at most 40 characters, at most 8 points), or \`bcmsBlock\` carrying a
    \`schemaKey\` \u2014 and a foreign node (a Sanity image, \`{_type:"image", asset:{_ref}}\`, for one)
    is not merely unrendered: it has no component here, so it
    vanishes from the HTML every delivery surface reads while the stored value still looks whole.
@@ -8248,7 +8290,7 @@ function buildServer(deps) {
       // one definition of done; without this an agent converts the page it landed on and stops.
       instructions: RECEIPT_FIRST_INSTRUCTION + " When the user asks to make a site or all of its pages editable, to convert it, or to bind its fields: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. " + LAYOUT_CHROME_INSTRUCTION + " " + CTA_BUTTON_INSTRUCTION + " When the user asks to componentize the whole site, to turn every section into a component, or to build a component library from the site: this is playbook \xA712. Read `bettercms://playbook/schema` \xA712, start with get_site_composition, and use the batch tools \u2014 componentize_sections, compose_pages, update_layout with `commands`, publish_components \u2014 rather than one call per component. Finish with get_site_composition and tell the user what the platform does not model (cookie banners, modals, breadcrumbs, pagination) and which components still need the owner's approval in the dashboard before they can be published. " + // The default after authoring (the structure standard): organise what you made. Same
       // sentence as the hosted connector's MCP_INSTRUCTIONS.
-      STRUCTURE_DEFAULT_INSTRUCTION + " " + SKILLS_ROUTING_INSTRUCTION + " " + DOCK_UI_ROUTING_INSTRUCTION
+      STRUCTURE_DEFAULT_INSTRUCTION + " " + SKILLS_ROUTING_INSTRUCTION + " " + DOCK_UI_ROUTING_INSTRUCTION + " " + PUBLISH_HOLD_INSTRUCTION
     }
   );
   server.registerResource(