@bettercms-ai/mcp 0.67.1 → 0.68.0

package/dist/index.js

@@ -2694,6 +2694,8 @@ 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 = {
+  helpText: "shown under the field: its purpose, where it shows, any constraint; never its label or value. Omitted: written for you.",
+  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",
   editorSetupForce: "re-run a setup already ready for the live build",
@@ -2962,9 +2964,7 @@ var fieldShape = {
   // builder. They were unreachable from MCP for ONE reason: the OutField/toField whitelist
   // below did not model them, so they were stripped after the model had gone to the trouble of
   // sending them. Declaring them here is what makes the existing panel agent-writable.
-  helpText: z.string().max(500).optional().describe(
-    "one line of guidance shown UNDER this field in the editor \u2014 what to write here, not what the field is. Write it for the person typing ('Roughly 60 characters; it becomes the browser tab title'), not for a developer."
-  ),
+  helpText: z.string().max(500).optional().describe(PARAM_TEXT.helpText),
   showIf: z.object({
     match: z.enum(["all", "any"]),
     rules: z.array(
@@ -3281,6 +3281,7 @@ var withProjectId = (def) => ({
     return currentProject.run(arg("projectId"), () => currentBranch.run(arg("branchId"), () => def.handler(args)));
   }
 });
+var autoHelpNote = (args) => typeof args.helpText === "string" && args.helpText.trim() ? "" : " No helpText was sent, so the platform wrote it (helpSource: auto); send helpText with update_field to write your own.";
 function buildToolDefs(deps) {
   async function withClient(fn) {
     const token = await deps.auth.getAccessToken();
@@ -3382,7 +3383,7 @@ function buildToolDefs(deps) {
   const createModelInput = z.object({
     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(),
+    description: z.string().optional().describe(PARAM_TEXT.describes),
     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."
@@ -3614,7 +3615,7 @@ function buildToolDefs(deps) {
     z.object({ type: z.literal("set-section-state"), ...sectionTarget, state: z.enum(["inherit", "override-content", "customize-structure", "disable", "reset"]) }),
     z.object({ type: z.literal("add-section"), name: z.string().min(1), icon: layoutIcon, zone: z.enum(["before_page", "after_page"]) }),
     z.object({ type: z.literal("restore-section"), section: z.object({ id: z.string().min(1) }).passthrough(), data: z.object({ fields: z.record(z.string(), z.unknown()) }), placement: z.object({ zone: z.enum(["above-page-content", "below-page-content"]), localOrderKey: z.string().min(1), afterSectionId: z.string().optional(), beforeSectionId: z.string().optional() }).optional() }),
-    z.object({ type: z.literal("update-section"), ...sectionTarget, name: z.string().min(1).optional(), icon: layoutIcon.optional(), slug: z.string().min(1).optional(), zone: z.enum(["above-page-content", "below-page-content"]).optional(), orderKey: z.string().min(1).optional() }),
+    z.object({ type: z.literal("update-section"), ...sectionTarget, name: z.string().min(1).optional(), icon: layoutIcon.optional(), slug: z.string().min(1).optional(), zone: z.enum(["above-page-content", "below-page-content"]).optional(), orderKey: z.string().min(1).optional(), description: z.string().optional() }),
     z.object({ type: z.literal("remove-section"), ...sectionTarget }),
     z.object({ type: z.literal("move-section"), ...sectionTarget, afterId: z.string().nullable().optional(), beforeId: z.string().nullable().optional() }),
     z.object({ type: z.literal("add-field"), ...sectionTarget, parentFieldId: z.string().optional(), fieldType: z.enum(["text", "longtext", "richtext", "number", "toggle", "date", "image", "file", "link", "email", "phone", "select", "color", "json", "reference", "multi-reference", "group", "repeater"]).optional(), field: z.object({ id: z.string(), slug: z.string(), label: z.string(), type: z.string() }).passthrough().optional() }),
@@ -3653,19 +3654,19 @@ 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 a sectionType are layout variants of one section."
+    "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."
   );
   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 createComponentInput = z.object({
     name: z.string().min(1),
     slug: slug.describe("url-safe unique slug (lowercase letters/numbers/hyphens)"),
     category: componentCategory.optional().describe("defaults to 'custom'"),
-    group: z.string().min(1).max(100).optional().describe("the folder editors see in the dashboard's Components tab, addressed by NAME (e.g. 'Sections', 'Navigation', 'Forms'). Resolved against this project's Groups and CREATED when missing, so a whole-site run can file everything without looking any id up first. Separate from `category`, which is the picker tab."),
+    group: z.string().min(1).max(100).optional().describe("the folder editors see in the dashboard's Components tab, by NAME (e.g. 'Sections', 'Forms'); CREATED when missing. Separate from `category`, the picker tab."),
     sectionType: sectionType.optional(),
     variantOf: z.string().min(1).max(255).optional().describe("id/slug of the component this is a VARIANT of: joins or starts its family (422 if its shared inputs are missing)"),
     projectId: z.string().nullable().optional().describe("owning project id; null creates a workspace-wide global component"),
     allowedOn: allowedOn.optional(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(PARAM_TEXT.describes),
     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."
@@ -5179,7 +5180,7 @@ ${notes.join("\n")}` : summary, created);
               body: JSON.stringify(input2),
               headers: confirmedHeaders(true)
             })).data : await client.addPageFields(args.pageId, input2);
-            return ok(`Added field '${args.key}' to page '${page.title}'. Page now has ${page.fields.length} field(s).`, page);
+            return ok(`Added field '${args.key}' to page '${page.title}'. Page now has ${page.fields.length} field(s).${autoHelpNote(args)}`, page);
           }
           const modelId = args.modelId;
           const model = await client.getModel(modelId);
@@ -5208,7 +5209,7 @@ ${notes.join("\n")}` : summary, created);
             headers: { ...opts ? { "If-Match": `W/"${opts.ifMatch}"` } : {}, ...confirmedHeaders(true) }
           })).data : opts ? await client.updateModel(modelId, input, opts) : await client.updateModel(modelId, input);
           return ok(
-            `Added field '${args.key}' to '${updated.name}'${args.after ? ` after '${args.after}'` : ""}. Model now has ${updated.fields.length} field(s).`,
+            `Added field '${args.key}' to '${updated.name}'${args.after ? ` after '${args.after}'` : ""}. Model now has ${updated.fields.length} field(s).${autoHelpNote(args)}`,
             updated
           );
         })
@@ -7031,7 +7032,13 @@ Do not stop at the plan or at a partial receipt \u2014 finish the whole site, ne
 8. \`get_binding_report\`: \`unmatched\` 0, \`unaddressable\` under 2% per route; fix the SOURCE, deploy, re-read (playbook \xA711).
 9. \`set_binding_mode { declaredBindings: true }\`, deploy AGAIN and poll, then confirm \`get_binding_report\`
    reads mode "declared", unmatched 0, bound above 0, \`coverage.pending\` empty. Send me that report.
-10. Ask me whether to commit and push to my repository, commit only, or leave it uncommitted (unpushed, the
+10. \`get_next_steps\`: if it lists \`upgrade-section-roots\` (section spacing and style handles), in the repo run
+   \`npx @bettercms-ai/convert@latest --upgrade-sections --root . --dry-run\`, read the plan, then run it for real. For every
+   root its receipt lists as \`skipped\`, pass the block down by hand: \`{...sectionRootAttrs(block)}\` on the section root, or
+   \`data-bcms-style=""\` plus \`style={...}\` from \`block.style\`. Run \`--verify-styles\` again and restore what it lists (the
+   marker and the inline style from \`block.style\` are allowed; changing a class or an existing style is not). Deploy,
+   poll, call \`get_next_steps\` again and tell me what it still lists. Not listed: say so and move on; invent no work.
+11. Ask me whether to commit and push to my repository, commit only, or leave it uncommitted (unpushed, the
    next rebuild from my repo drops it). Touch git only as I answer.`;
 var FIELD_UI_PROMPT = {
   title: "Declare how fields LOOK in the editor (guided)",