@bettercms-ai/mcp 0.38.2 → 0.41.1

package/dist/index.js

@@ -2133,7 +2133,9 @@ var fieldShape = {
   richText: z.boolean().optional().describe(
     "prose formatting. DEFAULTS TO TRUE for 'text': the field is created as rich text so editors can bold, link and format it on the canvas, and the API returns rich text (render with rich() from @bettercms-ai/sdk; plain() for titles and meta). Pass false for a value that is NOT prose and must stay a bare string \u2014 a URL/href, a slug, an id, an email, a phone number, a CSS class, an icon name. A link stored as rich text will not work as an href."
   ),
-  options: z.array(z.string()).optional().describe("choices when type is 'select'"),
+  options: z.array(z.union([z.string(), z.object({ label: z.string(), value: z.string() })])).optional().describe(
+    "choices when type is 'select'. A plain string, or {label, value} when the stored value differs from what the editor shows (e.g. {label:'Sold out', value:'soldOut'})."
+  ),
   config: z.record(z.string(), z.unknown()).optional().describe(
     "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, array {itemType: 'text'|'number'|'date'}, date {includeTime}, modular {blockSlugs: ['quote','gallery'], minItems?, maxItems?} \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model"
   ),
@@ -2162,9 +2164,34 @@ var fieldShape = {
   ),
   ui: uiObject.optional().describe(
     "AUTHORING CHROME \u2014 how this field presents in the editor. Never a delivery effect. `preview` and `layout` are valid ONLY on a nesting field ('group', 'repeater', an 'array' with config.zones, or 'modular'); `reorderable` only where there is a LIST to lock ('repeater', an 'array' with config.zones.repeatable, or 'modular' \u2014 a 'group' holds one item). preview keys must name real children, or the write is refused with the valid keys listed. An unknown key inside `ui` is a 400, not a silent strip. Read it back with get_content_model / get_page to confirm it landed. There is deliberately no `order`: field order is the array index \u2014 use add_field's `after` to insert."
+  ),
+  // ── G5: the four keys the backend field schema accepts that this whitelist stripped. ──
+  fieldsetId: z.string().min(1).optional().describe(
+    "id of one of this model's `fieldsets` (create_content_model / update_content_model). The field is shown inside that card in the editor. Editor-only: never changes what is stored or delivered."
+  ),
+  placement: z.enum(["cover", "title", "excerpt", "body", "inline", "panel"]).optional().describe(
+    "where the control sits in the entry editor: 'title' the entry's heading, 'cover' its lead image, 'excerpt' the summary, 'body' the document body, 'inline' or 'panel'. Omit to let the editor decide. Editor-only."
+  ),
+  defaultValue: z.unknown().optional().describe("the value a new entry starts with"),
+  searchable: z.boolean().optional().describe("omit (\u2261 true) to index this field for site search; false excludes it"),
+  unique: z.boolean().optional().describe(
+    "true: no two entries of this model may hold the same value (compared trimmed and case-insensitively). On a repeater child such as a variant SKU it also covers every row of every entry. Only on text, longtext, slug, email, phone, link and number. A clash is refused with 409 `unique_conflict`."
   )
 };
 var fieldObject = z.object(fieldShape);
+var urlPatternArg = z.string().nullable().optional().describe(
+  "the public URL of one entry, e.g. '/blog/:slug'. Must start with '/' and contain ':slug' exactly once ('{slug}' is refused). Drives RSS item links and the automatic 301 when an entry's slug changes. null clears it."
+);
+var fieldsetsArg = z.array(
+  z.object({
+    id: z.string().min(1),
+    name: z.string().min(1).max(60),
+    description: z.string().max(500).optional()
+  })
+).max(30).optional().describe(
+  "the model's editor cards: [{id, name, description?}], at most 30, ids unique, order = array index. `description` is one line under the card title. A field joins one with `fieldsetId`. Editor-only: never changes what is stored or delivered."
+);
+var RICH_TEXT_NOTE = "\u{1F534} A field of type 'text' is created as RICH TEXT unless you send `richText: false` on it. Send `richText: false` for every value that is not prose: a name used as a title, a URL, slug, id, SKU, email, phone, CSS class or icon name.";
 function flatFieldKeys(fields) {
   const out = [];
   const childrenOf = (f) => {
@@ -2205,7 +2232,14 @@ function toField(f) {
     ...f.required !== void 0 ? { required: f.required } : {},
     ...f.helpText !== void 0 ? { helpText: f.helpText } : {},
     ...f.showIf !== void 0 ? { showIf: f.showIf } : {},
-    ...f.ui !== void 0 ? { ui: f.ui } : {}
+    ...f.ui !== void 0 ? { ui: f.ui } : {},
+    // G5: these four persist on the backend and were stripped here, like helpText once was.
+    ...f.fieldsetId !== void 0 ? { fieldsetId: f.fieldsetId } : {},
+    ...f.placement !== void 0 ? { placement: f.placement } : {},
+    ...f.defaultValue !== void 0 ? { defaultValue: f.defaultValue } : {},
+    ...f.searchable !== void 0 ? { searchable: f.searchable } : {},
+    // BE-6: a leaf key like the four above, so it rides on `base` and survives every branch.
+    ...f.unique !== void 0 ? { unique: f.unique } : {}
   };
   if (f.type === "group") {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
@@ -2415,12 +2449,14 @@ function buildToolDefs(deps) {
     name: z.string().min(1).describe("human model name, e.g. 'Blog Post'"),
     slug: slug.describe("url-safe unique slug, e.g. 'blog-post'"),
     description: z.string().optional(),
+    urlPattern: urlPatternArg,
     kind: z.enum(["model", "block"]).optional().describe(
       "'model' (default) = a collection with its own entries. 'block' = a type that exists only to be stacked inside another model's 'modular' field \u2014 it holds no entries, and create_content_entry against it is refused. Create blocks FIRST, then the model whose modular field lists their slugs. Cannot be changed later."
     ),
     fields: z.array(fieldObject).optional().describe(
       "the model's typed schema fields. 'group'/'repeater' NEST their child fields (any depth) \u2014 don't flatten zones into top-level fields."
-    )
+    ),
+    fieldsets: fieldsetsArg
   });
   const afterArg = z.string().min(1).optional().describe(
     "OPTIONAL insertion point: the key of an existing TOP-LEVEL field to insert this one directly after. Omit to append at the end (the default, and the behaviour before this existed). Use it to put a field where an author expects it instead of at the bottom \u2014 e.g. after:'hero_title' for a subtitle. An unknown key is refused rather than silently appended."
@@ -2441,6 +2477,7 @@ function buildToolDefs(deps) {
     filename: z.string().optional().describe("override the stored filename"),
     altText: z.string().optional().describe("accessibility alt text"),
     caption: z.string().optional(),
+    transcript: z.string().max(1e5).optional().describe("video/audio only: the spoken words (\u2264 100,000 chars), published wherever the file is used"),
     folderId: z.string().optional().describe("target Media Library folder (defaults to project root)")
   });
   const createEntryInput = z.object({
@@ -2668,6 +2705,18 @@ function buildToolDefs(deps) {
       "REPLACES the prop array \u2014 include every prop you want to keep, WITH its stored `ui`, or that prop's authoring chrome is dropped along with the prop. Read get_component first."
     )
   });
+  const setComponentSourceInput = z.object({
+    componentId: z.string().min(1).describe("component id (from list_components)"),
+    path: z.string().min(1).max(512).describe("file path relative to the app root, e.g. src/components/sections/Hero.astro"),
+    export: z.string().min(1).max(128).optional().describe("named export that renders it; omit for a default export"),
+    kind: z.enum(["file", "section"]).optional().describe("'file' (props are this component's fields; default) or 'section' (a codemod-extracted section: props { blockId, bind, overrides, page })")
+  });
+  const submitComponentizeReceiptInput = z.object({
+    receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --componentize --receipt <file>` wrote, verbatim.")
+  });
+  const clearComponentSourceInput = z.object({
+    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)")
   });
@@ -2819,9 +2868,22 @@ function buildToolDefs(deps) {
           filename: z.string().min(1).describe("file name incl. extension"),
           altText: z.string().optional(),
           caption: z.string().optional(),
+          transcript: z.string().max(1e5).optional().describe("video/audio only: the spoken words (\u2264 100,000 chars)"),
           folderId: z.string().optional()
         }).shape,
-        async (c, a) => ok("Media asset.", await data(c, "POST", `/management/media/from-upload`, { assetId: a.assetId, uploadKey: a.uploadKey, filename: a.filename, altText: a.altText, caption: a.caption, folderId: a.folderId }))
+        async (c, a) => ok("Media asset.", await data(c, "POST", `/management/media/from-upload`, { assetId: a.assetId, uploadKey: a.uploadKey, filename: a.filename, altText: a.altText, caption: a.caption, transcript: a.transcript, folderId: a.folderId }))
+      ),
+      def(
+        "update_media",
+        "Update a media asset",
+        "Describe an existing media asset: set its alt text, caption or transcript. A transcript (video/audio only, \u2264 100,000 chars) is stored ON the asset, so every page and entry using the file publishes it \u2014 hosted pages, the .md twin, llms-full.txt and the delivery API. Pass null to clear a field. Use this after your own speech-to-text; BetterCMS does not generate transcripts.",
+        z.object({
+          assetId: z.string().min(1).describe("media asset id (from list_media / upload_asset)"),
+          altText: z.string().max(500).nullable().optional().describe("alt text; null clears"),
+          caption: z.string().max(1e3).nullable().optional().describe("caption; null clears"),
+          transcript: z.string().max(1e5).nullable().optional().describe("the spoken words; null clears. Video/audio only.")
+        }).shape,
+        async (c, a) => ok("Updated media asset.", await data(c, "PATCH", `/management/media/${encodeURIComponent(s(a.assetId))}`, { altText: a.altText, caption: a.caption, transcript: a.transcript }))
       ),
       def(
         "list_media",
@@ -3091,9 +3153,10 @@ function buildToolDefs(deps) {
       def(
         "update_content_model",
         "Update a content model's metadata",
-        "Rename a content model or edit its description/slug (metadata only \u2014 does NOT touch fields; use add_field to extend the schema). Provide modelId plus the fields to change.",
-        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional() }).shape,
-        async (c, a) => ok("Updated content model.", await data(c, "PATCH", `/management/content/models/${s(a.modelId)}`, { name: a.name, slug: a.slug, description: a.description }))
+        "Rename a content model, edit its description/slug/urlPattern, or set its `fieldsets`. Never touches `fields`: use add_field to extend the schema. Provide modelId plus what to change. `fieldsets` REPLACES the list (send null to drop them all); then put a field in one with add_field's `fieldsetId`. `urlPattern` is the collection's entry URL, e.g. '/blog/:slug' (null clears it). A slug already used in this project and branch is refused with 409 `slug_taken`.",
+        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), urlPattern: urlPatternArg, fieldsets: fieldsetsArg.nullable() }).shape,
+        // `fields` is deliberately not sent: the PATCH replaces `fields` wholesale when present.
+        async (c, a) => ok("Updated content model.", await data(c, "PATCH", `/management/content/models/${s(a.modelId)}`, { name: a.name, slug: a.slug, description: a.description, urlPattern: a.urlPattern, fieldsets: a.fieldsets }))
       ),
       def(
         "get_content_types",
@@ -3108,7 +3171,20 @@ function buildToolDefs(deps) {
         "Edit a page",
         "Edit a page: title, slug, SEO metaTitle/metaDescription, publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first). It does NOT change the field SCHEMA \u2014 use add_page_field / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call. " + SECTION_DOCTRINE,
         z.object({ 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(), status: z.enum(["draft", "published"]).optional() }).shape,
-        async (c, a) => ok("Updated page.", await data(c, "PATCH", `/management/pages/${s(a.pageId)}/meta`, { title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, status: a.status }))
+        async (c, a) => {
+          const res = await c.fetchJSON(
+            c.url(`/management/pages/${s(a.pageId)}/meta`),
+            {
+              method: "PATCH",
+              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, status: a.status })
+            }
+          );
+          const note = res.redirectNote;
+          return ok(
+            note ? `Updated page. An existing redirect from ${note.source} already points to ${note.existingDestination}; it wasn't changed, so the old address does not redirect to the new one.` : "Updated page.",
+            res.data
+          );
+        }
       ),
       // ── Code + deploy (parity with remote /mcp; needs artifact:write) ──
       // Both grant shapes carry that scope now; a workspace-wide one names its target per
@@ -3447,6 +3523,8 @@ function buildToolDefs(deps) {
             slug: args.slug,
             pageType: args.pageType ?? "singleton",
             ...args.blockJson ? { blockJson: args.blockJson } : {},
+            // Cast: the SDK's ContentModelField types `options` as string[], narrower than the API,
+            // which also takes {label, value} (backend selectFieldSchema).
             ...args.fields ? { fields: args.fields.map(toField) } : {},
             ...args.metaTitle !== void 0 ? { metaTitle: args.metaTitle } : {},
             ...args.metaDescription !== void 0 ? { metaDescription: args.metaDescription } : {}
@@ -3462,7 +3540,7 @@ function buildToolDefs(deps) {
       name: "create_content_model",
       config: {
         title: "Create a content model (reusable schema)",
-        description: "Create a content model \u2014 a reusable schema for a dynamic collection (Blog, Products, Testimonials). `fields` may NEST: type 'group' = one nested object of child fields; type 'repeater' = a repeatable array of child objects. Put child fields in each group/repeater's own `fields` (any depth). Pass kind:'block' to create a BLOCK type instead \u2014 see that argument.",
+        description: "Create a content model \u2014 a reusable schema for a dynamic collection (Blog, Products, Testimonials). `fields` may NEST: type 'group' = one nested object of child fields; type 'repeater' = a repeatable array of child objects. Put child fields in each group/repeater's own `fields` (any depth). Pass kind:'block' to create a BLOCK type instead \u2014 see that argument. `fieldsets` ([{id, name}]) are the model's editor cards; a field joins one with `fieldsetId`. The slug must be unique in this project and branch: a taken one is refused with 409 `slug_taken` and free `suggestions`. " + RICH_TEXT_NOTE,
         inputSchema: createModelInput.shape
       },
       handler: guard(
@@ -3473,7 +3551,9 @@ function buildToolDefs(deps) {
             name: args.name,
             slug: args.slug,
             ...args.description !== void 0 ? { description: args.description } : {},
+            ...args.urlPattern !== void 0 ? { urlPattern: args.urlPattern } : {},
             ...args.kind !== void 0 ? { kind: args.kind } : {},
+            ...args.fieldsets !== void 0 ? { fieldsets: args.fieldsets } : {},
             fields: toFields(args.fields)
           });
           return ok(
@@ -3487,7 +3567,7 @@ function buildToolDefs(deps) {
       name: "add_field",
       config: {
         title: "Add a field to a content model",
-        description: "Append a field to an existing content model. Reads the model's current fields and adds yours (read-modify-write) \u2014 never removes existing fields. For a section/zone, add ONE 'group' (fixed block) or 'repeater' (repeating list) field carrying its child `fields` \u2014 don't add the zone's inner fields as separate top-level fields.",
+        description: "Append a field to an existing content model. Reads the model's current fields and adds yours (read-modify-write) \u2014 never removes existing fields. For a section/zone, add ONE 'group' (fixed block) or 'repeater' (repeating list) field carrying its child `fields` \u2014 don't add the zone's inner fields as separate top-level fields. `fieldsetId` puts it in one of the model's fieldsets (set them with update_content_model). " + RICH_TEXT_NOTE,
         inputSchema: addFieldInput.shape
       },
       handler: guard(
@@ -3530,6 +3610,8 @@ function buildToolDefs(deps) {
       handler: guard(
         async (args) => withClient(async (client) => {
           const page = await client.addPageFields(args.pageId, {
+            // Cast: same as create_page. The SDK types `options` as string[], narrower than the
+            // API, which also takes {label, value} (backend selectFieldSchema).
             addFields: [toField(args)],
             ...args.after !== void 0 ? { after: args.after } : {}
           });
@@ -4053,6 +4135,61 @@ ${lines.join("\n")}`, found);
         })
       )
     },
+    {
+      name: "set_component_source",
+      config: {
+        title: "Record which file implements a component",
+        description: "Call this RIGHT AFTER you write or locate the code for a component in the app's repository. It tells BetterCMS which file renders the component, so the dashboard's Output button can build a live preview and validate it with no setup. Without it Output says no source is recorded and nothing is validated. Record ONLY a file that renders exactly this component from its own fields: a component whose props are this component's field keys (`kind: 'file'`, the default), or a section the codemod extracted with `npx @bettercms-ai/convert --componentize` \u2014 a file starting `// @bettercms-ai/convert section` whose props are `{ blockId, bind, overrides, page }` (`kind: 'section'`). Never record a different component that merely contains this markup (e.g. a card that needs a `post` object): it cannot render from these fields and validation fails. If the markup is inline in a page, extract it into a section first. `path` is relative to the app root (e.g. 'src/components/sections/Hero.astro'); `export` is the export name, omitted for a default export. Call it again if the file moves; call clear_component_source if a recorded file is wrong.",
+        inputSchema: setComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/preview-source`),
+            { method: "PUT", body: JSON.stringify({ path: args.path, ...args.export ? { export: args.export } : {}, ...args.kind ? { kind: args.kind } : {} }) }
+          );
+          return ok(`Recorded ${res.data.path}${res.data.export === "default" ? "" : ` (export ${res.data.export})`} as the source of component ${res.data.componentId}.`, res.data);
+        })
+      )
+    },
+    {
+      name: "submit_componentize_receipt",
+      config: {
+        title: "Record the sources a componentize run wrote",
+        description: "Record every section the componentize codemod extracted as its component's source. Call it right after `npx @bettercms-ai/convert --componentize --receipt componentize.json` (and after pushing the files): pass that receipt verbatim. Each extracted section is recorded as kind 'section' for the component with the same slug, so Output can build and validate it with no set_component_source per component. Answers which components were recorded, and any slug this project has no component for.",
+        inputSchema: submitComponentizeReceiptInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url("/management/components/preview-sources/componentize-receipt"),
+            { method: "POST", body: JSON.stringify({ receipt: args.receipt }) }
+          );
+          const { recorded, unknown, invalid } = res.data;
+          return ok(
+            `Recorded ${recorded.length} section source${recorded.length === 1 ? "" : "s"}${unknown.length ? `; no component for ${unknown.join(", ")}` : ""}${invalid.length ? `; unimportable path for ${invalid.join(", ")}` : ""}.`,
+            res.data
+          );
+        })
+      )
+    },
+    {
+      name: "clear_component_source",
+      config: {
+        title: "Remove a component's recorded source file",
+        description: "Remove the file recorded as a component's source (by set_component_source or a conversion receipt). Use it when the recorded file is wrong \u2014 Output then shows no source until the right file is recorded. Safe to call when nothing is recorded.",
+        inputSchema: clearComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/preview-source`),
+            { method: "DELETE" }
+          );
+          return ok(res.data.cleared ? `Removed the recorded source of component ${res.data.componentId}.` : `Component ${res.data.componentId} had no recorded source.`, res.data);
+        })
+      )
+    },
     {
       name: "publish_component",
       config: {
@@ -4621,6 +4758,19 @@ cluster \u2192 \`group\`. Nesting is capped at TWO levels from the prop (a \`tab
 utilities, aria attributes and alt text all survive. Never restyle while componentizing. Run
 \`componentize_sections { dryRun: true }\` and the codemod's \`--dry-run\` first.
 
+**5b. Every component's Output must render \u2014 record its SOURCE.** The dashboard's Output builds and
+validates a component from the file in the repository that renders it, and only a file whose props
+match renders it. A section the codemod extracted is such a file: after \`npx @bettercms-ai/convert
+--componentize --receipt componentize.json\`, push the files and call \`submit_componentize_receipt
+{ receipt }\` \u2014 every extracted section is recorded for the component with the same slug. A section
+you write BY HAND follows the same contract: props exactly \`{ blockId, bind, overrides, page }\`, the
+root element carries \`data-bcms-block={blockId}\`, and copy is read through \`bcmsSection(page, bind,
+overrides)\` (or \`bcmsSectionPaths\` for a flat field family like \`wrap-h2-latest\`); then call
+\`set_component_source { kind: 'section' }\`. A component module whose props ARE its fields is
+\`set_component_source\` with the default kind. NEVER record a different component that merely
+contains the markup (a card needing a \`post\` object): it cannot render from these fields and its
+validation fails every time \u2014 \`clear_component_source\` removes a wrong one.
+
 **6. The final validation is \`get_site_composition\`.** It is the receipt for "is every page
 assembled from registered components?": per page its blocks and every component placement with
 that component's status, plus site totals \u2014 unpublished, awaiting evidence, awaiting approval,
@@ -4635,6 +4785,8 @@ bulk approve, and no tool here can grant that approval. Finish with \`get_next_s
     1.  get_site_composition        the before picture
     2.  get_componentize_plan       DERIVED site only \u2014 confirm it with the user
     3.  componentize_sections       dryRun first, then for real
+    3b. npx @bettercms-ai/convert --componentize --receipt componentize.json, push,
+        then submit_componentize_receipt { receipt }   every section's Output source, ONE call
     4.  create_components           everything the plan did not cover, ONE call, each with a group
     5.  compose_pages               every page's blockJson, ONE call
     6.  update_layout { commands }  nav/footer chrome + add-component, ONE call