@kywi-software/mcp 0.11.0 → 0.12.0

package/AGENT-PATTERNS.md

@@ -76,7 +76,7 @@ the full proposal — ten minutes of sign-off beats re-entering fifty nodes.
 | Hardcode a list (testimonials, logos, posts, products, team) | Folder of nodes + a Feed + the Feed Display module (§1) |
 | Create one-off pages with identical field shapes | A custom content type + one node per item (§2) |
 | Filter/group content by topic, industry, audience | Categories & tags, queried by feeds (§3) |
-| Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component (§4) |
+| Copy-paste a CTA/banner/snippet across pages | Save it as a reusable component — linked, so one edit updates them all (§4) |
 | Write page sections as JSX | Build them as layout sections/modules the owner can edit (§5) |
 | Build a page as one column of full-width headings and paragraphs | Compose: section bands, columns, object modules (§5) |
 | Put a custom module's editable copy in a `json` prop | One `text`/`textarea`/`richText` prop per field the owner edits (§5) |
@@ -179,14 +179,99 @@ Anything designed once and used on multiple pages — CTA bands, promo banners,
 newsletter signup blocks, campaign snippets, "as seen in" strips — should be a
 **reusable component**, not copy-pasted sections.
 
-- In the layout editor, select the module and **Save as Component**; insert it
-  elsewhere from the component picker. Placed instances are **live
-  references**: editing the source component updates every page that uses it.
-- **Detach** an instance when a page genuinely needs a one-off variant — it
-  becomes an independent copy from that point on.
-- Rule of thumb: the second time you paste the same section, stop and make it
-  a component. The owner should be able to update the sitewide CTA in one
-  place, ten minutes before their webinar.
+A component is a **live source**, not a snapshot. Every page that places one
+holds a *link* to it (a `componentId` on the node), and the link is resolved on
+every request — so writing a new definition changes every page that uses it
+immediately, published pages included, with nothing to re-publish. That is the
+whole point, and it is also the thing to be careful with.
+
+**What can be one.** A single module, a whole section (band), or a personalized /
+A-B tested band with its variants intact — the three `type` values are `module`,
+`section` and `variantContainer`. A band's variants travel with it; which arm a
+visitor sees is still decided per request, per placement, so the same personalized
+component can sit on five pages and target correctly on each.
+
+**In the editors** (front-of-site overlay or the admin Layout tab): select the
+module, section or band → **Save as component** → name it. The selection is
+replaced in place by a linked instance, marked with an outline and a pill naming
+the component. Place it again from the section picker's *Components* rows.
+
+**Editing a linked instance ends in a question.** There are no per-prop overrides
+in v1: an instance renders its component exactly. So when you edit one and save,
+Kywi asks, naming the blast radius ("updates 3 instances across 2 pages, including
+published"):
+
+- **Save and update all instances** — the edit becomes the component. Every
+  instance everywhere follows it, live.
+- **Save to this page only** — this instance *detaches*: it keeps the edit as its
+  own independent content and stops following the component. Everything else is
+  untouched.
+
+**Rule of thumb:** the second time you paste the same section, stop and make it a
+component. The owner should be able to update the sitewide CTA in one place, ten
+minutes before their webinar.
+
+**Managing them:** *Components* in the admin nav is the library — every component
+with the number of pages using it, rename, an editing canvas for the definition,
+and delete. Deleting **detaches every instance first**: each page keeps rendering
+exactly what it rendered, as its own copy, and stops following.
+
+### Components over the API
+
+The admin UI is one client; the endpoints are the contract. `siteId` is optional
+and defaults to the resolved site — components are **per-site** in v1, and
+per-site authorization applies.
+
+1. `POST /api/v1/components` — `{ name, type, definition, moduleType?, description? }`.
+   The `definition` is the node itself: a `section` component stores the whole
+   `LayoutSection`, a `variantContainer` the whole container, a `module` component
+   stores `{ props, style }` and names its `moduleType`.
+2. **Place it** by writing a layout that carries the link. There is no separate
+   "insert" endpoint: `PUT /api/v1/content/:type/:id/layout` with the definition's
+   own shape plus `componentId` on the node, giving the placement a fresh `id` of
+   its own. The node's inline content is the *fallback copy* — what renders if the
+   component ever stops resolving — so write the definition's content there, not a
+   placeholder.
+
+   **An `ab_test` placement must mint its own `experimentId`.** A
+   `variantContainer` definition normally carries an `experimentId` — the one the
+   band had on the page it was saved from — because `mode: 'ab_test'` without one
+   is invalid, so it cannot simply be left out of the definition. A placement that
+   names no binding of its own **inherits the definition's**. Place that component
+   on three pages and all three arms report into a *single* experiment run; a
+   `winnerId` that travels the same way locks every placement to a finished test,
+   permanently serving one arm on pages nobody tested. So when you write an
+   `ab_test` placement: set a **fresh `experimentId`** on the placement node (any
+   uuid — one run per placement is the whole model) and **never copy `winnerId`**.
+   The editors do exactly this (`buildConnectedVariantContainerNode`), and a
+   definition saved from an editor carries no `winnerId` at all; a definition
+   POSTed straight over the API can, so read what you are placing. A
+   `personalization` container has no binding and needs none.
+3. `GET /api/v1/components/:id/usage` — where it is placed (`instances`, `pages`,
+   the page ids and node ids, and trashed pages counted separately). This is the
+   blast radius; read it *before* changing a definition.
+4. `PUT /api/v1/components/:id` — a body with `definition` **is the propagation
+   write**: every linked instance renders the new definition on its next request.
+   A body with only `name` / `description` is a rename and changes nothing any page
+   renders.
+5. `POST /api/v1/components/:id/detach-all` — materialize the definition into every
+   page that links it and drop the links; each page keeps rendering identically.
+6. `DELETE /api/v1/components/:id` — refuses (409) while instances exist; add
+   `?detachAll=1` to detach-then-delete. `GET /api/v1/components?withUsage=1` folds
+   the counts into a list, in one read.
+
+**Two refusals to design around.** A component definition may not link to another
+component (one level only, deliberately: a nested link is invisible to usage counts
+and the delete gate, so the editors *materialize* an inner component when you save
+a section that contains one — the inner instance stops following its own source, and
+the dialog says so). And a stored layout that a live layout could not hold is
+rejected at the door, because detaching would copy it into every page that links it.
+
+**Component writes bypass approvals in v1.** They are not routed through
+changesets or the review workflow — a `PUT` with a definition is live on publish
+pages the moment it returns. On a site with an editorial workflow, treat a
+definition write as a publish, not a draft: no draft, schedule or review step
+holds it back. Changeset integration is a follow-up.
 
 ## 5. Page layouts & modules — not hardcoded JSX
 
@@ -588,7 +673,8 @@ early, so ask at scoping time.
 - Creating types and entering content before the owner signed off on a
   content model.
 - A hardcoded array of testimonials/logos/posts in a page component.
-- The same CTA JSX pasted on four pages.
+- The same CTA JSX pasted on four pages — or the same section duplicated on four
+  pages in the editor, which the owner then has to update four times (§4).
 - A `<form>` that POSTs to a hand-rolled route (or nowhere).
 - Marketing imagery in `/public`.
 - A "blog" that is a folder of `.mdx` files the owner can't edit.

package/dist/site/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAYjD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CA8BpE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAEnE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAajD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CA8CjB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAiCpE"}

package/dist/site/server.js

@@ -7,6 +7,7 @@ import { registerModuleTypesTool } from '../module-types.js';
 import { registerContentTools } from './tools/content.js';
 import { registerLayoutTools } from './tools/layout.js';
 import { registerFeedTools } from './tools/feeds.js';
+import { registerComponentTools } from './tools/components.js';
 import { registerMenuTools } from './tools/menus.js';
 import { registerSearchTools } from './tools/search.js';
 import { registerMediaTools } from './tools/media.js';
@@ -69,6 +70,9 @@ export function createSiteMcpServer(config) {
     registerContentTools(server, sdk, config.baseUrl, config.apiKey);
     registerLayoutTools(server, sdk);
     registerFeedTools(server, sdk);
+    // Reusable components: discovery only — see tools/components.ts for why there is
+    // no write tool.
+    registerComponentTools(server, sdk);
     registerMenuTools(server, sdk);
     registerSearchTools(server, sdk);
     registerMediaTools(server, sdk);

package/dist/site/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/site/server.ts"],"names":[],"mappings":"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"}

package/dist/site/tools/components.d.ts

@@ -0,0 +1,35 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { KywiSdkScope } from '@kywi-software/sdk';
+/**
+ * Reusable components, for an authoring agent (kywi-cms#147).
+ *
+ * WHY THIS TOOL EXISTS. A component is placed by writing a layout node that
+ * carries its `componentId` — `update_layout` / `add_module` already do the
+ * writing. What an agent could not do was find out that a component exists, what
+ * it contains, or what its id is, which made the whole feature unreachable over
+ * MCP. This is the discovery half, in the same spirit as `list_module_types`:
+ * read, cheap, and the thing you call before composing a page.
+ *
+ * WHY THERE IS NO create/update/delete TOOL HERE. A definition write propagates:
+ * every page linking the component renders the new definition on its next request,
+ * published pages included, with no draft or approval step in v1. The editors put a
+ * named blast radius ("updates 3 instances across 2 pages, including published") in
+ * front of a person before doing it. An MCP tool has no equivalent, and a tool that
+ * quietly rewrites live pages is not one to add for symmetry's sake — so writes stay
+ * on the REST API, where the caller reaches for `GET /components/:id/usage` first.
+ * The full recipe (create, place, usage, detach-all, delete) is in
+ * `docs/agents/AGENT-PATTERNS.md` §4, which `kywi_patterns` serves.
+ */
+export declare function handleListComponents(sdk: KywiSdkScope, args: {
+    siteId?: string | undefined;
+    type?: string | undefined;
+    withUsage?: boolean | undefined;
+}): Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    isError?: undefined;
+}>;
+export declare function registerComponentTools(server: McpServer, sdk: KywiSdkScope): void;
+//# sourceMappingURL=components.d.ts.map

package/dist/site/tools/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../../src/site/tools/components.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACxE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAGtD;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE;IACJ,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;CAChC;;;;;;GAQF;AAID,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,YAAY,GAAG,IAAI,CAsBjF"}

package/dist/site/tools/components.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { textResult } from '../../shared.js';
+/**
+ * Reusable components, for an authoring agent (kywi-cms#147).
+ *
+ * WHY THIS TOOL EXISTS. A component is placed by writing a layout node that
+ * carries its `componentId` — `update_layout` / `add_module` already do the
+ * writing. What an agent could not do was find out that a component exists, what
+ * it contains, or what its id is, which made the whole feature unreachable over
+ * MCP. This is the discovery half, in the same spirit as `list_module_types`:
+ * read, cheap, and the thing you call before composing a page.
+ *
+ * WHY THERE IS NO create/update/delete TOOL HERE. A definition write propagates:
+ * every page linking the component renders the new definition on its next request,
+ * published pages included, with no draft or approval step in v1. The editors put a
+ * named blast radius ("updates 3 instances across 2 pages, including published") in
+ * front of a person before doing it. An MCP tool has no equivalent, and a tool that
+ * quietly rewrites live pages is not one to add for symmetry's sake — so writes stay
+ * on the REST API, where the caller reaches for `GET /components/:id/usage` first.
+ * The full recipe (create, place, usage, detach-all, delete) is in
+ * `docs/agents/AGENT-PATTERNS.md` §4, which `kywi_patterns` serves.
+ */
+// ─── Exported handler function (testable without a server) ──────────────────
+export async function handleListComponents(sdk, args) {
+    const components = await sdk.components.list({
+        siteId: args.siteId,
+        type: args.type,
+        withUsage: args.withUsage,
+    });
+    return textResult({ components, total: components.length });
+}
+// ─── Registration ───────────────────────────────────────────────────────────
+export function registerComponentTools(server, sdk) {
+    server.registerTool('list_components', {
+        description: 'List the site\'s reusable components (saved modules, sections and personalized/A-B bands). ' +
+            'Each row carries its `definition` — the stored node. To PLACE one, write a layout node ' +
+            'shaped like that definition with a fresh `id` of its own plus `componentId: <the id>`; the ' +
+            'inline content is the fallback copy, so keep the definition\'s content there. Every ' +
+            'placement is a live link: whoever edits the component changes every page that uses it, ' +
+            'published pages included. Creating or editing a component is REST-only in v1 (see ' +
+            'kywi_patterns §4) because a definition write has no draft or approval step.',
+        inputSchema: {
+            siteId: z.string().optional().describe('Site ID (uses the default site if omitted)'),
+            type: z
+                .enum(['module', 'section', 'variantContainer'])
+                .optional()
+                .describe('Filter by granularity: a single module, a whole section, or a personalized/A-B band'),
+            withUsage: z
+                .boolean()
+                .optional()
+                .describe('Include placement counts per component (instances, pages, trashed instances)'),
+        },
+    }, async (args) => handleListComponents(sdk, args));
+}
+//# sourceMappingURL=components.js.map

package/dist/site/tools/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../../../src/site/tools/components.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,+EAA+E;AAE/E,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAiB,EACjB,IAIC;IAED,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC;QAC3C,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;KAC1B,CAAC,CAAA;IACF,OAAO,UAAU,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,+EAA+E;AAE/E,MAAM,UAAU,sBAAsB,CAAC,MAAiB,EAAE,GAAiB;IACzE,MAAM,CAAC,YAAY,CAAC,iBAAiB,EAAE;QACrC,WAAW,EACT,6FAA6F;YAC7F,yFAAyF;YACzF,6FAA6F;YAC7F,sFAAsF;YACtF,yFAAyF;YACzF,oFAAoF;YACpF,6EAA6E;QAC/E,WAAW,EAAE;YACX,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;YACpF,IAAI,EAAE,CAAC;iBACJ,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC;iBAC/C,QAAQ,EAAE;iBACV,QAAQ,CAAC,qFAAqF,CAAC;YAClG,SAAS,EAAE,CAAC;iBACT,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,8EAA8E,CAAC;SAC5F;KACF,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAA;AACrD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kywi-software/mcp",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Model Context Protocol servers for Kywi CMS — a site server (content/nav/media over the REST API) and a developer server (kywi.config.ts scaffolding and mutation).",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -47,8 +47,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.25.0",
-    "@kywi-software/sdk": "0.11.0",
-    "@kywi-software/core": "0.11.0"
+    "@kywi-software/core": "0.12.0",
+    "@kywi-software/sdk": "0.12.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",