@bettercms-ai/mcp 0.73.2 → 0.74.0

package/dist/index.js

@@ -2,12 +2,12 @@
 
 // src/index.ts
 import { realpathSync } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { loadConfig, FileTokenStore, DeviceAuthClient } from "@bettercms-ai/device-auth";
 
 // src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BetterCMS } from "@bettercms-ai/sdk";
 
 // src/tools.ts
@@ -2758,11 +2758,11 @@ function patchAt(fields, [key, ...rest], edit) {
   let next = null;
   if (rest.length === 0) next = edit(field);
   else {
-    for (const list of CHILD_LISTS) {
-      const kids = getIn(field, list);
+    for (const list2 of CHILD_LISTS) {
+      const kids = getIn(field, list2);
       const patched = Array.isArray(kids) ? patchAt(kids, rest, edit) : null;
       if (patched) {
-        next = setIn(field, list, patched);
+        next = setIn(field, list2, patched);
         break;
       }
     }
@@ -2777,8 +2777,8 @@ function fieldAt(fields, keys) {
 function allKeys(fields) {
   return fields.flatMap((f) => [
     String(f.key),
-    ...CHILD_LISTS.flatMap((list) => {
-      const kids = getIn(f, list);
+    ...CHILD_LISTS.flatMap((list2) => {
+      const kids = getIn(f, list2);
       return Array.isArray(kids) ? allKeys(kids) : [];
     })
   ]);
@@ -3308,8 +3308,8 @@ var fieldShape = {
     rules: z.array(
       z.object({
         field: z.string().describe("the BARE KEY of another field on this same model"),
-        op: z.enum(["eq", "neq", "in", "isSet", "notEmpty", "empty"]),
-        value: z.union([z.string(), z.array(z.string())]).optional().describe("omit for 'isSet'/'notEmpty' (the source holds any value) and 'empty' (it holds none); required for every other op")
+        op: z.enum(["eq", "neq", "in", "notIn", "gt", "lt", "isSet", "notEmpty", "empty"]),
+        value: z.union([z.string(), z.array(z.string())]).optional().describe(`omit for 'isSet'/'notEmpty' (the source holds any value) and 'empty' (it holds none); 'gt'/'lt' take one number as a string ("10"); required for every other op`)
       })
     )
   }).optional().describe(
@@ -3995,14 +3995,18 @@ function buildToolDefs(deps) {
       match: z.enum(["all", "any"]),
       rules: z.array(z.object({
         field: z.string().min(1),
-        op: z.enum(["eq", "neq", "in", "isSet", "notEmpty", "empty"]),
+        op: z.enum(["eq", "neq", "in", "notIn", "gt", "lt", "isSet", "notEmpty", "empty"]),
         value: z.union([z.string(), z.array(z.string())]).optional()
       })).min(1).max(20)
-    }).optional().describe("show this prop only while SIBLING props (by key) match: {match:'all'|'any', rules:[{field, op:'eq'|'neq'|'in'|'isSet'|'notEmpty'|'empty', value?}]}. 'isSet', 'notEmpty' and 'empty' take no value. Editor-only."),
+    }).optional().describe("show this prop only while SIBLING props (by key) match: {match:'all'|'any', rules:[{field, op:'eq'|'neq'|'in'|'notIn'|'gt'|'lt'|'isSet'|'notEmpty'|'empty', value?}]}. 'isSet', 'notEmpty' and 'empty' take no value; 'gt'/'lt' one number as a string. Editor-only."),
     // V2 editor-only keys, the model field's (playbook §14). Declared: this is a strip site.
     helpMore: z.string().max(2e3).optional().describe(PARAM_TEXT.helpMore),
     advanced: z.boolean().optional().describe(PARAM_TEXT.advanced),
     recommendedMax: z.number().int().positive().optional().describe(PARAM_TEXT.recommendedMax),
+    // F1.x `unique` (a list's items / a table's rows distinct) and the server's `stale` marker:
+    // undeclared here, an agent's `unique` and an echoed `stale` were dropped with a 200.
+    unique: z.boolean().optional(),
+    stale: z.boolean().optional(),
     openMode: z.enum(["inline", "drill", "popover", "dialog"], { error: OPEN_MODE_INVALID }).optional().describe("object/group/table props: how the value (or each row) opens"),
     // ⚠ A STRIP SITE, exactly like OutField above: this is a `z.object`, so a key the model
     // sends and this shape does not declare is dropped BEFORE the request leaves — a 200 with
@@ -6039,13 +6043,13 @@ ${notes.join("\n")}` : summary, created);
       handler: guard(
         async (args) => withClient(async (client) => {
           if (args.detail) {
-            const list2 = await client.listComponents();
-            return ok(`${list2.length} component(s) in the bound project (full definitions).`, list2);
+            const list3 = await client.listComponents();
+            return ok(`${list3.length} component(s) in the bound project (full definitions).`, list3);
           }
-          const list = await client.listComponents({ select: "summary" });
+          const list2 = await client.listComponents({ select: "summary" });
           return ok(
-            `${list.length} component(s) in the bound project.`,
-            list.map((cmp) => ({
+            `${list2.length} component(s) in the bound project.`,
+            list2.map((cmp) => ({
               id: cmp.id,
               name: cmp.name,
               slug: cmp.slug,
@@ -6490,6 +6494,11 @@ DERIVED by \`editor_setup\`, where the componentize lane in \xA710 reuses every
 
 ## 2. The decision tree
 
+    Designing ANY section?                 -> FIRST find its closest kit entry in bettercms://kit
+                                              (by category, then edge tag); follow that entry's
+                                              mcp notes and avoid its pitfalls (tag rules below).
+                                              Its props carry NO target: give each one a target
+                                              into YOUR blockJson (\xA73) before create_component
     Repeated visual region on a page?      -> a COMPONENT with sectionType (a Section)
       ...and it comes in more than one look? -> siblings sharing that sectionType = VARIANTS
     A stack of mixed, reorderable content? -> kind:'block' models + a \`modular\` field
@@ -6510,6 +6519,29 @@ DERIVED by \`editor_setup\`, where the componentize lane in \xA710 reuses every
     Site-wide nav/footer/modal?            -> the LAYOUT (get_layout/update_layout), never a
                                               page section and never one component per page
 
+Kit edge tags, one rule each (long form with entry ids: the skill's kit-scenarios reference):
+
+    deep-nesting       levels = content kinds, not wrappers; past 6, split the deepest subtree out
+    repeater           one band holds the list; never store what order says (step no., totals)
+    polymorphic-array  each item names its _type; merge consecutive prose into one text item
+    slots              children differ in shape; span/surface/phone order go in slotSettings
+    variants           column count, side, carousel = a variant, never a free number or boolean
+    conditional        a select reveals one branch; fill only it (hidden values still publish)
+    references         reference the entry/product/page; store only what differs as overrides
+    dynamic-query      store collection + filters + sort + limit; import the items as entries first
+    global-synced      same on ~80% of pages = one global; an instance overrides only what differs
+    localized          match locales by position, never text; never translate on import; no hreflang
+    rich-text          one body; callouts, tables, media, instances are islands; no h1, no chrome
+    media-heavy        largest source, real alt, video poster + caption file, positions in %
+    embed              store provider + id or canonical URL, never the script; iframes need a title
+    form               a Form reference by id; never the inputs copied into the section
+    commerce           the store owns price, stock, SKU, options, cart: reference, never copy
+    personalization    only with evidence; complete default, audiences hold only the differences
+    validation         numbers as numbers, datetimes with offset; check cross-field rules on import
+    a11y               every visual-only element gets text: logo name, pin label, iframe title
+    seo-structured     JSON-LD is emitted from content; never model meta or JSON-LD fields (\xA75b)
+    responsive-layout  per-breakpoint values as settings that inherit desktop; spacing as tokens
+
 ## 3. Anatomy of a real section component
 
 A component that is only headings and text renders as an unstyled stack \u2014 plain text on white
@@ -7263,7 +7295,7 @@ conversion is yours to write.
    markup inside a \`text\` field.
    **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
    this platform stores \u2014 \`block\`, \`table\` (\`{_type:"table", rows:[{_key, cells:[{_key,
-   content:[...blocks], header?, group?, highlight?, sortable?}], group?, footer?, highlight?}], caption?, notes?, rowGroups?, columnGroups?, filterable?, jsonLd?: {type: "ItemList"|"Dataset"|"Offers", axis?, priceRow?}, design?: {responsive?: "stack"|"cards", sticky?}}\`,
+   content:[...blocks], header?, group?, highlight?, sortable?, note?, column?: {type?: "text"|"number"|"money"|"boolean"|"rating"|"link", unit?, currency?, decimals?, align?, trueLabel?, falseLabel?, max?, description?} (first row only), type?, value?: number|boolean (content keeps its words)}], group?, footer?, highlight?, type?}], caption?, notes?, rowGroups?, columnGroups?, filterable?, jsonLd?: {type: "ItemList"|"Dataset"|"Offers", axis?, priceRow?}, design?: {responsive?: "stack"|"cards", sticky?}, footnotes?: [{_key, text}]}\`,
    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]}\`,
@@ -7502,7 +7534,7 @@ Importance orders a screen: required fields first, then array order.
 | Calm defaults for rare settings | \`advanced: true\` |
 | A soft length warning (amber, never a refusal) | \`recommendedMax: 60\` |
 | A marketer cannot change it | \`readOnly: 'developer'\` plus \`lockReason\` |
-| A field that shows only sometimes | \`showIf\` (it SHOWS the field): ops \`eq\`, \`neq\`, \`in\`, \`isSet\`, \`notEmpty\`, \`empty\` |
+| A field that shows only sometimes | \`showIf\` (it SHOWS the field): ops \`eq\`, \`neq\`, \`in\`, \`notIn\`, \`gt\`, \`lt\` (one number as a string), \`isSet\`, \`notEmpty\`, \`empty\` |
 | A good row title and thumbnail | \`ui.preview: { title, subtitle, media, fallback }\` (\`fallback\` is a literal label) |
 | Labels that classify or filter (topics, keywords), never a feature list | \`type: 'tags'\`: a string[], trimmed, de-duplicated, each \u226464 characters; \`config.options\` are suggestions, \`config.max\`, \`config.allowCustom: false\` closes the list (\`tags_value_invalid\`) |
 | A star rating | \`type: 'rating'\`: a number from 0 to \`config.max\` (5), \`config.step\` 1 or 0.5 (\`rating_value_invalid\`) |
@@ -8307,6 +8339,93 @@ function loadSkillDocs(dir = defaultSkillDir()) {
   return docs;
 }
 
+// src/kit.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var KIT_URI = "bettercms://kit";
+var KIT_ENTRY_URI_PREFIX = "bettercms://kit/entry/";
+var KIT_ENTRY_URI_TEMPLATE = `${KIT_ENTRY_URI_PREFIX}{id}`;
+function loadKitCatalog(path = fileURLToPath2(new URL("./kit-catalog.json", import.meta.url))) {
+  return existsSync2(path) ? JSON.parse(readFileSync2(path, "utf8")) : null;
+}
+var list = (xs) => xs.map((x) => `- ${x}`).join("\n");
+function entryNotes(e, h = "###") {
+  const out = [`${h} ${e.name} (\`${e.id}\`)`, "", `Tags: ${e.tags.join(", ") || "none"}. Proves: ${e.proves}`];
+  if (!e.why && !e.mcp) out.push("", "No model notes in the kit for this entry: read its props.");
+  if (e.why) out.push("", `**Why this shape.** ${e.why}`);
+  if (e.htmlSignals.length) out.push("", "**HTML signals.**", list(e.htmlSignals));
+  if (e.mcp) out.push("", `**Do.** ${e.mcp}`);
+  if (e.pitfalls.length) out.push("", "**Pitfalls.**", list(e.pitfalls));
+  if (e.notCarried.length) out.push("", `Not carried by a stored component: ${e.notCarried.join(", ")}.`);
+  return out.join("\n");
+}
+function kitIndexText(k) {
+  const byId = new Map(k.entries.map((e) => [e.id, e]));
+  return [
+    "# BetterCMS kit catalogue",
+    "",
+    `${k.entries.length} modelled website sections. Before designing a section, find the closest entry by its edge tag or category, read its notes and follow its mcp + pitfalls; its create_component props are at ${KIT_ENTRY_URI_TEMPLATE}.`,
+    "",
+    "## Categories",
+    "",
+    ...k.categories.map((c) => `- ${c.name} (${c.entries.length}): ${KIT_URI}/${c.slug}`),
+    "",
+    "## Edge tags",
+    "",
+    ...k.tags.map((t) => `- \`${t.tag}\` (${t.hint}): ${t.entries.join(", ") || "none"}`),
+    "",
+    "## Entries",
+    "",
+    ...k.categories.flatMap((c) => [
+      `### ${c.name}`,
+      "",
+      ...c.entries.map((id) => {
+        const e = byId.get(id);
+        return `- \`${e.id}\` ${e.name} [${e.tags.join(", ")}]: ${e.proves}`;
+      }),
+      ""
+    ])
+  ].join("\n");
+}
+function kitCategoryText(k, slug2) {
+  const c = k.categories.find((x) => x.slug === slug2);
+  const byId = new Map(k.entries.map((e) => [e.id, e]));
+  return [
+    `# Kit: ${c.name}`,
+    "",
+    `${c.entries.length} entries. Each one's create_component props: ${KIT_ENTRY_URI_TEMPLATE}. Index: ${KIT_URI}.`,
+    "",
+    ...c.entries.map((id) => entryNotes(byId.get(id), "##") + "\n")
+  ].join("\n");
+}
+function kitEntryText(e) {
+  return [
+    entryNotes(e, "#"),
+    "",
+    "## create_component payload",
+    "",
+    "Props in the exact shape create_component accepts. Adapt keys and copy to the site; keep the types, `ui` and config.",
+    "",
+    "```json",
+    JSON.stringify(e.component, null, 1),
+    "```",
+    ""
+  ].join("\n");
+}
+function kitDocs(k = loadKitCatalog()) {
+  if (!k) return [];
+  const doc = (uri, name, title, description, text2) => ({ uri, name, title, description, mimeType: "text/markdown", text: text2 });
+  return [
+    doc(KIT_URI, "kit", "BetterCMS kit catalogue", "Index of modelled website sections by category and edge tag: find the closest one before designing a section.", kitIndexText(k)),
+    ...k.categories.map(
+      (c) => doc(`${KIT_URI}/${c.slug}`, `kit-${c.slug}`, `Kit: ${c.name}`, `Model notes for the ${c.entries.length} ${c.name} entries: why, HTML signals, mcp, pitfalls.`, kitCategoryText(k, c.slug))
+    )
+  ];
+}
+function kitEntryTexts(k = loadKitCatalog()) {
+  return k ? Object.fromEntries(k.entries.map((e) => [`${KIT_ENTRY_URI_PREFIX}${e.id}`, kitEntryText(e)])) : {};
+}
+
 // src/server.ts
 var SERVER_NAME = "bettercms";
 var SERVER_VERSION = "1.5.0";
@@ -8368,6 +8487,22 @@ function buildServer(deps) {
   for (const { uri, name, text: text2, ...meta } of loadSkillDocs()) {
     server.registerResource(name, uri, meta, () => ({ contents: [{ uri, mimeType: meta.mimeType, text: text2 }] }));
   }
+  for (const { uri, name, text: text2, ...meta } of kitDocs()) {
+    server.registerResource(name, uri, meta, () => ({ contents: [{ uri, mimeType: meta.mimeType, text: text2 }] }));
+  }
+  const kitEntries = kitEntryTexts();
+  if (Object.keys(kitEntries).length) {
+    server.registerResource(
+      "kit-entry",
+      new ResourceTemplate(KIT_ENTRY_URI_TEMPLATE, { list: void 0 }),
+      { title: "Kit entry", description: "One kit entry: its model notes and the create_component props. Ids are in bettercms://kit.", mimeType: "text/markdown" },
+      (uri) => {
+        const text2 = kitEntries[uri.href];
+        if (text2 === void 0) throw new Error(`Unknown kit entry: ${uri.href}`);
+        return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: text2 }] };
+      }
+    );
+  }
   registerTools(server, {
     auth: deps.auth,
     // `project` is the per-call target of a workspace-wide grant; the SDK sends it as
@@ -8395,7 +8530,7 @@ function isMainModule() {
   const argv1 = process.argv[1];
   if (!argv1) return false;
   try {
-    return realpathSync(argv1) === fileURLToPath2(import.meta.url);
+    return realpathSync(argv1) === fileURLToPath3(import.meta.url);
   } catch {
     return false;
   }