frameworc-mcp 0.2.0

package/README.md

@@ -0,0 +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
+
+MIT.

package/dist/api-client.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiClient = void 0;
+class ApiClient {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    async request(path, init = {}) {
+        const base = this.session.getUrl();
+        const url = `${base}/api/mcp/v1${path}`;
+        const headers = {
+            "Authorization": `Bearer ${this.session.getToken()}`,
+            "Accept": "application/json",
+            ...(init.headers ?? {}),
+        };
+        if (init.body && !headers["Content-Type"]) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(url, { ...init, headers });
+        const text = await res.text();
+        let json = null;
+        try {
+            json = text ? JSON.parse(text) : null;
+        }
+        catch {
+            json = text;
+        }
+        if (!res.ok) {
+            const msg = json && typeof json === "object" && json.errors
+                ? `HTTP ${res.status}: ${JSON.stringify(json.errors)}`
+                : `HTTP ${res.status}: ${typeof json === "string" ? json : JSON.stringify(json)}`;
+            throw new Error(msg);
+        }
+        return json;
+    }
+    listPages() {
+        return this.request("/pages");
+    }
+    getPage(id) {
+        return this.request(`/pages/${id}`);
+    }
+    createPage(payload) {
+        return this.request("/pages", { method: "POST", body: JSON.stringify(payload) });
+    }
+    updatePage(id, payload) {
+        return this.request(`/pages/${id}`, { method: "PATCH", body: JSON.stringify(payload) });
+    }
+    deletePage(id) {
+        return this.request(`/pages/${id}`, { method: "DELETE" });
+    }
+    addBlock(pageId, block, position) {
+        return this.request(`/pages/${pageId}/blocks`, {
+            method: "POST",
+            body: JSON.stringify({ block, position }),
+        });
+    }
+    updateBlock(pageId, blockId, block) {
+        return this.request(`/pages/${pageId}/blocks/${blockId}`, {
+            method: "PATCH",
+            body: JSON.stringify(block),
+        });
+    }
+    removeBlock(pageId, blockId) {
+        return this.request(`/pages/${pageId}/blocks/${blockId}`, { method: "DELETE" });
+    }
+    reorderBlocks(pageId, order) {
+        return this.request(`/pages/${pageId}/blocks/order`, {
+            method: "POST",
+            body: JSON.stringify({ order }),
+        });
+    }
+    listForms() {
+        return this.request("/forms");
+    }
+    listMenus() {
+        return this.request("/menus");
+    }
+    listPrefills() {
+        return this.request("/prefills");
+    }
+}
+exports.ApiClient = ApiClient;

package/dist/catalogue.js

@@ -0,0 +1,346 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOCK_CATALOGUE_TEXT = exports.BLOCKS = void 0;
+const buttonsMixin = [
+    { name: "buttonLabel1", type: "text", comment: "Text of button 1" },
+    { 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: "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" },
+    { name: "buttonContrast2", type: "switch", default: false },
+    { name: "buttonLink2", type: "text", comment: "Pagefinder path or URL for button 2" },
+    { name: "buttonIcon2", type: "media-single" },
+    { name: "buttonBlank2", type: "switch", default: false },
+];
+const buttons2Mixin = [
+    { name: "buttonLabel3", type: "text" },
+    { name: "buttonVariant3", type: "dropdown", enum: ["default", "outline", "blurLight", "blurDark", "plain"], default: "default" },
+    { name: "buttonContrast3", type: "switch", default: false },
+    { name: "buttonLink3", type: "text" },
+    { name: "buttonIcon3", type: "media-single" },
+    { name: "buttonBlank3", type: "switch", default: false },
+    { name: "buttonLabel4", type: "text" },
+    { name: "buttonVariant4", type: "dropdown", enum: ["default", "outline", "blurLight", "blurDark", "plain"], default: "default" },
+    { name: "buttonContrast4", type: "switch", default: false },
+    { name: "buttonLink4", type: "text" },
+    { name: "buttonIcon4", type: "media-single" },
+    { name: "buttonBlank4", type: "switch", default: false },
+];
+const baseBlock = [
+    { name: "blockId", type: "text", comment: "Unique anchor id, slug-safe (e.g. 'o-nas' or 'kontakt')" },
+    { name: "headline", type: "richeditor", comment: "Block headline. Use H2/H3 (Header block uses H1/H2). Wrap text in <p> or <h2> tags as appropriate." },
+    { 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: "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",
+    "embedHalfAndHalf", "embed70", "embed30", "embedOnly",
+];
+exports.BLOCKS = [
+    {
+        content_group: "Header",
+        name: "Header (hero)",
+        description: "Page hero / headline banner at the top of a page.",
+        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: "imageMobile", type: "media-single" },
+            { name: "isVideoBg", type: "switch", default: false, comment: "If true, 'image' is treated as a video file and 'imageMobile' as poster." },
+            ...buttonsMixin,
+            { 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." },
+            { name: "overlay", type: "switch", default: false, comment: "Darken the background image." },
+        ],
+    },
+    {
+        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.",
+        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: "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')." },
+            ...buttons2Mixin.map((f) => ({ ...f, shownWhen: { field: "variant", equals: ["textAndText"] } })),
+            { name: "doubleText", type: "switch", default: false, shownWhen: { field: "variant", equals: ["halfAndHalf", "img70", "text70"] }, comment: "Split the text column into two text columns (no image)." },
+        ],
+    },
+    {
+        content_group: "Tiles",
+        name: "Tiles (grid of cards)",
+        description: "Grid of cards (icon + headline + rich text + button each).",
+        whenToUse: "Feature lists, service grids, 'value proposition' card rows,ething lists of related items.",
+        base: baseBlock,
+        content: [
+            { name: "tiles", type: "taglist", comment: "Array of tile items, each {headline, image, text, buttonLabel1, buttonVariant1, buttonContrast1, buttonLink1, buttonIcon1, buttonBlank1, buttonLabel2, ...}. Use this to list the tiles." },
+            { name: "tileLink", type: "switch", default: false, comment: "Whole tile acts as a link." },
+            { name: "tileIcon", type: "switch", default: false, comment: "Display icon-only tiles." },
+            { name: "contrastHover", type: "switch", default: false },
+            { name: "contrastBorderHover", type: "switch", default: false },
+            { name: "outline", type: "switch", default: false, comment: "Cards have outline border." },
+            { name: "borderless", type: "switch", default: false, comment: "No border / no shadow." },
+            { name: "buttonStyle", type: "dropdown", enum: ["Button--contrast", "Button--outline"], default: "Button--contrast" },
+            { name: "count", type: "dropdown", enum: ["2", "3", "4"], default: "3", comment: "Tiles per row." },
+        ],
+        nestedRepeaters: [
+            {
+                name: "tiles",
+                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: "text", type: "richeditor", comment: "Tile body text." },
+                    ...buttonsMixin,
+                ],
+            },
+        ],
+    },
+    {
+        content_group: "Slider",
+        name: "Slider",
+        description: "Splide carousel of slides (image + headline + text + buttons each). Can render as tabs.",
+        whenToUse: "Image-heavy content that benefits from sequential browsing — testimonials, step-by-step walkthroughs, gallery-like rows.",
+        base: baseBlock,
+        content: [
+            { name: "slides", type: "taglist", comment: "Array of slide items, each {image, headline, text, buttonLabel1, buttonVariant1, ...}." },
+            { name: "gallery", type: "switch", default: false, comment: "Clicking a slide opens the gallery lightbox." },
+            { name: "loop", type: "switch", default: false, comment: "Infinite loop playback." },
+            { name: "autoWidth", type: "switch", default: false, comment: "Slide width matches image width." },
+            { name: "variant", type: "dropdown", enum: ["basic", "double", "tabs-horizontal", "tabs-vertical"], default: "basic" },
+            { name: "perView", type: "number", default: 1, comment: "Visible slides at once (1+)." },
+            { name: "gap", type: "number", default: 30, comment: "Pixels between slides." },
+            { name: "focusedSlidePosition", type: "dropdown", enum: ["left", "center", "right"] },
+            { name: "startIndex", type: "number", default: 0, comment: "Default active slide (0-based; must be less than total slides)." },
+            { name: "syncWith", type: "text", comment: "ID of another slider to synchronize with." },
+            { name: "autoplay", type: "number", comment: "Autoplay interval in ms. 0 or blank = off." },
+        ],
+        nestedRepeaters: [
+            {
+                name: "slides",
+                description: "One repeater item per slide.",
+                items: [
+                    { name: "image", type: "media-single" },
+                    { name: "headline", type: "text" },
+                    { name: "text", type: "richeditor" },
+                    ...buttonsMixin,
+                ],
+            },
+        ],
+        hasBreakpoints: true,
+    },
+    {
+        content_group: "Tabs",
+        name: "Tabs",
+        description: "Tabbed content panels (image + headline + text + button each).",
+        whenToUse: "Long content split into topic tabs (e.g. 'What we do' / 'Who we are' / 'Contact'). Don't use if there are only 1–2 logical sections — use Section instead.",
+        base: baseBlock,
+        content: [
+            { name: "slides", type: "taglist", comment: "Array of tab items, each {image, headline, text, buttonLabel1, ...}." },
+            { name: "gallery", type: "switch", default: false },
+            { name: "variant", type: "dropdown", enum: ["tabs-horizontal", "tabs-vertical"], default: "tabs-horizontal" },
+        ],
+        nestedRepeaters: [
+            {
+                name: "slides",
+                description: "One repeater item per tab.",
+                items: [
+                    { name: "image", type: "media-single" },
+                    { name: "headline", type: "text", required: true },
+                    { name: "text", type: "richeditor" },
+                    ...buttonsMixin,
+                ],
+            },
+        ],
+    },
+    {
+        content_group: "Accordion",
+        name: "Accordion",
+        description: "Expandable Q&A / collapsible sections.",
+        whenToUse: "FAQs, 'Common questions', or any content the user wants collapsed by default. Each item has a headline + rich text.",
+        base: baseBlock,
+        content: [
+            { name: "items", type: "taglist", comment: "Array of items, each {headline, text}." },
+            { name: "variant", type: "dropdown", enum: ["default", "outline", "shadow"], default: "default" },
+            { name: "firstItemOpen", type: "switch", default: false, comment: "First item is expanded on load." },
+            { name: "singleMode", type: "switch", default: false, comment: "Only one item open at a time." },
+            { name: "icon", type: "codeeditor", comment: "Custom SVG icon (raw SVG markup). Leave blank for default +/- icon." },
+        ],
+        nestedRepeaters: [
+            {
+                name: "items",
+                description: "One repeater item per accordion row.",
+                items: [
+                    { name: "headline", type: "text", required: true, comment: "Question / collapsed heading." },
+                    { name: "text", type: "richeditor", comment: "Expanded answer / body." },
+                ],
+            },
+        ],
+    },
+    {
+        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.",
+        base: baseBlock,
+        content: [
+            { name: "variant", type: "dropdown", enum: ["default", "outline", "card"], default: "default" },
+        ],
+        referencing: { kind: "form", location: "block", jsonKey: "form_entry", column: "form_id" },
+    },
+    {
+        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).",
+        base: baseBlock,
+        content: [
+            { name: "images", type: "media-multi", comment: "Array of image paths; MUST be empty in MCP." },
+            { name: "columns", type: "number", default: 3, comment: "Number of columns (blank = 3)." },
+        ],
+    },
+    {
+        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).",
+        base: baseBlock,
+        content: [],
+        nestedRepeaters: [
+            {
+                name: "files",
+                description: "One repeater item per downloadable file.",
+                items: [
+                    { 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." },
+                ],
+            },
+        ],
+    },
+    {
+        content_group: "Columns",
+        name: "Columns (recursive Builder)",
+        description: "Multi-column layout where each column contains its own full Builder (any blocks).",
+        whenToUse: "When you need to present 2–4 distinct blocks side-by-side at desktop widths. Each column individually can host any of the other block types (Header doesn't fit here — use Section/Tiles/etc). Recursion: each column has a 'builder' array of blocks.",
+        base: baseBlock,
+        content: [],
+        nestedRepeaters: [
+            {
+                name: "columns",
+                description: "One repeater item per column. Each column has {blockId, builder: [...blocks]} where builder is a full Builder array.",
+                items: [
+                    { name: "blockId", type: "text", comment: "Optional column anchor id (used for the column wrapper)." },
+                    { name: "builder", type: "taglist", comment: "Array of block objects (same shape as top-level 'builder' in a page). You can nest any block here, including another Columns (avoid deep nesting)." },
+                ],
+            },
+        ],
+    },
+    {
+        content_group: "Prefill",
+        name: "Prefill (reusable block template)",
+        description: "References a Prefill Tailor entry whose builder content is shared across pages — edit once, updates everywhere it is used.",
+        whenToUse: "For shared/global blocks like a newsletter CTA, a contact form snippet, or a footer-style band that should appear the same on many pages. The actual block content lives on the Prefill entry — get its id via `list_prefills`. Don't use this for one-off content.",
+        base: baseBlock,
+        content: [],
+        referencing: { kind: "prefill", location: "content", jsonKey: "prefill_entry", column: "block_id" },
+    },
+    {
+        content_group: "BlogList",
+        name: "Blog list",
+        description: "Lists BlogPost stream entries, optional pagination + category switcher.",
+        whenToUse: "Blog index page or category listing. Pulls BlogPost entries automatically — no content of its own beyond pagination/layout options.",
+        base: baseBlock,
+        content: [
+            { name: "count", type: "dropdown", enum: ["1", "2", "3", "4"], default: "3", comment: "Posts per row." },
+            { name: "perPage", type: "number", comment: "Posts per page before pagination kicks in. Blank = all." },
+            { name: "pagination", type: "switch", default: false, comment: "Show 'load more'." },
+            { name: "categorySwitcher", type: "switch", default: false, comment: "Show tag/category filter row." },
+        ],
+    },
+    {
+        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`.",
+        base: baseBlock,
+        content: [],
+        referencing: { kind: "menu", location: "content", jsonKey: "menu_entry", column: "menu_id" },
+    },
+    {
+        content_group: "ImageStrip",
+        name: "Image strip (marquee)",
+        description: "Horizontal scrolling strip/marquee of images.",
+        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: "centered", type: "switch", default: false, comment: "Center the strip horizontally." },
+            { name: "autoScroll", type: "switch", default: false },
+            { name: "stopOnHover", type: "switch", default: false },
+            { name: "intervalDelay", type: "number", default: 20, comment: "Scroll interval delay. Lower = faster. 20 is sensible default." },
+        ],
+    },
+    {
+        content_group: "InstaFeed",
+        name: "Instagram feed",
+        description: "Instagram feed grid (uses Yizack\InstagramFeed module).",
+        whenToUse: "Showing a live Instagram feed inline. Requires the Instagram token — set in backend Blocks/InstaFeed settings; the MCP passes the same token through.",
+        base: baseBlock,
+        content: [
+            { name: "token", type: "text", comment: "Instagram API access token (sensitive; the API accepts but typically you should set these via backend)." },
+            { name: "columnCount", type: "number", default: 3, comment: "Grid columns." },
+            { name: "imageCount", type: "number", default: 6, comment: "Total images shown. Should divide evenly by columnCount." },
+        ],
+    },
+];
+exports.BLOCK_CATALOGUE_TEXT = exports.BLOCKS.map((b) => {
+    const lines = [];
+    lines.push(`### ${b.name} (content_group="${b.content_group}")`);
+    lines.push(`When to use: ${b.whenToUse}`);
+    lines.push("");
+    lines.push("base fields (shared BaseBlock mixin):");
+    for (const f of b.base) {
+        lines.push(`  - ${f.name}: ${f.type}${f.enum ? ` (one of: ${f.enum.join(", ")})` : ""}${f.default !== undefined ? ` [default=${JSON.stringify(f.default)}]` : ""}${f.comment ? ` — ${f.comment}` : ""}`);
+    }
+    if (b.content.length > 0) {
+        lines.push("");
+        lines.push("content fields:");
+        for (const f of b.content) {
+            lines.push(`  - ${f.name}: ${f.type}${f.enum ? ` (one of: ${f.enum.join(", ")})` : ""}${f.default !== undefined ? ` [default=${JSON.stringify(f.default)}]` : ""}${f.hiddenWhen ? ` (hidden when ${f.hiddenWhen.field} in [${f.hiddenWhen.equals.join("|")}])` : ""}${f.shownWhen ? ` (only when ${f.shownWhen.field} in [${f.shownWhen.equals.join("|")}])` : ""}${f.comment ? ` — ${f.comment}` : ""}`);
+        }
+    }
+    if (b.referencing) {
+        lines.push("");
+        lines.push(`references: ${b.referencing.kind} (set in JSON ${b.referencing.location === "block" ? "at block level" : "inside content"} via key "${b.referencing.jsonKey}"); stored on the "${b.referencing.column}" column.`);
+    }
+    if (b.nestedRepeaters && b.nestedRepeaters.length > 0) {
+        for (const nr of b.nestedRepeaters) {
+            lines.push("");
+            lines.push(`nested repeater "${nr.name}": ${nr.description}`);
+            for (const f of nr.items) {
+                lines.push(`  - ${f.name}: ${f.type}${f.enum ? ` (one of: ${f.enum.join(", ")})` : ""}${f.default !== undefined ? ` [default=${JSON.stringify(f.default)}]` : ""}${f.comment ? ` — ${f.comment}` : ""}`);
+            }
+        }
+    }
+    if (b.hasBreakpoints) {
+        lines.push("");
+        lines.push("optional nestedform 'breakpoints': { tablet: number, mobile: number }");
+    }
+    lines.push("");
+    return lines.join("\n");
+}).join("\n");

package/dist/index.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const api_client_js_1 = require("./api-client.js");
+const session_js_1 = require("./session.js");
+const catalogue_js_1 = require("./catalogue.js");
+const sites_js_1 = require("./sites.js");
+const CATALOGUE_URI = "frameworc://blocks";
+(0, sites_js_1.ensureFile)();
+(0, sites_js_1.warnIfWorldReadable)();
+const session = new session_js_1.Session();
+const client = new api_client_js_1.ApiClient(session);
+const tools = [
+    {
+        name: "use_site",
+        description: "Pin the OctCMS site for all subsequent tool calls in this session. Required before any page/block tool. The token is resolved from the local file ~/.config/frameworc/sites.json by URL; pass the optional `site_token` arg only if you want to override that lookup for this session. If neither resolves a token, the call errors with a helpful message about editing sites.json.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "Base HTTPS URL of the OctCMS site, e.g. https://example.com" },
+                site_token: {
+                    type: "string",
+                    description: "Optional override bearer token for this site. If omitted, the MCP looks up the token by URL in ~/.config/frameworc/sites.json.",
+                },
+            },
+            required: ["url"],
+        },
+    },
+    {
+        name: "list_sites",
+        description: "List the OctCMS sites configured in the local file ~/.config/frameworc/sites.json. Returns [{label, url}] WITHOUT tokens. Use this when the user asks 'which sites are available' or wants to switch but only remembers the label.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "list_pages",
+        description: "List all FrameworC pages on the pinned site.",
+        inputSchema: {
+            type: "object",
+            properties: { site_url: { type: "string", description: "Override the pinned site URL for this call." } },
+        },
+    },
+    {
+        name: "get_page",
+        description: "Fetch a full page including its builder blocks (base + content + nested repeaters).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer", description: "Page id." },
+                site_url: { type: "string" },
+            },
+            required: ["id"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                payload: {
+                    type: "object",
+                    description: "Page + builder payload per the schema described in the frameworc://blocks resource.",
+                    properties: {
+                        page: { type: "object" },
+                        builder: { type: "array" },
+                    },
+                    required: ["page"],
+                },
+                site_url: { type: "string" },
+            },
+            required: ["payload"],
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                payload: { type: "object" },
+                site_url: { type: "string" },
+            },
+            required: ["id", "payload"],
+        },
+    },
+    {
+        name: "delete_page",
+        description: "Soft-delete a page (sets deleted_at).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                id: { type: "integer" },
+                site_url: { type: "string" },
+            },
+            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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page_id: { type: "integer" },
+                block: { type: "object" },
+                position: { type: "integer" },
+                site_url: { type: "string" },
+            },
+            required: ["page_id", "block"],
+        },
+    },
+    {
+        name: "update_block",
+        description: "Replace a single block by id (the row id returned by get_page's builder[].id). The new `block` must include `content_group` (matching or changing the block type) plus `base` + `content`.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page_id: { type: "integer" },
+                block_id: { type: "integer" },
+                block: { type: "object" },
+                site_url: { type: "string" },
+            },
+            required: ["page_id", "block_id", "block"],
+        },
+    },
+    {
+        name: "remove_block",
+        description: "Remove a block by its row id from the page's builder.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page_id: { type: "integer" },
+                block_id: { type: "integer" },
+                site_url: { type: "string" },
+            },
+            required: ["page_id", "block_id"],
+        },
+    },
+    {
+        name: "reorder_blocks",
+        description: "Reorder blocks. Send every block row id in the desired order (all existing block ids must be present, no extras).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                page_id: { type: "integer" },
+                order: { type: "array", items: { type: "integer" } },
+                site_url: { type: "string" },
+            },
+            required: ["page_id", "order"],
+        },
+    },
+    {
+        name: "list_forms",
+        description: "List Form Tailor entries available for the `Form` block's `form_entry` argument.",
+        inputSchema: {
+            type: "object",
+            properties: { site_url: { type: "string" } },
+        },
+    },
+    {
+        name: "list_menus",
+        description: "List Menu Tailor entries available for the `MenuBlock`'s `content.menu_entry` argument.",
+        inputSchema: {
+            type: "object",
+            properties: { site_url: { type: "string" } },
+        },
+    },
+    {
+        name: "list_prefills",
+        description: "List Prefill Tailor entries available for the `Prefill` block's `content.prefill_entry` argument.",
+        inputSchema: {
+            type: "object",
+            properties: { site_url: { type: "string" } },
+        },
+    },
+    {
+        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.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", enum: catalogue_js_1.BLOCKS.map((b) => b.content_group) },
+            },
+            required: ["name"],
+        },
+    },
+];
+const server = new index_js_1.Server({ name: "frameworc-mcp", version: "0.2.0" }, { capabilities: { tools: {}, resources: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools,
+}));
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const args = (req.params.arguments ?? {});
+    (0, sites_js_1.refreshIfChanged)();
+    if (name !== "use_site" && name !== "list_sites" && !args.site_url && !session.getUrl()) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Error: no site pinned. Call use_site(url) first, or pass site_url in this call.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        if (args.site_url && name !== "use_site") {
+            session.pin(args.site_url);
+        }
+        switch (name) {
+            case "use_site": {
+                session.pin(args.url, args.site_token);
+                let resolvedVia;
+                if (args.site_token) {
+                    resolvedVia = "explicit site_token arg";
+                }
+                else {
+                    try {
+                        session.getToken();
+                        resolvedVia = "sites.json lookup";
+                    }
+                    catch (err) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Pinned ${args.url}, but no token resolved. ${err?.message ?? "Add an entry to ~/.config/frameworc/sites.json or pass site_token explicitly."}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Pinned site ${args.url} (token via ${resolvedVia})`,
+                        },
+                    ],
+                };
+            }
+            case "list_sites": {
+                const sites = (0, sites_js_1.listSites)();
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ sites }, null, 2) }],
+                };
+            }
+            case "list_pages": {
+                const r = await client.listPages();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "get_page": {
+                const r = await client.getPage(Number(args.id));
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "create_page": {
+                const r = await client.createPage(args.payload);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "update_page": {
+                const r = await client.updatePage(Number(args.id), args.payload);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "delete_page": {
+                const r = await client.deletePage(Number(args.id));
+                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);
+                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);
+                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));
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "reorder_blocks": {
+                const r = await client.reorderBlocks(Number(args.page_id), args.order);
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "list_forms": {
+                const r = await client.listForms();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "list_menus": {
+                const r = await client.listMenus();
+                return { content: [{ type: "text", text: JSON.stringify(r, null, 2) }] };
+            }
+            case "list_prefills": {
+                const r = await client.listPrefills();
+                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) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Unknown block "${args.name}". Available: ${catalogue_js_1.BLOCKS.map((b) => b.content_group).join(", ")}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                return { content: [{ type: "text", text: JSON.stringify(block, null, 2) }] };
+            }
+            default: {
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+            }
+        }
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err?.message ?? String(err)}` }],
+            isError: true,
+        };
+    }
+});
+server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+    resources: [
+        {
+            uri: CATALOGUE_URI,
+            name: "FrameworC block catalogue",
+            description: "Reference for all 15 FrameworC builder block types: when-to-use, base fields, content fields (with enums / defaults / conditional visibility), nested repeaters, and reference fields (Form/Menu/Prefill). READ THIS FIRST before composing a page.",
+            mimeType: "text/plain",
+        },
+    ],
+}));
+server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (req) => {
+    const uri = String(req.params.uri);
+    if (uri !== CATALOGUE_URI) {
+        throw new Error(`Unknown resource: ${uri}`);
+    }
+    return {
+        contents: [
+            {
+                uri: CATALOGUE_URI,
+                mimeType: "text/plain",
+                text: catalogue_js_1.BLOCK_CATALOGUE_TEXT,
+            },
+        ],
+    };
+});
+const transport = new stdio_js_1.StdioServerTransport();
+server
+    .connect(transport)
+    .then(() => {
+    process.stderr.write("frameworc-mcp ready (stdio).\n");
+})
+    .catch((err) => {
+    process.stderr.write(`frameworc-mcp failed to start: ${err?.message ?? err}\n`);
+    process.exit(1);
+});

package/dist/session.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Session = void 0;
+const node_crypto_1 = require("node:crypto");
+const sites_js_1 = require("./sites.js");
+class Session {
+    url = null;
+    tokenOverride = null;
+    id;
+    constructor() {
+        this.id = (0, node_crypto_1.randomUUID)();
+    }
+    pin(url, token) {
+        this.url = url.replace(/\/+$/, "");
+        if (token) {
+            this.tokenOverride = token;
+        }
+        else {
+            this.tokenOverride = null;
+        }
+    }
+    getToken() {
+        if (!this.url) {
+            throw new Error("No site pinned. Call use_site(url) first, or pass site_url explicitly.");
+        }
+        if (this.tokenOverride) {
+            return this.tokenOverride;
+        }
+        const fromStore = (0, sites_js_1.findToken)(this.url);
+        if (fromStore) {
+            return fromStore;
+        }
+        throw new Error(`No token for ${this.url}. Add an entry to ~/.config/frameworc/sites.json, or pass site_token explicitly in use_site().`);
+    }
+    getUrl() {
+        if (!this.url) {
+            throw new Error("No site pinned. Call use_site(url) first, or pass site_url explicitly.");
+        }
+        return this.url;
+    }
+    clear() {
+        this.url = null;
+        this.tokenOverride = null;
+    }
+}
+exports.Session = Session;

package/dist/sites.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITES_FILE = void 0;
+exports.ensureFile = ensureFile;
+exports.reload = reload;
+exports.findToken = findToken;
+exports.listSites = listSites;
+exports.refreshIfChanged = refreshIfChanged;
+exports.warnIfWorldReadable = warnIfWorldReadable;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const SITES_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".config", "frameworc");
+exports.SITES_FILE = (0, node_path_1.join)(SITES_DIR, "sites.json");
+const TEMPLATE = {
+    sites: [
+        {
+            label: "Example site",
+            url: "https://example.test",
+            token: "paste-your-token-here",
+        },
+    ],
+};
+function normalizeUrl(url) {
+    return String(url).replace(/\/+$/, "");
+}
+let lastMtime = 0;
+let cached = { sites: [] };
+function ensureFile() {
+    if ((0, node_fs_1.existsSync)(exports.SITES_FILE)) {
+        return;
+    }
+    (0, node_fs_1.mkdirSync)(SITES_DIR, { recursive: true, mode: 0o700 });
+    (0, node_fs_1.writeFileSync)(exports.SITES_FILE, JSON.stringify(TEMPLATE, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+    try {
+        (0, node_fs_1.chmodSync)(exports.SITES_FILE, 0o600);
+    }
+    catch {
+        // best effort
+    }
+    process.stderr.write(`frameworc-mcp: created ${exports.SITES_FILE} with a template — edit it with your real site URLs and tokens, then retry.\n`);
+}
+function reload() {
+    try {
+        const st = (0, node_fs_1.statSync)(exports.SITES_FILE);
+        const mtime = st.mtimeMs;
+        if (mtime === lastMtime && cached.sites.length > 0) {
+            return cached;
+        }
+        const raw = (0, node_fs_1.readFileSync)(exports.SITES_FILE, "utf8");
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            process.stderr.write(`frameworc-mcp: ${exports.SITES_FILE} is not valid JSON (${err?.message ?? err}). Site tokens are unavailable — please fix the file. Using empty site list.\n`);
+            cached = { sites: [] };
+            lastMtime = mtime;
+            return cached;
+        }
+        if (!parsed || !Array.isArray(parsed.sites)) {
+            process.stderr.write(`frameworc-mcp: ${exports.SITES_FILE} is missing the "sites" array. Treating as empty.\n`);
+            cached = { sites: [] };
+        }
+        else {
+            cached = { sites: parsed.sites.filter((s) => s && typeof s.url === "string" && typeof s.token === "string") };
+        }
+        lastMtime = mtime;
+        return cached;
+    }
+    catch {
+        cached = { sites: [] };
+        return cached;
+    }
+}
+function findToken(url) {
+    const store = reload();
+    const target = normalizeUrl(url);
+    for (const entry of store.sites) {
+        if (normalizeUrl(entry.url) === target) {
+            return entry.token || null;
+        }
+    }
+    return null;
+}
+function listSites() {
+    const store = reload();
+    return store.sites.map((s) => ({ label: s.label, url: normalizeUrl(s.url) }));
+}
+function refreshIfChanged() {
+    try {
+        const st = (0, node_fs_1.statSync)(exports.SITES_FILE);
+        if (st.mtimeMs !== lastMtime) {
+            reload();
+        }
+    }
+    catch {
+        // file may have been deleted mid-session; reload() handles farther down
+        reload();
+    }
+}
+function warnIfWorldReadable() {
+    try {
+        const st = (0, node_fs_1.statSync)(exports.SITES_FILE);
+        const mode = st.mode & 0o777;
+        if (mode & 0o077) {
+            process.stderr.write(`frameworc-mcp: warning: ${exports.SITES_FILE} is readable by group/others (mode ${mode.toString(8)}).Recommend \`chmod 600 ${exports.SITES_FILE}\` to protect tokens.\n`);
+        }
+    }
+    catch {
+        // ignore
+    }
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "frameworc-mcp",
+  "version": "0.2.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/"
+  }
+}