@bettercms-ai/mcp 0.67.3 → 0.68.1

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
           );
         })
@@ -6711,6 +6712,11 @@ conversion is yours to write.
 5. Codemod the templates. Read each value from the CMS (\`@bettercms-ai/astro\` /
    \`@bettercms-ai/next\` client, or the \`bcms-content.json\` build snapshot), KEEP the in-code
    copy as the fallback, and declare the binding on the element that already renders it.
+   Read the snapshot ONLY through a supported reader: the helper \`npx @bettercms-ai/convert\`
+   writes (\`bcms\`, \`bcmsRows\`, \`bcmsImage\`) or \`publishedEntry(slug)\` from
+   \`@bettercms-ai/sdk\`. Never hand-write a parser of the file: a row holds its values under
+   \`data\`, so \`row.title\` is undefined and the page renders its fallback on every publish. An
+   editable image is \`bcmsImage(page, path, importedImage)\`, never the bare import with a stamp.
    Prefer schema-derived bindings \u2014 the TypeGen analogue:
    \`npx @bettercms-ai/codegen --bindings-out src/bettercms.bindings.generated.ts\`, then spread
    \`{...bcms.home.hero.title}\` / \`{...bcms.blog.features.$(i)}\`. The hand form is
@@ -6745,7 +6751,7 @@ conversion is yours to write.
       \`bcms-content.json\` into the repo root before \`build\`, with a key it mints per build: no
       repo secret feeds it. (The secret a connect sets, \`BCMS_API_KEY_<RUNG>\` such as
       \`BCMS_API_KEY_PROD\`, is the validation workflows' key; they fall back to the shared
-      \`BCMS_API_KEY\` only for a repo whose last connect predates it.) Read that file, with in-code
+      \`BCMS_API_KEY\` only for a repo whose last connect predates it.) Read that file (step 5's readers), with in-code
       fallbacks so a local or CI build without it still renders.
     - ARCHIVE (\`deploy_project\`, inline or by \`uploadKey\`): the sandbox build runs with no env
       and no network content step, by design. So the archive MUST SHIP its own