frameworc-mcp 0.3.0 → 0.5.1

package/README.md

@@ -6,8 +6,11 @@ A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Cla
 
 - Composes 15 prebuilt FrameworC blocks (`Header`, `Section`, `Tiles`, `Slider`, `Tabs`, `Accordion`, `Form`, `Gallery`, `Downloads`, `Columns`, `Prefill`, `BlogList`, `MenuBlock`, `ImageStrip`, `InstaFeed`) into pages
 - Lists existing pages and their full builder JSON
-- Creates pages, adds / updates / removes / reorders individual blocks
-- Resolves referenced `Form` / `Menu` / `Prefill` entries via dedicated list tools
+- Creates pages, adds / updates / removes / reorders individual blocks — on pages and on Prefill entries
+- Full CRUD for `Form` entries (incl. their field rows), `Menu` entries (incl. the navigation tree) and `Prefill` entries (incl. their builder blocks)
+- Extracts a repeated page section into a Prefill entry and replaces it with a reference (`extract_block_to_prefill`) — the intended FrameworC de-duplication workflow
+- Reads and writes the per-site singles (Meta & SEO, Navigation, Footer) and the global FrameworC settings (navbar options, SCSS variables; integration secrets are not accessible by design)
+- Multisite-aware: every content tool takes/pins a `site_id`; page and prefill translations are linked for the language switcher
 - Publishes the block catalogue as an MCP resource (`frameworc://blocks`) so the chat agent knows each block's fields, defaults, and when-to-use notes
 - Draft by default — created pages have `is_enabled = false`; the human flips the switch in the OctCMS backend after assigning images
 
@@ -23,10 +26,10 @@ node dist/index.js         (local, spawned by the chat client)
   reads ~/.config/frameworc/sites.json (auto-created on first run; hot-reloaded)
   │ HTTPS + Authorization: Bearer <token resolved by URL>
   ▼
-any OctCMS install         /api/mcp/v1/*  (provided by the FrameworC plugin v1.10.0+)
+any OctCMS install         /api/mcp/v1/*  (provided by the crscompany/frameworcmcp plugin v1.1.0+)
 ```
 
-No Docker, no ToolHive, no remote gateway, no second auth layer. Each OctCMS install has its own bearer token stored in its own `FrameworcSetting → Integration → MCP API token`, and your laptop keeps the URL → token map in one local file.
+No Docker, no ToolHive, no remote gateway, no second auth layer. Each OctCMS install has its own bearer token stored in its backend under `Settings → FrameworC → MCP API`, and your laptop keeps the URL → token map in one local file.
 
 ## Install
 
@@ -93,8 +96,8 @@ If the file is missing or empty, `use_site` errors with a pointer to where to ad
 
 ### Adding a new OctCMS site
 
-1. Spin up the new OctCMS install with the FrameworC plugin (v1.10.0 or newer).
-2. Backend → Settings → FrameworC → Integration → **MCP API token** → paste a freshly generated random string (e.g. `openssl rand -hex 32`) → Save.
+1. Spin up the new OctCMS install with the FrameworC suite incl. the `crscompany/frameworcmcp` plugin (v1.2.0 or newer; media assignment needs v1.2.0).
+2. Backend → Settings → FrameworC → **MCP API** → paste a freshly generated random string (e.g. `openssl rand -hex 32`) → Save.
 3. Edit `~/.config/frameworc/sites.json` on your laptop, add one entry: `{ "label": "New Client", "url": "https://newsite.test", "token": "<that string>" }`.
 4. In your next chat (no Claude Desktop restart needed): *"Use `https://newsite.test`."* → MCP hot-reloads the file, finds the token, sends it. Done.
 
@@ -106,25 +109,39 @@ No env var, no chat-client config edit, no ToolHive touch, no repo push. The who
 - A leak of the file compromises every site listed in it. Treat it like an SSH private key — back it up, rotate tokens periodically, never commit it to git.
 - One-off override: `use_site("https://X", "token-string")` lets you pass a token inline (without storing it) for the duration of the chat session. Useful for testing a token before saving it.
 
-## Tools (v1)
+## Tools (0.5.0)
 
 | Tool | Description |
 |---|---|
 | `use_site(url, site_token?)` | Pin the target OctCMS site for the session. Token resolved from `~/.config/frameworc/sites.json` by URL, or supplied via the optional `site_token` arg. |
 | `list_sites` | List configured sites (label + URL only, no tokens) from `sites.json`. |
+| `list_cms_sites` | List the multisite sites (languages) inside the pinned install. |
+| `use_cms_site(site_id)` | Pin the multisite site for subsequent calls (null = primary). |
 | `list_pages` | List all pages on the pinned site. |
 | `get_page(id)` | Full page JSON (page meta + builder blocks + nested repeaters). |
 | `create_page(payload)` | Create a draft page. `payload = { page: {...}, builder: [...] }`. |
-| `update_page(id, payload)` | Edit page meta, or full-rebuild the builder array. |
+| `update_page(id, payload)` | Edit page meta, or full-rebuild the builder array (prefer the per-block tools). |
 | `delete_page(id)` | Soft-delete a page. |
-| `add_block(page_id, block, position?)` | Append (or insert at `position`) a block. |
-| `update_block(page_id, block_id, block)` | Replace one block by row id. |
-| `remove_block(page_id, block_id)` | Remove one block by row id. |
-| `reorder_blocks(page_id, order)` | Reorder blocks (order = array of all row ids in new order). |
-| `list_forms` | Form Tailor entries for the `Form` block's `form_entry`. |
-| `list_menus` | Menu Tailor entries for the `MenuBlock`'s `content.menu_entry`. |
-| `list_prefills` | Prefill Tailor entries for the `Prefill` block's `content.prefill_entry`. |
-| `get_block_schema(name)` | Field schema + usage notes for one block. |
+| `create_translation(id, target_site_id, prefill?)` | Linked sibling of a page (or Prefill with `prefill:true`) on another multisite site. |
+| `add_block(page_id \| prefill_id, block, position?)` | Append (or insert at `position`) a block. |
+| `update_block(page_id \| prefill_id, block_id, block)` | Replace one block by row id (new id returned). A media field you omit is inherited; one you send is written verbatim, so `""` clears it. |
+| `remove_block(page_id \| prefill_id, block_id)` | Remove one block by row id. |
+| `reorder_blocks(page_id \| prefill_id, order)` | Reorder blocks (order = array of all row ids in new order). |
+| `extract_block_to_prefill(page_id, block_id, title)` | Move a page block into a new Prefill entry (lossless from plugin v1.2.0) and reference it in place. |
+| `list_forms` / `get_form(id)` | Form entries; `get_form` includes the `fwcFields` rows. |
+| `get_form_schema` | Live field-group catalogue for authoring forms. |
+| `create_form` / `update_form` / `delete_form` | Form CRUD. `fwcFields` rows: `{group, label, name, required, width, ...}`; delete guarded unless `force:true`. |
+| `list_menus` / `get_menu(id)` | Menu entries; `get_menu` includes the navigation tree. |
+| `create_menu` / `update_menu` / `delete_menu` | Menu CRUD. Tree items `{title, url \| {page_id}, anchor, blank, children}`, max 2 levels; delete guarded. |
+| `list_prefills` / `get_prefill(id)` | Prefill entries; `get_prefill` includes the builder blocks. |
+| `create_prefill` / `update_prefill` / `delete_prefill` | Prefill CRUD — same block shape as pages; delete guarded. |
+| `get_page_meta(handle)` / `update_page_meta(handle, fields)` | Per-site singles: `Meta` (SEO), `Navigation` (navbar incl. `nav` menu link + buttons), `Footer` (incl. `socials` rows + `nav`). |
+| `get_settings` / `update_settings(fields)` | Global FrameworC settings: navbar options + custom SCSS variables. Integration secrets are not exposed. |
+| `get_block_schema(name)` | Field schema + usage notes for one block (live from the CMS). |
+| `list_media(folder?, type?, sort?, limit?, offset?)` | Browse the media library. Returns files with their `path` — write that into a mediafinder field. |
+| `search_media(q, folder?, type?, ...)` | Find library files by name across all folders. Every whitespace-separated word must appear in the path. |
+
+Form and Menu entries have no translation linking — create them per site by passing `site_id`.
 
 ## Resource
 
@@ -173,7 +190,7 @@ No env var, no chat-client config edit, no ToolHive touch, no repo push. The who
     {
       "content_group": "Form",
       "base": { "blockId": "formular", "headline": "<h2>Write us</h2>" },
-      "form_entry": 7,
+      "form": 7,
       "content": { "variant": "default" }
     }
   ]
@@ -182,14 +199,23 @@ No env var, no chat-client config edit, no ToolHive touch, no repo push. The who
 
 ### Storage encoding (what the MCP understands)
 
-- Media fields (`image`, `imageMobile`, `backgroundImage`, `buttonIcon1..4`, `ogImage`, `images`, `file`) **must be empty** in the JSON — they are rejected if non-empty. Fill them in the OctCMS backend.
+- Media fields hold **media library paths**, root-relative with a leading slash (`/images/hero.jpg`). Assignment only: the API cannot upload, and a path that is not in the library is a 422. Single-item fields (`maxItems: 1`) are strings and read as `""` when unset; multi fields are arrays and read as `[]`. Find paths with `search_media` / `list_media`.
 - `switch` fields accept booleans; the API normalises to `"1"` / `"0"` for storage.
 - `customCssClass` + `responsiveHide` are arrays of strings.
-- Multi-`mediafinder` fields (`images` for `Gallery` / `ImageStrip`) are arrays of path strings — but must be empty `[]` per the rule above.
-- `entries` links are integers: `form_entry` (block level for `Form`), `content.menu_entry` (for `MenuBlock`), `content.prefill_entry` (for `Prefill`).
+- Multi-`mediafinder` fields are arrays of path strings: `Gallery.images` and `ImageStrip.images`, where **every** item renders, plus `Section.content.image` and the `Footer` single's `logo`, which are arrays in storage but of which the theme renders **only the first item**.
+- `entries` links are integers (or `{id: n}`): `form` (block level for `Form`), `content.menu` (for `MenuBlock`), `content.block` (for `Prefill`). Reads return them as `{id, title}`.
 - `Slider` accepts an optional `content.breakpoints = { tablet: number, mobile: number }`.
 - `Columns` blocks have `content.columns = [{ blockId, builder: [...blocks] }]` — recursive: each column's `builder` follows the exact same shape as the top-level `builder`.
 
+### Working with media
+
+`mode: image` on a blueprint field is only a hint for the backend widget; October never enforces it, and real FrameworC content relies on the slack. The API therefore accepts any image, SVG or video extension in a `mode: image` field and rejects the rest (a `.pdf` in a hero would break `resize()`), which means:
+
+- The `Navigation` logo is an SVG and `Header.image` holds an `.mp4` when `isVideoBg` is on. Both are valid.
+- `buttonIcon1..4` and `Downloads`' `file` declare no `mode` at all, so any file type is accepted there.
+- Whether SVG reports as `file_type: image` or `document` depends on the install's `media.image_extensions` config, so treat `list_media`'s `type` filter as a convenience rather than a guarantee.
+- Folders are not selectable, and filenames containing `+ # % !` are unreachable through the API — an October media library limitation that applies to its own backend manager too.
+
 ## Catalogue drift
 
 The hand-authored block catalogue lives in `src/catalogue.ts`. It mirrors `plugins/crscompany/frameworc/blueprints/Blocks/*.yaml` + `Mixins/Buttons.yaml` + `Mixins/Buttons2.yaml` + `BaseBlock.yaml`. If a block blueprint changes (new field, new enum value, removed field), update `src/catalogue.ts` to match and rebuild. No generator script — kept manual because blocks change rarely per the FrameworC convention.

package/dist/api-client.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiClient = void 0;
+/** Renders the defined params as a leading-`?` query string, or "" when empty. */
+function qs(params) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null && value !== "") {
+            search.set(key, String(value));
+        }
+    }
+    const rendered = search.toString();
+    return rendered ? `?${rendered}` : "";
+}
 class ApiClient {
     session;
     constructor(session) {
@@ -60,6 +71,13 @@ class ApiClient {
     getBlockSchema(name) {
         return this.request(`/blocks/${encodeURIComponent(name)}`);
     }
+    // --- media library (global) -------------------------------------------
+    listMedia(params = {}, siteId) {
+        return this.request(this.q(`/media${qs(params)}`, siteId));
+    }
+    searchMedia(query, params = {}, siteId) {
+        return this.request(this.q(`/media/search${qs({ q: query, ...params })}`, siteId));
+    }
     // --- pages ------------------------------------------------------------
     listPages(siteId) {
         return this.request(this.q("/pages", siteId));
@@ -84,38 +102,103 @@ class ApiClient {
         }
         return this.request(`/pages/${id}/translations`, { method: "POST", body: JSON.stringify(body) });
     }
-    // --- blocks (per-page) ------------------------------------------------
-    addBlock(pageId, block, position, siteId) {
-        return this.request(`/pages/${pageId}/blocks`, {
+    // --- blocks (per page or per prefill) ---------------------------------
+    blockBase(host) {
+        return host.type === "prefill" ? `/prefills/${host.id}` : `/pages/${host.id}`;
+    }
+    addBlock(host, block, position, siteId) {
+        return this.request(`${this.blockBase(host)}/blocks`, {
             method: "POST",
             body: this.b({ block, position }, siteId),
         });
     }
-    updateBlock(pageId, blockId, block, siteId) {
-        return this.request(`/pages/${pageId}/blocks/${blockId}`, {
+    updateBlock(host, blockId, block, siteId) {
+        return this.request(`${this.blockBase(host)}/blocks/${blockId}`, {
             method: "PATCH",
             body: this.b(block, siteId),
         });
     }
-    removeBlock(pageId, blockId, siteId) {
-        return this.request(this.q(`/pages/${pageId}/blocks/${blockId}`, siteId), { method: "DELETE" });
+    removeBlock(host, blockId, siteId) {
+        return this.request(this.q(`${this.blockBase(host)}/blocks/${blockId}`, siteId), { method: "DELETE" });
     }
-    reorderBlocks(pageId, order, siteId) {
-        return this.request(`/pages/${pageId}/blocks/order`, {
+    reorderBlocks(host, order, siteId) {
+        return this.request(`${this.blockBase(host)}/blocks/order`, {
             method: "POST",
             body: this.b({ order }, siteId),
         });
     }
-    // --- referenced entries ----------------------------------------------
+    extractBlockToPrefill(pageId, blockId, title, siteId) {
+        return this.request(`/pages/${pageId}/blocks/${blockId}/extract-to-prefill`, {
+            method: "POST",
+            body: this.b({ title }, siteId),
+        });
+    }
+    // --- forms --------------------------------------------------------------
     listForms(siteId) {
         return this.request(this.q("/forms", siteId));
     }
+    getFormSchema() {
+        return this.request("/forms/schema");
+    }
+    getForm(id, siteId) {
+        return this.request(this.q(`/forms/${id}`, siteId));
+    }
+    createForm(payload, siteId) {
+        return this.request("/forms", { method: "POST", body: this.b(payload, siteId) });
+    }
+    updateForm(id, payload, siteId) {
+        return this.request(`/forms/${id}`, { method: "PATCH", body: this.b(payload, siteId) });
+    }
+    deleteForm(id, force, siteId) {
+        return this.request(this.q(`/forms/${id}${force ? "?force=1" : ""}`, siteId), { method: "DELETE" });
+    }
+    // --- menus --------------------------------------------------------------
     listMenus(siteId) {
         return this.request(this.q("/menus", siteId));
     }
+    getMenu(id, siteId) {
+        return this.request(this.q(`/menus/${id}`, siteId));
+    }
+    createMenu(payload, siteId) {
+        return this.request("/menus", { method: "POST", body: this.b(payload, siteId) });
+    }
+    updateMenu(id, payload, siteId) {
+        return this.request(`/menus/${id}`, { method: "PATCH", body: this.b(payload, siteId) });
+    }
+    deleteMenu(id, force, siteId) {
+        return this.request(this.q(`/menus/${id}${force ? "?force=1" : ""}`, siteId), { method: "DELETE" });
+    }
+    // --- prefills -----------------------------------------------------------
     listPrefills(siteId) {
         return this.request(this.q("/prefills", siteId));
     }
+    getPrefill(id, siteId) {
+        return this.request(this.q(`/prefills/${id}`, siteId));
+    }
+    createPrefill(payload, siteId) {
+        return this.request("/prefills", { method: "POST", body: this.b(payload, siteId) });
+    }
+    updatePrefill(id, payload, siteId) {
+        return this.request(`/prefills/${id}`, { method: "PATCH", body: this.b(payload, siteId) });
+    }
+    deletePrefill(id, force, siteId) {
+        return this.request(this.q(`/prefills/${id}${force ? "?force=1" : ""}`, siteId), { method: "DELETE" });
+    }
+    createPrefillTranslation(id, targetSiteId, payload, sourceSiteId) {
+        const body = { ...(payload ?? {}), site_id: targetSiteId };
+        const source = sourceSiteId ?? this.session.getSiteId();
+        if (source !== null && source !== undefined) {
+            body.source_site_id = source;
+        }
+        return this.request(`/prefills/${id}/translations`, { method: "POST", body: JSON.stringify(body) });
+    }
+    // --- FrameworC settings (global) ---------------------------------------
+    getSettings() {
+        return this.request("/settings");
+    }
+    updateSettings(fields) {
+        return this.request("/settings", { method: "PATCH", body: JSON.stringify({ fields }) });
+    }
     // --- singles ----------------------------------------------------------
     getSingle(handle, siteId) {
         return this.request(this.q(`/singles/${encodeURIComponent(handle)}`, siteId));

package/dist/catalogue.js

@@ -6,7 +6,7 @@ const buttonsMixin = [
     { name: "buttonVariant1", type: "dropdown", enum: ["default", "outline", "blurLight", "blurDark", "plain"], default: "default" },
     { name: "buttonContrast1", type: "switch", default: false },
     { name: "buttonLink1", type: "text", comment: "Pagefinder path or URL for button 1 (left blank = no link)" },
-    { name: "buttonIcon1", type: "media-single", comment: "Must stay empty — human fills via backend" },
+    { name: "buttonIcon1", type: "media-single", comment: "Media library path, e.g. \"/icons/arrow.svg\". Find one with search_media. No mode restriction, so any file type is accepted." },
     { name: "buttonBlank1", type: "switch", default: false },
     { name: "buttonLabel2", type: "text", comment: "Text of button 2" },
     { name: "buttonVariant2", type: "dropdown", enum: ["default", "outline", "blurLight", "blurDark", "plain"], default: "default" },
@@ -35,7 +35,7 @@ const baseBlock = [
     { name: "elevated", type: "switch", default: false, comment: "Lifts this block up into the previous block visually." },
     { name: "containerWidth", type: "dropdown", enum: ["default", "narrow", "full", "pop"], default: "default" },
     { name: "backgroundColor", type: "dropdown", enum: ["default", "accent", "contrast", "image", "containerAccent", "containerContrast", "containerImage"], default: "default" },
-    { name: "backgroundImage", type: "media-single", comment: "Must stay empty — leave for human to fill in backend." },
+    { name: "backgroundImage", type: "media-single", comment: "Media library path from list_media/search_media. Only renders when backgroundColor is 'image' or 'containerImage'." },
     { name: "backgroundImageMobile", type: "media-single" },
     { name: "customCssClass", type: "taglist", enum: ["animate", "noSpacing", "noSpacingTop", "noSpacingBottom", "narrowSpacing", "centerButtons"], comment: "Array of class keys to apply as Builder-container--<class>." },
     { name: "aliasOverride", type: "text", comment: "Custom component alias (theme partial hook). Leave blank unless specifically needed." },
@@ -53,7 +53,7 @@ exports.BLOCKS = [
         whenToUse: "Always first block on a page. Use H1/H2 here (other blocks use H2/H3). One per page.",
         base: baseBlock,
         content: [
-            { name: "image", type: "media-single", comment: "Must stay empty for MCP; human fills via backend." },
+            { name: "image", type: "media-single", comment: "Media library path. Declared mode:image, but an .mp4 is valid here when isVideoBg is on." },
             { name: "imageMobile", type: "media-single" },
             { name: "isVideoBg", type: "switch", default: false, comment: "If true, 'image' is treated as a video file and 'imageMobile' as poster." },
             ...buttonsMixin,
@@ -71,7 +71,7 @@ exports.BLOCKS = [
         content: [
             { name: "variant", type: "dropdown", enum: sectionVariants, default: "halfAndHalf" },
             { name: "reverse", type: "switch", default: false, hiddenWhen: { field: "variant", equals: ["noText", "noImage", "embedOnly"] }, comment: "Swap sides (image left vs right)." },
-            { name: "image", type: "media-single", hiddenWhen: { field: "variant", equals: ["noImage", "embedHalfAndHalf", "embedOnly", "embed30", "embed70", "textAndText"] } },
+            { name: "image", type: "media-multi", comment: "Stored as an ARRAY of paths (the blueprint sets no maxItems) but the theme renders only the FIRST item, so send [\"/photo.jpg\"].", hiddenWhen: { field: "variant", equals: ["noImage", "embedHalfAndHalf", "embedOnly", "embed30", "embed70", "textAndText"] } },
             { name: "embed", type: "codeeditor", shownWhen: { field: "variant", equals: ["embedHalfAndHalf", "embedOnly", "embed30", "embed70"] }, comment: "Raw embed HTML (iframe etc.)." },
             ...buttonsMixin,
             { name: "headline2", type: "richeditor", shownWhen: { field: "variant", equals: ["textAndText"] }, comment: "Second column text (only when variant is 'textAndText')." },
@@ -83,10 +83,10 @@ exports.BLOCKS = [
         content_group: "Tiles",
         name: "Tiles (grid of cards)",
         description: "Grid of cards (icon + headline + rich text + button each).",
-        whenToUse: "Feature lists, service grids, 'value proposition' card rows,ething lists of related items.",
+        whenToUse: "Feature lists, service grids, 'value proposition' card rows, or any list of related items.",
         base: baseBlock,
         content: [
-            { name: "tiles", type: "taglist", comment: "Array of tile items, each {headline, image, text, buttonLabel1, buttonVariant1, buttonContrast1, buttonLink1, buttonIcon1, buttonBlank1, buttonLabel2, ...}. Use this to list the tiles." },
+            { name: "tiles", type: "repeater", comment: "Array of tile items, each {headline, image, text, buttonLabel1, buttonVariant1, buttonContrast1, buttonLink1, buttonIcon1, buttonBlank1, buttonLabel2, ...}. Use this to list the tiles." },
             { name: "tileLink", type: "switch", default: false, comment: "Whole tile acts as a link." },
             { name: "tileIcon", type: "switch", default: false, comment: "Display icon-only tiles." },
             { name: "contrastHover", type: "switch", default: false },
@@ -102,7 +102,7 @@ exports.BLOCKS = [
                 description: "One repeater item per tile/card.",
                 items: [
                     { name: "headline", type: "text", required: true, comment: "Tile title." },
-                    { name: "image", type: "media-single", comment: "Tile image. Leave empty for text-only tiles." },
+                    { name: "image", type: "media-single", comment: "Tile image: a media library path, or \"\" for a text-only tile." },
                     { name: "text", type: "richeditor", comment: "Tile body text." },
                     ...buttonsMixin,
                 ],
@@ -116,7 +116,7 @@ exports.BLOCKS = [
         whenToUse: "Image-heavy content that benefits from sequential browsing — testimonials, step-by-step walkthroughs, gallery-like rows.",
         base: baseBlock,
         content: [
-            { name: "slides", type: "taglist", comment: "Array of slide items, each {image, headline, text, buttonLabel1, buttonVariant1, ...}." },
+            { name: "slides", type: "repeater", comment: "Array of slide items, each {image, headline, text, buttonLabel1, buttonVariant1, ...}." },
             { name: "gallery", type: "switch", default: false, comment: "Clicking a slide opens the gallery lightbox." },
             { name: "loop", type: "switch", default: false, comment: "Infinite loop playback." },
             { name: "autoWidth", type: "switch", default: false, comment: "Slide width matches image width." },
@@ -149,7 +149,7 @@ exports.BLOCKS = [
         whenToUse: "Long content split into topic tabs (e.g. 'What we do' / 'Who we are' / 'Contact'). Don't use if there are only 1–2 logical sections — use Section instead.",
         base: baseBlock,
         content: [
-            { name: "slides", type: "taglist", comment: "Array of tab items, each {image, headline, text, buttonLabel1, ...}." },
+            { name: "slides", type: "repeater", comment: "Array of tab items, each {image, headline, text, buttonLabel1, ...}." },
             { name: "gallery", type: "switch", default: false },
             { name: "variant", type: "dropdown", enum: ["tabs-horizontal", "tabs-vertical"], default: "tabs-horizontal" },
         ],
@@ -173,7 +173,7 @@ exports.BLOCKS = [
         whenToUse: "FAQs, 'Common questions', or any content the user wants collapsed by default. Each item has a headline + rich text.",
         base: baseBlock,
         content: [
-            { name: "items", type: "taglist", comment: "Array of items, each {headline, text}." },
+            { name: "items", type: "repeater", comment: "Array of items, each {headline, text}." },
             { name: "variant", type: "dropdown", enum: ["default", "outline", "shadow"], default: "default" },
             { name: "firstItemOpen", type: "switch", default: false, comment: "First item is expanded on load." },
             { name: "singleMode", type: "switch", default: false, comment: "Only one item open at a time." },
@@ -205,10 +205,10 @@ exports.BLOCKS = [
         content_group: "Gallery",
         name: "Gallery (masonry)",
         description: "Masonry image gallery.",
-        whenToUse: "Multiple images shown together in a grid. Lightbox on expand. Use 'images' array (must be empty in MCP — human fills via backend).",
+        whenToUse: "Multiple images shown together in a grid, lightbox on expand. 'images' is an array of media library paths and every item renders.",
         base: baseBlock,
         content: [
-            { name: "images", type: "media-multi", comment: "Array of image paths; MUST be empty in MCP." },
+            { name: "images", type: "media-multi", comment: "Array of media library paths, e.g. [\"/a.jpg\",\"/b.jpg\"]. Each must already exist; find them with search_media." },
             { name: "columns", type: "number", default: 3, comment: "Number of columns (blank = 3)." },
         ],
     },
@@ -216,7 +216,7 @@ exports.BLOCKS = [
         content_group: "Downloads",
         name: "Downloads",
         description: "List of downloadable files (name + icon + description + file each).",
-        whenToUse: "Document / spec / PDF lists. Each row has a name, an icon dropdown, an optional description, and a file (which must remain empty in MCP — human fills).",
+        whenToUse: "Document / spec / PDF lists. Each row has a name, an icon dropdown, an optional description, and a file taken from the media library.",
         base: baseBlock,
         content: [],
         nestedRepeaters: [
@@ -227,7 +227,7 @@ exports.BLOCKS = [
                     { name: "name", type: "text", required: true },
                     { name: "icon", type: "dropdown", enum: ["none", "file", "pdf", "dl"], default: "none" },
                     { name: "description", type: "richeditor" },
-                    { name: "file", type: "media-single", comment: "Must stay empty — human fills via backend." },
+                    { name: "file", type: "media-single", comment: "Media library path to the document, e.g. \"/docs/spec.pdf\". No mode restriction, so any file type is accepted." },
                 ],
             },
         ],
@@ -245,7 +245,7 @@ exports.BLOCKS = [
                 description: "One repeater item per column. Each column has {blockId, builder: [...blocks]} where builder is a full Builder array.",
                 items: [
                     { name: "blockId", type: "text", comment: "Optional column anchor id (used for the column wrapper)." },
-                    { name: "builder", type: "taglist", comment: "Array of block objects (same shape as top-level 'builder' in a page). You can nest any block here, including another Columns (avoid deep nesting)." },
+                    { name: "builder", type: "repeater", comment: "Array of block objects (same shape as top-level 'builder' in a page). You can nest any block here, including another Columns (avoid deep nesting)." },
                 ],
             },
         ],
@@ -254,7 +254,7 @@ exports.BLOCKS = [
         content_group: "Prefill",
         name: "Prefill (reusable block template)",
         description: "References a Prefill Tailor entry whose builder content is shared across pages — edit once, updates everywhere it is used.",
-        whenToUse: "For shared/global blocks like a newsletter CTA, a contact form snippet, or a footer-style band that should appear the same on many pages. The actual block content lives on the Prefill entry — get its id via `list_prefills`. Don't use this for one-off content.",
+        whenToUse: "For shared/global blocks like a newsletter CTA, a contact form snippet, or a footer-style band that should appear the same on many pages. The actual block content lives on the Prefill entry — get its id via `list_prefills`. Whenever the same section would appear on more than one page, do NOT copy it: keep it in one Prefill (create_prefill, or extract_block_to_prefill for an existing page block) and insert this block on every page that needs it. Don't use this for one-off content.",
         base: baseBlock,
         content: [],
         referencing: { kind: "prefill", location: "content", jsonKey: "block", column: "block_id" },
@@ -288,7 +288,7 @@ exports.BLOCKS = [
         whenToUse: "Brand/logos row, partners strip, photo strip with horizontal scroll. Optional auto-scroll.",
         base: baseBlock,
         content: [
-            { name: "images", type: "media-multi", comment: "Array of image paths; MUST be empty in MCP." },
+            { name: "images", type: "media-multi", comment: "Array of media library paths; every item renders, side by side." },
             { name: "centered", type: "switch", default: false, comment: "Center the strip horizontally." },
             { name: "autoScroll", type: "switch", default: false },
             { name: "stopOnHover", type: "switch", default: false },
@@ -308,7 +308,30 @@ exports.BLOCKS = [
         ],
     },
 ];
-exports.BLOCK_CATALOGUE_TEXT = exports.BLOCKS.map((b) => {
+/**
+ * Lands once, ahead of every block, rather than being repeated per field.
+ * Media is the part of a block payload that models get wrong most often.
+ */
+const MEDIA_PREAMBLE = [
+    "## Media fields",
+    "",
+    "`media-single` takes ONE path string; `media-multi` takes an ARRAY of path",
+    "strings. Paths are root-relative with a leading slash, exactly as stored:",
+    '"/hero.jpg", "/logos/brand.svg".',
+    "",
+    "The file must ALREADY EXIST in the library. Call search_media (by name) or",
+    "list_media (by folder) and copy the `path` from the result — never the `url`,",
+    "and never invent a filename: a path that does not resolve is rejected. This",
+    "server cannot upload. If what the user wants is not in the library, say so",
+    "and ask them to add it in Backend > Media.",
+    "",
+    'To leave a field unset send "" (single) or [] (multi). On update_block a',
+    "media key you OMIT keeps whatever is stored, while a key you SEND is written",
+    'as given — so sending "" is how you clear an image.',
+    "",
+    "",
+].join("\n");
+exports.BLOCK_CATALOGUE_TEXT = MEDIA_PREAMBLE + exports.BLOCKS.map((b) => {
     const lines = [];
     lines.push(`### ${b.name} (content_group="${b.content_group}")`);
     lines.push(`When to use: ${b.whenToUse}`);

package/dist/index.js

@@ -13,6 +13,17 @@ const CATALOGUE_URI = "frameworc://blocks";
 (0, sites_js_1.warnIfWorldReadable)();
 const session = new session_js_1.Session();
 const client = new api_client_js_1.ApiClient(session);
+/** Resolves the block-op target from page_id / prefill_id args. */
+function blockHost(args) {
+    const hasPage = args.page_id !== undefined && args.page_id !== null;
+    const hasPrefill = args.prefill_id !== undefined && args.prefill_id !== null;
+    if (hasPage === hasPrefill) {
+        throw new Error("Pass exactly one of page_id / prefill_id.");
+    }
+    return hasPrefill
+        ? { type: "prefill", id: Number(args.prefill_id) }
+        : { type: "page", id: Number(args.page_id) };
+}
 const tools = [
     {
         name: "use_site",
@@ -82,7 +93,7 @@ const tools = [
     },
     {
         name: "create_page",
-        description: "Create a new FrameworC page. Send a `page` object (title, slug, fullslug, is_enabled, metaTitle, metaDescription, menuStyle, menuHide) and a `builder` array of block objects per the frameworc://blocks resource. Pages are created with is_enabled=false (draft) by default. Media fields must be left empty — the human fills them in the backend. After creating, surface the returned page id so the user can assign images and flip is_enabled to publish.",
+        description: "Create a new FrameworC page. Send a `page` object (title, slug, fullslug, is_enabled, metaTitle, metaDescription, menuStyle, menuHide) and a `builder` array of block objects per the frameworc://blocks resource. Pages are created with is_enabled=false (draft) by default. Media fields take a media library path such as \"/images/hero.jpg\" — find one with search_media or list_media; the file must already exist, as this server cannot upload. Leave a media field as \"\" (single) or [] (multi) to leave it unset. After creating, surface the returned page id so the user can review and flip is_enabled to publish.",
         inputSchema: {
             type: "object",
             properties: {
@@ -103,7 +114,7 @@ const tools = [
     },
     {
         name: "update_page",
-        description: "Update an existing page. Partial updates: send only `page` (meta edits) and/or `builder` (full rebuild — all existing blocks are deleted and the new array is written). To only add/edit/remove one block, use add_block / update_block / remove_block instead.",
+        description: "Update an existing page. Partial updates: send only `page` (meta edits) and/or `builder` (full rebuild — all existing blocks are deleted and the new array is written). A rebuild also rewrites media, so send the builder array exactly as get_page returned it, paths included, or the existing images are cleared. To add, edit or remove one block, prefer add_block / update_block / remove_block. `page.ogImage` takes a media library path.",
         inputSchema: {
             type: "object",
             properties: {
@@ -130,86 +141,352 @@ const tools = [
     },
     {
         name: "add_block",
-        description: "Append a block to a page's builder. Optional `position` (1-indexed) inserts at that position; otherwise appends at the end. The `block` arg has the shape { content_group, base, content, form? } per the catalogue — `form` sits at block level, while Menu and Prefill references live at `content.menu` and `content.block`.",
+        description: "Append a block to a page's builder — or a prefill's, by passing prefill_id instead of page_id. Optional `position` (1-indexed) inserts at that position; otherwise appends at the end. The `block` arg has the shape { content_group, base, content, form? } per the catalogue — `form` sits at block level, while Menu and Prefill references live at `content.menu` and `content.block`. If the section you are adding already exists on another page, do NOT copy it: reference its Prefill entry with a `Prefill` block (extract_block_to_prefill turns an existing page block into one).",
         inputSchema: {
             type: "object",
             properties: {
-                page_id: { type: "integer" },
+                page_id: { type: "integer", description: "Page to edit. Pass exactly one of page_id / prefill_id." },
+                prefill_id: { type: "integer", description: "Prefill entry to edit instead of a page." },
                 block: { type: "object" },
                 position: { type: "integer" },
                 site_url: { type: "string" },
                 site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
-            required: ["page_id", "block"],
+            required: ["block"],
         },
     },
     {
         name: "update_block",
-        description: "Replace a single block by id (the row id returned by get_page's builder[].id). The new `block` must include `content_group` (matching or changing the block type) plus `base` + `content`.",
+        description: "Replace a single block by id (the row id from get_page's builder[].id) on a page — or a prefill via prefill_id. The new `block` must include `content_group` plus `base` + `content`. The block is replaced, not patched: the returned row id is NEW. A media field you OMIT is inherited from the old block; one you SEND is written verbatim, so sending \"\" (or [] for a multi field) is how you clear an image. Keep each repeater row's `id` from get_page so media follows the right row. Inheritance is skipped when you change content_group. Other blocks are untouched.",
         inputSchema: {
             type: "object",
             properties: {
-                page_id: { type: "integer" },
+                page_id: { type: "integer", description: "Page to edit. Pass exactly one of page_id / prefill_id." },
+                prefill_id: { type: "integer", description: "Prefill entry to edit instead of a page." },
                 block_id: { type: "integer" },
                 block: { type: "object" },
                 site_url: { type: "string" },
                 site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
-            required: ["page_id", "block_id", "block"],
+            required: ["block_id", "block"],
         },
     },
     {
         name: "remove_block",
-        description: "Remove a block by its row id from the page's builder.",
+        description: "Remove a block by its row id from a page's builder (or a prefill's via prefill_id). Remaining blocks keep their ids; ordering closes the gap.",
         inputSchema: {
             type: "object",
             properties: {
-                page_id: { type: "integer" },
+                page_id: { type: "integer", description: "Page to edit. Pass exactly one of page_id / prefill_id." },
+                prefill_id: { type: "integer", description: "Prefill entry to edit instead of a page." },
                 block_id: { type: "integer" },
                 site_url: { type: "string" },
                 site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
-            required: ["page_id", "block_id"],
+            required: ["block_id"],
         },
     },
     {
         name: "reorder_blocks",
-        description: "Reorder blocks. Send every block row id in the desired order (all existing block ids must be present, no extras).",
+        description: "Reorder blocks on a page (or a prefill via prefill_id). Send every block row id in the desired order (all existing block ids must be present, no extras).",
         inputSchema: {
             type: "object",
             properties: {
-                page_id: { type: "integer" },
+                page_id: { type: "integer", description: "Page to edit. Pass exactly one of page_id / prefill_id." },
+                prefill_id: { type: "integer", description: "Prefill entry to edit instead of a page." },
                 order: { type: "array", items: { type: "integer" } },
                 site_url: { type: "string" },
                 site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
-            required: ["page_id", "order"],
+            required: ["order"],
+        },
+    },
+    {
+        name: "extract_block_to_prefill",
+        description: "Move an existing page block into a NEW Prefill entry and replace it in place with a `Prefill` reference block. Lossless: assigned media survives the move (requires the frameworcmcp plugin at v1.2.0 or newer; older versions silently dropped it). Use this whenever a section should appear on more than one page: extract it once, then add_block a `Prefill` block ({content_group:'Prefill', content:{block:<prefill id>}}) on the other pages. This is the intended FrameworC workflow; never copy the same section onto multiple pages.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page_id: { type: "integer" },
+                block_id: { type: "integer", description: "Row id of the block to extract." },
+                title: { type: "string", description: "Title for the new Prefill entry, e.g. 'Newsletter CTA'." },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["page_id", "block_id", "title"],
         },
     },
     {
         name: "list_forms",
-        description: "List Form Tailor entries available for the `Form` block's block-level `form` key.",
+        description: "List Form entries (id, title, slug, field_count, ...). Use get_form for a form's fields, create_form / update_form / delete_form for CRUD, and the id for the `Form` block's block-level `form` key.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+        },
+    },
+    {
+        name: "get_form_schema",
+        description: "Fetch the live field-group catalogue for Form entries from the CMS: every fwcFields group with its exact fields, enums and defaults, plus the form-level fields. Use before create_form / update_form when unsure of the shape.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
         },
     },
+    {
+        name: "get_form",
+        description: "Fetch one Form entry including its fwcFields rows (each {id, group, ...fields}).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "create_form",
+        description: "Create a Form entry. Payload: {form: {title (required), headline?, recipients?: [emails], is_enabled?}, fwcFields?: [rows]}. Each row names its `group` — one of: section, text, number, email, phone, textarea, file, select, checkbox, radio, agreement — plus that group's fields: input groups take {label, placeholder?, name (required, unique), fieldId?, required?, width?: full|half|third|twoThirds}; select/checkbox/radio add options: [{value, label}]; agreement adds text (rich HTML); section takes only content (rich HTML, not an input). Call get_form_schema when unsure of a group's exact fields. Reference the created form from a page with a `Form` block ({content_group:'Form', form:<id>, content:{variant:...}}).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payload: {
+                    type: "object",
+                    properties: { form: { type: "object" }, fwcFields: { type: "array" } },
+                    required: ["form"],
+                },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["payload"],
+        },
+    },
+    {
+        name: "update_form",
+        description: "Update a Form entry. `form` merges scalar fields; if `fwcFields` is present the field rows are fully rebuilt from the array (send ALL rows, not a diff — they carry no media, so nothing is lost).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                payload: { type: "object", properties: { form: { type: "object" }, fwcFields: { type: "array" } } },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id", "payload"],
+        },
+    },
+    {
+        name: "delete_form",
+        description: "Delete a Form entry. Refused with a 422 naming the referencing pages if any `Form` block still points at it; pass force:true to delete anyway.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                force: { type: "boolean" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
+        },
+    },
     {
         name: "list_menus",
-        description: "List Menu Tailor entries available for the `MenuBlock`'s `content.menu` key.",
+        description: "List Menu entries (id, title, item_count, ...). Use get_menu / create_menu / update_menu / delete_menu for CRUD, and the id for `content.menu` on a MenuBlock or the `nav` field of the Navigation/Footer singles.",
         inputSchema: {
             type: "object",
-            properties: { site_url: { type: "string" } },
+            properties: {
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+        },
+    },
+    {
+        name: "get_menu",
+        description: "Fetch one Menu entry including its navigation tree (items {id, title, url, anchor, blank, children?}).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "create_menu",
+        description: "Create a Menu entry. Payload: {menu: {title (required)}, navigation?: [items]}. Each item: {title (required), url, anchor?, blank?, children?: [items]}. `url` is a string ('/', '/kontakt#form', full URL) OR {page_id: n} to link a FrameworC page robustly. Max 2 levels — children may not have children.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payload: {
+                    type: "object",
+                    properties: { menu: { type: "object" }, navigation: { type: "array" } },
+                    required: ["menu"],
+                },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["payload"],
+        },
+    },
+    {
+        name: "update_menu",
+        description: "Update a Menu entry. `menu` merges title/slug/is_enabled; if `navigation` is present the whole tree is replaced from the array (send ALL items — they carry no media).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                payload: { type: "object", properties: { menu: { type: "object" }, navigation: { type: "array" } } },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id", "payload"],
+        },
+    },
+    {
+        name: "delete_menu",
+        description: "Delete a Menu entry. Refused with a 422 naming the referencing hosts (MenuBlocks, Navigation/Footer singles) if still referenced; pass force:true to delete anyway.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                force: { type: "boolean" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
         },
     },
     {
         name: "list_prefills",
-        description: "List Prefill Tailor entries available for the `Prefill` block's `content.block` key.",
+        description: "List Prefill entries (id, title, block_count, ...). Prefills hold sections shared across pages; reference one from a page with a `Prefill` block ({content_group:'Prefill', content:{block:<id>}}). Use get_prefill / create_prefill / update_prefill / delete_prefill for CRUD.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+        },
+    },
+    {
+        name: "get_prefill",
+        description: "Fetch one Prefill entry including its builder blocks — same block shape as get_page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "create_prefill",
+        description: "Create a Prefill entry — a reusable section shared across pages. Payload: {prefill: {title (required), slug?}, builder?: [blocks]} with the SAME block shape as create_page. When several pages need the same section, create the Prefill FIRST and reference it from each page with a `Prefill` block instead of duplicating the section. (To factor out a section that already exists on a page, use extract_block_to_prefill instead.) Per-block edits work via add_block/update_block/remove_block/reorder_blocks with prefill_id.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payload: {
+                    type: "object",
+                    properties: { prefill: { type: "object" }, builder: { type: "array" } },
+                    required: ["prefill"],
+                },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["payload"],
+        },
+    },
+    {
+        name: "update_prefill",
+        description: "Update a Prefill entry. `prefill` merges title/slug/is_enabled; a `builder` array fully rebuilds the blocks (prefer the per-block tools with prefill_id — a rebuild rewrites media from your payload, so send the blocks as get_prefill returned them or the images are cleared). Edits apply everywhere the prefill is referenced.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                payload: { type: "object", properties: { prefill: { type: "object" }, builder: { type: "array" } } },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id", "payload"],
+        },
+    },
+    {
+        name: "delete_prefill",
+        description: "Delete a Prefill entry. Refused with a 422 naming the referencing pages if any `Prefill` block still points at it; pass force:true to delete anyway (the referencing blocks would break).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                force: { type: "boolean" },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        name: "get_settings",
+        description: "Read the FrameworC plugin settings exposed over the API: navbar layout options and the custom SCSS variables. Settings are GLOBAL (not per multisite site). Integration/secret settings are not accessible by design.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
         },
     },
+    {
+        name: "update_settings",
+        description: "Update FrameworC plugin settings. `fields` is a partial map; writable keys: navigation_width (full|container), navigation_align (left|center|right), navigation_mobile_extra_links (navbar|open), variable_variablesScss (SCSS overriding the design tokens). Settings are GLOBAL and affect the whole install — confirm with the user first. Integration/secret settings cannot be read or written through this API by design.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fields: { type: "object", description: "Field name => value map (partial)." },
+                site_url: { type: "string" },
+            },
+            required: ["fields"],
+        },
+    },
+    {
+        name: "list_media",
+        description: "Browse the media library one folder at a time. Returns {folder, parent, folders:[{path,name,item_count}], files:[{path,name,file_type,extension,size,last_modified,url}], total_files, truncated}. To put a file on a page, write its `path` — the root-relative form with a leading slash, e.g. \"/logos/brand.svg\" — into a mediafinder field; never the `url`. This server CANNOT upload: if the file the user wants is not here, say so and ask them to add it in Backend > Media. Prefer search_media when you know part of the name. Note that `file_type` buckets follow the install's media config (SVG may report as image or as document), so treat `type` as a convenience filter rather than a guarantee. The library is global: site_id is accepted and ignored.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                folder: { type: "string", description: "Folder to list, root-relative with a leading slash. Defaults to \"/\". A folder that does not exist is a 404." },
+                type: { type: "string", enum: ["image", "video", "audio", "document"], description: "Filter files by kind." },
+                sort: { type: "string", enum: ["title", "size", "modified"], description: "Defaults to title." },
+                direction: { type: "string", enum: ["asc", "desc"], description: "Defaults to asc." },
+                limit: { type: "integer", description: "Max files to return (default 100, max 500). Folders are never paged." },
+                offset: { type: "integer", description: "Files to skip, for paging." },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Accepted and ignored; the media library is global." },
+            },
+        },
+    },
+    {
+        name: "search_media",
+        description: "Find files anywhere in the media library by name. The query is lowercased and split on spaces, and EVERY word must appear somewhere in the file's full path — so \"logo dark\" matches \"/brand/logo-dark.svg\" and \"2024 pdf\" matches \"/reports/2024-annual.pdf\". It matches the whole path, not just the filename. Returns the same file shape as list_media; write the returned `path` into a mediafinder field. Prefer this over list_media whenever the user names a file. This server cannot upload files. Filenames containing + # % or ! are not addressable through this API (an October media library limit), so do not retry those.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                q: { type: "string", description: "Search words; at least 2 characters." },
+                folder: { type: "string", description: "Optional: keep only results inside this folder subtree." },
+                type: { type: "string", enum: ["image", "video", "audio", "document"] },
+                sort: { type: "string", enum: ["title", "size", "modified"] },
+                direction: { type: "string", enum: ["asc", "desc"] },
+                limit: { type: "integer", description: "Max files (default 50, max 200)." },
+                offset: { type: "integer", description: "Files to skip, for paging." },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Accepted and ignored; the media library is global." },
+            },
+            required: ["q"],
+        },
+    },
     {
         name: "get_block_schema",
         description: "Get the JSON schema + usage notes for one block by content_group name. Fetched live from the CMS, which derives it from the actual Tailor blueprints, so it is always current. Use this to recall field enums, defaults and conditional visibility.",
@@ -238,7 +515,7 @@ const tools = [
     },
     {
         name: "update_page_meta",
-        description: "Update a per-site single (Meta / Navigation / Footer). Send only the fields you want to change, e.g. {handle:'Meta', fields:{metaTitle:'...', description:'...'}}. Media fields must be left empty. Affects every page on that site, so confirm with the user first.",
+        description: "Update a per-site single (Meta / Navigation / Footer). Send only the fields you want to change, e.g. {handle:'Meta', fields:{metaTitle:'...', description:'...'}}. Media fields take a media library path from search_media: Meta.ogImage and Navigation.logo / logoDark are single paths, while Footer.logo is an ARRAY of paths of which only the first renders. Affects every page on that site, so confirm with the user first.",
         inputSchema: {
             type: "object",
             properties: {
@@ -252,13 +529,14 @@ const tools = [
     },
     {
         name: "create_translation",
-        description: "Create the sibling of an existing page on another multisite site, linked to the original so the language switcher connects them. Pass target_site_id, and optionally `page` (title/slug overrides) and `builder` (the translated blocks). Omitting builder copies nothing — the translation starts empty, ready for you to fill.",
+        description: "Create the sibling of an existing page — or Prefill entry, with prefill:true — on another multisite site, linked to the original so the language switcher connects them. Pass target_site_id, and optionally `page` (title/slug overrides) and `builder` (the translated blocks). Omitting builder copies nothing — the translation starts empty, ready for you to fill. Form and Menu entries have no translation linking; create them per site with site_id instead.",
         inputSchema: {
             type: "object",
             properties: {
-                id: { type: "integer", description: "Source page id." },
+                id: { type: "integer", description: "Source page (or prefill) id." },
                 target_site_id: { type: "integer", description: "Site to create the translation on." },
-                source_site_id: { type: "integer", description: "Site the source page lives on. Defaults to the pinned CMS site." },
+                source_site_id: { type: "integer", description: "Site the source record lives on. Defaults to the pinned CMS site." },
+                prefill: { type: "boolean", description: "Set true when id is a Prefill entry, not a page." },
                 page: { type: "object" },
                 builder: { type: "array" },
                 site_url: { type: "string" },
@@ -268,7 +546,7 @@ const tools = [
         },
     },
 ];
-const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.3.0" }, { capabilities: { tools: {}, resources: {} } });
+const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.5.0" }, { capabilities: { tools: {}, resources: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools,
 }));
@@ -371,37 +649,127 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "create_translation": {
-                const r = await client.createTranslation(Number(args.id), Number(args.target_site_id), { page: args.page ?? {}, builder: args.builder }, args.source_site_id !== undefined ? Number(args.source_site_id) : undefined);
+                const payload = { page: args.page ?? {}, builder: args.builder };
+                const source = args.source_site_id !== undefined ? Number(args.source_site_id) : undefined;
+                const r = args.prefill
+                    ? await client.createPrefillTranslation(Number(args.id), Number(args.target_site_id), { prefill: args.page ?? {}, builder: args.builder }, source)
+                    : await client.createTranslation(Number(args.id), Number(args.target_site_id), payload, source);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "add_block": {
-                const r = await client.addBlock(Number(args.page_id), args.block, args.position !== undefined ? Number(args.position) : undefined, site);
+                const r = await client.addBlock(blockHost(args), args.block, args.position !== undefined ? Number(args.position) : undefined, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "update_block": {
-                const r = await client.updateBlock(Number(args.page_id), Number(args.block_id), args.block, site);
+                const r = await client.updateBlock(blockHost(args), Number(args.block_id), args.block, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "remove_block": {
-                const r = await client.removeBlock(Number(args.page_id), Number(args.block_id), site);
+                const r = await client.removeBlock(blockHost(args), Number(args.block_id), site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "reorder_blocks": {
-                const r = await client.reorderBlocks(Number(args.page_id), args.order, site);
+                const r = await client.reorderBlocks(blockHost(args), args.order, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "extract_block_to_prefill": {
+                const r = await client.extractBlockToPrefill(Number(args.page_id), Number(args.block_id), args.title ?? "", site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "list_forms": {
                 const r = await client.listForms(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
+            case "get_form_schema": {
+                const r = await client.getFormSchema();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "get_form": {
+                const r = await client.getForm(Number(args.id), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "create_form": {
+                const r = await client.createForm(args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_form": {
+                const r = await client.updateForm(Number(args.id), args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "delete_form": {
+                const r = await client.deleteForm(Number(args.id), Boolean(args.force), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
             case "list_menus": {
                 const r = await client.listMenus(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
+            case "get_menu": {
+                const r = await client.getMenu(Number(args.id), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "create_menu": {
+                const r = await client.createMenu(args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_menu": {
+                const r = await client.updateMenu(Number(args.id), args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "delete_menu": {
+                const r = await client.deleteMenu(Number(args.id), Boolean(args.force), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
             case "list_prefills": {
                 const r = await client.listPrefills(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
+            case "get_prefill": {
+                const r = await client.getPrefill(Number(args.id), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "create_prefill": {
+                const r = await client.createPrefill(args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_prefill": {
+                const r = await client.updatePrefill(Number(args.id), args.payload, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "delete_prefill": {
+                const r = await client.deletePrefill(Number(args.id), Boolean(args.force), site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "list_media": {
+                const r = await client.listMedia({
+                    folder: args.folder,
+                    type: args.type,
+                    sort: args.sort,
+                    direction: args.direction,
+                    limit: args.limit,
+                    offset: args.offset,
+                }, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "search_media": {
+                const r = await client.searchMedia(String(args.q ?? ""), {
+                    folder: args.folder,
+                    type: args.type,
+                    sort: args.sort,
+                    direction: args.direction,
+                    limit: args.limit,
+                    offset: args.offset,
+                }, site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "get_settings": {
+                const r = await client.getSettings();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_settings": {
+                const r = await client.updateSettings(args.fields ?? {});
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
             case "get_page_meta": {
                 const r = await client.getSingle(String(args.handle), site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };

package/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "frameworc-mcp",
-  "version": "0.3.0",
-  "description": "MCP server for the FrameworC OctoberCMS plugin — programmatically create/edit FrameworC pages and blocks.",
-  "license": "MIT",
-  "type": "commonjs",
-  "bin": {
-    "frameworc-mcp": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "publishConfig": {
-    "@yourorg:registry": "https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/"
-  }
-}
+{
+  "name": "frameworc-mcp",
+  "version": "0.5.1",
+  "description": "MCP server for the FrameworC OctoberCMS plugin — programmatically create/edit FrameworC pages and blocks.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "frameworc-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "@yourorg:registry": "https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/"
+  }
+}