@bettercms-ai/mcp 0.84.1 → 0.84.3

package/README.md

@@ -1,25 +1,20 @@
 # @bettercms-ai/mcp
 
-BetterCMS [Model Context Protocol](https://modelcontextprotocol.io) server. Lets an
-AI assistant author your content schema and entries through the BetterCMS Management
-API, authenticated with a short-lived, per-project `content:manage` key minted via
-the OAuth 2.0 Device Authorization Grant (RFC 8628) — no pasted long-lived key.
+BetterCMS [Model Context Protocol](https://modelcontextprotocol.io) server, as a local stdio
+process. It signs in with the OAuth 2.0 Device Authorization Grant (RFC 8628): no pasted
+long-lived key.
 
-## Tools
-
-| Tool | Description |
-|------|-------------|
-| `create_model` | Create a content model (schema) with optional initial fields. |
-| `add_field` | Append a field to an existing model (read-modify-write; never removes fields). |
-| `create_entry` | Create a content entry; applies `data`/`status` via a follow-up update. |
-| `create_form` / `update_form` | Author a form (fields + settings) to embed with `<BcmsForm>`. |
-| `create_component` / `update_component` | Author a reusable component (blockJson tree + props) to render with `<BcmsBlocks>`. |
-| `list_forms` / `get_form` / `list_components` / `get_component` | Discover forms & components to wire into site code. |
+> Most people should use the **hosted** server instead: add `https://mcp.bettercms.ai/mcp` to
+> your client, or run `npx @bettercms-ai/install --mcp`. This package exposes the same tools
+> for clients that only speak stdio. Setup per client and the full tool reference:
+> https://bettercms.ai/docs/ai/connect-mcp and https://bettercms.ai/docs/ai/mcp-tools
 
-See [SKILL.md](./SKILL.md) for how an AI agent should author pages, forms, and components.
+## Tools
 
-All operations are **additive** — there are no destructive tools. Deleting models,
-fields, or entries is dashboard-only by design.
+The same tool set as the hosted server: pages and sections, content models and fields, entries,
+components, media, forms, SEO, publishing and deploys, and more. Writes stay drafts unless you
+allowed publishing when you approved the client. Agents learn the order of work from the
+`bettercms` skill (`npx @bettercms-ai/install`).
 
 ## Usage
 
@@ -30,28 +25,12 @@ Add to your MCP client config (e.g. Claude Desktop / Claude Code):
   "mcpServers": {
     "bettercms": {
       "command": "npx",
-      "args": ["-y", "@bettercms-ai/mcp"],
-      "env": { "BETTERCMS_API_URL": "https://api.bettercms.ai" }
+      "args": ["-y", "@bettercms-ai/mcp"]
     }
   }
 }
 ```
 
-### Registry auth (current)
-
-This package is published to **GitHub Packages**, which requires authentication
-**even for public scoped packages**. For `npx @bettercms-ai/mcp` to resolve, the
-host machine needs an `~/.npmrc` with:
-
-```
-@bettercms-ai:registry=https://npm.pkg.github.com/
-//npm.pkg.github.com/:_authToken=<a GitHub PAT with read:packages>
-```
-
-> **TODO (future):** publish `@bettercms-ai/mcp` (and `types`/`sdk`) to the public
-> **npmjs.org** registry so `npx @bettercms-ai/mcp` works with zero `.npmrc` setup
-> for any host/user. Until then the GitHub Packages auth above is required.
-
 On the first tool call the server prints an authorization prompt to **stderr**
 (visible in your MCP client's logs):
 

package/dist/index.js

@@ -3488,7 +3488,7 @@ var fieldShape = {
     "choices when type is 'select'. A plain string, or {label, value, icon?, description?} when the stored value differs from what the editor shows (e.g. {label:'Sold out', value:'soldOut'}); icon a dock name, description one line \u2264140."
   ),
   config: z.record(z.string(), z.unknown()).optional().describe(
-    "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, repeater {minItems, maxItems} (the list's item limits; the editor shows 'max N' and stops Add there), array {itemType: text|number|date|image|link|richtext}, date {includeTime, timezone}, modular|slot {blockSlugs: ['quote','gallery'], minItems?, maxItems?} (slot: playbook \xA75) \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph; limits: text/longtext {minLength,maxLength,pattern,patternMessage}, richtext {minLength,maxLength}, number {validation:{min,max}}, array {minItems,maxItems}, tags {min,max}, rating {min,max,step}. Undocumented keys open the classic editor."
+    "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, repeater {minItems, maxItems} (the list's item limits; the editor shows 'max N' and stops Add there), array {itemType: text|number|date|image|link|richtext}, date {includeTime, timezone}, modular|slot {blockSlugs: ['quote','gallery'], minItems?, maxItems?} (slot: playbook \xA75) \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph; richtext article blocks and references {posts?, authors?}: playbook/schema \xA75c; limits: text/longtext {minLength,maxLength,pattern,patternMessage}, richtext {minLength,maxLength}, number {validation:{min,max}}, array {minItems,maxItems}, tags {min,max}, rating {min,max,step}. Undocumented keys open the classic editor."
   ),
   fields: z.array(z.lazy(() => fieldObject)).optional().describe(
     "NESTED child fields \u2014 REQUIRED for type 'group' (one nested object, a Non-Repeatable Zone like blog_hero \u2192 heading, description, hero_image) and type 'repeater' (a repeatable array of such objects, a Repeatable Zone / section-list like testimonials \u2192 quote, author). A section with repeating items is a 'repeater'; a fixed grouped block is a 'group'. Recurse to any depth \u2014 do NOT flatten zones into separate top-level fields."
@@ -7093,6 +7093,49 @@ The one legitimate exception is a field that is genuinely CONTENT and happens to
 too \u2014 a blog post's \`excerpt\`, an article's \`coverImage\`. Model those as content, name them
 for what they are, and let \`generate_seo_meta\` read them.
 
+## 5c. Rich-text article blocks (V2)
+
+A \`richtext\` or \`document\` value (Portable Text) holds V2's article blocks as types of its own. A
+field's \`config.features\` gates each one, and a new field accepts them all; a block outside its
+field's features is refused \`richtext.block_not_accepted:<type>\`, never stripped. Store ONLY these
+shapes:
+
+    feature          stored node
+    button           a \`link\` markDef with \`button: true\`
+    embed            {_type:'embed', url, title (\u2264120), aspect: '16:9'|'4:3'|'1:1'|'9:16'}
+    gallery          {_type:'gallery', layout: 'grid'|'carousel', images: [{_key, image: {src, alt,
+                     mediaId?, crop?, focal?} | null, caption? (\u2264160)}]}, at most 24 images
+    tableOfContents  {_type:'tableOfContents', title? (\u226440), depth: '2'|'3'}
+    footnotes        INLINE {_type:'footnote', _key, note} in a body text block's children
+                     (never in a table cell or a column)
+    columns          {_type:'columns', gap: 's'|'m'|'l', columns: [{_key, content: [text blocks]}]},
+                     2 to 4, text blocks only (no block, no columns, no footnote inside)
+    authorBio        {_type:'authorBio', author?: {_ref}}
+    relatedPosts     {_type:'relatedPosts', title? (\u226440), mode: 'topic'|'newest'|'manual',
+                     count: 1-6, posts?: [{_key, _ref}] (hand-picked, at most 6, unique)}
+
+\`crop\` ({top, right, bottom, left}) and \`focal\` ({x, y}) are 0\u20131 fractions of the source, the
+image-url shape; a \`builtin:image\`'s fields take them too. A top-level h2 or h3 may carry
+\`anchor\`: the id an imported page gave it.
+
+**Never write what is derived.** Each is refused \`richtext.derived_field:<type>.<path>\`: embed
+provider, shape, src; footnote number; columns cols; tableOfContents outline; authorBio name,
+avatar, bio; relatedPosts posts[].title, slug, url, cover, category; and \`resolved\`, on a block or
+a value. Who an author is and which posts are related are resolved when the page is produced, from
+the field's \`config.references: { posts?, authors? }\` (content-model ids; posts absent = the
+entry's own collection, authors absent = no author bio). A \`topic\` block in a collection with no
+topic field is refused \`relatedPosts.no_topic_field\`.
+
+**An X post is an \`embed\` with its url.** The server fetches its card. Never paste X's
+blockquote or its script: X's widget script is a site setting (\`custom_scripts.embeds.xScript\`),
+loaded once per page.
+
+**Refused at the write, by name:** \`gallery_invalid\`, \`gallery_limit_exceeded\`, \`toc_invalid\`,
+\`toc_limit_exceeded\`, \`footnote_invalid\`, \`columns_invalid\`, \`columns_limit_exceeded\`,
+\`author_bio_invalid\`, \`related_posts_invalid\`, \`related_posts_limit_exceeded\`,
+\`relatedPosts.no_topic_field\`. A block still being built stores: one gallery image, no author yet,
+no picks yet.
+
 ## 6. Blogs
 
     author     collection: name, avatar, bio
@@ -7726,7 +7769,9 @@ conversion is yours to write.
    groups \`[{_key, label}]\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
    is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, \`pullQuote\`
    (\`{quote, name, role?, link?}\`), \`keyTakeaways\` (\`{title?, points:[...strings]}\`,
-   title at most 40 characters, at most 8 points), or \`bcmsBlock\` carrying a
+   title at most 40 characters, at most 8 points), the article blocks (\xA75c: \`embed\`,
+   \`gallery\`, \`tableOfContents\`, \`columns\`, \`authorBio\`, \`relatedPosts\`, an inline
+   \`footnote\`), or \`bcmsBlock\` carrying a
    \`schemaKey\` \u2014 and a foreign node (a Sanity image, \`{_type:"image", asset:{_ref}}\`, for one)
    is not merely unrendered: it has no component here, so it
    vanishes from the HTML every delivery surface reads while the stored value still looks whole.