@nextblock-cms/cortex 0.20.0 → 0.20.1

package/lib/mcp-server.es.js

@@ -1,41 +1,41 @@
-import { getCortexMcpPrompt as d, readCortexMcpResource as m, callCortexMcpTool as T, CortexMcpUnknownToolError as P, CortexMcpForbiddenToolError as M, buildCortexMcpToolDefinitions as x, CORTEX_MCP_PROMPTS as g, CORTEX_MCP_RESOURCES as y } from "./mcp-tool-registry.es.js";
-const N = "nextblock-cortex-ai", b = "NextBlock Cortex AI", S = "2025-06-18", O = "2025-11-25", p = "2026-07-28", w = [
+import { getCortexMcpPrompt as x, readCortexMcpResource as M, callCortexMcpTool as P, CortexMcpUnknownToolError as b, CortexMcpForbiddenToolError as g, buildCortexMcpToolDefinitions as v, CORTEX_MCP_PROMPTS as S, CORTEX_MCP_RESOURCES as y } from "./mcp-tool-registry.es.js";
+const E = "nextblock-cortex-ai", d = "NextBlock Cortex AI", N = "2025-06-18", O = "2025-11-25", p = "2026-07-28", m = [
   p,
   O,
   "2025-06-18",
   "2025-03-26",
   "2024-11-05"
-], k = -32700, C = -32600, A = -32601, l = -32602, E = -32603;
+], V = -32700, R = -32600, w = -32601, l = -32602, h = -32603;
 function u(t, o) {
   return { body: { id: t, jsonrpc: "2.0", result: o }, status: 200 };
 }
-function a(t, o, i, r = 200, c) {
+function a(t, o, i, e = 200, c) {
   return {
     body: {
       error: { code: o, message: i },
       id: t,
       jsonrpc: "2.0"
     },
-    status: r
+    status: e
   };
 }
 const s = { body: null, status: 202 };
-function v(t) {
+function A(t) {
   return typeof t.method == "string" && t.id === void 0;
 }
 function D(t, o) {
   const i = t.params?._meta;
   if (i && typeof i == "object") {
-    const r = i["io.modelcontextprotocol/protocolVersion"];
-    if (typeof r == "string" && r >= p)
+    const e = i["io.modelcontextprotocol/protocolVersion"];
+    if (typeof e == "string" && e >= p)
       return !0;
   }
   return !!(o && o >= p);
 }
-function I(t) {
-  return typeof t != "string" || !t ? S : w.includes(t) ? t : O;
+function k(t) {
+  return typeof t != "string" || !t ? N : m.includes(t) ? t : O;
 }
-function L(t, o) {
+function I(t, o) {
   const i = t.scopes.includes("write");
   return {
     capabilities: {
@@ -52,107 +52,131 @@ function L(t, o) {
       "Conventions: a page or post feature_image_id renders as a full-width title banner above the content and is its share preview — give posts one, never the home page or a page with its own hero section (use update_site_identity social_image for the site-wide preview); mark hero sections is_hero:true; slider:true plus slides makes a carousel.",
       i ? "Page builds should go through generate_jsonb_layout, which stages a reviewable Live Draft rather than publishing directly." : "This connection is READ-ONLY. Mutating tools are not available on this token."
     ].join(" "),
-    protocolVersion: I(o),
+    protocolVersion: k(o),
     serverInfo: {
-      name: N,
-      title: b,
+      name: E,
+      title: d,
       version: t.serverVersion,
       websiteUrl: "https://nextblock.dev"
     }
   };
 }
-async function j(t, o) {
+function U(t) {
+  return {
+    authentication: {
+      header: "Authorization",
+      instructions: "POST JSON-RPC 2.0 messages with `Authorization: Bearer <token>`. Create the token in the NextBlock CMS (Settings → Cortex AI → MCP server access) or set MCP_BEARER_TOKEN in the environment. Cortex AI must be active on the site.",
+      required: !0,
+      schemes: ["bearer"]
+    },
+    capabilities: { prompts: {}, resources: {}, tools: {} },
+    endpoint: { transport: "streamable-http", url: t.endpointUrl },
+    name: E,
+    protocolVersions: m,
+    serverCard: t.serverCardUrl,
+    status: "ok",
+    title: d,
+    version: t.serverVersion,
+    websiteUrl: "https://nextblock.dev"
+  };
+}
+function j(t) {
+  return !!(t && t.toLowerCase().includes("text/event-stream"));
+}
+async function J(t, o) {
   if (t === null || typeof t != "object" || Array.isArray(t))
-    return a(null, C, "Expected a single JSON-RPC message.", 400);
+    return a(null, R, "Expected a single JSON-RPC message.", 400);
   if (typeof t.method != "string")
-    return "result" in t || "error" in t ? s : a(t.id ?? null, C, 'Missing "method".', 400);
-  const { method: i } = t, r = t.id ?? null, c = v(t);
+    return "result" in t || "error" in t ? s : a(t.id ?? null, R, 'Missing "method".', 400);
+  const { method: i } = t, e = t.id ?? null, c = A(t);
   if (i.startsWith("notifications/"))
     return s;
   switch (i) {
     case "initialize":
-      return c ? s : u(r, L(o, t.params?.protocolVersion));
+      return c ? s : u(e, I(o, t.params?.protocolVersion));
     case "ping":
-      return c ? s : u(r, {});
+      return c ? s : u(e, {});
     case "tools/list":
-      return c ? s : u(r, {
-        tools: x({ context: o.context, scopes: o.scopes })
+      return c ? s : u(e, {
+        tools: v({ context: o.context, scopes: o.scopes })
       });
     case "tools/call": {
       if (c)
         return s;
       const n = t.params?.name;
       if (typeof n != "string" || !n)
-        return a(r, l, "tools/call requires params.name.");
+        return a(e, l, "tools/call requires params.name.");
       try {
-        const e = await T({
+        const r = await P({
           args: t.params?.arguments,
           context: o.context,
           name: n,
           scopes: o.scopes
         });
-        return u(r, e);
-      } catch (e) {
-        return e instanceof P || e instanceof M ? a(r, l, e.message) : a(
-          r,
-          E,
-          e instanceof Error ? e.message : "Tool execution failed."
+        return u(e, r);
+      } catch (r) {
+        return r instanceof b || r instanceof g ? a(e, l, r.message) : a(
+          e,
+          h,
+          r instanceof Error ? r.message : "Tool execution failed."
         );
       }
     }
     case "resources/list":
-      return c ? s : u(r, { resources: y });
+      return c ? s : u(e, { resources: y });
     case "resources/templates/list":
-      return c ? s : u(r, { resourceTemplates: [] });
+      return c ? s : u(e, { resourceTemplates: [] });
     case "resources/read": {
       if (c)
         return s;
       const n = t.params?.uri;
       if (typeof n != "string" || !n)
-        return a(r, l, "resources/read requires params.uri.");
+        return a(e, l, "resources/read requires params.uri.");
       try {
-        const e = await m({ context: o.context, uri: n });
-        return e ? u(r, { contents: [e] }) : a(r, l, `Unknown resource: ${n}`);
-      } catch (e) {
+        const r = await M({ context: o.context, uri: n });
+        return r ? u(e, { contents: [r] }) : a(e, l, `Unknown resource: ${n}`);
+      } catch (r) {
         return a(
-          r,
-          E,
-          e instanceof Error ? e.message : "Resource read failed."
+          e,
+          h,
+          r instanceof Error ? r.message : "Resource read failed."
         );
       }
     }
     case "prompts/list":
-      return c ? s : u(r, { prompts: g });
+      return c ? s : u(e, { prompts: S });
     case "prompts/get": {
       if (c)
         return s;
       const n = t.params?.name;
       if (typeof n != "string" || !n)
-        return a(r, l, "prompts/get requires params.name.");
-      const e = t.params?.arguments, f = {};
-      if (e && typeof e == "object")
-        for (const [h, R] of Object.entries(e))
-          typeof R == "string" && (f[h] = R);
-      const _ = d({ args: f, name: n });
-      return _ ? u(r, _) : a(r, l, `Unknown prompt: ${n}`);
+        return a(e, l, "prompts/get requires params.name.");
+      const r = t.params?.arguments, f = {};
+      if (r && typeof r == "object")
+        for (const [T, C] of Object.entries(r))
+          typeof C == "string" && (f[T] = C);
+      const _ = x({ args: f, name: n });
+      return _ ? u(e, _) : a(e, l, `Unknown prompt: ${n}`);
     }
     default:
-      return c ? s : a(r, A, `Method not found: ${i}`);
+      return c ? s : a(e, w, `Method not found: ${i}`);
   }
 }
 export {
-  S as CORTEX_MCP_DEFAULT_PROTOCOL_VERSION,
+  N as CORTEX_MCP_DEFAULT_PROTOCOL_VERSION,
   O as CORTEX_MCP_LATEST_LEGACY_PROTOCOL_VERSION,
   p as CORTEX_MCP_MODERN_PROTOCOL_VERSION,
-  N as CORTEX_MCP_SERVER_NAME,
-  b as CORTEX_MCP_SERVER_TITLE,
-  w as CORTEX_MCP_SUPPORTED_PROTOCOL_VERSIONS,
-  E as JSON_RPC_INTERNAL_ERROR,
+  E as CORTEX_MCP_SERVER_NAME,
+  d as CORTEX_MCP_SERVER_TITLE,
+  m as CORTEX_MCP_SUPPORTED_PROTOCOL_VERSIONS,
+  h as JSON_RPC_INTERNAL_ERROR,
   l as JSON_RPC_INVALID_PARAMS,
-  C as JSON_RPC_INVALID_REQUEST,
-  A as JSON_RPC_METHOD_NOT_FOUND,
-  k as JSON_RPC_PARSE_ERROR,
-  j as handleCortexMcpMessage,
-  v as isJsonRpcNotification,
-  D as isModernEraMessage
+  R as JSON_RPC_INVALID_REQUEST,
+  w as JSON_RPC_METHOD_NOT_FOUND,
+  V as JSON_RPC_PARSE_ERROR,
+  U as buildCortexMcpDiscoveryDocument,
+  J as handleCortexMcpMessage,
+  A as isJsonRpcNotification,
+  D as isModernEraMessage,
+  j as wantsMcpEventStream
 };

package/lib/mcp-tool-registry.cjs.js

@@ -1,6 +1,6 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const k=require("./ai-global-agent-tools.cjs.js"),x=require("./block-content-schemas.cjs.js");require("./zod-config.cjs.js");const v=require("zod"),n={create_cms_page:"write",create_cms_post:"write",create_cms_product:"write",create_custom_block:"write",delete_cms_item:"write",delete_custom_block:"write",describe_database_schema:"read",execute_cms_action_plan:"write",execute_database_action_plan:"write",execute_database_mutation:"write",fetch_ecommerce_stats:"read",fetch_url_content:"read",finish_site_build:"write",get_site_overview:"read",insert_content_block:"write",list_custom_blocks:"read",list_media:"read",list_product_categories:"read",list_site_script_revisions:"read",list_site_scripts:"read",list_site_themes:"read",manage_language:"write",manage_product_category:"write",manage_product_variants:"write",manage_site_script:"write",manage_site_theme:"write",prepare_delete_cms_item:"read",publish_content_draft:"write",read_current_cms_item:"read",read_database_records:"read",reset_site_content:"write",revert_site_script:"write",rewrite_page_draft:"write",save_site_brief:"write",search_documentation:"read",search_stock_photos:"read",set_content_images:"write",start_site_build:"write",translate_content_bulk:"write",translate_page:"write",update_cms_item_field:"write",upload_media:"write",update_content_block:"write",update_current_cms_fields:"write",update_custom_block:"write",update_footer:"write",update_global_css:"write",update_navigation_bar:"write",update_section_column_block:"write",update_site_identity:"write"},s={create_page_layout:{canonical:"create_cms_page",description:'Create a new page from a slug, a title and a strictly typed block layout in one call. Every block is normalized and validated against the NextBlock block schema (built-in types from the `cortex://schema/blocks` resource, or a custom block slug from `list_custom_blocks`) before anything is written; an invalid block rejects the whole call. Pass `status: "published"` to go live immediately, or leave the default draft and publish later. To rewrite an existing page instead, use `generate_jsonb_layout`. Alias of `create_cms_page`.',title:"Create page layout"},generate_jsonb_layout:{canonical:"rewrite_page_draft",description:"Generate a complete, strictly-validated JSONB block layout and write it into a target page or post. Blocks are normalized and validated against the NextBlock block schema, then staged as a Live Draft on the target record — nothing goes live until an editor publishes the draft, and publishing snapshots a revision so the change is reversible. Use for whole-page builds and redesigns. Alias of `rewrite_page_draft`.",title:"Generate JSONB layout"},get_database_schema:{canonical:"describe_database_schema",description:"Return the current CMS database structure: every table Cortex AI may read or mutate, its columns, primary keys, and whether it is read-only. Pair with `list_custom_blocks` for the active data-defined block definitions and with the `cortex://schema/blocks` resource for the built-in block types. Read-only. Alias of `describe_database_schema`.",title:"Get database schema"},query_site_analytics:{canonical:"fetch_ecommerce_stats",description:"Query quantitative site analytics: revenue, order counts, order-status breakdowns, and top-selling products over a time range. Read-only. For inventory levels and post/page metrics that this report does not cover, use `read_database_records` against the `products`, `product_variants`, `posts`, or `pages` tables. Alias of `fetch_ecommerce_stats`.",title:"Query site analytics"},search_stock_media:{canonical:"search_stock_photos",description:"Search free stock media (Pexels, then Unsplash) for contextually relevant imagery, returning direct image URLs with dimensions, alt text, and photographer attribution. Drop a returned `url` straight into an image block's `external_url` or a section background. Read-only and zero cost. Requires a stock provider key in CMS Settings → Cortex AI. Alias of `search_stock_photos`.",title:"Search stock media"},update_site_navigation:{canonical:"update_navigation_bar",description:'Alter the public site navigation: header menu items and their nested child hierarchy, per locale. Use mode "append" to add links while preserving the existing menu, "update" to rename or re-point one link, and "replace" only when rebuilding the whole menu. For footer links and copyright use `update_footer`. Alias of `update_navigation_bar`.',title:"Update site navigation"}};function h(e){return e in s?s[e].canonical:e in n?e:null}function b(e){const t=h(e);return t?n[t]:null}function c(e,t){const a=b(t);return a?a==="read"?e.length>0:e.includes("write"):!1}function g(e){return e.split("_").map((a,r)=>r===0?a.charAt(0).toUpperCase()+a.slice(1):a).join(" ")}function _(e){const t={additionalProperties:!1,type:"object"};if(!e||typeof e!="object")return t;try{const a=v.z.toJSONSchema(e,{cycles:"ref",io:"input",reused:"inline",target:"draft-2020-12",unrepresentable:"any"});return delete a.$schema,a.type==="object"?a:t}catch{return t}}function l(e){return k.createCortexGlobalAgentTools(e)}function C(e){const t=Object.keys(l(e)),a=Object.keys(n);return{missingFromRegistry:a.filter(r=>!t.includes(r)),unclassified:t.filter(r=>!a.includes(r))}}function T(e){const t=l(e.context),a=[];for(const[r,i]of Object.entries(t))!(r in n)||!c(e.scopes,r)||a.push({description:i.description??`Cortex AI ${g(r)} tool.`,inputSchema:_(i.inputSchema),name:r,title:g(r)});for(const[r,i]of Object.entries(s)){const o=t[i.canonical];!o||!c(e.scopes,r)||a.push({description:i.description,inputSchema:_(o.inputSchema),name:r,title:i.title})}return a.sort((r,i)=>r.name.localeCompare(i.name))}function m(e,t){return{content:[{text:e,type:"text"}],isError:t}}function S(e){return e.issues.map(t=>`${t.path.length>0?t.path.join("."):"(root)"}: ${t.message}`).join("; ")}class p extends Error{constructor(t){super(`Unknown tool: ${t}`),this.name="CortexMcpUnknownToolError"}}class f extends Error{constructor(t){super(`Tool "${t}" requires the "write" scope. This MCP token is read-only — mint a read+write token in CMS Settings → Cortex AI.`),this.name="CortexMcpForbiddenToolError"}}async function M(e){const t=h(e.name);if(!t)throw new p(e.name);if(!c(e.scopes,e.name))throw new f(e.name);const r=l(e.context)[t];if(!r||typeof r.execute!="function")throw new p(e.name);const i=e.args&&typeof e.args=="object"?e.args:{};if(r.inputSchema&&typeof r.inputSchema.safeParse=="function"){const o=r.inputSchema.safeParse(i);if(!o.success)return m(`Invalid arguments for "${e.name}": ${S(o.error)}`,!0)}try{const o=await r.execute(i),u=JSON.stringify(o??{success:!0},null,2),d=o&&typeof o=="object"&&!Array.isArray(o)?o:null,w=d?.success===!1;return{content:[{text:u,type:"text"}],isError:w,...d?{structuredContent:d}:{}}}catch(o){const u=o instanceof Error?o.message:String(o);return m(`Tool "${e.name}" failed: ${u}`,!0)}}const R=[{description:"The CMS database structure Cortex AI can read and mutate: tables, columns, primary keys, and read-only flags.",mimeType:"application/json",name:"database-schema",title:"NextBlock database schema",uri:"cortex://schema/database"},{description:"The built-in NextBlock block types available when composing page, post, and product layouts.",mimeType:"application/json",name:"block-types",title:"NextBlock block types",uri:"cortex://schema/blocks"},{description:"Data-defined custom block definitions registered in this workspace, keyed by the slug used as a block instance `block_type`.",mimeType:"application/json",name:"custom-blocks",title:"NextBlock custom block definitions",uri:"cortex://schema/custom-blocks"}];async function O(e){const t=l(e.context);if(e.uri==="cortex://schema/database"){const a=await t.describe_database_schema?.execute?.({includeReadOnly:!0});return{mimeType:"application/json",text:JSON.stringify(a??{},null,2),uri:e.uri}}if(e.uri==="cortex://schema/blocks")return{mimeType:"application/json",text:JSON.stringify({blockTypes:x.availableCortexAiBlockTypes},null,2),uri:e.uri};if(e.uri==="cortex://schema/custom-blocks"){const a=await t.list_custom_blocks?.execute?.({});return{mimeType:"application/json",text:JSON.stringify(a??{},null,2),uri:e.uri}}return null}const y=[{arguments:[{description:'Everything known about the client and the site they want: business, audience, goals, pages (or "one landing page"), languages, brand, contact details. Leave blank to be asked.',name:"brief",required:!1}],description:"Build (or rebuild) the whole NextBlock site from a brief: remove the sample content, set the identity and theme, create and publish every page, the menus, the footer, and the translations.",name:"build-site",title:"Build the whole site"},{arguments:[{description:"What the page is for, and any brand or tone notes.",name:"brief",required:!0},{description:'Slug of the page or post to rewrite, e.g. "home".',name:"slug",required:!0}],description:"Build or redesign a NextBlock page from a brief, following the section-based layout recipe, and stage it as a reviewable Live Draft.",name:"build-page",title:"Build a NextBlock page"},{arguments:[{description:"Source URL to draw structure and copy from.",name:"url",required:!0},{description:"Slug of the page to write the result into.",name:"slug",required:!0}],description:"Read an external page and rebuild an equivalent NextBlock page from it, reusing its imagery where available.",name:"clone-from-url",title:"Rebuild a page from a URL"},{arguments:[{description:'Target language code, e.g. "fr".',name:"languageCode",required:!0},{description:"Slug of the page or post to translate.",name:"slug",required:!0}],description:"Translate an existing page or post into another language, preserving its layout and imagery.",name:"translate-content",title:"Translate a page or post"}],j={"build-site":e=>["Build the whole NextBlock site for this client.","",e.brief?.trim()?`Brief:
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const x=require("./ai-global-agent-tools.cjs.js"),C=require("./block-content-schemas.cjs.js");require("./zod-config.cjs.js");const T=require("zod"),s={create_cms_page:"write",create_cms_post:"write",create_cms_product:"write",create_custom_block:"write",delete_cms_item:"write",delete_custom_block:"write",describe_database_schema:"read",execute_cms_action_plan:"write",execute_database_action_plan:"write",execute_database_mutation:"write",fetch_ecommerce_stats:"read",fetch_url_content:"read",finish_site_build:"write",get_site_overview:"read",insert_content_block:"write",list_custom_blocks:"read",list_media:"read",list_product_categories:"read",list_site_script_revisions:"read",list_site_scripts:"read",list_site_themes:"read",manage_language:"write",manage_product_category:"write",manage_product_variants:"write",manage_site_script:"write",manage_site_theme:"write",prepare_delete_cms_item:"read",publish_content_draft:"write",read_current_cms_item:"read",read_database_records:"read",reset_site_content:"write",revert_site_script:"write",rewrite_page_draft:"write",save_site_brief:"write",search_documentation:"read",search_stock_photos:"read",set_content_images:"write",start_site_build:"write",translate_content_bulk:"write",translate_page:"write",update_cms_item_field:"write",upload_media:"write",update_content_block:"write",update_current_cms_fields:"write",update_custom_block:"write",update_footer:"write",update_global_css:"write",update_navigation_bar:"write",update_section_column_block:"write",update_site_identity:"write"},b={create_cms_page:{destructive:!1,idempotent:!0,openWorld:!0},create_cms_post:{destructive:!1,idempotent:!0,openWorld:!0},create_cms_product:{destructive:!1,idempotent:!0,openWorld:!0},create_custom_block:{destructive:!1,idempotent:!1,openWorld:!1},delete_cms_item:{destructive:!0,idempotent:!0,openWorld:!1},delete_custom_block:{destructive:!0,idempotent:!0,openWorld:!1},execute_cms_action_plan:{destructive:!0,idempotent:!1,openWorld:!0},execute_database_action_plan:{destructive:!0,idempotent:!1,openWorld:!1},execute_database_mutation:{destructive:!0,idempotent:!1,openWorld:!1},finish_site_build:{destructive:!1,idempotent:!0,openWorld:!1},insert_content_block:{destructive:!1,idempotent:!1,openWorld:!1},manage_language:{destructive:!1,idempotent:!0,openWorld:!1},manage_product_category:{destructive:!0,idempotent:!0,openWorld:!1},manage_product_variants:{destructive:!0,idempotent:!1,openWorld:!1},manage_site_script:{destructive:!0,idempotent:!0,openWorld:!1},manage_site_theme:{destructive:!1,idempotent:!0,openWorld:!1},publish_content_draft:{destructive:!1,idempotent:!0,openWorld:!1},reset_site_content:{destructive:!0,idempotent:!0,openWorld:!1},revert_site_script:{destructive:!1,idempotent:!0,openWorld:!1},rewrite_page_draft:{destructive:!1,idempotent:!0,openWorld:!1},save_site_brief:{destructive:!0,idempotent:!0,openWorld:!1},set_content_images:{destructive:!0,idempotent:!1,openWorld:!0},start_site_build:{destructive:!0,idempotent:!1,openWorld:!1},translate_content_bulk:{destructive:!1,idempotent:!0,openWorld:!1},translate_page:{destructive:!1,idempotent:!0,openWorld:!1},update_cms_item_field:{destructive:!1,idempotent:!0,openWorld:!1},upload_media:{destructive:!1,idempotent:!1,openWorld:!0},update_content_block:{destructive:!1,idempotent:!0,openWorld:!1},update_current_cms_fields:{destructive:!1,idempotent:!0,openWorld:!1},update_custom_block:{destructive:!0,idempotent:!1,openWorld:!1},update_footer:{destructive:!0,idempotent:!0,openWorld:!1},update_global_css:{destructive:!0,idempotent:!1,openWorld:!1},update_navigation_bar:{destructive:!0,idempotent:!0,openWorld:!1},update_section_column_block:{destructive:!1,idempotent:!0,openWorld:!1},update_site_identity:{destructive:!1,idempotent:!0,openWorld:!1}},S=new Set(["fetch_url_content","search_stock_photos"]),c={create_page_layout:{canonical:"create_cms_page",description:'Create a new page from a slug, a title and a strictly typed block layout in one call. Every block is normalized and validated against the NextBlock block schema (built-in types from the `cortex://schema/blocks` resource, or a custom block slug from `list_custom_blocks`) before anything is written; an invalid block rejects the whole call. Pass `status: "published"` to go live immediately, or leave the default draft and publish later. To rewrite an existing page instead, use `generate_jsonb_layout`. Alias of `create_cms_page`.',title:"Create page layout"},generate_jsonb_layout:{canonical:"rewrite_page_draft",description:"Generate a complete, strictly-validated JSONB block layout and write it into a target page or post. Blocks are normalized and validated against the NextBlock block schema, then staged as a Live Draft on the target record — nothing goes live until an editor publishes the draft, and publishing snapshots a revision so the change is reversible. Use for whole-page builds and redesigns. Alias of `rewrite_page_draft`.",title:"Generate JSONB layout"},get_database_schema:{canonical:"describe_database_schema",description:"Return the current CMS database structure: every table Cortex AI may read or mutate, its columns, primary keys, and whether it is read-only. Pair with `list_custom_blocks` for the active data-defined block definitions and with the `cortex://schema/blocks` resource for the built-in block types. Read-only. Alias of `describe_database_schema`.",title:"Get database schema"},query_site_analytics:{canonical:"fetch_ecommerce_stats",description:"Query quantitative site analytics: revenue, order counts, order-status breakdowns, and top-selling products over a time range. Read-only. For inventory levels and post/page metrics that this report does not cover, use `read_database_records` against the `products`, `product_variants`, `posts`, or `pages` tables. Alias of `fetch_ecommerce_stats`.",title:"Query site analytics"},search_stock_media:{canonical:"search_stock_photos",description:"Search free stock media (Pexels, then Unsplash) for contextually relevant imagery, returning direct image URLs with dimensions, alt text, and photographer attribution. Drop a returned `url` straight into an image block's `external_url` or a section background. Read-only and zero cost. Requires a stock provider key in CMS Settings → Cortex AI. Alias of `search_stock_photos`.",title:"Search stock media"},update_site_navigation:{canonical:"update_navigation_bar",description:'Alter the public site navigation: header menu items and their nested child hierarchy, per locale. Use mode "append" to add links while preserving the existing menu, "update" to rename or re-point one link, and "replace" only when rebuilding the whole menu. For footer links and copyright use `update_footer`. Alias of `update_navigation_bar`.',title:"Update site navigation"}};function d(e){return e in c?c[e].canonical:e in s?e:null}function y(e){const t=d(e);return t?s[t]:null}function _(e){const t=d(e);if(!t)return null;if(s[t]==="read")return{destructiveHint:!1,idempotentHint:!0,openWorldHint:S.has(t),readOnlyHint:!0};const r=b[t];return{destructiveHint:r.destructive,idempotentHint:r.idempotent,openWorldHint:r.openWorld,readOnlyHint:!1}}function l(e,t){const r=y(t);return r?r==="read"?e.length>0:e.includes("write"):!1}function h(e){return e.split("_").map((r,o)=>o===0?r.charAt(0).toUpperCase()+r.slice(1):r).join(" ")}function g(e){const t={additionalProperties:!1,type:"object"};if(!e||typeof e!="object")return t;try{const r=T.z.toJSONSchema(e,{cycles:"ref",io:"input",reused:"inline",target:"draft-2020-12",unrepresentable:"any"});return delete r.$schema,r.type==="object"?r:t}catch{return t}}function u(e){return x.createCortexGlobalAgentTools(e)}function O(e){const t=Object.keys(u(e)),r=Object.keys(s);return{missingFromRegistry:r.filter(o=>!t.includes(o)),unclassified:t.filter(o=>!r.includes(o))}}function M(e){const t=u(e.context),r=[];for(const[o,i]of Object.entries(t)){if(!(o in s)||!l(e.scopes,o))continue;const a=_(o);a&&r.push({annotations:a,description:i.description??`Cortex AI ${h(o)} tool.`,inputSchema:g(i.inputSchema),name:o,title:h(o)})}for(const[o,i]of Object.entries(c)){const a=t[i.canonical];if(!a||!l(e.scopes,o))continue;const n=_(o);n&&r.push({annotations:n,description:i.description,inputSchema:g(a.inputSchema),name:o,title:i.title})}return r.sort((o,i)=>o.name.localeCompare(i.name))}function f(e,t){return{content:[{text:e,type:"text"}],isError:t}}function R(e){return e.issues.map(t=>`${t.path.length>0?t.path.join("."):"(root)"}: ${t.message}`).join("; ")}class m extends Error{constructor(t){super(`Unknown tool: ${t}`),this.name="CortexMcpUnknownToolError"}}class v extends Error{constructor(t){super(`Tool "${t}" requires the "write" scope. This MCP token is read-only — mint a read+write token in CMS Settings → Cortex AI.`),this.name="CortexMcpForbiddenToolError"}}async function W(e){const t=d(e.name);if(!t)throw new m(e.name);if(!l(e.scopes,e.name))throw new v(e.name);const o=u(e.context)[t];if(!o||typeof o.execute!="function")throw new m(e.name);const i=e.args&&typeof e.args=="object"?e.args:{};if(o.inputSchema&&typeof o.inputSchema.safeParse=="function"){const a=o.inputSchema.safeParse(i);if(!a.success)return f(`Invalid arguments for "${e.name}": ${R(a.error)}`,!0)}try{const a=await o.execute(i),n=JSON.stringify(a??{success:!0},null,2),p=a&&typeof a=="object"&&!Array.isArray(a)?a:null,k=p?.success===!1;return{content:[{text:n,type:"text"}],isError:k,...p?{structuredContent:p}:{}}}catch(a){const n=a instanceof Error?a.message:String(a);return f(`Tool "${e.name}" failed: ${n}`,!0)}}const E=[{description:"The CMS database structure Cortex AI can read and mutate: tables, columns, primary keys, and read-only flags.",mimeType:"application/json",name:"database-schema",title:"NextBlock database schema",uri:"cortex://schema/database"},{description:"The built-in NextBlock block types available when composing page, post, and product layouts.",mimeType:"application/json",name:"block-types",title:"NextBlock block types",uri:"cortex://schema/blocks"},{description:"Data-defined custom block definitions registered in this workspace, keyed by the slug used as a block instance `block_type`.",mimeType:"application/json",name:"custom-blocks",title:"NextBlock custom block definitions",uri:"cortex://schema/custom-blocks"}];async function P(e){const t=u(e.context);if(e.uri==="cortex://schema/database"){const r=await t.describe_database_schema?.execute?.({includeReadOnly:!0});return{mimeType:"application/json",text:JSON.stringify(r??{},null,2),uri:e.uri}}if(e.uri==="cortex://schema/blocks")return{mimeType:"application/json",text:JSON.stringify({blockTypes:C.availableCortexAiBlockTypes},null,2),uri:e.uri};if(e.uri==="cortex://schema/custom-blocks"){const r=await t.list_custom_blocks?.execute?.({});return{mimeType:"application/json",text:JSON.stringify(r??{},null,2),uri:e.uri}}return null}const w=[{arguments:[{description:'Everything known about the client and the site they want: business, audience, goals, pages (or "one landing page"), languages, brand, contact details. Leave blank to be asked.',name:"brief",required:!1}],description:"Build (or rebuild) the whole NextBlock site from a brief: remove the sample content, set the identity and theme, create and publish every page, the menus, the footer, and the translations.",name:"build-site",title:"Build the whole site"},{arguments:[{description:"What the page is for, and any brand or tone notes.",name:"brief",required:!0},{description:'Slug of the page or post to rewrite, e.g. "home".',name:"slug",required:!0}],description:"Build or redesign a NextBlock page from a brief, following the section-based layout recipe, and stage it as a reviewable Live Draft.",name:"build-page",title:"Build a NextBlock page"},{arguments:[{description:"Source URL to draw structure and copy from.",name:"url",required:!0},{description:"Slug of the page to write the result into.",name:"slug",required:!0}],description:"Read an external page and rebuild an equivalent NextBlock page from it, reusing its imagery where available.",name:"clone-from-url",title:"Rebuild a page from a URL"},{arguments:[{description:'Target language code, e.g. "fr".',name:"languageCode",required:!0},{description:"Slug of the page or post to translate.",name:"slug",required:!0}],description:"Translate an existing page or post into another language, preserving its layout and imagery.",name:"translate-content",title:"Translate a page or post"}],A={"build-site":e=>["Build the whole NextBlock site for this client.","",e.brief?.trim()?`Brief:
 ${e.brief}`:"A site brief may already be saved (get_site_overview returns it under `brief`): if it is, use it and skip the questions; otherwise ask, in one short numbered list, about the business and what it does, the audience and the one action visitors should take, the site shape (one landing page or which pages), the languages, brand colours and tone, contact details, and whether existing content is kept.","","Process:","1. Call get_site_overview to see what exists, the active languages, and whether the NextBlock demo content is still present. Record what you know with save_site_brief.","2. Present the plan (what is removed, every page with its sections, menus, footer, theme, languages) and call start_site_build with `summary`, `brief`, and `reset` (keepLanguages = the languages wanted) unless existing content is kept. Over MCP the host approves the call; there is no chat confirmation.",'3. Build: update_site_identity (title, description, keywords, copyright, and social_image for the share preview of pages without a feature image); manage_language as needed; manage_site_theme with the brand colours; search_stock_media for imagery when available; rewrite the empty "home" page with generate_jsonb_layout then publish_content_draft; create_cms_page (status "published") for every other page; update_site_navigation (mode "replace") and update_footer for every language; translate_content_bulk for each extra language.',"4. Call finish_site_build with a summary, then report every page with its URL.","Write real copy from the brief, never placeholders. Every page must exist in every active language.","Conventions: mark each page's opening section is_hero:true (priority image loading, centred content); slider:true with a slides array makes a rotating banner; NEVER set feature_image_id on the home page or on a page that opens with a hero section — on a page it renders a full-width title banner above the blocks — but give every post one."].join(`
 `),"build-page":e=>[`Build the NextBlock page with slug "${e.slug??"<slug>"}" from this brief:`,"",e.brief??"<brief>","","Process:","1. Call get_database_schema and read_current_cms_item (or read_database_records on `pages`) to ground yourself in what exists.",'2. Compose the page from `section` blocks: one column entry per grid track, the first section a hero (is_hero:true), alternating none / theme:"muted" / theme:"primary" backgrounds for rhythm. Use discrete heading blocks rather than <h2> inside text HTML. Do not set feature_image_id on a page that opens with a hero: on a page it renders a full-width title banner above the blocks.',"3. Call search_stock_media for real photography; copy each photo's attribution fields onto the image block.","4. Write the result with generate_jsonb_layout. It stages a Live Draft — tell the user to preview and publish it."].join(`
 `),"clone-from-url":e=>[`Rebuild the NextBlock page "${e.slug??"<slug>"}" based on ${e.url??"<url>"}.`,"","Process:","1. Call fetch_url_content on the URL first. Use its headings, text, and mainImage — never invent an image URL.","2. Map the source structure onto NextBlock `section` blocks; do not copy its markup verbatim.","3. Write the result with generate_jsonb_layout so it lands as a reviewable Live Draft."].join(`
 `),"translate-content":e=>[`Translate the page or post "${e.slug??"<slug>"}" into "${e.languageCode??"<languageCode>"}".`,"","Use the translate_page tool: it copies layout, structure, and imagery automatically and links the copy to the original translation group. Supply only the text translations — every visible string, including headings, paragraph text, button labels, image alt text, and captions. Do not rebuild the layout and do not search for new imagery."].join(`
-`)};function E(e){const t=y.find(r=>r.name===e.name),a=j[e.name];return!t||!a?null:{description:t.description,messages:[{content:{text:a(e.args??{}),type:"text"},role:"user"}]}}exports.CORTEX_MCP_PROMPTS=y;exports.CORTEX_MCP_RESOURCES=R;exports.CORTEX_MCP_TOOL_ALIASES=s;exports.CORTEX_MCP_TOOL_KINDS=n;exports.CortexMcpForbiddenToolError=f;exports.CortexMcpUnknownToolError=p;exports.assertCortexMcpToolCoverage=C;exports.buildCortexMcpToolDefinitions=T;exports.callCortexMcpTool=M;exports.cortexMcpScopesAllow=c;exports.getCortexMcpPrompt=E;exports.getCortexMcpToolKind=b;exports.readCortexMcpResource=O;exports.resolveCortexMcpToolName=h;
+`)};function N(e){const t=w.find(o=>o.name===e.name),r=A[e.name];return!t||!r?null:{description:t.description,messages:[{content:{text:r(e.args??{}),type:"text"},role:"user"}]}}exports.CORTEX_MCP_PROMPTS=w;exports.CORTEX_MCP_RESOURCES=E;exports.CORTEX_MCP_TOOL_ALIASES=c;exports.CORTEX_MCP_TOOL_KINDS=s;exports.CORTEX_MCP_WRITE_TOOL_BEHAVIOURS=b;exports.CortexMcpForbiddenToolError=v;exports.CortexMcpUnknownToolError=m;exports.assertCortexMcpToolCoverage=O;exports.buildCortexMcpToolDefinitions=M;exports.callCortexMcpTool=W;exports.cortexMcpScopesAllow=l;exports.getCortexMcpPrompt=N;exports.getCortexMcpToolAnnotations=_;exports.getCortexMcpToolKind=y;exports.readCortexMcpResource=P;exports.resolveCortexMcpToolName=d;

package/lib/mcp-tool-registry.d.ts

@@ -79,6 +79,238 @@ export declare const CORTEX_MCP_TOOL_KINDS: {
     readonly update_site_identity: "write";
 };
 export type CortexMcpCanonicalToolName = keyof typeof CORTEX_MCP_TOOL_KINDS;
+/** Canonical names classified `write`; the annotation table must cover exactly these. */
+export type CortexMcpWriteToolName = {
+    [K in CortexMcpCanonicalToolName]: (typeof CORTEX_MCP_TOOL_KINDS)[K] extends 'write' ? K : never;
+}[CortexMcpCanonicalToolName];
+/**
+ * MCP `ToolAnnotations` (spec 2025-03-26 onward; unchanged through 2026-07-28).
+ *
+ * Mirrors the spec interface field for field so a client typed against
+ * `@modelcontextprotocol/sdk` reads it without translation. Every field is a *hint*:
+ * the spec tells clients to treat them as untrusted, so they inform approval UX and
+ * retry policy, never authorization — that stays with the token scope.
+ *
+ * The defaults matter: when a server sends no annotations a client assumes
+ * `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`. So an
+ * unannotated read tool looks, to Claude Code or Cursor, exactly like a raw DELETE.
+ */
+export type CortexMcpToolAnnotations = {
+    /** Reserved by the spec for a display title; ours goes on the Tool itself. */
+    title?: string;
+    /** True when the tool only reads. Derived from CORTEX_MCP_TOOL_KINDS, never declared twice. */
+    readOnlyHint: boolean;
+    /** True when the tool can delete rows or discard content wholesale (see the table). */
+    destructiveHint: boolean;
+    /** True when repeating the same call leaves the site in the same state. */
+    idempotentHint: boolean;
+    /** True when an argument may name an arbitrary external host (URL fetch, web search). */
+    openWorldHint: boolean;
+};
+/**
+ * Behavioural hints for every WRITE tool, keyed by canonical name and typed against the
+ * scope table so a tool added to CORTEX_MCP_TOOL_KINDS without a row here fails to
+ * compile. Read tools are not listed: they are `destructive: false, idempotent: true`
+ * by definition and only choose `openWorld` (see READ_TOOL_OPEN_WORLD).
+ *
+ * The rules, applied from the executor code rather than the tool description:
+ *
+ * - `destructive` is true when the tool can delete rows or discard existing content
+ *   wholesale — a delete action or operation, a reset, or a "replace" mode that drops
+ *   what is there — with no revision snapshot or Live Draft to restore from. Field-level
+ *   overwrites of metadata and settings are not destructive; neither are page/post/
+ *   product edits, which `recordRevision` snapshots, nor `rewrite_page_draft`, which only
+ *   stages a draft. Mode-dependent tools take their worst mode, because the spec defines
+ *   the hint as "MAY perform destructive updates".
+ * - `idempotent` is true when a retry with identical arguments converges on the same
+ *   state: creates are refused on a duplicate slug (`assertUniqueSlug`) or an existing
+ *   translation before anything is written, drafts are delete-then-insert per parent,
+ *   navigation "append" skips URLs already present, settings and languages are upserts,
+ *   and deletes of something already gone are no-ops. It is false where a retry adds a
+ *   second copy (`insert_content_block`, CSS "append", variant "append", raw inserts,
+ *   URL imports that re-download into the media library) or where the output is
+ *   generated by a model and so differs run to run (custom block definitions).
+ * - `openWorld` is true only when an argument may name an arbitrary external host:
+ *   fetching a URL, searching stock providers, importing an image by URL. Writes that
+ *   merely register a stock-photo download as a side effect stay closed-world.
+ */
+export declare const CORTEX_MCP_WRITE_TOOL_BEHAVIOURS: {
+    readonly create_cms_page: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: true;
+    };
+    readonly create_cms_post: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: true;
+    };
+    readonly create_cms_product: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: true;
+    };
+    readonly create_custom_block: {
+        readonly destructive: false;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly delete_cms_item: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly delete_custom_block: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly execute_cms_action_plan: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: true;
+    };
+    readonly execute_database_action_plan: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly execute_database_mutation: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly finish_site_build: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly insert_content_block: {
+        readonly destructive: false;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly manage_language: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly manage_product_category: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly manage_product_variants: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly manage_site_script: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly manage_site_theme: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly publish_content_draft: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly reset_site_content: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly revert_site_script: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly rewrite_page_draft: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly save_site_brief: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly set_content_images: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: true;
+    };
+    readonly start_site_build: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly translate_content_bulk: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly translate_page: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_cms_item_field: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly upload_media: {
+        readonly destructive: false;
+        readonly idempotent: false;
+        readonly openWorld: true;
+    };
+    readonly update_content_block: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_current_cms_fields: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_custom_block: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly update_footer: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_global_css: {
+        readonly destructive: true;
+        readonly idempotent: false;
+        readonly openWorld: false;
+    };
+    readonly update_navigation_bar: {
+        readonly destructive: true;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_section_column_block: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+    readonly update_site_identity: {
+        readonly destructive: false;
+        readonly idempotent: true;
+        readonly openWorld: false;
+    };
+};
 /**
  * MCP-contract tool names that map onto existing executors.
  *
@@ -125,9 +357,16 @@ export type CortexMcpToolName = CortexMcpAliasToolName | CortexMcpCanonicalToolN
 /** Resolve an alias to the executor that actually runs, or pass a canonical name through. */
 export declare function resolveCortexMcpToolName(name: string): CortexMcpCanonicalToolName | null;
 export declare function getCortexMcpToolKind(name: string): CortexAiMcpScope | null;
+/**
+ * Annotations for a tool or alias, or `null` for an unknown name. An alias carries the
+ * annotations of the executor it forwards to — it cannot be safer than what it runs.
+ */
+export declare function getCortexMcpToolAnnotations(name: string): CortexMcpToolAnnotations | null;
 /** A token holding `write` implicitly holds `read`; there is no write-without-read tool. */
 export declare function cortexMcpScopesAllow(scopes: readonly CortexAiMcpScope[], name: string): boolean;
 export type CortexMcpToolDefinition = {
+    /** Always present: to a client, an absent annotation means "assume destructive". */
+    annotations: CortexMcpToolAnnotations;
     description: string;
     inputSchema: Record<string, unknown>;
     name: string;