frameworc-mcp 0.2.0 → 0.3.0

package/README.md

@@ -1,216 +1,216 @@
-# @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
-- Resolves referenced `Form` / `Menu` / `Prefill` entries via dedicated list tools
-- 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 FrameworC plugin v1.10.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.
-
-## 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 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.
-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 (v1)
-
-| 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_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. |
-| `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. |
-
-## 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_entry": 7,
-      "content": { "variant": "default" }
-    }
-  ]
-}
-```
-
-### 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.
-- `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`).
-- `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`.
-
-## 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
+- Resolves referenced `Form` / `Menu` / `Prefill` entries via dedicated list tools
+- 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 FrameworC plugin v1.10.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.
+
+## 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 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.
+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 (v1)
+
+| 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_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. |
+| `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. |
+
+## 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_entry": 7,
+      "content": { "variant": "default" }
+    }
+  ]
+}
+```
+
+### 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.
+- `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`).
+- `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`.
+
+## 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/api-client.js

@@ -28,56 +28,103 @@ class ApiClient {
         }
         if (!res.ok) {
             const msg = json && typeof json === "object" && json.errors
-                ? `HTTP ${res.status}: ${JSON.stringify(json.errors)}`
+                ? `HTTP ${res.status}: ${json.message ?? ""} ${JSON.stringify(json.errors)}`
                 : `HTTP ${res.status}: ${typeof json === "string" ? json : JSON.stringify(json)}`;
-            throw new Error(msg);
+            throw new Error(msg.trim());
         }
         return json;
     }
-    listPages() {
-        return this.request("/pages");
+    /** Appends the effective CMS site id to a query string. */
+    q(path, siteId) {
+        const id = siteId ?? this.session.getSiteId();
+        if (id === null || id === undefined)
+            return path;
+        return path + (path.includes("?") ? "&" : "?") + `site_id=${id}`;
     }
-    getPage(id) {
-        return this.request(`/pages/${id}`);
+    /** Merges the effective CMS site id into a JSON body. */
+    b(body, siteId) {
+        const id = siteId ?? this.session.getSiteId();
+        const merged = { ...(body ?? {}) };
+        if (id !== null && id !== undefined && merged.site_id === undefined) {
+            merged.site_id = id;
+        }
+        return JSON.stringify(merged);
+    }
+    // --- sites & schema ---------------------------------------------------
+    listCmsSites() {
+        return this.request("/sites");
+    }
+    listBlocks() {
+        return this.request("/blocks");
+    }
+    getBlockSchema(name) {
+        return this.request(`/blocks/${encodeURIComponent(name)}`);
+    }
+    // --- pages ------------------------------------------------------------
+    listPages(siteId) {
+        return this.request(this.q("/pages", siteId));
+    }
+    getPage(id, siteId) {
+        return this.request(this.q(`/pages/${id}`, siteId));
     }
-    createPage(payload) {
-        return this.request("/pages", { method: "POST", body: JSON.stringify(payload) });
+    createPage(payload, siteId) {
+        return this.request("/pages", { method: "POST", body: this.b(payload, siteId) });
     }
-    updatePage(id, payload) {
-        return this.request(`/pages/${id}`, { method: "PATCH", body: JSON.stringify(payload) });
+    updatePage(id, payload, siteId) {
+        return this.request(`/pages/${id}`, { method: "PATCH", body: this.b(payload, siteId) });
     }
-    deletePage(id) {
-        return this.request(`/pages/${id}`, { method: "DELETE" });
+    deletePage(id, siteId) {
+        return this.request(this.q(`/pages/${id}`, siteId), { method: "DELETE" });
     }
-    addBlock(pageId, block, position) {
+    createTranslation(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(`/pages/${id}/translations`, { method: "POST", body: JSON.stringify(body) });
+    }
+    // --- blocks (per-page) ------------------------------------------------
+    addBlock(pageId, block, position, siteId) {
         return this.request(`/pages/${pageId}/blocks`, {
             method: "POST",
-            body: JSON.stringify({ block, position }),
+            body: this.b({ block, position }, siteId),
         });
     }
-    updateBlock(pageId, blockId, block) {
+    updateBlock(pageId, blockId, block, siteId) {
         return this.request(`/pages/${pageId}/blocks/${blockId}`, {
             method: "PATCH",
-            body: JSON.stringify(block),
+            body: this.b(block, siteId),
         });
     }
-    removeBlock(pageId, blockId) {
-        return this.request(`/pages/${pageId}/blocks/${blockId}`, { method: "DELETE" });
+    removeBlock(pageId, blockId, siteId) {
+        return this.request(this.q(`/pages/${pageId}/blocks/${blockId}`, siteId), { method: "DELETE" });
     }
-    reorderBlocks(pageId, order) {
+    reorderBlocks(pageId, order, siteId) {
         return this.request(`/pages/${pageId}/blocks/order`, {
             method: "POST",
-            body: JSON.stringify({ order }),
+            body: this.b({ order }, siteId),
         });
     }
-    listForms() {
-        return this.request("/forms");
+    // --- referenced entries ----------------------------------------------
+    listForms(siteId) {
+        return this.request(this.q("/forms", siteId));
+    }
+    listMenus(siteId) {
+        return this.request(this.q("/menus", siteId));
     }
-    listMenus() {
-        return this.request("/menus");
+    listPrefills(siteId) {
+        return this.request(this.q("/prefills", siteId));
     }
-    listPrefills() {
-        return this.request("/prefills");
+    // --- singles ----------------------------------------------------------
+    getSingle(handle, siteId) {
+        return this.request(this.q(`/singles/${encodeURIComponent(handle)}`, siteId));
+    }
+    updateSingle(handle, fields, siteId) {
+        return this.request(`/singles/${encodeURIComponent(handle)}`, {
+            method: "PATCH",
+            body: this.b(fields, siteId),
+        });
     }
 }
 exports.ApiClient = ApiClient;

package/dist/catalogue.js

@@ -194,12 +194,12 @@ exports.BLOCKS = [
         content_group: "Form",
         name: "Form",
         description: "Contact / inquiry form wired to a separately-defined Form Tailor entry.",
-        whenToUse: "Only when a contact form is needed AND the referenced Form entry already exists. Get the form_entry id via the `list_forms` tool. The actual form fields live on the linked Form entry, not on this block.",
+        whenToUse: "Only when a contact form is needed AND the referenced Form entry already exists. Set the block-level `form` key to the entry id from the `list_forms` tool. The actual form fields live on the linked Form entry, not on this block.",
         base: baseBlock,
         content: [
             { name: "variant", type: "dropdown", enum: ["default", "outline", "card"], default: "default" },
         ],
-        referencing: { kind: "form", location: "block", jsonKey: "form_entry", column: "form_id" },
+        referencing: { kind: "form", location: "block", jsonKey: "form", column: "form_id" },
     },
     {
         content_group: "Gallery",
@@ -257,7 +257,7 @@ exports.BLOCKS = [
         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.",
         base: baseBlock,
         content: [],
-        referencing: { kind: "prefill", location: "content", jsonKey: "prefill_entry", column: "block_id" },
+        referencing: { kind: "prefill", location: "content", jsonKey: "block", column: "block_id" },
     },
     {
         content_group: "BlogList",
@@ -276,10 +276,10 @@ exports.BLOCKS = [
         content_group: "MenuBlock",
         name: "Menu block",
         description: "Renders an existing Menu Tailor entry inline in the page body (flattened to 2 levels).",
-        whenToUse: "When you need to embed navigation as content (e.g. an on-page section that lists links). Get the menu_entry id via `list_menus`.",
+        whenToUse: "When you need to embed navigation as content (e.g. an on-page section that lists links). Set `content.menu` to the entry id from `list_menus`.",
         base: baseBlock,
         content: [],
-        referencing: { kind: "menu", location: "content", jsonKey: "menu_entry", column: "menu_id" },
+        referencing: { kind: "menu", location: "content", jsonKey: "menu", column: "menu_id" },
     },
     {
         content_group: "ImageStrip",

package/dist/index.js

@@ -37,12 +37,34 @@ const tools = [
             properties: {},
         },
     },
+    {
+        name: "list_cms_sites",
+        description: "List the multisite sites configured INSIDE the pinned OctoberCMS install (languages, regional variants). Returns [{id, name, code, locale, is_enabled, is_primary}]. Call this before creating content on a multi-language project so you know which site_id to target. Not to be confused with list_sites, which lists separate CMS installs from your local config file.",
+        inputSchema: {
+            type: "object",
+            properties: { site_url: { type: "string" } },
+        },
+    },
+    {
+        name: "use_cms_site",
+        description: "Pin which multisite site (language) subsequent calls read and write. Pass the id from list_cms_sites, or null to go back to the primary site. Every page/single tool also accepts a one-off site_id argument that overrides this.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                site_id: { type: ["integer", "null"], description: "Site id from list_cms_sites, or null for the primary site." },
+            },
+            required: ["site_id"],
+        },
+    },
     {
         name: "list_pages",
-        description: "List all FrameworC pages on the pinned site.",
+        description: "List all FrameworC pages on the pinned site (and pinned CMS site, if set).",
         inputSchema: {
             type: "object",
-            properties: { site_url: { type: "string", description: "Override the pinned site URL for this call." } },
+            properties: {
+                site_url: { type: "string", description: "Override the pinned site URL for this call." },
+                site_id: { type: "integer", description: "Override the pinned multisite site for this call." },
+            },
         },
     },
     {
@@ -53,6 +75,7 @@ const tools = [
             properties: {
                 id: { type: "integer", description: "Page id." },
                 site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
             required: ["id"],
         },
@@ -73,6 +96,7 @@ const tools = [
                     required: ["page"],
                 },
                 site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
             required: ["payload"],
         },
@@ -86,6 +110,7 @@ const tools = [
                 id: { type: "integer" },
                 payload: { type: "object" },
                 site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
             required: ["id", "payload"],
         },
@@ -98,13 +123,14 @@ const tools = [
             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: "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_entry? / menu_entry? / prefill_entry? } per the catalogue.",
+        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`.",
         inputSchema: {
             type: "object",
             properties: {
@@ -112,6 +138,7 @@ const tools = [
                 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"],
         },
@@ -126,6 +153,7 @@ const tools = [
                 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"],
         },
@@ -139,6 +167,7 @@ const tools = [
                 page_id: { type: "integer" },
                 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"],
         },
@@ -152,13 +181,14 @@ const tools = [
                 page_id: { type: "integer" },
                 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"],
         },
     },
     {
         name: "list_forms",
-        description: "List Form Tailor entries available for the `Form` block's `form_entry` argument.",
+        description: "List Form Tailor entries available for the `Form` block's block-level `form` key.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
@@ -166,7 +196,7 @@ const tools = [
     },
     {
         name: "list_menus",
-        description: "List Menu Tailor entries available for the `MenuBlock`'s `content.menu_entry` argument.",
+        description: "List Menu Tailor entries available for the `MenuBlock`'s `content.menu` key.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
@@ -174,7 +204,7 @@ const tools = [
     },
     {
         name: "list_prefills",
-        description: "List Prefill Tailor entries available for the `Prefill` block's `content.prefill_entry` argument.",
+        description: "List Prefill Tailor entries available for the `Prefill` block's `content.block` key.",
         inputSchema: {
             type: "object",
             properties: { site_url: { type: "string" } },
@@ -182,17 +212,63 @@ const tools = [
     },
     {
         name: "get_block_schema",
-        description: "Get the JSON schema + usage notes for a single block by content_group name. Use this when you need to recall field enums / required fields / conditional visibility for one block.",
+        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.",
         inputSchema: {
             type: "object",
             properties: {
                 name: { type: "string", enum: catalogue_js_1.BLOCKS.map((b) => b.content_group) },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
             },
             required: ["name"],
         },
     },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                handle: { type: "string", enum: ["Meta", "Navigation", "Footer"] },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["handle"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                handle: { type: "string", enum: ["Meta", "Navigation", "Footer"] },
+                fields: { type: "object", description: "Field name => value map." },
+                site_url: { type: "string" },
+                site_id: { type: "integer", description: "Target multisite site id; defaults to the pinned CMS site." },
+            },
+            required: ["handle", "fields"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Source page 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." },
+                page: { 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", "target_site_id"],
+        },
+    },
 ];
-const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.2.0" }, { capabilities: { tools: {}, resources: {} } });
+const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.3.0" }, { capabilities: { tools: {}, resources: {} } });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
     tools,
 }));
@@ -200,6 +276,10 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
     const name = req.params.name;
     const args = (req.params.arguments ?? {});
     (0, sites_js_1.refreshIfChanged)();
+    // A one-off site_id argument overrides the pinned CMS site for this call.
+    const site = args.site_id !== undefined && args.site_id !== null
+        ? Number(args.site_id)
+        : undefined;
     if (name !== "use_site" && name !== "list_sites" && !args.site_url && !session.getUrl()) {
         return {
             content: [
@@ -254,68 +334,108 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
                     content: [{ type: "text", text: JSON.stringify({ sites }, null, 2) }],
                 };
             }
+            case "list_cms_sites": {
+                const r = await client.listCmsSites();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "use_cms_site": {
+                const id = args.site_id === null || args.site_id === undefined ? null : Number(args.site_id);
+                session.setSiteId(id);
+                return {
+                    content: [{
+                            type: "text",
+                            text: id === null
+                                ? "Using the primary CMS site."
+                                : `Using CMS site id ${id} for subsequent calls.`,
+                        }],
+                };
+            }
             case "list_pages": {
-                const r = await client.listPages();
+                const r = await client.listPages(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "get_page": {
-                const r = await client.getPage(Number(args.id));
+                const r = await client.getPage(Number(args.id), site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "create_page": {
-                const r = await client.createPage(args.payload);
+                const r = await client.createPage(args.payload, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "update_page": {
-                const r = await client.updatePage(Number(args.id), args.payload);
+                const r = await client.updatePage(Number(args.id), args.payload, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "delete_page": {
-                const r = await client.deletePage(Number(args.id));
+                const r = await client.deletePage(Number(args.id), site);
+                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);
                 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);
+                const r = await client.addBlock(Number(args.page_id), 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);
+                const r = await client.updateBlock(Number(args.page_id), 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));
+                const r = await client.removeBlock(Number(args.page_id), 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);
+                const r = await client.reorderBlocks(Number(args.page_id), args.order, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "list_forms": {
-                const r = await client.listForms();
+                const r = await client.listForms(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "list_menus": {
-                const r = await client.listMenus();
+                const r = await client.listMenus(site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "list_prefills": {
-                const r = await client.listPrefills();
+                const r = await client.listPrefills(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) }] };
+            }
+            case "update_page_meta": {
+                const r = await client.updateSingle(String(args.handle), args.fields ?? {}, site);
                 return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
             }
             case "get_block_schema": {
-                const block = catalogue_js_1.BLOCKS.find((b) => b.content_group === args.name);
-                if (!block) {
+                // Served by the CMS so it always matches the live blueprints; the
+                // bundled catalogue is only a fallback for an older plugin version.
+                try {
+                    const r = await client.getBlockSchema(String(args.name));
+                    return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+                }
+                catch (err) {
+                    const block = catalogue_js_1.BLOCKS.find((b) => b.content_group === args.name);
+                    if (!block) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `Unknown block "${args.name}". Available: ${catalogue_js_1.BLOCKS.map((b) => b.content_group).join(", ")}`,
+                                }],
+                            isError: true,
+                        };
+                    }
                     return {
-                        content: [
-                            {
+                        content: [{
                                 type: "text",
-                                text: `Unknown block "${args.name}". Available: ${catalogue_js_1.BLOCKS.map((b) => b.content_group).join(", ")}`,
-                            },
-                        ],
-                        isError: true,
+                                text: `(served from the bundled catalogue; live schema unavailable: ${err?.message ?? err})\n`
+                                    + JSON.stringify(block, null, 2),
+                            }],
                     };
                 }
-                return { content: [{ type: "text", text: JSON.stringify(block, null, 2) }] };
             }
             default: {
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };

package/dist/session.js

@@ -6,6 +6,8 @@ const sites_js_1 = require("./sites.js");
 class Session {
     url = null;
     tokenOverride = null;
+    /** The CMS multisite site to read and write. Null means the primary site. */
+    siteId = null;
     id;
     constructor() {
         this.id = (0, node_crypto_1.randomUUID)();
@@ -18,6 +20,14 @@ class Session {
         else {
             this.tokenOverride = null;
         }
+        // A different install has its own site ids.
+        this.siteId = null;
+    }
+    setSiteId(siteId) {
+        this.siteId = siteId;
+    }
+    getSiteId() {
+        return this.siteId;
     }
     getToken() {
         if (!this.url) {
@@ -41,6 +51,7 @@ class Session {
     clear() {
         this.url = null;
         this.tokenOverride = null;
+        this.siteId = null;
     }
 }
 exports.Session = Session;

package/package.json

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