@centrali-io/centrali-mcp 4.2.14 → 4.2.16

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' }",
+                            "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,27 @@ 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",
+                                    unresolved: "If any variable cannot be resolved, the block returns an empty result with a variableError message — NEVER unfiltered data",
+                                },
+                                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?')",
@@ -1212,7 +1240,7 @@ function registerDescribeTools(server) {
                                     type: "'text' | 'number' | 'email' | 'date' | 'boolean' | 'select' | 'textarea' | 'hidden'",
                                     required: "boolean (default: false) — ignored for hidden fields",
                                     placeholder: "string | null",
-                                    defaultValue: "string | number | boolean | { source: 'auth' | 'system', field: string } — static value or derived default. For hidden fields, this is the value injected at submit time. For visible fields, this pre-populates the input. Derived sources: auth.userId, auth.email, auth.name (from logged-in user), system.now (server timestamp). Derived defaults are resolved server-side.",
+                                    defaultValue: "string | number | boolean | { source: 'auth' | 'system', field: string } — static value or derived default. For hidden fields, this is the value injected at submit time. For visible fields, this pre-populates the input. Derived sources: auth.userId, auth.email, auth.name (from logged-in user's JWT), system.now (server timestamp), system.uuid (random UUID). Derived defaults are resolved server-side.",
                                     resolveErrorMessage: "string | null — custom error message shown when a derived defaultValue cannot be resolved (e.g. user not signed in). Defaults to 'This form requires you to be signed in' for auth source.",
                                     options: "For 'select' type: { label: string, value: string }[] — inline static options",
                                     optionSource: "For 'select' type (alternative): { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-uuid', labelField?, valueField? }",

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. 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,24 @@ 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.
+
+Common patterns:
+- Detail page related list: { requestId: { source: 'url', param: 'id' } }
+- User-scoped view: { assigneeId: { source: 'auth', field: 'userId' } }
+- Navigate with params: action config { useQueryParams: true } + paramConfig { source: 'row', mode: 'selected', selectedFields: ['id'] }`, {
         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.14",
+  "version": "4.2.16",
   "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' }",
+                "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,22 @@ 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",
+                    unresolved: "If any variable cannot be resolved, the block returns an empty result with a variableError message — NEVER unfiltered data",
+                  },
+                  precedence: "url > record > auth > static (highest to lowest priority)",
+                },
                 aggregation: {
                   description:
                     "For metric/chart blocks. Defines computations over the data.",
@@ -1197,7 +1226,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:
@@ -1409,7 +1437,7 @@ export function registerDescribeTools(server: McpServer) {
                     type: "'text' | 'number' | 'email' | 'date' | 'boolean' | 'select' | 'textarea' | 'hidden'",
                     required: "boolean (default: false) — ignored for hidden fields",
                     placeholder: "string | null",
-                    defaultValue: "string | number | boolean | { source: 'auth' | 'system', field: string } — static value or derived default. For hidden fields, this is the value injected at submit time. For visible fields, this pre-populates the input. Derived sources: auth.userId, auth.email, auth.name (from logged-in user), system.now (server timestamp). Derived defaults are resolved server-side.",
+                    defaultValue: "string | number | boolean | { source: 'auth' | 'system', field: string } — static value or derived default. For hidden fields, this is the value injected at submit time. For visible fields, this pre-populates the input. Derived sources: auth.userId, auth.email, auth.name (from logged-in user's JWT), system.now (server timestamp), system.uuid (random UUID). Derived defaults are resolved server-side.",
                     resolveErrorMessage: "string | null — custom error message shown when a derived defaultValue cannot be resolved (e.g. user not signed in). Defaults to 'This form requires you to be signed in' for auth source.",
                     options: "For 'select' type: { label: string, value: string }[] — inline static options",
                     optionSource: "For 'select' type (alternative): { type: 'static' | 'dynamic', staticOptions?: [{label, value}], dynamicRef?: 'collection-uuid', labelField?, valueField? }",

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. 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,24 @@ 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.
+
+Common patterns:
+- Detail page related list: { requestId: { source: 'url', param: 'id' } }
+- User-scoped view: { assigneeId: { source: 'auth', field: 'userId' } }
+- Navigate with params: action config { useQueryParams: true } + paramConfig { source: 'row', mode: 'selected', selectedFields: ['id'] }`,
     {
       pageId: z.string().describe("The page ID (UUID)"),
       definition: z