@caelo-cms/mcp-server 0.11.3 → 0.11.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@caelo-cms/mcp-server",
   "mcpName": "io.github.caelo-cms/caelo",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "private": false,
   "license": "MPL-2.0",
   "description": "MCP servers for Caelo CMS: `caelo_chat` (talk to Caelo's own AI) and the admin-scoped Power-MCP (the full chat-runner tool catalogue, driven by your own agent). Lets Claude Code (or any MCP-aware client) drive a Caelo install from outside the browser.",

package/power-catalogue.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.11.3",
+  "version": "0.11.4",
   "tools": [
     {
       "name": "read_content",
@@ -229,7 +229,7 @@
     },
     {
       "name": "build_page",
-      "description": "Build a WHOLE page in ONE transaction: create (`page:{slug, title}`) or target existing (`page:{pageId}`) + the full ordered module list (each entry places one module into a template block, top to bottom; on an existing page entries append). Any invalid entry aborts everything (error names `modules[i]` + failing field); nothing is written.\nUSE FOR: every page creation (THE page-creation tool); any page needing >1 module — never `add_module` / `create_content_instances` chains. `modules: []` = intentionally empty page shell.\nDO NOT USE FOR: one incremental module on an existing page -> `add_module` (target `page`); site chrome header/footer -> `add_module` (target `layout`; chrome never rides in a page body).\nCORE RULES:\n- Creating: typed page -> `page.pageType` (+ `properties`/`terms`; an ordinary page omits pageType); always `page.metaDescription`, and `status:\"published\"` for a page that belongs on the site — a Stage refuses published pages without a description and builds only published ones; the result says what still blocks a Stage.\n- Per module, two modes: `moduleId` places an EXISTING module (`list_modules`; reuse first — shared modules keep pages consistent), or mint with `displayName` + `html` + `description` + `kind` + explicit `fields[]` (all required).\n- Pair `{{field_name}}` placeholders in `html` with `fields[]` in semantic snake_case (`hero_title`, `primary_cta_href`); never heuristic names (`cta2label2`) or numbered scalars (`label1`..`label10` -> ONE `list` field or a `module-list`).\n- Nested modules in the SAME call: inner entry gets `ref` and NO `blockName` (detached: minted + content-bound, not placed); the outer module's `module`/`module-list` field value references it as `{\"$ref\":\"<ref>\"}`, any array order. Never an `add_module` -> `remove_module_from` -> `create_content_instances` chain. E.g. `modules:[{ref:'btn', displayName:'Button', html:'<button>{{label}}</button>', fields:[…], content:{source:'inline', values:{label:'Go'}}}, {blockName:'content', displayName:'CTA', html:'<section>{{>cta}}</section>', fields:[{name:'cta', kind:'module', label:'CTA', allowedModuleTypes:['button']}], content:{source:'inline', values:{cta:{'$ref':'btn'}}}}]`\n- Zero templates on the site -> bootstrap first (`create_layout` -> `create_template`).\n- INTERNAL LINKS (`html` hrefs, `url`/`link` fields, list-entry links): write the page path (e.g. `/about`). Target MUST be an existing page (`list_pages`) or it is refused — create an empty shell first (`build_page({page:{slug, title}, modules:[]})`) or link after. `/` and `/#section` are always valid. Exception: links to pages of this chat's site-import run are kept and resolved by `resolve_import_links` at the end. Media/files: media URL (`find_media`). External: full `https://` URL.\nTypical call: `{page:{slug:'pricing', title:'Pricing', status:'published', metaDescription:'…'}, modules:[{blockName:'content', displayName:'Pricing Hero', kind:'hero', description:'…', html:'<section><h1>{{hero_title}}</h1></section>', fields:[{name:'hero_title', kind:'text', label:'Hero title'}], content:{source:'inline', values:{hero_title:'Fair pricing'}}}, …]}`",
+      "description": "Build a WHOLE page in ONE transaction: create (`page:{slug, title}`) or target existing (`page:{pageId}`) + the full ordered module list (each entry places one module into a template block, top to bottom; on an existing page entries append). Any invalid entry aborts everything (error names `modules[i]` + failing field); nothing is written.\nUSE FOR: every page creation (THE page-creation tool); any page needing >1 module — never `add_module` / `create_content_instances` chains. `modules: []` = intentionally empty page shell.\nDO NOT USE FOR: one incremental module on an existing page -> `add_module` (target `page`); site chrome header/footer -> `add_module` (target `layout`; chrome never rides in a page body).\nCORE RULES:\n- Creating: typed page -> `page.pageType` (+ `properties`/`terms`; an ordinary page omits pageType); always `page.metaDescription`, and `status:\"published\"` for a page that belongs on the site — a Stage refuses published pages without a description and builds only published ones; the result says what still blocks a Stage.\n- Per module, two modes: `moduleId` places an EXISTING module (`list_modules`; reuse first — shared modules keep pages consistent), or mint with `displayName` + `html` + `description` + `kind` + explicit `fields[]` (all required).\n- Pair `{{field_name}}` placeholders in `html` with `fields[]` in semantic snake_case (`hero_title`, `primary_cta_href`); never heuristic names (`cta2label2`) or numbered scalars (`label1`..`label10` -> ONE `list` field or a `module-list`).\n- An overview of pages (guides hub, category page) is ONE `list` field bound to a page query (`bind:\"source\"`, `source:{kind:\"query\", defaults:{page_type:…}}`; `term_pages` / `children`), never a hand-kept card per page.\n- Nested modules in the SAME call: inner entry gets `ref` and NO `blockName` (detached: minted + content-bound, not placed); the outer module's `module`/`module-list` field value references it as `{\"$ref\":\"<ref>\"}`, any array order. Never an `add_module` -> `remove_module_from` -> `create_content_instances` chain. E.g. `modules:[{ref:'btn', displayName:'Button', html:'<button>{{label}}</button>', fields:[…], content:{source:'inline', values:{label:'Go'}}}, {blockName:'content', displayName:'CTA', html:'<section>{{>cta}}</section>', fields:[{name:'cta', kind:'module', label:'CTA', allowedModuleTypes:['button']}], content:{source:'inline', values:{cta:{'$ref':'btn'}}}}]`\n- Zero templates on the site -> bootstrap first (`create_layout` -> `create_template`).\n- INTERNAL LINKS (`html` hrefs, `url`/`link` fields, list-entry links): write the page path (e.g. `/about`). Target MUST be an existing page (`list_pages`) or it is refused — create an empty shell first (`build_page({page:{slug, title}, modules:[]})`) or link after. `/` and `/#section` are always valid. Exception: links to pages of this chat's site-import run are kept and resolved by `resolve_import_links` at the end. Media/files: media URL (`find_media`). External: full `https://` URL.\nTypical call: `{page:{slug:'pricing', title:'Pricing', status:'published', metaDescription:'…'}, modules:[{blockName:'content', displayName:'Pricing Hero', kind:'hero', description:'…', html:'<section><h1>{{hero_title}}</h1></section>', fields:[{name:'hero_title', kind:'text', label:'Hero title'}], content:{source:'inline', values:{hero_title:'Fair pricing'}}}, …]}`",
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
@@ -528,7 +528,28 @@
                       },
                       "source": {
                         "type": "object",
-                        "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                        "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages|pagination} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                      },
+                      "paginate": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "description": "Overview of ALL matching pages (query without `limit`, or term_pages): page 1 here, then <path>/page/2/…; one per module. Needs a pager field (source system \"pagination\": {{number}}, {{link}}, is_current/is_prev/is_next). A placement may override with value `paginate`.",
+                        "properties": {
+                          "per_page": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 50,
+                            "description": "Default 50."
+                          },
+                          "follow_ups": {
+                            "type": "string",
+                            "enum": [
+                              "index",
+                              "noindex"
+                            ],
+                            "description": "Default \"index\" (self-canonical, in sitemap)."
+                          }
+                        }
                       },
                       "allowedModuleTypes": {
                         "type": "array",
@@ -715,7 +736,7 @@
     },
     {
       "name": "list_content_instances",
-      "description": "List content_instances — values filling module placeholders (TOON rows: id, module, kind, slug, displayName, purpose, placements, parents), most-placed first; counts as this chat's draft sees them.\n- `purpose` = why a shared row exists: read it BEFORE minting (`create_content_instances`); reuse a row whose purpose + module fit.\n- `placements` = blast radius: >1 = SHARED, edits propagate to every bound page -> check BEFORE `set_content_instance_values_many`.\n- `parents` = instances showing this one in a `module`/`module-list` field. ORPHAN (safe to delete) = placements 0 AND parents 0.\nNarrow by `moduleId` / `slug` / `pageId` (instances used on that page).",
+      "description": "List content_instances — values filling module placeholders (TOON rows: id, module, kind, slug, displayName, purpose, placements, parents, pages), widest reach first; counts as this chat's draft sees them.\n- `purpose` = why a shared row exists: read it BEFORE minting (`create_content_instances`); reuse a row whose purpose + module fit.\n- `placements` = its own placements; `parents` = instances, module defaults (layout chrome) and shared lists that show it inside them.\n- `pages` = blast radius: every page it renders on, its own placements plus everything its parents render on (`+site` = also layout chrome or a shared list) -> check BEFORE `set_content_instance_values_many`; `get_content_instance` names them.\n- ORPHAN (safe to delete) = placements 0 AND parents 0.\nNarrow by `moduleId` / `slug` / `pageId` (instances used on that page).",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -757,7 +778,7 @@
     },
     {
       "name": "get_content_instance",
-      "description": "Fetch one content_instance, as this chat's draft sees it: values, placements (page path, block, position, sync_mode) and parent instances showing it in a `module`/`module-list` field. Check blast radius before `set_content_instance_values_many` and before deleting (orphan = no placements AND no parents).",
+      "description": "Fetch one content_instance, as this chat's draft sees it: values, placements (page path, block, position, sync_mode), parents showing it (instances' `module`/`module-list` fields, module defaults, shared lists) and every page it renders on. Check that blast radius before `set_content_instance_values_many` and before deleting (orphan = no placements AND no parents).",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -774,7 +795,7 @@
     },
     {
       "name": "set_content_instance_values_many",
-      "description": "Edit values of 1..N shared content_instances in one transaction. Each item propagates to EVERY placement bound to that instance with sync_mode `synced` (blast radius = its placement count).\nUSE FOR: deliberate shared-content changes — check `purpose`, sample pages, placement count first (`list_content_instances` / `get_content_instance`).\nDO NOT USE FOR: an edit meant for ONE page -> `set_page_module_content_many` (unsynced placement) or `fork_placement_content` first (synced); module structure -> `update_modules_many`.\nCORE RULES:\n- All-or-nothing: an invalid item aborts the batch (error names `items[i]`); nothing is written.\n- Optional metadata in the same write: `slug`, `displayName` (`null` clears), `purpose`.\n- The result names per item where the edit now shows — relay it when the reach is wider than the operator asked for.\n- INTERNAL LINKS (`html` hrefs, `url`/`link` fields, list-entry links): write the page path (e.g. `/about`). Target MUST be an existing page (`list_pages`) or it is refused — create an empty shell first (`build_page({page:{slug, title}, modules:[]})`) or link after. `/` and `/#section` are always valid. Exception: links to pages of this chat's site-import run are kept and resolved by `resolve_import_links` at the end. Media/files: media URL (`find_media`). External: full `https://` URL.",
+      "description": "Edit values of 1..N shared content_instances in one transaction. Each item propagates to EVERY page it renders on: its `synced` placements and every page of the parents that show it (blast radius = `pages` in `list_content_instances`).\nUSE FOR: deliberate shared-content changes — check `purpose`, pages and parents first (`list_content_instances` / `get_content_instance`).\nDO NOT USE FOR: an edit meant for ONE page -> `set_page_module_content_many` (unsynced placement) or `fork_placement_content` first (synced); module structure -> `update_modules_many`.\nCORE RULES:\n- All-or-nothing: an invalid item aborts the batch (error names `items[i]`); nothing is written.\n- Optional metadata in the same write: `slug`, `displayName` (`null` clears), `purpose`.\n- The result names per item where the edit now shows — relay it when the reach is wider than the operator asked for.\n- INTERNAL LINKS (`html` hrefs, `url`/`link` fields, list-entry links): write the page path (e.g. `/about`). Target MUST be an existing page (`list_pages`) or it is refused — create an empty shell first (`build_page({page:{slug, title}, modules:[]})`) or link after. `/` and `/#section` are always valid. Exception: links to pages of this chat's site-import run are kept and resolved by `resolve_import_links` at the end. Media/files: media URL (`find_media`). External: full `https://` URL.",
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
@@ -836,7 +857,7 @@
     },
     {
       "name": "delete_content_instances",
-      "description": "Soft-delete 1..N ORPHAN content_instances in one transaction. Orphan = no placements AND no parent instance shows it in a `module`/`module-list` field (`list_content_instances`: placements=0, parents=0).\nCORE RULES:\n- ANY refused item rolls back the WHOLE batch; the refusal names the blockers:\n  - placements (page path, pageId, blockName, position) -> detach each via `fork_placement_content` with those values (page keeps a private copy), then retry.\n  - parents -> first remove the ref from each parent's field via `set_content_instance_values_many`.\n- In a chat this lands on the draft; live changes when staged.",
+      "description": "Soft-delete 1..N ORPHAN content_instances in one transaction. Orphan = no placements AND no parent shows it — no instance's `module`/`module-list` field, module default or shared list (`list_content_instances`: placements=0, parents=0).\nCORE RULES:\n- ANY refused item rolls back the WHOLE batch; the refusal names the blockers:\n  - placements (page path, pageId, blockName, position) -> detach each via `fork_placement_content` with those values (page keeps a private copy), then retry.\n  - parents -> detach first: an instance parent via `set_content_instance_values_many` (or delete the parent EARLIER in the same call), a module default via `update_modules_many`, a shared list entry via `patch_list_items_many`.\n- In a chat this lands on the draft; live changes when staged.",
       "inputSchema": {
         "type": "object",
         "additionalProperties": false,
@@ -1116,7 +1137,7 @@
     },
     {
       "name": "list_modules",
-      "description": "List the module catalog (metadata, no HTML/CSS/JS): id, slug, type, kind, description, fields, placement usage.\nUSE FOR: a reuse candidate before placing/creating (prefer `add_module` with `moduleId` over a near-duplicate); the accepted child types before filling a `module`/`module-list` field.\nFields column: `blocks:module-list allowed=faq/cta` -> child `type` must be one of them (`allowed=any` = unrestricted). `nav:list(menu) shared=main-nav` = shared list (edit entries via `patch_list_items_many`) | `items:list(texts) local` = entries per placement | `latest:list(links) source=query(…)`.",
+      "description": "List the module catalog (metadata, no HTML/CSS/JS): id, slug, type, kind, description, fields, placement usage.\nUSE FOR: a reuse candidate before placing/creating (prefer `add_module` with `moduleId` over a near-duplicate); the accepted child types before filling a `module`/`module-list` field.\nFields column: `blocks:module-list allowed=faq/cta` -> child `type` must be one of them (`allowed=any` = unrestricted). `nav:list(menu) shared=main-nav` = shared list (edit entries via `patch_list_items_many`) | `items:list(texts) local` = entries per placement | `latest:list(links) source=query(…)` | `… paginate(per_page=50 follow_ups=index)` = overview of every match over follow-up pages.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -2387,7 +2408,28 @@
                 },
                 "source": {
                   "type": "object",
-                  "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                  "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages|pagination} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                },
+                "paginate": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "description": "Overview of ALL matching pages (query without `limit`, or term_pages): page 1 here, then <path>/page/2/…; one per module. Needs a pager field (source system \"pagination\": {{number}}, {{link}}, is_current/is_prev/is_next). A placement may override with value `paginate`.",
+                  "properties": {
+                    "per_page": {
+                      "type": "integer",
+                      "minimum": 1,
+                      "maximum": 50,
+                      "description": "Default 50."
+                    },
+                    "follow_ups": {
+                      "type": "string",
+                      "enum": [
+                        "index",
+                        "noindex"
+                      ],
+                      "description": "Default \"index\" (self-canonical, in sitemap)."
+                    }
+                  }
                 },
                 "allowedModuleTypes": {
                   "type": "array",
@@ -4061,6 +4103,10 @@
             "minLength": 1,
             "maxLength": 300,
             "description": "CSS selector: capture only the first match (e.g. '[data-caelo-module-id=\"<uuid>\"]', 'footer.caelo-layout-footer') — cheaper when checking one module. Error if nothing matches."
+          },
+          "fullPage": {
+            "type": "boolean",
+            "description": "Server render only: true = the whole page; default = the visible viewport. Prefer `selector` for one section below the fold."
           }
         }
       }
@@ -4577,7 +4623,28 @@
                       },
                       "source": {
                         "type": "object",
-                        "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                        "description": "bind \"source\": {kind:\"query\", editable, defaults} | {kind:\"system\", name: breadcrumbs|children|siblings|page_terms|term_pages|pagination} | {kind:\"plugin\", name} (a plugin list iterated by name needs no field)."
+                      },
+                      "paginate": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "description": "Overview of ALL matching pages (query without `limit`, or term_pages): page 1 here, then <path>/page/2/…; one per module. Needs a pager field (source system \"pagination\": {{number}}, {{link}}, is_current/is_prev/is_next). A placement may override with value `paginate`.",
+                        "properties": {
+                          "per_page": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 50,
+                            "description": "Default 50."
+                          },
+                          "follow_ups": {
+                            "type": "string",
+                            "enum": [
+                              "index",
+                              "noindex"
+                            ],
+                            "description": "Default \"index\" (self-canonical, in sitemap)."
+                          }
+                        }
                       },
                       "allowedModuleTypes": {
                         "type": "array",