@bettercms-ai/mcp 0.51.1 → 0.52.0

package/dist/index.js

@@ -1999,6 +1999,7 @@ import { DeviceAuthPendingError } from "@bettercms-ai/device-auth";
 // src/structure-playbook.ts
 var STRUCTURE_PLAYBOOK_URI = "bettercms://playbook/structure";
 var STRUCTURE_DEFAULT_INSTRUCTION = `After you create collections or pages, organise them per the structure playbook: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure (read-only), show the user its outline, then apply it with set_content_structure and the version it returned (the If-Match). A project that already has a structure keeps it: file only what you created, with move_to_folder, unless the user asks for a full re-organisation.`;
+var SKILLS_ROUTING_INSTRUCTION = "Before writing code in a repo that uses BetterCMS, read the installed `bettercms` skill if there is one: it explores the repo and names the one or two bettercms-* skills the task needs.";
 var STRUCTURE_EXAMPLE_PAYLOAD = {
   version: 0,
   doc: {
@@ -2921,6 +2922,15 @@ function buildToolDefs(deps) {
   const submitComponentizeReceiptInput = z.object({
     receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --componentize --receipt <file>` wrote, verbatim.")
   });
+  const componentValidationRouteInput = z.object({
+    componentId: z.string().min(1).describe("component id (from list_components)"),
+    path: z.string().min(1).max(500).optional().describe("route in the app that serves the preview; omit for the default"),
+    nativeViewports: z.array(z.object({
+      name: z.string().min(1).max(64),
+      width: z.number().int().positive().max(1e4),
+      height: z.number().int().positive().max(1e4)
+    })).min(1).max(8).optional().describe("viewports to check; omit for the defaults")
+  });
   const clearComponentSourceInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)")
   });
@@ -3433,7 +3443,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "submit_conversion_receipt",
         "Record what the conversion codemod could and could not do",
-        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message, fix }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. \u{1F534} A RECEIPT WITH PENDING PATHS IS A PROGRESS REPORT, NOT A FINISH LINE. The response answers `complete` and `pendingTotal`, and echoes the first 40 pending rows WITH their `fix` \u2014 `{ action, file, line, col?, snippet, why? }`, where `action` is one of `wrap-span` (wrap the literal in a `<span data-bcms-field=\u2026>`), `declare-attr` (add `data-bcms-field=\u2026` to the element at file:line), `bind-expression` (replace the expression with the framework's bcmsField helper), `declare-richtext` (bind the container with the richtext helper), `bind-data` (the literal comes from the data file at file:line \u2014 bind that field) or `manual` (with a one-sentence `why`). Apply every fix in the source, rerun the codemod, resubmit. `complete: true` is the only receipt that ends a conversion \u2014 do not report a site converted on anything less. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. \u{1F534} SUBMIT THE BINDING RECEIPT, NOT THE `--forms` ONE. A run of `npx @bettercms-ai/convert --forms` writes a receipt whose `paths` are all zero and whose account is in a `forms` block (`{ wired, alreadyWired, pending[{ id, name, reason }], notes }`); it passes this endpoint's arithmetic and would overwrite the real coverage with zeros. Write it to its own file (`--receipt forms-receipt.json`), read `forms.pending` and publish every form `forms.notes` names in the Forms tab, and submit the binding run's receipt here. Requires artifact:write, the same authority as set_binding_mode; on a workspace-wide connection pass `projectId`.",
+        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message, fix }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. \u{1F534} A RECEIPT WITH PENDING PATHS IS A PROGRESS REPORT, NOT A FINISH LINE. The response answers `complete` and `pendingTotal`, and echoes the first 40 pending rows WITH their `fix` \u2014 `{ action, file, line, col?, snippet, why? }`, where `action` is one of `wrap-span` (wrap the literal in a `<span data-bcms-field=\u2026>`), `declare-attr` (add `data-bcms-field=\u2026` to the element at file:line), `bind-expression` (replace the expression with the framework's bcmsField helper), `declare-richtext` (bind the container with the richtext helper), `bind-data` (the literal comes from the data file at file:line \u2014 bind that field) or `manual` (with a one-sentence `why`). Apply every fix in the source, rerun the codemod, resubmit. `complete: true` is the only receipt that ends a conversion \u2014 do not report a site converted on anything less. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. \u{1F534} SUBMIT THE `--forms` RECEIPT TOO, AS A SECOND CALL. A run of `npx @bettercms-ai/convert --forms` writes a receipt whose `paths` are all zero and whose account is in a `forms` block (`{ wired, alreadyWired, pending[{ id, name, reason }], notes, wiredForms[{ id, file }] }`). Write it to its own file (`--receipt forms-receipt.json`) and submit it here under the same `briefDigest`: it is stored BESIDE the binding receipt and never touches coverage, and the next release reads `wiredForms` to say which component renders each form. Then read `forms.pending` and publish every form `forms.notes` names in the Forms tab. Requires artifact:write, the same authority as set_binding_mode; on a workspace-wide connection pass `projectId`.",
         z.object({
           briefDigest: z.string().min(1).describe("The `briefDigest` get_conversion_brief { complete: true } returned. Must match the receipt's own."),
           receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --receipt out.json` wrote, verbatim.")
@@ -4247,7 +4257,7 @@ ${notes.join("\n")}` : summary, created);
       name: "publish_layout",
       config: {
         title: "Publish the Global Layout draft",
-        description: "Publish the connected project's GLOBAL Layout draft (navigation, footer, every reserved section) so the live site builds from it. Until this is called the layout stays draft and get_layout copy:'published' answers PUBLISHED_LAYOUT_UNAVAILABLE \u2014 site chrome authored with update_layout is NOT live. Read get_layout first and pass its revision as ifMatch; a stale revision returns 409 \u2014 re-read, never retry blindly. A 422 lists validation issues to fix with update_layout first. Verify with get_layout copy:'published' and check the copy echo \u2014 this tool's own response is the write's echo, not a receipt. Page overrides go live with the page (update_page status:'published'). A 403 PUBLISH_NOT_GRANTED means this connection can author drafts but cannot publish \u2014 say so and let the user allow publishing or publish from the dashboard.",
+        description: "Publish the connected project's GLOBAL Layout draft (navigation, footer, every reserved section) so the live site builds from it. Until this is called the layout stays draft and get_layout copy:'published' answers PUBLISHED_LAYOUT_UNAVAILABLE \u2014 site chrome authored with update_layout is NOT live. Read get_layout first and pass its revision as ifMatch; a stale revision returns 409 \u2014 re-read, never retry blindly. A 422 lists validation issues to fix with update_layout first. A new project's chrome is draft: publish_component navigation-default and footer-default first (each can publish while the other is draft), then publish_layout. navigation.logo is a REQUIRED image \u2014 new projects get a generated one; if it is empty (required_value) or not a stored asset (image_asset_missing), upload one and set it with update_layout as { id, url, name, altText }. Verify with get_layout copy:'published' and check the copy echo \u2014 this tool's own response is the write's echo, not a receipt. Page overrides go live with the page (update_page status:'published'). A 403 PUBLISH_NOT_GRANTED means this connection can author drafts but cannot publish \u2014 say so and let the user allow publishing or publish from the dashboard.",
         inputSchema: publishLayoutInput.shape
       },
       handler: guard(async (args) => withClient(async (client) => {
@@ -4548,6 +4558,56 @@ ${lines.join("\n")}`, found);
         })
       )
     },
+    {
+      name: "get_component_readiness",
+      config: {
+        title: "Read a component's Output validation readiness",
+        description: "Read what stands between a component and a validated Output: `validation.gap` and `validation.fix` say why a validation run cannot take it yet (COMPONENT_SOURCE_NOT_RECORDED: record its file with set_component_source, or place it and deploy a build whose markup carries its data-bcms-block / data-bcms-field attributes), and the readiness says where its request, evidence and approval stand. Call it after authoring a component and after every validation run. outputReady means the Output renders; publishReady also needs the owner's Visual Approval in the dashboard, which no tool can give.",
+        inputSchema: clearComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/readiness`)
+          );
+          return ok("Component validation readiness.", res.data);
+        })
+      )
+    },
+    {
+      name: "declare_component_route",
+      config: {
+        title: "Declare where a component's preview is served",
+        description: "Declare where this component's preview is served in the app (the dashboard's \"Show preview\"). Omit `path` to use the server's default route; pass `nativeViewports` only to check sizes other than the defaults. The origin is the project's preview URL and is never taken from you. Answers the readiness.",
+        inputSchema: componentValidationRouteInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/adapter`),
+            { method: "PUT", body: JSON.stringify({ path: args.path, nativeViewports: args.nativeViewports }) }
+          );
+          return ok("Preview route declared.", res.data);
+        })
+      )
+    },
+    {
+      name: "request_component_validation",
+      config: {
+        title: "Request Output validation for a component",
+        description: "Ask for this component's Output to be validated by YOU, the connected agent (provider user-agent). Record its source first (set_component_source, or the componentize codemod plus a deploy): a component nothing renders is refused with 422 and the fix, and no request is opened. After a 202, run `npx @bettercms-ai/preview-runtime validate --local --request <requestId>` in the app's repository with BCMS_API_KEY set in the environment (never pass a key in a tool call), then read get_component_readiness. Your evidence is self-attested: publishing still needs the owner's Visual Approval in the dashboard \u2014 never claim you approved it. CI validation (github-app) runs in the owner's repository at their cost, so it is refused here with VALIDATION_PROVIDER_DASHBOARD_ONLY: ask the owner to start it from the dashboard. 409 COMPONENT_ORCHESTRATION_V2_REQUIRED means continue in Agent Dock.",
+        inputSchema: clearComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/implementation-requests`),
+            { method: "POST", body: JSON.stringify({}) }
+          );
+          return ok("Validation requested. Run `npx @bettercms-ai/preview-runtime validate --local --request <requestId>` in the repository next.", res.data);
+        })
+      )
+    },
     {
       name: "publish_component",
       config: {
@@ -5240,8 +5300,9 @@ hand. THE ORDER, and every step of it matters:
    fallback, and declares each binding.
 2b. IF THE BRIEF CARRIES \`forms\`, wire them too:
    \`npx @bettercms-ai/convert --forms --brief brief.json --root . --receipt forms-receipt.json\`
-   \u2014 ITS OWN receipt file, because the forms receipt claims no path and submitting it would
-   overwrite the coverage the binding run just earned with zeros.
+   \u2014 ITS OWN receipt file, submitted with submit_conversion_receipt as a second call: the
+   server stores its \`forms\` block beside the binding receipt (coverage is untouched), and
+   the next release reads \`wiredForms\` to say which component renders each form.
    A site imported by phase 1 has a DRAFT form row per \`<form>\` in its build, so the Forms tab
    is full while the repository's markup still posts wherever it always did \u2014 to nothing, or to
    somebody else's endpoint. This pass writes the endpoint, the form id, a marker per field and
@@ -6182,7 +6243,7 @@ function buildServer(deps) {
       // one definition of done; without this an agent converts the page it landed on and stops.
       instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to bind its fields: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. When the user asks to componentize the whole site, to turn every section into a component, or to build a component library from the site: this is playbook \xA712. Read `bettercms://playbook/schema` \xA712, start with get_site_composition, and use the batch tools \u2014 create_components, compose_pages, update_layout with `commands`, publish_components \u2014 rather than one call per component. Finish with get_site_composition and tell the user what the platform does not model (cookie banners, modals, breadcrumbs, pagination) and which components still need the owner's approval in the dashboard before they can be published. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication. " + // The default after authoring (the structure standard): organise what you made. Same
       // sentence as the hosted connector's MCP_INSTRUCTIONS.
-      STRUCTURE_DEFAULT_INSTRUCTION
+      STRUCTURE_DEFAULT_INSTRUCTION + " " + SKILLS_ROUTING_INSTRUCTION
     }
   );
   server.registerResource(