@centrali-io/centrali-mcp 4.2.15 → 4.3.0

package/dist/tools/describe.js

@@ -941,7 +941,19 @@ function registerDescribeTools(server) {
                             "Use generate_starter_pages to auto-generate page proposals from your collections",
                             "Always validate_page before publish_page — publishing will reject if there are errors",
                             "Set access policy with set_page_access_policy before publishing if you need auth",
+                            "Use variable bindings on data sources to scope data dynamically — bind to URL params, auth context, record context, or static defaults",
+                            "For list→detail navigation: set useQueryParams:true on navigate-to-page actions, then bind the detail page's data source variables to { source: 'url', param: 'id' }. Use config.paramMapping to rename fields if source and target use different names (e.g., { requestId: 'id' })",
+                            "For user-scoped views (e.g., My Approvals): bind a variable to { source: 'auth', field: 'userId' } and use a smart query with {{assigneeId}}",
                         ],
+                        multi_page_pattern: {
+                            description: "How to build a list→detail app with scoped related data",
+                            steps: [
+                                "1. Create a smart query with {{variables}} for the detail page's related data (e.g., filter by {{requestId}})",
+                                "2. Create a list page with a data-table block and a navigate-to-page action: set config.useQueryParams:true, paramConfig: { source:'row', mode:'selected', selectedFields:['id'] }",
+                                "3. Create a detail page with: (a) a record-card block with mode:'single' and variables: { id: { source:'url', param:'id' } }, (b) a related-list block with dataSource type:'query', ref:smartQueryId, variables: { requestId: { source:'url', param:'id' } }",
+                                "4. Publish both pages. Clicking a row on the list navigates to /ws/detail-slug?id=rowId, and the detail page scopes all blocks to that ID.",
+                            ],
+                        },
                     }, null, 2),
                 },
             ],
@@ -1008,9 +1020,10 @@ function registerDescribeTools(server) {
                             filterableColumns: "string[] | null — which columns users can filter on (for data-table blocks)",
                         },
                         data_source_shape: {
-                            type: "'structure' — the data source type",
-                            ref: "string — the collection ID (UUID)",
-                            recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended.",
+                            type: "'structure' | 'query' — 'structure' fetches collection records directly, 'query' executes a smart query with {{variable}} substitution",
+                            ref: "string — the collection ID (for structure) or smart query ID (for query) — UUID",
+                            mode: "'list' | 'single' | 'aggregate' — optional. 'single' fetches one record (detail pages), 'list' fetches paginated records, 'aggregate' computes metrics",
+                            recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended for structure type.",
                             config: {
                                 description: "Optional query configuration",
                                 filter: "object | null — same filter syntax as query_records",
@@ -1018,12 +1031,29 @@ function registerDescribeTools(server) {
                                 page: "number | null — for pagination",
                                 pageSize: "number | null — records per page",
                             },
+                            variables: {
+                                description: "Optional variable bindings map. Each key is a variable name, each value declares the runtime source.",
+                                example: "{ requestId: { source: 'url', param: 'id' }, status: { source: 'static', value: 'active' } }",
+                                sources: {
+                                    url: "{ source: 'url', param: 'paramName' } — reads from URL query params (e.g., ?id=abc)",
+                                    auth: "{ source: 'auth', field: 'userId' | 'email' | 'name' } — from the logged-in user",
+                                    record: "{ source: 'record', field: 'fieldName' } — from the page's primary record (detail pages only)",
+                                    static: "{ source: 'static', value: 'literalValue' } — a hardcoded default",
+                                },
+                                behavior: {
+                                    query_type: "For type:'query' — resolved variables substitute into smart query {{placeholders}} before execution",
+                                    structure_type: "For type:'structure' — resolved variables become equality filters on the collection. IMPORTANT: the variable name 'id' is special — it matches the system record UUID (used for single-record fetch by ID). ALL OTHER variable names filter against user data fields and are automatically prefixed with 'data.' (e.g., variable 'requestId' filters on data.requestId in the JSONB column). System columns like createdAt, updatedAt, status do NOT get the data. prefix.",
+                                    unresolved: "If any variable cannot be resolved, the block returns an empty result with a variableError message — NEVER unfiltered data",
+                                    detail_page_pattern: "For a detail page: use variables: { id: { source: 'url', param: 'id' } } on the primary record-card block to fetch by system ID. For related-list blocks, use the actual data field name (e.g., variables: { requestId: { source: 'url', param: 'id' } }) — this filters related records where data.requestId matches the URL param. The 'id' variable fetches a record BY its UUID; other variable names filter records WHERE a field equals the value.",
+                                    reference_fields: "Reference fields (foreign keys between collections) store the target record's system UUID. To filter a related list by a reference field, bind the variable to the parent record's system ID (from URL param), not a custom field value. Example: approval_steps has a data.requestId field that stores the governance_request's UUID.",
+                                },
+                                precedence: "url > record > auth > static (highest to lowest priority)",
+                            },
                             aggregation: {
                                 description: "For metric/chart blocks. Defines computations over the data.",
                                 operations: "Record<string, { count?: '*', sum?: 'fieldName', avg?: 'fieldName', min?: 'fieldName', max?: 'fieldName' }>",
                                 groupBy: "string[] | null — fields to group by",
                             },
-                            mode: "'list' | 'single' | 'aggregate' — optional. Set to 'aggregate' for metric-card and chart blocks that use aggregation. For list and detail pages, mode is inferred from context.",
                         },
                         narrative_shape: {
                             primaryQuestion: "string — the business question this block answers (e.g., 'How are sales trending?')",
@@ -1312,11 +1342,65 @@ function registerDescribeTools(server) {
                                 requires: "content property (string) — the HTML markup",
                                 category: "content-block",
                             },
+                            "data-html": {
+                                description: "Data-bound HTML block. Write HTML templates with {{fieldName}} placeholders that resolve against a data source. Supports two modes: LIST mode (default) renders the template ONCE PER RECORD — perfect for card grids, custom list layouts, or any repeating template. SINGLE mode renders the template once for a single record (detail pages). Records are auto-flattened so {{firstName}} works directly — no need for {{data.firstName}}. Output is sanitized via DOMPurify. No JavaScript allowed.",
+                                dataSource: "Required — type: 'structure' or 'query'. Data is resolved server-side and injected into the template.",
+                                requires: "content property (string) — HTML template with {{field}} placeholders. Must have non-empty content to pass publishing validation.",
+                                template_syntax: "{{fieldName}} for top-level fields, {{data.status}} for nested. Unresolved placeholders render as empty string.",
+                                modes: {
+                                    list: "Default. Template repeats for EACH record. Write a single card/row template and it renders N times for N records. Example: a styled customer card template produces a grid of cards.",
+                                    single: "Template renders once for ONE record. Use with mode:'single' and a variable binding like { id: { source: 'url', param: 'id' } } to fetch a specific record.",
+                                },
+                                example_list_mode: {
+                                    blockType: "data-html",
+                                    dataSource: { type: "structure", ref: "<collection-uuid>", recordSlug: "customers", config: { sort: [{ field: "createdAt", direction: "desc" }], limit: 20 } },
+                                    content: "<div style='display:inline-block; width:280px; margin:8px; padding:16px; border:1px solid #e5e7eb; border-radius:8px; vertical-align:top;'><h3>{{firstName}} {{lastName}}</h3><p style='color:#6b7280;'>{{email}}</p></div>",
+                                },
+                                example_single_mode: {
+                                    blockType: "data-html",
+                                    dataSource: { type: "structure", ref: "<collection-uuid>", mode: "single", config: {}, variables: { id: { source: "url", param: "id" } } },
+                                    content: "<div style='padding:16px; border:1px solid #e5e7eb; border-radius:8px;'><h2>{{firstName}} {{lastName}}</h2><p>{{email}}</p><p>Company: {{company}}</p></div>",
+                                },
+                                IMPORTANT: "No iteration syntax needed for lists. Just write a single template — the runtime repeats it automatically for each record. Records are auto-flattened: use {{fieldName}} directly, not {{data.fieldName}}.",
+                                category: "data-block",
+                            },
+                            "image": {
+                                description: "Image block. Displays an image from a URL with responsive sizing, lazy loading, optional caption, alignment, and link-on-click.",
+                                dataSource: "Not required",
+                                requires: "src property (string) — the image URL. Optional: alt, caption, alignment (left|center|right), maxWidth, linkUrl.",
+                                category: "media-block",
+                            },
+                            "video": {
+                                description: "Video block. Embeds YouTube/Vimeo videos via iframe or direct MP4/WebM via native <video>. Auto-detects provider from URL.",
+                                dataSource: "Not required",
+                                requires: "src property (string) — video URL (YouTube, Vimeo, or direct). Optional: autoplay (boolean, muted only), loop, controls (default true), poster, caption.",
+                                category: "media-block",
+                            },
+                            "modal": {
+                                description: "Declarative modal block. Invisible by default — renders as an overlay when triggered by an 'open-modal' action. Content can be static HTML, markdown, or data-bound HTML. Supports actions (buttons) inside the modal for confirm/cancel flows. Uses Radix Dialog.",
+                                dataSource: "Optional — only needed if contentType is 'data-html'",
+                                requires: "content property (string), contentType ('html' | 'markdown' | 'data-html', default 'html'). Optional: title, modalSize ('sm' | 'md' | 'lg' | 'fullscreen', default 'md').",
+                                actions: "Optional actions array — renders as buttons at the bottom of the modal. Supports close-modal (close the modal), invoke-trigger, navigate-to-page, start-orchestration, open-modal (open another modal). Use close-modal with targetRef set to this modal's own ID for a 'Cancel' button.",
+                                trigger: "Add an 'open-modal' action on another block with targetRef set to this modal block's ID. The modal opens when the action fires.",
+                                category: "interactive-block",
+                                example_confirm_modal: {
+                                    blockType: "modal",
+                                    title: "Confirm Delete",
+                                    modalSize: "sm",
+                                    contentType: "html",
+                                    content: "<p>Are you sure you want to delete this item? This action cannot be undone.</p>",
+                                    actions: [
+                                        { id: "cancel", type: "close-modal", label: "Cancel", targetRef: "THIS_MODAL_ID", presentation: { color: "neutral" } },
+                                        { id: "confirm", type: "invoke-trigger", label: "Delete", targetRef: "TRIGGER_ID", presentation: { color: "destructive" } },
+                                    ],
+                                },
+                            },
                         },
                         block_categories: {
-                            "data-block": "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator)",
+                            "data-block": "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator, data-html)",
                             "form-block": "Use 'field-group' blockType with a 'fields' array for form pages. Do NOT use individual field block types (text-input, select, etc.) — the runtime renders field types from the field-group's fields array.",
                             "content-block": "Static content blocks (markdown, static-html). Must have non-empty 'content' property.",
+                            "media-block": "Media blocks (image, video). Require a 'src' URL property.",
                             "layout-block": "Blocks that control page-level behavior (filter-bar)",
                         },
                         action_mappings: {
@@ -1403,16 +1487,18 @@ function registerDescribeTools(server) {
                                 targetRef: "Page slug to navigate to",
                                 typical_activation: "row-click",
                                 paramConfig: "Use source: 'row', mode: 'selected', selectedFields: ['id'] to pass the record ID to the detail page",
+                                paramMapping: "Optional config.paramMapping: { sourceField: 'targetParam' } to rename fields in the URL. E.g., { requestId: 'id' } passes ?id=<value> instead of ?requestId=<value>. Only applies when useQueryParams is true.",
                                 example: {
                                     id: "view-detail",
                                     type: "navigate-to-page",
                                     label: "View Details",
                                     targetRef: "customer-detail",
                                     activation: "row-click",
+                                    config: { useQueryParams: true, paramMapping: { requestId: "id" } },
                                     paramConfig: {
                                         source: "row",
                                         mode: "selected",
-                                        selectedFields: ["id"],
+                                        selectedFields: ["requestId"],
                                     },
                                 },
                             },
@@ -1449,6 +1535,16 @@ function registerDescribeTools(server) {
                                 typical_activation: "button",
                                 executionMode: "'fire-and-forget'",
                             },
+                            "open-modal": {
+                                description: "Open a modal block. Client-side only — no backend call. The modal block must be defined on the same page with blockType 'modal'.",
+                                targetRef: "The modal block's ID (UUID) — must match a block with blockType 'modal' on this page.",
+                                typical_activation: "button",
+                            },
+                            "close-modal": {
+                                description: "Close an open modal. Client-side only.",
+                                targetRef: "The modal block's ID (UUID) to close.",
+                                typical_activation: "button",
+                            },
                         },
                         tips: [
                             "Every action needs an 'id' — use UUIDs for uniqueness",

package/dist/tools/pages.js

@@ -61,20 +61,37 @@ function createPagesClient(sdk, centraliUrl, workspaceId) {
     const client = axios_1.default.create({ baseURL });
     // Attach the SDK's bearer token to every request
     client.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e;
+        var _a, _b, _c;
         const token = (_c = (_b = (_a = sdk).getToken) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : sdk.token;
-        if (!token) {
-            // Force the SDK to fetch a token by calling getTokenOrFetch
-            const freshToken = yield ((_e = (_d = sdk).getTokenOrFetch) === null || _e === void 0 ? void 0 : _e.call(_d));
-            if (freshToken) {
-                config.headers.Authorization = `Bearer ${freshToken}`;
-            }
-        }
-        else {
+        if (token) {
             config.headers.Authorization = `Bearer ${token}`;
         }
         return config;
     }));
+    // Retry on 401/403 after refreshing the token via the SDK
+    client.interceptors.response.use((response) => response, (error) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        const originalRequest = error.config;
+        const isAuthError = ((_a = error.response) === null || _a === void 0 ? void 0 : _a.status) === 401 || ((_b = error.response) === null || _b === void 0 ? void 0 : _b.status) === 403;
+        if (isAuthError && !originalRequest._hasRetried) {
+            originalRequest._hasRetried = true;
+            // Force SDK to fetch a fresh token
+            const freshToken = yield ((_d = (_c = sdk).getTokenOrFetch) === null || _d === void 0 ? void 0 : _d.call(_c));
+            if (!freshToken) {
+                // SDK can't get a token either — trigger a re-auth by making any SDK call
+                try {
+                    yield ((_f = (_e = sdk.axios) === null || _e === void 0 ? void 0 : _e.get) === null || _f === void 0 ? void 0 : _f.call(_e, '/health'));
+                }
+                catch ( /* ignore — we just want the token refresh side effect */_k) { /* ignore — we just want the token refresh side effect */ }
+            }
+            const token = (_j = (_h = (_g = sdk).getToken) === null || _h === void 0 ? void 0 : _h.call(_g)) !== null && _j !== void 0 ? _j : sdk.token;
+            if (token) {
+                originalRequest.headers.Authorization = `Bearer ${token}`;
+                return client.request(originalRequest);
+            }
+        }
+        return Promise.reject(error);
+    }));
     return { client, workspaceId };
 }
 function registerPageTools(server, sdk, centraliUrl, workspaceId) {
@@ -125,7 +142,9 @@ function registerPageTools(server, sdk, centraliUrl, workspaceId) {
             };
         }
     }));
-    server.tool("create_page", "Create a new page in the workspace. A page is a UI view backed by data from structures. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.", {
+    server.tool("create_page", `Create a new page in the workspace. A page is a UI view backed by data from structures. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.
+
+Navigate-to-page actions can use config.useQueryParams: true to pass selected row fields as URL query params to the target page. Pair with paramConfig: { source: 'row', mode: 'selected', selectedFields: ['id'] } to control which fields are passed. Use config.paramMapping: { sourceField: 'targetParam' } to rename fields in the URL (e.g., { requestId: 'id' } passes ?id=<value> instead of ?requestId=<value>). The target detail page can then use variable bindings with { source: 'url', param: 'id' } to read those params.`, {
         name: zod_1.z.string().describe("Display name for the page (e.g., 'Customer List')"),
         slug: zod_1.z.string().describe("URL-safe slug (e.g., 'customer-list')"),
         pageType: zod_1.z
@@ -192,7 +211,26 @@ function registerPageTools(server, sdk, centraliUrl, workspaceId) {
         }
     }));
     // ── Drafts & Versions ─────────────────────────────────────────────
-    server.tool("save_page_draft", "Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.", {
+    server.tool("save_page_draft", `Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.
+
+Each block's dataSource can include an optional 'variables' map for runtime variable binding:
+variables: { [varName]: { source, param?, field?, value? } }
+
+Variable binding sources:
+- { source: 'url', param: 'id' } — read from URL query param
+- { source: 'auth', field: 'userId' | 'email' | 'name' } — from authenticated user
+- { source: 'record', field: 'fieldName' } — from page's primary record (detail pages)
+- { source: 'static', value: 'active' } — literal default value
+
+For query data sources: variables substitute into smart query {{placeholders}}.
+For structure data sources: variables become equality filters. IMPORTANT: variable name 'id' is special — it fetches the record BY its system UUID. All other variable names filter against data.<fieldName> in the JSONB column (e.g., variable 'requestId' → filters on data.requestId). Reference fields between collections store system UUIDs.
+
+Common patterns:
+- Detail page primary record: { id: { source: 'url', param: 'id' } } — fetches single record by system ID
+- Detail page related list: { requestId: { source: 'url', param: 'id' } } — filters where data.requestId = URL param
+- User-scoped view: { assigneeId: { source: 'auth', field: 'userId' } }
+- Navigate with params: action config { useQueryParams: true } + paramConfig { source: 'row', mode: 'selected', selectedFields: ['id'] }
+- Rename params: action config { useQueryParams: true, paramMapping: { requestId: 'id' } } — passes ?id=<value> instead of ?requestId=<value>`, {
         pageId: zod_1.z.string().describe("The page ID (UUID)"),
         definition: zod_1.z
             .record(zod_1.z.string(), zod_1.z.any())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.2.15",
+  "version": "4.3.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

package/src/tools/describe.ts

@@ -1088,7 +1088,19 @@ export function registerDescribeTools(server: McpServer) {
                 "Use generate_starter_pages to auto-generate page proposals from your collections",
                 "Always validate_page before publish_page — publishing will reject if there are errors",
                 "Set access policy with set_page_access_policy before publishing if you need auth",
+                "Use variable bindings on data sources to scope data dynamically — bind to URL params, auth context, record context, or static defaults",
+                "For list→detail navigation: set useQueryParams:true on navigate-to-page actions, then bind the detail page's data source variables to { source: 'url', param: 'id' }. Use config.paramMapping to rename fields if source and target use different names (e.g., { requestId: 'id' })",
+                "For user-scoped views (e.g., My Approvals): bind a variable to { source: 'auth', field: 'userId' } and use a smart query with {{assigneeId}}",
               ],
+              multi_page_pattern: {
+                description: "How to build a list→detail app with scoped related data",
+                steps: [
+                  "1. Create a smart query with {{variables}} for the detail page's related data (e.g., filter by {{requestId}})",
+                  "2. Create a list page with a data-table block and a navigate-to-page action: set config.useQueryParams:true, paramConfig: { source:'row', mode:'selected', selectedFields:['id'] }",
+                  "3. Create a detail page with: (a) a record-card block with mode:'single' and variables: { id: { source:'url', param:'id' } }, (b) a related-list block with dataSource type:'query', ref:smartQueryId, variables: { requestId: { source:'url', param:'id' } }",
+                  "4. Publish both pages. Clicking a row on the list navigates to /ws/detail-slug?id=rowId, and the detail page scopes all blocks to that ID.",
+                ],
+              },
             },
             null,
             2
@@ -1180,9 +1192,10 @@ export function registerDescribeTools(server: McpServer) {
                   "string[] | null — which columns users can filter on (for data-table blocks)",
               },
               data_source_shape: {
-                type: "'structure' — the data source type",
-                ref: "string — the collection ID (UUID)",
-                recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended.",
+                type: "'structure' | 'query' — 'structure' fetches collection records directly, 'query' executes a smart query with {{variable}} substitution",
+                ref: "string — the collection ID (for structure) or smart query ID (for query) — UUID",
+                mode: "'list' | 'single' | 'aggregate' — optional. 'single' fetches one record (detail pages), 'list' fetches paginated records, 'aggregate' computes metrics",
+                recordSlug: "string | undefined — the collection's record slug for direct resolution (avoids an extra lookup). Recommended for structure type.",
                 config: {
                   description: "Optional query configuration",
                   filter: "object | null — same filter syntax as query_records",
@@ -1190,6 +1203,24 @@ export function registerDescribeTools(server: McpServer) {
                   page: "number | null — for pagination",
                   pageSize: "number | null — records per page",
                 },
+                variables: {
+                  description: "Optional variable bindings map. Each key is a variable name, each value declares the runtime source.",
+                  example: "{ requestId: { source: 'url', param: 'id' }, status: { source: 'static', value: 'active' } }",
+                  sources: {
+                    url: "{ source: 'url', param: 'paramName' } — reads from URL query params (e.g., ?id=abc)",
+                    auth: "{ source: 'auth', field: 'userId' | 'email' | 'name' } — from the logged-in user",
+                    record: "{ source: 'record', field: 'fieldName' } — from the page's primary record (detail pages only)",
+                    static: "{ source: 'static', value: 'literalValue' } — a hardcoded default",
+                  },
+                  behavior: {
+                    query_type: "For type:'query' — resolved variables substitute into smart query {{placeholders}} before execution",
+                    structure_type: "For type:'structure' — resolved variables become equality filters on the collection. IMPORTANT: the variable name 'id' is special — it matches the system record UUID (used for single-record fetch by ID). ALL OTHER variable names filter against user data fields and are automatically prefixed with 'data.' (e.g., variable 'requestId' filters on data.requestId in the JSONB column). System columns like createdAt, updatedAt, status do NOT get the data. prefix.",
+                    unresolved: "If any variable cannot be resolved, the block returns an empty result with a variableError message — NEVER unfiltered data",
+                    detail_page_pattern: "For a detail page: use variables: { id: { source: 'url', param: 'id' } } on the primary record-card block to fetch by system ID. For related-list blocks, use the actual data field name (e.g., variables: { requestId: { source: 'url', param: 'id' } }) — this filters related records where data.requestId matches the URL param. The 'id' variable fetches a record BY its UUID; other variable names filter records WHERE a field equals the value.",
+                    reference_fields: "Reference fields (foreign keys between collections) store the target record's system UUID. To filter a related list by a reference field, bind the variable to the parent record's system ID (from URL param), not a custom field value. Example: approval_steps has a data.requestId field that stores the governance_request's UUID.",
+                  },
+                  precedence: "url > record > auth > static (highest to lowest priority)",
+                },
                 aggregation: {
                   description:
                     "For metric/chart blocks. Defines computations over the data.",
@@ -1197,7 +1228,6 @@ export function registerDescribeTools(server: McpServer) {
                     "Record<string, { count?: '*', sum?: 'fieldName', avg?: 'fieldName', min?: 'fieldName', max?: 'fieldName' }>",
                   groupBy: "string[] | null — fields to group by",
                 },
-                mode: "'list' | 'single' | 'aggregate' — optional. Set to 'aggregate' for metric-card and chart blocks that use aggregation. For list and detail pages, mode is inferred from context.",
               },
               narrative_shape: {
                 primaryQuestion:
@@ -1518,14 +1548,73 @@ export function registerDescribeTools(server: McpServer) {
                   requires: "content property (string) — the HTML markup",
                   category: "content-block",
                 },
+                "data-html": {
+                  description:
+                    "Data-bound HTML block. Write HTML templates with {{fieldName}} placeholders that resolve against a data source. Supports two modes: LIST mode (default) renders the template ONCE PER RECORD — perfect for card grids, custom list layouts, or any repeating template. SINGLE mode renders the template once for a single record (detail pages). Records are auto-flattened so {{firstName}} works directly — no need for {{data.firstName}}. Output is sanitized via DOMPurify. No JavaScript allowed.",
+                  dataSource: "Required — type: 'structure' or 'query'. Data is resolved server-side and injected into the template.",
+                  requires: "content property (string) — HTML template with {{field}} placeholders. Must have non-empty content to pass publishing validation.",
+                  template_syntax: "{{fieldName}} for top-level fields, {{data.status}} for nested. Unresolved placeholders render as empty string.",
+                  modes: {
+                    list: "Default. Template repeats for EACH record. Write a single card/row template and it renders N times for N records. Example: a styled customer card template produces a grid of cards.",
+                    single: "Template renders once for ONE record. Use with mode:'single' and a variable binding like { id: { source: 'url', param: 'id' } } to fetch a specific record.",
+                  },
+                  example_list_mode: {
+                    blockType: "data-html",
+                    dataSource: { type: "structure", ref: "<collection-uuid>", recordSlug: "customers", config: { sort: [{ field: "createdAt", direction: "desc" }], limit: 20 } },
+                    content: "<div style='display:inline-block; width:280px; margin:8px; padding:16px; border:1px solid #e5e7eb; border-radius:8px; vertical-align:top;'><h3>{{firstName}} {{lastName}}</h3><p style='color:#6b7280;'>{{email}}</p></div>",
+                  },
+                  example_single_mode: {
+                    blockType: "data-html",
+                    dataSource: { type: "structure", ref: "<collection-uuid>", mode: "single", config: {}, variables: { id: { source: "url", param: "id" } } },
+                    content: "<div style='padding:16px; border:1px solid #e5e7eb; border-radius:8px;'><h2>{{firstName}} {{lastName}}</h2><p>{{email}}</p><p>Company: {{company}}</p></div>",
+                  },
+                  IMPORTANT: "No iteration syntax needed for lists. Just write a single template — the runtime repeats it automatically for each record. Records are auto-flattened: use {{fieldName}} directly, not {{data.fieldName}}.",
+                  category: "data-block",
+                },
+                "image": {
+                  description:
+                    "Image block. Displays an image from a URL with responsive sizing, lazy loading, optional caption, alignment, and link-on-click.",
+                  dataSource: "Not required",
+                  requires: "src property (string) — the image URL. Optional: alt, caption, alignment (left|center|right), maxWidth, linkUrl.",
+                  category: "media-block",
+                },
+                "video": {
+                  description:
+                    "Video block. Embeds YouTube/Vimeo videos via iframe or direct MP4/WebM via native <video>. Auto-detects provider from URL.",
+                  dataSource: "Not required",
+                  requires: "src property (string) — video URL (YouTube, Vimeo, or direct). Optional: autoplay (boolean, muted only), loop, controls (default true), poster, caption.",
+                  category: "media-block",
+                },
+                "modal": {
+                  description:
+                    "Declarative modal block. Invisible by default — renders as an overlay when triggered by an 'open-modal' action. Content can be static HTML, markdown, or data-bound HTML. Supports actions (buttons) inside the modal for confirm/cancel flows. Uses Radix Dialog.",
+                  dataSource: "Optional — only needed if contentType is 'data-html'",
+                  requires: "content property (string), contentType ('html' | 'markdown' | 'data-html', default 'html'). Optional: title, modalSize ('sm' | 'md' | 'lg' | 'fullscreen', default 'md').",
+                  actions: "Optional actions array — renders as buttons at the bottom of the modal. Supports close-modal (close the modal), invoke-trigger, navigate-to-page, start-orchestration, open-modal (open another modal). Use close-modal with targetRef set to this modal's own ID for a 'Cancel' button.",
+                  trigger: "Add an 'open-modal' action on another block with targetRef set to this modal block's ID. The modal opens when the action fires.",
+                  category: "interactive-block",
+                  example_confirm_modal: {
+                    blockType: "modal",
+                    title: "Confirm Delete",
+                    modalSize: "sm",
+                    contentType: "html",
+                    content: "<p>Are you sure you want to delete this item? This action cannot be undone.</p>",
+                    actions: [
+                      { id: "cancel", type: "close-modal", label: "Cancel", targetRef: "THIS_MODAL_ID", presentation: { color: "neutral" } },
+                      { id: "confirm", type: "invoke-trigger", label: "Delete", targetRef: "TRIGGER_ID", presentation: { color: "destructive" } },
+                    ],
+                  },
+                },
               },
               block_categories: {
                 "data-block":
-                  "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator)",
+                  "Blocks that display data from collections (data-table, chart, metric-card, stat-group, field-display, related-list, activity-feed, kanban, calendar, progress-indicator, data-html)",
                 "form-block":
                   "Use 'field-group' blockType with a 'fields' array for form pages. Do NOT use individual field block types (text-input, select, etc.) — the runtime renders field types from the field-group's fields array.",
                 "content-block":
                   "Static content blocks (markdown, static-html). Must have non-empty 'content' property.",
+                "media-block":
+                  "Media blocks (image, video). Require a 'src' URL property.",
                 "layout-block":
                   "Blocks that control page-level behavior (filter-bar)",
               },
@@ -1635,16 +1724,19 @@ export function registerDescribeTools(server: McpServer) {
                   typical_activation: "row-click",
                   paramConfig:
                     "Use source: 'row', mode: 'selected', selectedFields: ['id'] to pass the record ID to the detail page",
+                  paramMapping:
+                    "Optional config.paramMapping: { sourceField: 'targetParam' } to rename fields in the URL. E.g., { requestId: 'id' } passes ?id=<value> instead of ?requestId=<value>. Only applies when useQueryParams is true.",
                   example: {
                     id: "view-detail",
                     type: "navigate-to-page",
                     label: "View Details",
                     targetRef: "customer-detail",
                     activation: "row-click",
+                    config: { useQueryParams: true, paramMapping: { requestId: "id" } },
                     paramConfig: {
                       source: "row",
                       mode: "selected",
-                      selectedFields: ["id"],
+                      selectedFields: ["requestId"],
                     },
                   },
                 },
@@ -1691,6 +1783,18 @@ export function registerDescribeTools(server: McpServer) {
                   typical_activation: "button",
                   executionMode: "'fire-and-forget'",
                 },
+                "open-modal": {
+                  description:
+                    "Open a modal block. Client-side only — no backend call. The modal block must be defined on the same page with blockType 'modal'.",
+                  targetRef: "The modal block's ID (UUID) — must match a block with blockType 'modal' on this page.",
+                  typical_activation: "button",
+                },
+                "close-modal": {
+                  description:
+                    "Close an open modal. Client-side only.",
+                  targetRef: "The modal block's ID (UUID) to close.",
+                  typical_activation: "button",
+                },
               },
               tips: [
                 "Every action needs an 'id' — use UUIDs for uniqueness",

package/src/tools/pages.ts

@@ -54,18 +54,42 @@ function createPagesClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: s
   // Attach the SDK's bearer token to every request
   client.interceptors.request.use(async (config) => {
     const token = (sdk as any).getToken?.() ?? (sdk as any).token;
-    if (!token) {
-      // Force the SDK to fetch a token by calling getTokenOrFetch
-      const freshToken = await (sdk as any).getTokenOrFetch?.();
-      if (freshToken) {
-        config.headers.Authorization = `Bearer ${freshToken}`;
-      }
-    } else {
+    if (token) {
       config.headers.Authorization = `Bearer ${token}`;
     }
     return config;
   });
 
+  // Retry on 401/403 after refreshing the token via the SDK
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      const originalRequest = error.config;
+      const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+
+      if (isAuthError && !originalRequest._hasRetried) {
+        originalRequest._hasRetried = true;
+
+        // Force SDK to fetch a fresh token
+        const freshToken = await (sdk as any).getTokenOrFetch?.();
+        if (!freshToken) {
+          // SDK can't get a token either — trigger a re-auth by making any SDK call
+          try {
+            await (sdk as any).axios?.get?.('/health');
+          } catch { /* ignore — we just want the token refresh side effect */ }
+        }
+
+        const token = (sdk as any).getToken?.() ?? (sdk as any).token;
+        if (token) {
+          originalRequest.headers.Authorization = `Bearer ${token}`;
+          return client.request(originalRequest);
+        }
+      }
+
+      return Promise.reject(error);
+    }
+  );
+
   return { client, workspaceId };
 }
 
@@ -134,7 +158,9 @@ export function registerPageTools(
 
   server.tool(
     "create_page",
-    "Create a new page in the workspace. A page is a UI view backed by data from structures. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.",
+    `Create a new page in the workspace. A page is a UI view backed by data from structures. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.
+
+Navigate-to-page actions can use config.useQueryParams: true to pass selected row fields as URL query params to the target page. Pair with paramConfig: { source: 'row', mode: 'selected', selectedFields: ['id'] } to control which fields are passed. Use config.paramMapping: { sourceField: 'targetParam' } to rename fields in the URL (e.g., { requestId: 'id' } passes ?id=<value> instead of ?requestId=<value>). The target detail page can then use variable bindings with { source: 'url', param: 'id' } to read those params.`,
     {
       name: z.string().describe("Display name for the page (e.g., 'Customer List')"),
       slug: z.string().describe("URL-safe slug (e.g., 'customer-list')"),
@@ -214,7 +240,26 @@ export function registerPageTools(
 
   server.tool(
     "save_page_draft",
-    "Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.",
+    `Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.
+
+Each block's dataSource can include an optional 'variables' map for runtime variable binding:
+variables: { [varName]: { source, param?, field?, value? } }
+
+Variable binding sources:
+- { source: 'url', param: 'id' } — read from URL query param
+- { source: 'auth', field: 'userId' | 'email' | 'name' } — from authenticated user
+- { source: 'record', field: 'fieldName' } — from page's primary record (detail pages)
+- { source: 'static', value: 'active' } — literal default value
+
+For query data sources: variables substitute into smart query {{placeholders}}.
+For structure data sources: variables become equality filters. IMPORTANT: variable name 'id' is special — it fetches the record BY its system UUID. All other variable names filter against data.<fieldName> in the JSONB column (e.g., variable 'requestId' → filters on data.requestId). Reference fields between collections store system UUIDs.
+
+Common patterns:
+- Detail page primary record: { id: { source: 'url', param: 'id' } } — fetches single record by system ID
+- Detail page related list: { requestId: { source: 'url', param: 'id' } } — filters where data.requestId = URL param
+- User-scoped view: { assigneeId: { source: 'auth', field: 'userId' } }
+- Navigate with params: action config { useQueryParams: true } + paramConfig { source: 'row', mode: 'selected', selectedFields: ['id'] }
+- Rename params: action config { useQueryParams: true, paramMapping: { requestId: 'id' } } — passes ?id=<value> instead of ?requestId=<value>`,
     {
       pageId: z.string().describe("The page ID (UUID)"),
       definition: z