frameworc-mcp 0.4.0 → 0.6.1

package/README.md

@@ -9,7 +9,7 @@ A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Cla
 - 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)
+- Reads and writes the per-site singles (Meta & SEO, Navigation, Footer) and the FrameworC settings (global navbar options and SCSS, per-site SCSS; 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
@@ -96,7 +96,7 @@ 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 suite incl. the `crscompany/frameworcmcp` plugin (v1.1.0 or newer).
+1. Spin up the new OctCMS install with the FrameworC suite incl. the `crscompany/frameworcmcp` plugin (v1.3.0 or newer; media assignment needs v1.2.0, per-site settings need v1.3.0 with FrameworC v1.10.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.
@@ -109,7 +109,7 @@ 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 (0.4.0)
+## Tools (0.5.0)
 
 | Tool | Description |
 |---|---|
@@ -124,10 +124,10 @@ No env var, no chat-client config edit, no ToolHive touch, no repo push. The who
 | `delete_page(id)` | Soft-delete a page. |
 | `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; human-assigned media carried over unless the type changes). |
+| `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, media survives) and reference it in place. |
+| `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`. |
@@ -136,8 +136,11 @@ No env var, no chat-client config edit, no ToolHive touch, no repo push. The who
 | `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_settings` / `update_settings(fields)` | Global FrameworC settings: navbar options + global custom SCSS (`styles_globalScss`). Integration secrets are not exposed. |
+| `get_site_settings` / `update_site_settings(fields)` | Per-site FrameworC settings: custom SCSS for one site (`siteScss`), compiled after the global SCSS. |
 | `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`.
 
@@ -197,14 +200,23 @@ Form and Menu entries have no translation linking — create them per site by pa
 
 ### 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.
+- 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));
@@ -181,6 +199,13 @@ class ApiClient {
     updateSettings(fields) {
         return this.request("/settings", { method: "PATCH", body: JSON.stringify({ fields }) });
     }
+    // --- FrameworC settings (per site) -------------------------------------
+    getSiteSettings(siteId) {
+        return this.request(this.q("/site-settings", siteId));
+    }
+    updateSiteSettings(fields, siteId) {
+        return this.request("/site-settings", { method: "PATCH", body: this.b({ fields }, siteId) });
+    }
     // --- 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,14 +35,14 @@ 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." },
     { name: "responsiveHide", type: "checkboxlist", enum: ["desktop", "tablet", "mobile"], comment: "Which devices to hide this block on." },
 ];
 const sectionVariants = [
-    "halfAndHalf", "noText", "noImage", "textAndText", "img70", "text70",
+    "halfAndHalf", "imgBleed", "noText", "noImage", "textAndText", "img70", "text70",
     "embedHalfAndHalf", "embed70", "embed30", "embedOnly",
 ];
 exports.BLOCKS = [
@@ -53,9 +53,11 @@ 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." },
+            { name: "fullVideo", type: "media-single", comment: "Only used when isVideoBg is on. Media library path to the full-length video; a play button opens it in a lightbox popup over the page." },
+            { name: "fullVideoLabel", type: "text", comment: "Only used when isVideoBg is on. Label of the button that opens fullVideo." },
             ...buttonsMixin,
             { name: "fullHeight", type: "switch", default: true },
             { name: "contrast", type: "switch", default: false, comment: "Use contrast (light-on-dark) text for the headline when the background image is dark." },
@@ -66,12 +68,13 @@ exports.BLOCKS = [
         content_group: "Section",
         name: "Section",
         description: "Text + image / embed in a configurable column layout. The most common content block.",
-        whenToUse: "Default choice for any paragraph + image content. Pick a variant that matches the proportion of text to visual. Use 'textAndText' for two text columns (e.g. a feature comparison). Use an 'embed*' variant when you have a YouTube video, map iframe, etc.",
+        whenToUse: "Default choice for any paragraph + image content. Pick a variant that matches the proportion of text to visual. Use 'imgBleed' for an image running to the edge of the viewport next to half-width text. Use 'textAndText' for two text columns (e.g. a feature comparison). Use an 'embed*' variant when you have a YouTube video, map iframe, etc.",
         base: baseBlock,
         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: "reverseMobile", type: "switch", default: false, hiddenWhen: { field: "variant", equals: ["noText", "noImage", "embedOnly"] }, comment: "On mobile the columns stack; this flips their stacking order." },
+            { 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')." },
@@ -102,7 +105,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,
                 ],
@@ -205,10 +208,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 +219,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 +230,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." },
                 ],
             },
         ],
@@ -288,7 +291,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 +311,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

@@ -93,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: {
@@ -114,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: {
@@ -157,7 +157,7 @@ const tools = [
     },
     {
         name: "update_block",
-        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. Media a human assigned in the backend is carried over automatically wherever your payload leaves the field empty — unless you change content_group. Other blocks are untouched.",
+        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: {
@@ -203,7 +203,7 @@ const tools = [
     },
     {
         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 — media a human assigned survives the move. 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.",
+        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: {
@@ -405,7 +405,7 @@ const tools = [
     },
     {
         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 loses human-assigned media). Edits apply everywhere the prefill is referenced.",
+        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: {
@@ -433,7 +433,7 @@ const tools = [
     },
     {
         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.",
+        description: "Read the FrameworC plugin settings exposed over the API: navbar layout options and the global custom SCSS. Settings are GLOBAL (not per multisite site); per-site SCSS lives in get_site_settings. Integration/secret settings are not accessible by design.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
@@ -441,7 +441,7 @@ const tools = [
     },
     {
         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.",
+        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), styles_globalScss (SCSS compiled into every site before that site's own SCSS, so its $variables and mixins are usable there; SCSS that does not compile is rejected). 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: {
@@ -451,6 +451,66 @@ const tools = [
             required: ["fields"],
         },
     },
+    {
+        name: "get_site_settings",
+        description: "Read the per-site FrameworC settings: siteScss, the custom SCSS for one multisite site. It is compiled after the global styles_globalScss from get_settings, so it can use that SCSS's $variables and mixins.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+        },
+    },
+    {
+        name: "update_site_settings",
+        description: "Update the per-site FrameworC settings. `fields` is a partial map; writable key: siteScss (SCSS for this site only, compiled after the global SCSS; SCSS that does not compile is rejected). Affects every page on that site, so confirm with the user first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                fields: { type: "object", description: "Field name => value map (partial)." },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            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.",
@@ -479,7 +539,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: {
@@ -510,7 +570,7 @@ const tools = [
         },
     },
 ];
-const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.4.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,
 }));
@@ -704,6 +764,28 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
                 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) }] };
@@ -712,6 +794,14 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
                 const r = await client.updateSettings(args.fields ?? {});
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
+            case "get_site_settings": {
+                const r = await client.getSiteSettings(site);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_site_settings": {
+                const r = await client.updateSiteSettings(args.fields ?? {}, site);
+                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.4.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.6.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/"
+  }
+}