@bettercms-ai/mcp 0.21.0 → 0.22.1

package/dist/index.js

@@ -3784,6 +3784,7 @@ function registerTools(server, deps) {
 import { z as z2 } from "zod";
 
 // src/playbook.ts
+var PLAYBOOK_URI = "bettercms://playbook/schema";
 var SCHEMA_PLAYBOOK = `# Designing a BetterCMS project
 
 Read this BEFORE creating anything. Confirm the shape with the user before you build it.
@@ -3951,6 +3952,47 @@ is schema-first by design (\xA71) and should stay that way. Say so and move on.
 Either way: ask, do not choose. The 409 carries this project's actual page counts \u2014 how many
 are field-driven, block-driven, and how many place a reusable component \u2014 so quote those to
 the user rather than describing the choice in the abstract.
+
+## 11. The canvas: what makes an imported site EDITABLE
+
+A deploy makes a site LIVE. It does not make it editable \u2014 those are different states, and the
+gap between them is the single most common disappointment after an import.
+
+**The canvas is the real site when it can be.** When a page's draft matches its published copy
+structurally, the visual editor frames the project's OWN deployed build and paints unpublished
+text over it. Structural drafts (new sections, unpublished pages, changed components) render on
+the platform's own renderer instead \u2014 and that renderer previews in a GENERIC theme unless the
+deploy artifact declares \`bcms-presentation.json\` at its root. Put the file in \`public/\`
+(the build lands it at the artifact root) declaring the site's presentation \u2014 container width,
+type scale, nav position and background, footer surface \u2014 as DTCG \`{"$type": ..., "$value": ...}\`
+entries. Redeclare it on every deploy; absent means "declared nothing" and previews fall back
+to platform defaults that will not look like this site.
+
+**Editing binds by VALUE.** The editor matches CMS field values against the text the site
+renders. Three consequences, each load-bearing:
+
+    1. Content that exists ONLY in the build can never be click-to-edit. Bring it in, per
+       route, in this order (get_next_steps reports the state until it is done):
+
+         a. create_page            one per route, slug matching the route
+         b. add_page_field         the fields its content needs (or create_component +
+                                   publish_component + component blocks, per your \xA710 answer)
+         c. set_page_content       values EXACTLY equal to the text the site renders \u2014
+                                   binding matches by value, so a paraphrase binds nothing
+         d. update_page            status 'published' \u2014 the canvas binds the PUBLISHED copy
+    2. A value that renders in more than one place stays uneditable on the canvas (deliberate:
+       binding it would edit all of them at once). It remains editable in the side panel.
+    3. Keep chrome semantic \u2014 \`<nav>\`, \`<footer>\`, page content inside \`<main>\`, mastheads
+       as a top-level \`<header>\`. Chrome is edited through the project Layout, not the page,
+       and semantic landmarks are how the editor keeps a nav edit from being written into page
+       content. Div-built chrome outside \`<main>\` is still excluded; div-built chrome with no
+       \`<main>\` anywhere loses that protection.
+
+**Hosting decides whether a canvas exists at all.** A site deployed here is framed through a
+same-origin proxy \u2014 that is what the canvas requires. A site hosted elsewhere (your own Vercel,
+your own server) has NO canvas today: the SDK's draft mode with \`stega: true\` embeds invisible
+per-field provenance in fetched strings, which prepares the content for editing surfaces, but do
+not promise a canvas for an externally-hosted site.
 `;
 
 // src/prompts.ts
@@ -4344,6 +4386,44 @@ On 401/403, the MCP key needs (re)authorizing.`
 
 ${SEO_FLOW}
 
+On 401/403, the MCP key needs (re)authorizing.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "import-site",
+    {
+      title: "Make an imported site editable (guided)",
+      description: "After deploying an existing site: bring its content into the CMS so the visual editor can bind it, declare its presentation manifest, and publish everything that renders. A deploy makes a site LIVE, not EDITABLE \u2014 this flow closes that gap.",
+      argsSchema: {
+        request: z2.string().optional().describe("scope, e.g. 'all routes' or 'just the home page'")
+      }
+    },
+    ({ request }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Make my imported site editable in BetterCMS.${request ? ` Scope: "${request}".` : ""}
+
+Read bettercms://playbook/schema section 11 first, then work this order:
+
+1. AUTHORING GATE \u2014 if any deploy answered 409 AUTHORING_DECISION_REQUIRED, ask ME
+   components-or-fields (do not choose), then set_authoring_preference.
+2. CONTENT INTO THE CMS, per route: create_page (slug = route) -> add_page_field (or
+   create_component + publish_component + component blocks) -> set_page_content with values
+   EXACTLY equal to the rendered text (binding matches by value; a paraphrase binds nothing)
+   -> update_page status 'published' (the canvas binds the PUBLISHED copy).
+3. PRESENTATION MANIFEST \u2014 add bcms-presentation.json to public/ (container width, type
+   scale, nav position/background, footer surface as DTCG {"$type","$value"} entries) and
+   redeploy, or structural draft previews render in a generic theme, not this site's design.
+4. VERIFY \u2014 call get_next_steps and fix what it lists (it knows about missing manifests,
+   content still only in the build, and placed-but-unpublished components), or tell me why
+   an item is being left.
+
 On 401/403, the MCP key needs (re)authorizing.`
           }
         }
@@ -4366,7 +4446,19 @@ var SERVER_DISPLAY = {
 function buildServer(deps) {
   const server = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION, ...SERVER_DISPLAY },
-    { capabilities: { tools: {}, prompts: {} } }
+    { capabilities: { tools: {}, prompts: {}, resources: {} } }
+  );
+  server.registerResource(
+    "schema-playbook",
+    PLAYBOOK_URI,
+    {
+      title: "BetterCMS schema & components playbook",
+      description: "How to design a components-first BetterCMS project: components vs collections, section anatomy, sectionType variants, kind:'block' + modular fields, the 'document' article body, the draft->publish order, and what makes an imported site editable.",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [{ uri: PLAYBOOK_URI, mimeType: "text/markdown", text: SCHEMA_PLAYBOOK }]
+    })
   );
   registerTools(server, {
     auth: deps.auth,