@bettercms-ai/mcp 0.85.0 → 0.87.0

package/dist/index.js

@@ -2988,6 +2988,10 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   // Reporting, history and workflow chrome.
   "get_analytics_overview",
   "get_analytics_top_pages",
+  "get_analytics_top_referrers",
+  "get_analytics_breakdown",
+  "get_conversions",
+  "get_ai_traffic",
   "list_activity",
   "get_workflow_board",
   "move_stage",
@@ -3112,7 +3116,9 @@ var WEBHOOK_EVENTS = [
   "content.created",
   "content.updated",
   "content.deleted",
-  "deployment.triggered"
+  "deployment.triggered",
+  "branch.created",
+  "branch.applied"
 ];
 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.",
@@ -3126,12 +3132,12 @@ var NEW_TOOL_TEXT = {
   create_webhook: "Create an outgoing webhook: BetterCMS POSTs each subscribed event to your https `url`, signed with HMAC-SHA256 in X-BetterCMS-Signature. The response carries the signing `secret` ONCE: store it now. `test: true` also sends a sample delivery. Payloads carry ids and metadata, never the content: fetch it from the API. A receiver that writes back on content.updated loops unless it skips its own writes.",
   list_branches: "List the project's content branches (id, name, slug, parent, status, whether main) and the `currentBranchId` this connection is on. To work inside a branch, pass its id as `branchId` on any tool call; apply_branch merges it into its parent.",
   create_branch: "Create a content branch: a copy of the project's content to edit without touching the live site. Returns the branch; pass its id as `branchId` on later calls to work in it, then apply_branch. 409 means the name or slug is taken.",
-  apply_branch: "Merge a branch into its parent. dryRun: true returns the diff (changes, summary, conflicts) and writes nothing: ALWAYS read it and show the user first. `include` limits the merge to those change keys; `fields` resolves a conflicting field per change key ('keep_branch' or 'keep_parent'). 409 names unresolved conflicts, missing dependencies, or a merge already running.",
+  apply_branch: "Merge a branch into its parent. dryRun: true returns the diff (changes, summary, conflicts) and writes nothing: ALWAYS read it and show the user first. `include` limits the merge to those change keys; `fields` resolves a conflicting field per change key ('keep_branch' or 'keep_parent'). `publish: true` takes the merged changes live in the same call; `scheduleAt` merges everything and publishes at that time instead (null cancels). Both need a branch made from main and a connection allowed to publish. 409 names unresolved conflicts, missing dependencies, or a merge already running.",
   search_docs: "Search the BetterCMS documentation. Returns the best pages (title, url, breadcrumbs, snippet). Use it before guessing how a feature works; `meta.unavailable` means docs search is down right now.",
   generate_image: "Generate an image with AI and add it to the Media Library (5 AI credits; free with the workspace's own Together key). `width`/`height` are 256-1440 in multiples of 16 (default 1024x768). Returns the new asset (id, url, altText): use the url as an 'image' field value. Always set `altText`.",
   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: derives pages, collections, forms, bindings and components from the live release (skill bindings). 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`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
+  editor_setup: "Make the live build editable: derives pages, collections, forms, bindings and components from the live release (skill bindings). Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` if already run for the live sha, else starts (`running`; poll with `check: true`). `state`: never or stale (run it), running, ready, failed. 409: deploy first. Then get_next_steps. `setup.naming`: skill editor-chrome.",
   get_editable_plan: "Choices the platform can't make alone: `rows`, `options`, `recommended`. Explore the site per row: if confident, answer via confirm_editable_plan and tell the owner; if unsure, ask the owner in chat, recommended first. Never finish with an unsure one unasked.",
   confirm_editable_plan: "Record answers: each `decisions` item is an option's `decision`, unchanged. `check: true` = dry run.",
   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).",
@@ -3149,11 +3155,11 @@ var NEW_TOOL_TEXT = {
   install_integration_template: "Install a workspace template on this project: missing collections are created and the integration waits for approval (`approval.approveUrl`); `secretsNeeded` lists the env vars to set.",
   test_integration_fetch: "Call the vendor once through the server, as the integration: an approved host only, with the integration's `inject` secrets added server-side and every secret redacted from the answer. The request itself takes no {{...}} templates, and the token endpoint cannot be called. Use it to read the response shape before writing a sync: `items`, `externalKey` and `map` are JSON Pointers into it. Bodies over 1 MB come back truncated. 409 integration_not_approved: an admin must approve it first.",
   // CMS-stored custom dock UI: write → approve (the user's yes) → validate → publish. Recipe: skill dock-input.
-  write_dock_ui: "Save a custom dock input or panel (one .tsx `source`) as a new DRAFT version of `name` (a letter, then [a-z0-9-], \u226448), what `cms:<name>` imports resolve. Imports: react, react-dom, @bettercms-ai/kit/*, @bettercms-ai/dock-input, cms:<name>. Same bytes write nothing. Skill dock-input",
+  write_dock_ui: "Save a custom dock input or panel (one .tsx `source`) as a new DRAFT version of `name` (a letter, then [a-z0-9-], \u226448), what `cms:<name>` imports resolve. Imports: react, react-dom, @bettercms-ai/kit/*, @bettercms-ai/dock-input, cms:<name>. Skill dock-input",
   approve_dock_ui: "Approve the newest `version` for publishing. Show the user the source first; userApproved: true only after their yes. A later write drops it",
-  validate_dock_ui: "Check one version (default newest) without publishing: allowed imports, size caps, a name the repo also has. Answers the build receipt",
-  publish_dock_ui: "Publish an APPROVED version (default newest): validates first, refusing policy.not_approved, build.name_conflict or the build's refusals, then rebuilds the project's dock UI release",
-  list_dock_ui: "The project's dock UI sources, with usage against the limits",
+  validate_dock_ui: "Check one version (default newest) without publishing: imports, size caps, a name the repo also has. Answers the build receipt",
+  publish_dock_ui: "Publish an APPROVED version (default newest); rebuilds the dock UI release. `notShown`: published, not drawn, and the fix to tell the user",
+  list_dock_ui: "The project's dock UI sources (`notShown` when not drawn), usage, limits",
   // A V2 TypeSchema into a model (lane fields, through a change set) or a component's props (lane props).
   write_schema: "Write a kit V2 TypeSchema into a model (lane fields, as a change set; model: null creates) or a component's props (lane props). Run dryRun first: a write whose `loss` is not all in acceptLoss is refused schema.loss_not_accepted"
 };
@@ -3180,6 +3186,7 @@ var PARAM_TEXT = {
   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",
+  componentDock: "propOrder: each top-level prop key once; tabs 'none': no tab strip; design 'fold': Design under the content, 'tab': own tab; null resets",
   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",
@@ -3207,9 +3214,10 @@ var PARAM_TEXT = {
   focalX: "focal point, 0-1 across from the left edge; null resets to the centre",
   focalY: "focal point, 0-1 down from the top edge; null resets to the centre",
   mergeHref: "pageId only: the link field paired with `path` (the label). Both become ONE `button` field keyed `key` (default: their stem, primaryCtaHref \u2192 primaryCta). Each entry's DRAFT gets {label, href} and keeps the old values; the live copy changes on publish. ifMatch is the page's version. 409 CODE_RENDERED_ROUTE: do its `next` recipe in code",
-  confirmedInput: "true only after the user explicitly approved adding this custom input (`ui.input`); else setting or changing one is refused input_needs_confirmation. Removing one needs no approval",
+  confirmedInput: "true only after the user explicitly approved adding this custom input (`ui.input`), or a hide/fold/required\u2192optional (else a named 409). Removing one needs no approval",
   dockUiUserApproved: "true only after the user said yes to this version",
   dockUiTarget: "per scope: field {modelId|pageId|componentId, path}, section {componentId}, page {pageId}, layout {}",
+  dockUiAction: "unpublish: off the dock; delete: an unpublished source",
   writeSchemaModel: "model or component id/slug; null creates a model",
   writeSchemaAcceptLoss: "loss keys or paths you accept",
   writeSchemaIfMatch: "the dry run's `version`; needed to write over a stored row"
@@ -3848,7 +3856,7 @@ var UPDATE_MODEL_DESCRIPTION = "Edit a content model: rename it, change descript
 var FIELD_REMOVAL_NOTE = "top-level field keys (from get_content_model) to DELETE from this model with every entry's value for them; needs allowFieldRemoval: true. An unknown key refuses the whole call. Never for a rename: rename the label instead.";
 var ALLOW_FIELD_REMOVAL_NOTE = "true = the user accepts that removeFields discards those fields' data in every entry. There is no dry run on this route: confirm first.";
 var MODEL_IF_MATCH_NOTE = "optimisticVersion from get_content_model (with pageId: get_page backingModel). The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply, never retry blindly. REQUIRED with field*, override or a fieldset kind/tab/icon/collapsed (428 without); otherwise, omitted, the last write wins.";
-var COMPONENT_IF_MATCH_NOTE = "optimisticVersion from get_component. The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply. REQUIRED with prop*, override or a prop ui icon/itemLabel/group/tab (428 without).";
+var COMPONENT_IF_MATCH_NOTE = "optimisticVersion from get_component. The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply. REQUIRED with prop*, dock, override or a prop ui icon/itemLabel/group/tab (428 without).";
 var PROP_UI_ARG_NOTE = "top-level prop key \u2192 ui patch, the same vocabulary as a prop's `ui` (group and tab included): each key merges, a null key clears it, null clears the whole ui. Patches keep every other prop as stored; sending `props` instead REPLACES the whole array, so echo each prop's stored `ui` (its `ui.group` AND `ui.tab`) or the prop leaves its tab";
 var OVERRIDE_NOTE = "replace chrome a person set (otherwise 409 ui_human_owned names those paths). Send it only on the user's word.";
 var FIELD_UI_ARG_NOTE = "path \u2192 ui patch, a field's `ui` vocabulary: each key merges, a null key clears it, null clears the whole ui";
@@ -4476,7 +4484,8 @@ function buildToolDefs(deps) {
     propHelpText: z.record(z.string(), z.string().max(200).nullable()).optional().describe("prop key \u2192 help text; null = no help on purpose (stays empty, never refilled)"),
     override: z.boolean().optional().describe(OVERRIDE_NOTE),
     ifMatch: z.number().int().min(0).optional().describe(COMPONENT_IF_MATCH_NOTE),
-    confirmed: z.boolean().optional().describe(PARAM_TEXT.confirmedInput)
+    confirmed: z.boolean().optional().describe(PARAM_TEXT.confirmedInput),
+    dock: z.object({ propOrder: z.array(z.string().min(1)).optional(), tabs: z.enum(["none"]).nullable().optional(), design: z.enum(["tab", "fold"]).nullable().optional() }).strict().optional().describe(PARAM_TEXT.componentDock)
   });
   const setComponentSourceInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)"),
@@ -4852,8 +4861,13 @@ ${d.outline}` : "Proposed Content structure.", d);
         "publish_dock_ui",
         "Publish custom dock UI",
         NEW_TOOL_TEXT.publish_dock_ui,
-        z.object({ name: dockUiName, version: z.number().int().min(1).optional() }).shape,
-        async (c, a) => ok("Published the dock UI version.", await data(c, "POST", `/management/dock-ui/${encodeURIComponent(s(a.name))}/publish`, { version: a.version }))
+        z.object({ name: dockUiName, version: z.number().int().min(1).optional(), action: z.enum(["unpublish", "delete"]).optional().describe(PARAM_TEXT.dockUiAction) }).shape,
+        async (c, a) => {
+          const at = `/management/dock-ui/${encodeURIComponent(s(a.name))}`;
+          if (a.action === "unpublish") return ok("Unpublished the dock UI source.", await data(c, "POST", `${at}/unpublish`, {}));
+          if (a.action === "delete") return ok("Deleted the dock UI source.", await data(c, "DELETE", at));
+          return ok("Published the dock UI version.", await data(c, "POST", `${at}/publish`, { version: a.version }));
+        }
       ),
       def(
         "list_dock_ui",
@@ -5690,9 +5704,11 @@ ${d.outline}` : "Proposed Content structure.", d);
           branchId: z.string().min(1).describe("the branch to merge (from list_branches)"),
           dryRun: z.boolean().optional().describe("true = return the diff and write nothing"),
           include: z.array(z.string().min(1)).max(500).optional().describe("change keys to merge (from the diff); all when omitted"),
-          fields: z.record(z.string(), z.record(z.string(), z.enum(["keep_branch", "keep_parent"]))).optional().describe("change key \u2192 field \u2192 'keep_branch' | 'keep_parent', for each conflict")
+          fields: z.record(z.string(), z.record(z.string(), z.enum(["keep_branch", "keep_parent"]))).optional().describe("change key \u2192 field \u2192 'keep_branch' | 'keep_parent', for each conflict"),
+          publish: z.boolean().optional().describe("true = also take the merged changes live, in the same call (a branch made from main)"),
+          scheduleAt: z.string().datetime({ offset: true }).nullable().optional().describe("ISO time to merge everything and publish then, instead of now; null cancels a schedule")
         }).shape,
-        async (c, a) => a.dryRun === true ? ok("Branch diff (nothing was written).", await data(c, "GET", `/management/branches/${s(a.branchId)}/diff`)) : ok("Branch applied.", await c.fetchJSON(c.url(`/management/branches/${s(a.branchId)}/apply`), { method: "POST", body: JSON.stringify({ include: a.include, fields: a.fields }) }))
+        async (c, a) => a.dryRun === true ? ok("Branch diff (nothing was written).", await data(c, "GET", `/management/branches/${s(a.branchId)}/diff`)) : a.scheduleAt !== void 0 ? ok(a.scheduleAt ? "Branch scheduled." : "Branch unscheduled.", await data(c, "PUT", `/management/branches/${s(a.branchId)}/schedule`, { at: a.scheduleAt })) : ok(a.publish ? "Branch applied and published." : "Branch applied.", await c.fetchJSON(c.url(`/management/branches/${s(a.branchId)}/apply`), { method: "POST", body: JSON.stringify({ include: a.include, fields: a.fields, publish: a.publish }) }))
       ),
       def(
         "search_docs",
@@ -5817,9 +5833,9 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "get_analytics_overview",
         "Get traffic overview",
-        "Traffic totals and the daily series for the connected project \u2014 views, unique visitors, bytes, sessions and bounces. Defaults to the last 30 days; pass `from`/`to` as YYYY-MM-DD.",
-        z.object({ from: z.string().optional(), to: z.string().optional() }).shape,
-        async (c, a) => ok("Analytics overview.", await data(c, "GET", `/management/insights/analytics/overview${q({ from: a.from, to: a.to })}`))
+        'Traffic totals and the daily series for the connected project: views, unique visitors, bytes, sessions, bounces and responses by status class. Defaults to the last 30 days; pass `from`/`to` as YYYY-MM-DD, and `compare: "previous"` for the previous period\'s totals beside them.',
+        z.object({ from: z.string().optional(), to: z.string().optional(), compare: z.enum(["previous"]).optional() }).shape,
+        async (c, a) => ok("Analytics overview.", await data(c, "GET", `/management/insights/analytics/overview${q({ from: a.from, to: a.to, compare: a.compare })}`))
       ),
       def(
         "get_analytics_top_pages",
@@ -5828,6 +5844,34 @@ ${d.outline}` : "Proposed Content structure.", d);
         z.object({ from: z.string().optional(), to: z.string().optional(), limit: z.number().optional() }).shape,
         async (c, a) => ok("Top pages.", await data(c, "GET", `/management/insights/analytics/top-pages${q({ from: a.from, to: a.to, limit: a.limit })}`))
       ),
+      def(
+        "get_analytics_top_referrers",
+        "Get top referrers",
+        "Traffic sources: the referrer hosts sending visitors, by views. Defaults to the last 30 days; pass `from`/`to` (YYYY-MM-DD) and `limit`.",
+        z.object({ from: z.string().optional(), to: z.string().optional(), limit: z.number().optional() }).shape,
+        async (c, a) => ok("Top referrers.", await data(c, "GET", `/management/insights/analytics/top-referrers${q({ from: a.from, to: a.to, limit: a.limit })}`))
+      ),
+      def(
+        "get_analytics_breakdown",
+        "Get traffic breakdown",
+        "Views and visitors by one dimension: `country` (ISO code), `device` (desktop, mobile, tablet), `browser` or `crawler` (the bots that fetched the site). Defaults to the last 30 days; pass `from`/`to` (YYYY-MM-DD) and `limit`.",
+        z.object({ dim: z.enum(["country", "device", "browser", "crawler"]), from: z.string().optional(), to: z.string().optional(), limit: z.number().optional() }).shape,
+        async (c, a) => ok("Traffic breakdown.", await data(c, "GET", `/management/insights/analytics/breakdown${q({ dim: a.dim, from: a.from, to: a.to, limit: a.limit })}`))
+      ),
+      def(
+        "get_conversions",
+        "Get conversions",
+        "Conversions: form submissions (the one goal a site measures) per form over the last `days` days (default 30, max 90), with last-7 vs previous-7, all-time spam, the pages each form is on, and the site's conversion rate (submissions per 100 page views). `degraded: true` means the submissions store didn't answer, so the counts are not measurements and the rate is null.",
+        z.object({ days: z.number().int().min(1).max(90).optional() }).shape,
+        async (c, a) => ok("Conversions.", await data(c, "GET", `/management/insights/analytics/conversions${q({ days: a.days })}`))
+      ),
+      def(
+        "get_ai_traffic",
+        "Get AI traffic",
+        "AI traffic: crawler visits for AI products (GPTBot, ClaudeBot\u2026, beside search crawlers) and visitors referred by answer engines (ChatGPT, Perplexity\u2026), with totals. Pro plan and above. Defaults to the last 30 days; pass `from`/`to` (YYYY-MM-DD).",
+        z.object({ from: z.string().optional(), to: z.string().optional() }).shape,
+        async (c, a) => ok("AI traffic.", await data(c, "GET", `/management/insights/analytics/ai-traffic${q({ from: a.from, to: a.to })}`))
+      ),
       def(
         "list_seo_issues",
         "List SEO issues",
@@ -6840,8 +6884,14 @@ ${lines.join("\n")}`, found);
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const { componentId, ifMatch, confirmed, ...input } = args;
-          const res = confirmed === true || typeof input.kitEntry === "string" ? await client.fetchJSON(client.url(`/management/components/${componentId}`), {
+          const { componentId, ifMatch, confirmed, dock, ...rest } = args;
+          const input = {
+            ...rest,
+            ...dock?.propOrder !== void 0 ? { propOrder: dock.propOrder } : {},
+            ...dock?.tabs !== void 0 ? { dockTabs: dock.tabs } : {},
+            ...dock?.design !== void 0 ? { dockDesign: dock.design } : {}
+          };
+          const res = confirmed === true || typeof input.kitEntry === "string" || dock !== void 0 ? await client.fetchJSON(client.url(`/management/components/${componentId}`), {
             method: "PATCH",
             body: JSON.stringify(input),
             headers: { ...ifMatch !== void 0 ? { "If-Match": `W/"${ifMatch}"` } : {}, ...confirmedHeaders(confirmed) }