@bettercms-ai/mcp 0.75.0 → 0.76.1

package/dist/index.js

@@ -2996,7 +2996,7 @@ var PARAM_TEXT = {
   readOnly: "'developer' = the value and this lock change only with schema access (needs lockReason); true = an editor marker",
   lockReason: "which system owns the value (\u2264 200 chars)",
   lockClears: "as on add_field; null clears it",
-  helpText: "shown under the field: its purpose, where it shows, any constraint; never its label or value. Omitted: written for you.",
+  helpText: "shown under the field. Most fields get none: write it only for a format or unit, a place the canvas cannot show, a real constraint or a fallback, as one plain sentence under 90 characters with no semicolons, no dashes and no values from the page, never its label or value. Omitted: the platform writes it where one of those reasons holds.",
   helpMore: "longer help behind the \u24D8 next to the label, when one helpText line cannot carry it",
   advanced: "true = a rare or developer setting: it collects in a closed 'Advanced' section",
   recommendedMax: "a SOFT limit (characters, items or value): the editor warns past it, never refuses",
@@ -3005,6 +3005,7 @@ var PARAM_TEXT = {
   componentPreview: "a slot row's look: {title?, subtitle?, media?} TOP-LEVEL prop keys, fallback?, icon?; null clears. \xA73 of bettercms://playbook/schema",
   componentIcon: "the block icon, a dock icon name; null clears. \xA73 of bettercms://playbook/schema",
   componentTabs: "/kit tabs no top-level prop sits in: [{id,label,icon?,order?}]. \xA73 of bettercms://playbook/schema",
+  componentKitEntry: "the bettercms://kit entry id its V2 dock UI follows, confirmed by you: import only SUGGESTS one, so check its htmlSignals and pitfalls first (kit_entry_unknown otherwise); null clears. The setup gate's dock row needs one",
   describes: "for editors: what it is and holds; omitted: written for you",
   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",
@@ -3047,6 +3048,7 @@ var SEO_KEY_TEXT = {
 };
 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 KIT_ENTRY_REBUILD_NOTE = "Setting or changing `kitEntry` rebuilds that entry's ui on every prop whose ui the server derived (ui a person or an agent set is kept); `kitUiApplied` lists the props it changed.";
 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.";
@@ -4090,7 +4092,7 @@ function buildToolDefs(deps) {
     "conversion"
   ]);
   const sectionType = z.string().min(1).max(64).describe(
-    "section family, e.g. 'Hero' \u2014 set this with a library category to make the component selectable in the page editor's 'Add a section' picker. Components sharing one are layout variants of one section."
+    "section family: what KIND of section this is, e.g. 'Hero', 'Logo cloud', 'Pricing', 'FAQ' (never its heading's words: a section's title is its own heading, shown as written). Set this with a library category to make the component selectable in the page editor's 'Add a section' picker. Components sharing one are layout variants of one section."
   );
   const allowedOn = z.array(z.string().regex(/^(\*|slug:[a-z0-9-]+|type:(singleton|dynamic|template))$/)).max(100).describe("placement allowlist: *, slug:<page-slug>, and/or type:singleton|dynamic|template");
   const componentPreviewArg = z.strictObject({
@@ -4114,6 +4116,7 @@ function buildToolDefs(deps) {
     preview: componentPreviewArg.optional(),
     icon: dockIconArg.nullable().optional().describe(PARAM_TEXT.componentIcon),
     tabs: z.array(z.object({ id: z.string(), label: z.string(), icon: z.string().optional(), order: z.number().int().optional() })).nullable().optional().describe(PARAM_TEXT.componentTabs),
+    kitEntry: z.string().min(1).max(100).nullable().optional().describe(PARAM_TEXT.componentKitEntry),
     blockJson: z.array(blockObject).default([]).describe("the component's block tree"),
     props: z.array(componentPropObject).default([]).describe(
       "overridable fields. DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch: only the leaves a prop targets are click-to-edit. Each one may carry `ui` to say how its control presents in the inspector \u2014 a collapsed group, what titles and thumbnails a table's rows, whether that table's rows can be dragged at all. 'button' is ONE unit {label, href, variant?, size?, arrow?, icon?, newTab?} on a button block's 'props', never a text prop plus a url prop. 'link' an href, 'date' YYYY-MM-DD, 'color' a hex, 'file' {url, name?}, 'icon' an icon name or an image, 'multiselect' a string[] from config.options (required). " + SLOT_MULTIPLE_NOTE + " " + PROP_V2_NOTE
@@ -4132,6 +4135,7 @@ function buildToolDefs(deps) {
     description: z.string().optional(),
     preview: componentPreviewArg.optional(),
     icon: dockIconArg.nullable().optional().describe(PARAM_TEXT.componentIcon),
+    kitEntry: z.string().min(1).max(100).nullable().optional().describe(PARAM_TEXT.componentKitEntry),
     blockJson: z.array(blockObject).optional().describe("REPLACES the block tree"),
     props: z.array(componentPropObject).optional().describe(
       "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."
@@ -6252,10 +6256,12 @@ ${lines.join("\n")}`, found);
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const { component, replaced } = await client.extractComponent(args);
+          const res = await client.extractComponent(args);
+          const { component, replaced } = res;
+          const kit = res.kit;
           return ok(
-            `Created component '${component.name}' (id ${component.id}) and repointed ${replaced} sections to it. Page drafts changed; publish those pages to make it live.`,
-            { ...component, nextAction: DOCK_UI_NEXT }
+            `Created component '${component.name}' (id ${component.id}) and repointed ${replaced} sections to it. Page drafts changed; publish those pages to make it live.${kit?.line ? ` ${kit.line}: only a suggestion, so check its htmlSignals and pitfalls, then confirm or replace it with update_component { kitEntry }.` : ""}`,
+            { ...component, ...kit ? { kit } : {}, nextAction: DOCK_UI_NEXT }
           );
         })
       )
@@ -6264,18 +6270,20 @@ ${lines.join("\n")}`, found);
       name: "update_component",
       config: {
         title: "Update a reusable component",
-        description: "Update a component by id \u2014 blockJson, props, name, or category. Read with get_component, then pass `ifMatch` = the version from that read. Passing `blockJson`/`props` REPLACES them. This writes the DRAFT: call publish_component to push the change live. " + UNPROPPED_COPY_NOTE,
+        description: "Update a component by id \u2014 blockJson, props, name, or category. Read with get_component, then pass `ifMatch` = the version from that read. Passing `blockJson`/`props` REPLACES them. This writes the DRAFT: call publish_component to push the change live. " + KIT_ENTRY_REBUILD_NOTE + " " + UNPROPPED_COPY_NOTE,
         inputSchema: updateComponentInput.shape
       },
       handler: guard(
         async (args) => withClient(async (client) => {
           const { componentId, ifMatch, confirmed, ...input } = args;
-          const cmp = confirmed === true ? (await client.fetchJSON(client.url(`/management/components/${componentId}`), {
+          const res = confirmed === true || typeof input.kitEntry === "string" ? await client.fetchJSON(client.url(`/management/components/${componentId}`), {
             method: "PATCH",
             body: JSON.stringify(input),
-            headers: { ...ifMatch !== void 0 ? { "If-Match": `W/"${ifMatch}"` } : {}, ...confirmedHeaders(true) }
-          })).data : await client.updateComponent(componentId, input, { ifMatch });
-          return ok(`Updated component '${cmp.name}' (id ${cmp.id}).`, cmp);
+            headers: { ...ifMatch !== void 0 ? { "If-Match": `W/"${ifMatch}"` } : {}, ...confirmedHeaders(confirmed) }
+          }) : { data: await client.updateComponent(componentId, input, { ifMatch }), kitUiApplied: void 0 };
+          const cmp = res.data;
+          const rebuilt = res.kitUiApplied ? ` kitEntry set: rebuilt the derived ui of ${res.kitUiApplied.length} prop(s)${res.kitUiApplied.length ? ` (${res.kitUiApplied.join(", ")})` : ""}.` : "";
+          return ok(`Updated component '${cmp.name}' (id ${cmp.id}).${rebuilt}`, res.kitUiApplied ? { ...cmp, kitUiApplied: res.kitUiApplied } : cmp);
         })
       )
     },
@@ -6516,6 +6524,12 @@ DERIVED by \`editor_setup\`, where the componentize lane in \xA710 reuses every
                                               mcp notes and avoid its pitfalls (tag rules below).
                                               Its props carry NO target: give each one a target
                                               into YOUR blockJson (\xA73) before create_component
+                                              Every component names its kitEntry
+                                              (bettercms://kit/entry/{id}). The import's entry
+                                              is only a SUGGESTION: check its htmlSignals and
+                                              pitfalls, confirm or replace it (update_component
+                                              kitEntry rebuilds the derived ui); exempt with
+                                              no-kit-match only with a note
     Repeated visual region on a page?      -> a COMPONENT with sectionType (a Section)
       ...and it comes in more than one look? -> siblings sharing that sectionType = VARIANTS
     A stack of mixed, reorderable content? -> kind:'block' models + a \`modular\` field
@@ -7428,9 +7442,9 @@ delivered value \u2014 they change editor chrome only.
   "fields": [ { "key": "author", ... }, { "key": "avatar", "type": "image", ... }, ... ] }
 \`\`\`
 
-- **\`helpText\`** \u2014 the exception: most fields need none. Write it only when the author needs it to
+- **\`helpText\`** \u2014 the exception: most fields get none. Write it only when the author needs it to
   type the right value: a format or unit ("Price in cents."), a placement the canvas cannot show, a
-  real constraint, a fallback. Never restate the label ("The title field"), never coach ("Keep it short").
+  real constraint, a fallback. One plain sentence under 90 characters, no semicolons, no dashes, no values copied from the page. Never restate the label ("The title field"), never coach ("Keep it short").
 - **\`showIf\`** \u2014 hide a field until another has a value:
   \`{match:'all',rules:[{field:'link_type',op:'eq',value:'external'}]}\`. Rules name fields by
   BARE KEY, and the key namespace is FLAT across the model (\xA7 the duplicate-key rule), so the
@@ -7584,7 +7598,7 @@ An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`op
   schema: the same call with \`pageId\` instead of \`modelId\`, and the version from \`get_page\`'s
   \`backingModel\`.
 - A component's props: \`update_component\` with \`propUi\`, \`propGroup\`, \`propTab\`, \`propLabel\`, \`propHelpText\` (keyed by prop key).
-  Name props from the code (\`plan.cents\` \u2192 Cents); help text guides ("Whole number, no currency symbol."), never repeats
+  Name props from the code (\`plan.cents\` \u2192 Cents); help text only where a format, a hidden placement, a constraint or a fallback needs it ("Whole number, no currency symbol."), one plain sentence under 90 characters with no semicolons or dashes, never repeating
   the value; repeated cards are one \`table\` prop. An icon (\`config.media: "icon"\`) is content: group it, never prune it.
   They write the DRAFT props; no publish is needed for the editor to show them.
 - Always send \`ifMatch\`, the \`optimisticVersion\` you read.