@centrali-io/centrali-mcp 6.0.0 → 6.1.0

package/dist/tools/compute.js

@@ -379,7 +379,7 @@ function registerComputeTools(server, sdk, centraliUrl, workspaceId) {
         triggerMetadata: zod_1.z
             .record(zod_1.z.string(), zod_1.z.any())
             .optional()
-            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }. All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
+            .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: { path } where path is a URL-safe slug (e.g. 'stripe-webhook'); the trigger is reachable at `<api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>`. Optional native HMAC signature verification (no crypto in the function body): the **recommended path** is { validateSignature: true, provider: 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', signingSecret } — the `provider` shortcut wires every wire-format detail (header names, signed-value format, digest encoding, secret encoding) from a built-in preset. Covers Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify out of the box. **Advanced**: any preset field can be overridden, or the preset can be skipped entirely by supplying the raw knobs directly — { validateSignature: true, signingSecret, signatureHeaderName, signatureIdHeaderName?, timestampHeaderName?, timestampExtractionPattern?, extractionPattern?, hmacAlgorithm?, hmacEncoding?, secretEncoding?, encoding?, payloadFormat? }. Defaults when no provider: hmacAlgorithm 'sha256', hmacEncoding 'base64', extractionPattern '^(?:v1,)?(.+)$', secretEncoding 'raw'; built-in 5-minute replay tolerance. Two-step setup recommended: (1) create the trigger with just { path } and optionally { provider } — the public URL is `<api-host>/data/workspace/<ws>/api/v1/http-trigger/<path>`; (2) register that URL with the webhook provider; (3) when the provider issues the signing secret, call update_trigger with validateSignature: true + signingSecret. Providers will not give a signing secret until they have the URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' | 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', secret? } — provider-named modes are HMAC verification with the matching preset (auth.secret is the colocated signing secret; legacy `mode: 'hmac'` keeps its single-header body-only behaviour for back-compat). All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
         enabled: zod_1.z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, functionId, executionType, description, triggerMetadata, enabled }) {
         try {

package/dist/tools/describe.js

@@ -845,6 +845,33 @@ function registerDescribeTools(server) {
                                 triggerMetadata_examples: {
                                     "event-driven": { eventType: "record_created", recordSlug: "orders" },
                                     scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                                    "http-trigger_url_shape": "Public URL: <api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>. The path is supplied by the caller in triggerMetadata.path and must be URL-safe. The URL is NOT returned in the create_trigger / get_trigger response — derive it from the workspaceSlug + path.",
+                                    "http-trigger_setup_flow": "Webhook signing secrets are chicken-and-egg: providers issue the secret only AFTER you give them a URL. Recommended flow — (1) create_trigger with { path, provider, validateSignature: true } and NO signingSecret — the trigger is created in a pending state with a stable URL; (2) register that URL in the provider's dashboard; (3) once the provider returns the signing secret, call update_trigger with signingSecret set. Until step 3 lands, the trigger rejects every request with 'HMAC signing secret not configured for this endpoint' — that's the desired safe default during URL-registration.",
+                                    "http-trigger_provider_shortcut": {
+                                        _note: "Recommended — one preset wires every wire-format detail. Use this for Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify. Override individual fields only if a provider's scheme has drifted (e.g. custom hmacAlgorithm).",
+                                        path: "clerk-webhook",
+                                        validateSignature: true,
+                                        provider: "svix",
+                                        signingSecret: "whsec_…",
+                                    },
+                                    "http-trigger_advanced_raw": {
+                                        _note: "Skip the preset for full manual control — useful for non-standard schemes the built-in providers don't cover. Every field maps 1:1 to the runtime SignatureMetadata interface.",
+                                        path: "custom-webhook",
+                                        validateSignature: true,
+                                        signingSecret: "whsec_…",
+                                        signatureHeaderName: "x-custom-signature",
+                                        timestampHeaderName: "x-custom-timestamp",
+                                        extractionPattern: "^v1,(.+)$",
+                                        hmacAlgorithm: "sha256",
+                                        hmacEncoding: "base64",
+                                        secretEncoding: "prefixed-base64",
+                                    },
+                                    endpoint_provider_shortcut: {
+                                        _note: "Provider-named endpoint auth mode + colocated secret. Equivalent to mode: 'hmac' + triggerMetadata.provider — the service layer normalises auth.secret onto triggerMetadata.signingSecret at create/update time.",
+                                        path: "stripe-events",
+                                        allowedMethods: ["POST"],
+                                        auth: { mode: "stripe", secret: "whsec_…" },
+                                    },
                                     endpoint: { path: "create-order", allowedMethods: ["POST"], timeoutMs: 10000, auth: { mode: "bearer" } },
                                 },
                             },

package/dist/tools/records.js

@@ -104,7 +104,7 @@ function dateWindowToWhere(dw) {
     return { and: conds };
 }
 function translateQueryRecordsArgs(args) {
-    var _a, _b;
+    var _a, _b, _c, _d;
     const isLegacy = args.recordSlug !== undefined ||
         args.filters !== undefined ||
         typeof args.sort === "string" ||
@@ -174,8 +174,19 @@ function translateQueryRecordsArgs(args) {
         if (relations.length > 0)
             definition.include = relations;
     }
-    // `includeTotal` is dropped — `meta.total` is always returned for offset
-    // pagination on POST /records/query. `includeDeleted` is rejected above.
+    // CEN-1259: count(*) is opt-in on POST /records/query. Default for the
+    // canonical surface is OFF (skip the duplicate predicate scan); legacy
+    // 5.4.0 callers expected `meta.total` always, so when the caller used a
+    // legacy field we preserve total-by-default. `includeTotal` (any surface)
+    // is the explicit override — including `includeTotal: false`, which must
+    // clear an existing canonical `page.withTotal: true` so the override is
+    // authoritative on both directions. `includeDeleted` is rejected above.
+    if (args.includeTotal !== undefined) {
+        definition.page = Object.assign(Object.assign({}, ((_c = definition.page) !== null && _c !== void 0 ? _c : { limit: 50 })), { withTotal: args.includeTotal === true });
+    }
+    else if (isLegacy) {
+        definition.page = Object.assign(Object.assign({}, ((_d = definition.page) !== null && _d !== void 0 ? _d : { limit: 50 })), { withTotal: true });
+    }
     return { resource, definition };
 }
 /**
@@ -384,7 +395,7 @@ Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' a
         includeTotal: zod_1.z
             .boolean()
             .optional()
-            .describe("[Deprecated 2026-10-28] Ignored — `meta.total` is always returned for offset pagination."),
+            .describe("Set to true to request `meta.total` in the response. Default false — counting is skipped to keep list calls fast (CEN-1259)."),
         // Templating
         variables: 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": "6.0.0",
+  "version": "6.1.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -25,7 +25,7 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^6.0.0",
+    "@centrali-io/centrali-sdk": "^6.1.0",
     "@modelcontextprotocol/sdk": "^1.28.0"
   },
   "devDependencies": {

package/src/tools/compute.ts

@@ -422,7 +422,7 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK, centra
       triggerMetadata: z
         .record(z.string(), z.any())
         .optional()
-        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: auto-generated URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' }. All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
+        .describe("Type-specific configuration. For event-driven: { eventType, recordSlug }. For scheduled: { scheduleType, cronExpression, timezone }. For http-trigger: { path } where path is a URL-safe slug (e.g. 'stripe-webhook'); the trigger is reachable at `<api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>`. Optional native HMAC signature verification (no crypto in the function body): the **recommended path** is { validateSignature: true, provider: 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', signingSecret } — the `provider` shortcut wires every wire-format detail (header names, signed-value format, digest encoding, secret encoding) from a built-in preset. Covers Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify out of the box. **Advanced**: any preset field can be overridden, or the preset can be skipped entirely by supplying the raw knobs directly — { validateSignature: true, signingSecret, signatureHeaderName, signatureIdHeaderName?, timestampHeaderName?, timestampExtractionPattern?, extractionPattern?, hmacAlgorithm?, hmacEncoding?, secretEncoding?, encoding?, payloadFormat? }. Defaults when no provider: hmacAlgorithm 'sha256', hmacEncoding 'base64', extractionPattern '^(?:v1,)?(.+)$', secretEncoding 'raw'; built-in 5-minute replay tolerance. Two-step setup recommended: (1) create the trigger with just { path } and optionally { provider } — the public URL is `<api-host>/data/workspace/<ws>/api/v1/http-trigger/<path>`; (2) register that URL with the webhook provider; (3) when the provider issues the signing secret, call update_trigger with validateSignature: true + signingSecret. Providers will not give a signing secret until they have the URL. For endpoint: { path, allowedMethods?, timeoutMs?, auth? } where path is URL-safe (e.g., 'create-order'), allowedMethods defaults to ['POST'], timeoutMs 1000-30000 (default 30000), auth is { mode: 'bearer'|'public'|'apiKey'|'hmac' | 'svix' | 'stripe' | 'slack' | 'github' | 'shopify', secret? } — provider-named modes are HMAC verification with the matching preset (auth.secret is the colocated signing secret; legacy `mode: 'hmac'` keeps its single-header body-only behaviour for back-compat). All trigger types accept params: a dictionary of static values passed to the function as triggerParams. Mark any secret with { value: 'plaintext', encrypt: true } to store it AES-256-GCM-encrypted at rest; it arrives as plaintext in triggerParams at execution time."),
       enabled: z.boolean().optional().describe("Whether the trigger is enabled (default: true)"),
     },
     async ({ name, functionId, executionType, description, triggerMetadata, enabled }) => {

package/src/tools/describe.ts

@@ -917,6 +917,33 @@ export function registerDescribeTools(server: McpServer) {
                   triggerMetadata_examples: {
                     "event-driven": { eventType: "record_created", recordSlug: "orders" },
                     scheduled: { scheduleType: "cron", cronExpression: "0 9 * * *", timezone: "America/New_York" },
+                    "http-trigger_url_shape": "Public URL: <api-host>/data/workspace/<workspaceSlug>/api/v1/http-trigger/<path>. The path is supplied by the caller in triggerMetadata.path and must be URL-safe. The URL is NOT returned in the create_trigger / get_trigger response — derive it from the workspaceSlug + path.",
+                    "http-trigger_setup_flow": "Webhook signing secrets are chicken-and-egg: providers issue the secret only AFTER you give them a URL. Recommended flow — (1) create_trigger with { path, provider, validateSignature: true } and NO signingSecret — the trigger is created in a pending state with a stable URL; (2) register that URL in the provider's dashboard; (3) once the provider returns the signing secret, call update_trigger with signingSecret set. Until step 3 lands, the trigger rejects every request with 'HMAC signing secret not configured for this endpoint' — that's the desired safe default during URL-registration.",
+                    "http-trigger_provider_shortcut": {
+                      _note: "Recommended — one preset wires every wire-format detail. Use this for Svix (Clerk, Resend, Loops, OpenAI, Brex), Stripe, Slack, GitHub, Shopify. Override individual fields only if a provider's scheme has drifted (e.g. custom hmacAlgorithm).",
+                      path: "clerk-webhook",
+                      validateSignature: true,
+                      provider: "svix",
+                      signingSecret: "whsec_…",
+                    },
+                    "http-trigger_advanced_raw": {
+                      _note: "Skip the preset for full manual control — useful for non-standard schemes the built-in providers don't cover. Every field maps 1:1 to the runtime SignatureMetadata interface.",
+                      path: "custom-webhook",
+                      validateSignature: true,
+                      signingSecret: "whsec_…",
+                      signatureHeaderName: "x-custom-signature",
+                      timestampHeaderName: "x-custom-timestamp",
+                      extractionPattern: "^v1,(.+)$",
+                      hmacAlgorithm: "sha256",
+                      hmacEncoding: "base64",
+                      secretEncoding: "prefixed-base64",
+                    },
+                    endpoint_provider_shortcut: {
+                      _note: "Provider-named endpoint auth mode + colocated secret. Equivalent to mode: 'hmac' + triggerMetadata.provider — the service layer normalises auth.secret onto triggerMetadata.signingSecret at create/update time.",
+                      path: "stripe-events",
+                      allowedMethods: ["POST"],
+                      auth: { mode: "stripe", secret: "whsec_…" },
+                    },
                     endpoint: { path: "create-order", allowedMethods: ["POST"], timeoutMs: 10000, auth: { mode: "bearer" } },
                   },
                 },

package/src/tools/records.ts

@@ -176,8 +176,18 @@ function translateQueryRecordsArgs(args: QueryRecordsArgs): {
     if (relations.length > 0) definition.include = relations;
   }
 
-  // `includeTotal` is dropped — `meta.total` is always returned for offset
-  // pagination on POST /records/query. `includeDeleted` is rejected above.
+  // CEN-1259: count(*) is opt-in on POST /records/query. Default for the
+  // canonical surface is OFF (skip the duplicate predicate scan); legacy
+  // 5.4.0 callers expected `meta.total` always, so when the caller used a
+  // legacy field we preserve total-by-default. `includeTotal` (any surface)
+  // is the explicit override — including `includeTotal: false`, which must
+  // clear an existing canonical `page.withTotal: true` so the override is
+  // authoritative on both directions. `includeDeleted` is rejected above.
+  if (args.includeTotal !== undefined) {
+    definition.page = { ...(definition.page ?? { limit: 50 }), withTotal: args.includeTotal === true };
+  } else if (isLegacy) {
+    definition.page = { ...(definition.page ?? { limit: 50 }), withTotal: true };
+  }
 
   return { resource, definition };
 }
@@ -414,7 +424,7 @@ Returns the canonical { data, meta } envelope. 'select', 'text', and 'include' a
       includeTotal: z
         .boolean()
         .optional()
-        .describe("[Deprecated 2026-10-28] Ignored — `meta.total` is always returned for offset pagination."),
+        .describe("Set to true to request `meta.total` in the response. Default false — counting is skipped to keep list calls fast (CEN-1259)."),
 
       // Templating
       variables: z

package/tests/records.translator.test.cjs

@@ -46,7 +46,10 @@ test("full 5.4.0 legacy shape translates", () => {
                 ],
             },
             sort: [{ field: "createdAt", direction: "desc" }],
-            page: { limit: 50, offset: 50 },
+            // CEN-1259: legacy 5.4.0 callers expected `meta.total` always; the
+            // translator preserves total-by-default by setting `withTotal: true`
+            // when any legacy field was used.
+            page: { limit: 50, offset: 50, withTotal: true },
         },
     });
 });
@@ -134,19 +137,41 @@ test("sort: multi-sort comma-separated mixes asc/desc", () => {
     ]);
 });
 
-test("page without pageSize defaults to limit 50", () => {
+test("page without pageSize defaults to limit 50 (legacy → withTotal:true)", () => {
     const out = translateQueryRecordsArgs({ recordSlug: "orders", page: 3 });
-    assert.deepEqual(out.definition.page, { limit: 50, offset: 100 });
+    assert.deepEqual(out.definition.page, { limit: 50, offset: 100, withTotal: true });
 });
 
-test("pageSize without page → limit only", () => {
+test("pageSize without page → limit only (legacy → withTotal:true)", () => {
     const out = translateQueryRecordsArgs({ recordSlug: "orders", pageSize: 25 });
-    assert.deepEqual(out.definition.page, { limit: 25 });
+    assert.deepEqual(out.definition.page, { limit: 25, withTotal: true });
 });
 
-test("includeTotal silently dropped (meta.total always returned)", () => {
+// CEN-1259: `includeTotal` is now an explicit override on any surface.
+// Legacy callers that pass it (with `recordSlug`) get `withTotal` reflected
+// directly; legacy callers that omit it get total-by-default for back-compat.
+test("includeTotal:true sets withTotal:true (explicit opt-in)", () => {
     const out = translateQueryRecordsArgs({ recordSlug: "orders", includeTotal: true });
-    assert.deepEqual(out.definition, { resource: "orders" });
+    assert.deepEqual(out.definition, { resource: "orders", page: { limit: 50, withTotal: true } });
+});
+
+test("includeTotal:false on legacy caller overrides default-on (explicit opt-out)", () => {
+    const out = translateQueryRecordsArgs({ recordSlug: "orders", includeTotal: false });
+    assert.deepEqual(out.definition, { resource: "orders", page: { limit: 50, withTotal: false } });
+});
+
+test("includeTotal:false clears canonical page.withTotal:true", () => {
+    const out = translateQueryRecordsArgs({
+        resource: "orders",
+        page: { limit: 25, withTotal: true },
+        includeTotal: false,
+    });
+    assert.deepEqual(out.definition.page, { limit: 25, withTotal: false });
+});
+
+test("canonical caller without includeTotal stays opt-out (no legacy default-on)", () => {
+    const out = translateQueryRecordsArgs({ resource: "orders", page: { limit: 25, offset: 0 } });
+    assert.deepEqual(out.definition.page, { limit: 25, offset: 0 });
 });
 
 test("includeDeleted: true throws clear error (no silent privacy regression)", () => {