frameworc-mcp 0.6.1 → 0.7.0

package/README.md

@@ -1,243 +1,246 @@
-# @yourorg/frameworc-mcp
-
-A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude / Cursor / opencode / other AI chat clients create and edit pages built with the **FrameworC** OctoberCMS plugin. One MCP process serves any number of OctCMS installs — you tell the chat which site to work on by calling `use_site`.
-
-## What it does
-
-- 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 — 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 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
-
-The chat-side flow (text → blocks) is **LLM-native**: you paste a markdown page (or upload `.docx` / `.pdf` and instruct Claude to convert it to markdown), Claude reads the `frameworc://blocks` resource once, segments the content into blocks, calls `list_forms` / `list_menus` / `list_prefills` as needed, then calls `create_page` with the assembled JSON. The MCP simply forwards authenticated HTTPS calls to the OctCMS install.
-
-## Architecture
-
-```
-chat client (Claude Desktop / opencode / Cursor / Cline / Continue / ...)
-  │ stdio JSON-RPC
-  ▼
-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 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 backend under `Settings → FrameworC → MCP API`, and your laptop keeps the URL → token map in one local file.
-
-## Install
-
-```bash
-git clone <your-gitlab-url>/frameworc-mcp.git
-cd frameworc-mcp
-npm install
-npm run build
-```
-
-(Optional) publish to your GitLab group's npm registry so colleagues can `npx` it without a clone — see [Publishing](#publishing) below.
-
-## Claude Desktop config
-
-Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Linux: `~/.config/Claude/`):
-
-```json
-{
-  "mcpServers": {
-    "frameworc": {
-      "command": "npx",
-      "args": ["-y", "@yourorg/frameworc-mcp"]
-    }
-  }
-}
-```
-
-If you cloned instead of `npx`-installed, point `args` to your local `dist/index.js`:
-
-```json
-{
-  "mcpServers": {
-    "frameworc": {
-      "command": "node",
-      "args": ["/absolute/path/to/frameworc-mcp/dist/index.js"]
-    }
-  }
-}
-```
-
-No env vars. Restart Claude → the `frameworc` tools appear. On first start the MCP creates `~/.config/frameworc/sites.json` with a template; edit it with your real sites (see below).
-
-## Per-site token file — `~/.config/frameworc/sites.json`
-
-The MCP stores one bearer token per OctCMS install in this file on your laptop. It's the only credential store. Format:
-
-```json
-{
-  "sites": [
-    { "label": "Client A prod",     "url": "https://clienta.test",          "token": "AAA..." },
-    { "label": "Client A staging",  "url": "https://staging.clienta.test",  "token": "BBB..." },
-    { "label": "Myco",              "url": "https://myco.example",           "token": "CCC..." }
-  ]
-}
-```
-
-- `label` is optional, shown by the `list_sites` tool so the chat can pick a site by name when you say "use the myco site".
-- `url` is matched after normalising trailing slashes — `https://x.test/` and `https://x.test` are the same.
-- `token` is sent as `Authorization: Bearer <token>` on every HTTP call to that site. Never committed to git.
-
-The file is created automatically on first MCP startup (with a template and `0600` perms). Edits are picked up via stat-on-every-tool-call hot-reload — no MCP or chat-client restart needed.
-
-If the file is missing or empty, `use_site` errors with a pointer to where to add it. The `list_sites` tool enumerates configured sites without exposing tokens.
-
-### Adding a new OctCMS site
-
-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.
-
-No env var, no chat-client config edit, no ToolHive touch, no repo push. The whole token map lives in one file on your machine.
-
-### Security
-
-- The file should be `0600` (auto-set on first creation). If you `chmod` it looser, the MCP prints a stderr warning on startup.
-- 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.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 (prefer the per-block tools). |
-| `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). 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 + 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`.
-
-## Resource
-
-- `frameworc://blocks` — reference for all 15 block types (fields, defaults, enums, conditional visibility, nested repeaters, reference fields). The chat reads this once per session; you don't invoke it manually.
-
-## Page-content JSON shape
-
-`create_page` / `update_page` `payload`:
-
-```json
-{
-  "page": {
-    "title": "Contact",
-    "slug": "contact",
-    "fullslug": "contact",
-    "is_enabled": false,
-    "metaTitle": "",
-    "metaDescription": "",
-    "menuStyle": "solid",
-    "menuHide": "no"
-  },
-  "builder": [
-    {
-      "content_group": "Header",
-      "base": {
-        "blockId": "kontakt",
-        "headline": "<h1>Contact us</h1>",
-        "elevated": false,
-        "containerWidth": "default",
-        "backgroundColor": "default",
-        "customCssClass": [],
-        "responsiveHide": []
-      },
-      "content": {
-        "image": "",
-        "imageMobile": "",
-        "isVideoBg": false,
-        "buttonLabel1": "",
-        "buttonLink1": "",
-        "buttonBlank1": false,
-        "fullHeight": true,
-        "contrast": false,
-        "overlay": false
-      }
-    },
-    {
-      "content_group": "Form",
-      "base": { "blockId": "formular", "headline": "<h2>Write us</h2>" },
-      "form": 7,
-      "content": { "variant": "default" }
-    }
-  ]
-}
-```
-
-### Storage encoding (what the MCP understands)
-
-- 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 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.
-
-## Publishing
-
-To publish to your GitLab group's npm registry:
-
-1. Edit `package.json`:
-   - Replace `@yourorg` in `name` and `publishConfig["@yourorg:registry"]` with your actual GitLab scope/group.
-   - Replace `<YOUR-PROJECT-ID>` in `publishConfig["@yourorg:registry"]` with the numeric project id of the `frameworc-mcp` GitLab repo.
-2. Create a GitLab deploy token / project access token with `api` + `write_registry` scope. Add a `.npmrc` at the registry host:
-
-   ```
-   @yourorg:registry=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/
-   //gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/:_authToken=<TOKEN>
-   ```
-3. `npm publish`.
-
-Colleagues then use `npx -y @yourorg/frameworc-mcp` in their `claude_desktop_config.json` (no clone needed).
-
-## License
-
+# @yourorg/frameworc-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets Claude / Cursor / opencode / other AI chat clients create and edit pages built with the **FrameworC** OctoberCMS plugin. One MCP process serves any number of OctCMS installs — you tell the chat which site to work on by calling `use_site`.
+
+## What it does
+
+- 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 — 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 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
+
+The chat-side flow (text → blocks) is **LLM-native**: you paste a markdown page (or upload `.docx` / `.pdf` and instruct Claude to convert it to markdown), Claude reads the `frameworc://blocks` resource once, segments the content into blocks, calls `list_forms` / `list_menus` / `list_prefills` as needed, then calls `create_page` with the assembled JSON. The MCP simply forwards authenticated HTTPS calls to the OctCMS install.
+
+## Architecture
+
+```
+chat client (Claude Desktop / opencode / Cursor / Cline / Continue / ...)
+  │ stdio JSON-RPC
+  ▼
+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 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 backend under `Settings → FrameworC → MCP API`, and your laptop keeps the URL → token map in one local file.
+
+## Install
+
+```bash
+git clone <your-gitlab-url>/frameworc-mcp.git
+cd frameworc-mcp
+npm install
+npm run build
+```
+
+(Optional) publish to your GitLab group's npm registry so colleagues can `npx` it without a clone — see [Publishing](#publishing) below.
+
+## Claude Desktop config
+
+Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Linux: `~/.config/Claude/`):
+
+```json
+{
+  "mcpServers": {
+    "frameworc": {
+      "command": "npx",
+      "args": ["-y", "@yourorg/frameworc-mcp"]
+    }
+  }
+}
+```
+
+If you cloned instead of `npx`-installed, point `args` to your local `dist/index.js`:
+
+```json
+{
+  "mcpServers": {
+    "frameworc": {
+      "command": "node",
+      "args": ["/absolute/path/to/frameworc-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+No env vars. Restart Claude → the `frameworc` tools appear. On first start the MCP creates `~/.config/frameworc/sites.json` with a template; edit it with your real sites (see below).
+
+## Per-site token file — `~/.config/frameworc/sites.json`
+
+The MCP stores one bearer token per OctCMS install in this file on your laptop. It's the only credential store. Format:
+
+```json
+{
+  "sites": [
+    { "label": "Client A prod",     "url": "https://clienta.test",          "token": "AAA..." },
+    { "label": "Client A staging",  "url": "https://staging.clienta.test",  "token": "BBB..." },
+    { "label": "Myco",              "url": "https://myco.example",           "token": "CCC..." }
+  ]
+}
+```
+
+- `label` is optional, shown by the `list_sites` tool so the chat can pick a site by name when you say "use the myco site".
+- `url` is matched after normalising trailing slashes — `https://x.test/` and `https://x.test` are the same.
+- `token` is sent as `Authorization: Bearer <token>` on every HTTP call to that site. Never committed to git.
+
+The file is created automatically on first MCP startup (with a template and `0600` perms). Edits are picked up via stat-on-every-tool-call hot-reload — no MCP or chat-client restart needed.
+
+If the file is missing or empty, `use_site` errors with a pointer to where to add it. The `list_sites` tool enumerates configured sites without exposing tokens.
+
+### Adding a new OctCMS site
+
+1. Spin up the new OctCMS install with the FrameworC suite incl. the `crscompany/frameworcmcp` plugin (v1.4.0 or newer; media assignment needs v1.2.0, per-site settings need v1.3.0 with FrameworC v1.10.0, page JSON-LD fields need v1.4.0 with FrameworC v1.13.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.
+
+No env var, no chat-client config edit, no ToolHive touch, no repo push. The whole token map lives in one file on your machine.
+
+### Security
+
+- The file should be `0600` (auto-set on first creation). If you `chmod` it looser, the MCP prints a stderr warning on startup.
+- 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.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 (prefer the per-block tools). |
+| `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). 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 + 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`.
+
+## Resource
+
+- `frameworc://blocks` — reference for all 15 block types (fields, defaults, enums, conditional visibility, nested repeaters, reference fields). The chat reads this once per session; you don't invoke it manually.
+
+## Page-content JSON shape
+
+`create_page` / `update_page` `payload`:
+
+```json
+{
+  "page": {
+    "title": "Contact",
+    "slug": "contact",
+    "fullslug": "contact",
+    "is_enabled": false,
+    "metaTitle": "",
+    "metaDescription": "",
+    "menuStyle": "solid",
+    "menuHide": "no",
+    "jsonLdPageType": "ContactPage",
+    "jsonLdDisable": false,
+    "jsonLdCustom": ""
+  },
+  "builder": [
+    {
+      "content_group": "Header",
+      "base": {
+        "blockId": "kontakt",
+        "headline": "<h1>Contact us</h1>",
+        "elevated": false,
+        "containerWidth": "default",
+        "backgroundColor": "default",
+        "customCssClass": [],
+        "responsiveHide": []
+      },
+      "content": {
+        "image": "",
+        "imageMobile": "",
+        "isVideoBg": false,
+        "buttonLabel1": "",
+        "buttonLink1": "",
+        "buttonBlank1": false,
+        "fullHeight": true,
+        "contrast": false,
+        "overlay": false
+      }
+    },
+    {
+      "content_group": "Form",
+      "base": { "blockId": "formular", "headline": "<h2>Write us</h2>" },
+      "form": 7,
+      "content": { "variant": "default" }
+    }
+  ]
+}
+```
+
+### Storage encoding (what the MCP understands)
+
+- 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 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.
+
+## Publishing
+
+To publish to your GitLab group's npm registry:
+
+1. Edit `package.json`:
+   - Replace `@yourorg` in `name` and `publishConfig["@yourorg:registry"]` with your actual GitLab scope/group.
+   - Replace `<YOUR-PROJECT-ID>` in `publishConfig["@yourorg:registry"]` with the numeric project id of the `frameworc-mcp` GitLab repo.
+2. Create a GitLab deploy token / project access token with `api` + `write_registry` scope. Add a `.npmrc` at the registry host:
+
+   ```
+   @yourorg:registry=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/
+   //gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/packages/npm/:_authToken=<TOKEN>
+   ```
+3. `npm publish`.
+
+Colleagues then use `npx -y @yourorg/frameworc-mcp` in their `claude_desktop_config.json` (no clone needed).
+
+## License
+
 MIT.

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 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.",
+        description: "Create a new FrameworC page. Send a `page` object (title, slug, fullslug, is_enabled, metaTitle, metaDescription, menuStyle, menuHide, jsonLdPageType, jsonLdDisable, jsonLdCustom) 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). 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.",
+        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. Structured data: the site renders schema.org JSON-LD automatically; `page.jsonLdPageType` is WebPage / AboutPage / ContactPage / CollectionPage / FAQPage, `page.jsonLdDisable` turns the generated graph off, and `page.jsonLdCustom` is an extra JSON-LD document as a JSON string (no script tag; invalid JSON is rejected).",
         inputSchema: {
             type: "object",
             properties: {
@@ -526,7 +526,7 @@ const tools = [
     },
     {
         name: "get_page_meta",
-        description: "Read a per-site single: Meta (SEO defaults, blog base path), Navigation (navbar) or Footer. Use before composing pages so titles and descriptions match the site's conventions.",
+        description: "Read a per-site single: Meta (SEO defaults, blog base path, organization data for JSON-LD), Navigation (navbar) or Footer. Use before composing pages so titles and descriptions match the site's conventions.",
         inputSchema: {
             type: "object",
             properties: {
@@ -539,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 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.",
+        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. Meta also holds the organization data rendered as JSON-LD on every page (orgType, orgName, orgLegalName, orgIco, orgLogo, orgPhone, orgEmail, orgStreet, orgCity, orgZip, orgCountry, orgLat, orgLng, orgOpeningHours, jsonLdCustom); read get_page_meta for the exact schema. Affects every page on that site, so confirm with the user first.",
         inputSchema: {
             type: "object",
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frameworc-mcp",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "MCP server for the FrameworC OctoberCMS plugin — programmatically create/edit FrameworC pages and blocks.",
   "license": "MIT",
   "type": "commonjs",