@centrali-io/centrali-mcp 5.2.0 → 5.3.0

package/dist/tools/webhook-subscriptions.js

@@ -0,0 +1,292 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWebhookSubscriptionTools = registerWebhookSubscriptionTools;
+const zod_1 = require("zod");
+const _register_js_1 = require("./_register.js");
+const RECORD_EVENT_VALUES = [
+    "record_created",
+    "record_updated",
+    "record_deleted",
+    "records_bulk_created",
+];
+const DELIVERY_STATUS_VALUES = ["success", "failed", "retrying"];
+function registerWebhookSubscriptionTools(server, sdk) {
+    // ── Subscription CRUD ──────────────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "list_webhook_subscriptions", "List all webhook subscriptions in the workspace. Subscriptions deliver record events to an external URL, signed with HMAC-SHA256 under the subscription's `whsec_` secret.", {}, () => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const result = yield sdk.webhookSubscriptions.list();
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, "listing webhook subscriptions") }],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "get_webhook_subscription", "Get a single webhook subscription by ID. The signing secret is not returned on reads — use rotate_webhook_subscription_secret to regenerate it.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId }) {
+        try {
+            const result = yield sdk.webhookSubscriptions.get(subscriptionId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    { type: "text", text: (0, _register_js_1.formatError)(error, `getting webhook subscription '${subscriptionId}'`) },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "create_webhook_subscription", "Create a webhook subscription. The response includes the signing secret (whsec_...) — capture it immediately, it is not returned on subsequent reads.", {
+        name: zod_1.z.string().describe("Display name for the subscription"),
+        url: zod_1.z.string().describe("HTTPS URL that will receive POSTed event payloads"),
+        events: zod_1.z
+            .array(zod_1.z.enum(RECORD_EVENT_VALUES))
+            .describe("Record events to subscribe to: record_created, record_updated, record_deleted, records_bulk_created"),
+        recordSlugs: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Optional list of collection record slugs to scope the subscription to. Omit for all collections."),
+        active: zod_1.z
+            .boolean()
+            .optional()
+            .describe("Whether the subscription is active on creation. Defaults to true."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, url, events, recordSlugs, active }) {
+        try {
+            const input = { name, url, events };
+            if (recordSlugs !== undefined)
+                input.recordSlugs = recordSlugs;
+            if (active !== undefined)
+                input.active = active;
+            const result = yield sdk.webhookSubscriptions.create(input);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    { type: "text", text: (0, _register_js_1.formatError)(error, `creating webhook subscription '${name}'`) },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "update_webhook_subscription", "Update fields on a webhook subscription. The signing secret is server-managed — use rotate_webhook_subscription_secret to change it.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+        name: zod_1.z.string().optional().describe("Updated display name"),
+        url: zod_1.z.string().optional().describe("Updated HTTPS URL"),
+        events: zod_1.z
+            .array(zod_1.z.enum(RECORD_EVENT_VALUES))
+            .optional()
+            .describe("Updated list of subscribed events"),
+        recordSlugs: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe("Updated collection scope. Pass [] to clear the restriction (subscribe to all collections). Omit to leave scope unchanged."),
+        active: zod_1.z.boolean().optional().describe("Enable or disable the subscription"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId, name, url, events, recordSlugs, active }) {
+        try {
+            const patch = {};
+            if (name !== undefined)
+                patch.name = name;
+            if (url !== undefined)
+                patch.url = url;
+            if (events !== undefined)
+                patch.events = events;
+            if (recordSlugs !== undefined)
+                patch.recordSlugs = recordSlugs;
+            if (active !== undefined)
+                patch.active = active;
+            const result = yield sdk.webhookSubscriptions.update(subscriptionId, patch);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `updating webhook subscription '${subscriptionId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "delete_webhook_subscription", "Delete a webhook subscription. Historical delivery records are retained but no new deliveries will be dispatched.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId }) {
+        try {
+            yield sdk.webhookSubscriptions.delete(subscriptionId);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Webhook subscription '${subscriptionId}' deleted successfully.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `deleting webhook subscription '${subscriptionId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "rotate_webhook_subscription_secret", "Rotate the signing secret on a webhook subscription. Immediate cutover — the old secret stops signing on the next dispatch. The response includes the new secret; capture it before closing.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId }) {
+        try {
+            const result = yield sdk.webhookSubscriptions.rotateSecret(subscriptionId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `rotating secret for webhook subscription '${subscriptionId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    // ── Delivery history + replay ──────────────────────────────────
+    (0, _register_js_1.registerTool)(server, "list_webhook_deliveries", "List delivery history for a webhook subscription. Rows omit requestPayload and responseBody — use get_webhook_delivery to fetch full payload and response body for a specific delivery.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+        status: zod_1.z
+            .enum(DELIVERY_STATUS_VALUES)
+            .optional()
+            .describe("Filter deliveries by status"),
+        since: zod_1.z
+            .string()
+            .optional()
+            .describe("ISO 8601 datetime — include deliveries created at or after this time"),
+        until: zod_1.z
+            .string()
+            .optional()
+            .describe("ISO 8601 datetime — include deliveries created at or before this time"),
+        limit: zod_1.z.number().optional().describe("Max rows to return (default 50)"),
+        offset: zod_1.z.number().optional().describe("Number of rows to skip for pagination"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId, status, since, until, limit, offset }) {
+        try {
+            const options = {};
+            if (status)
+                options.status = status;
+            if (since)
+                options.since = since;
+            if (until)
+                options.until = until;
+            if (limit !== undefined)
+                options.limit = limit;
+            if (offset !== undefined)
+                options.offset = offset;
+            const result = yield sdk.webhookSubscriptions.deliveries.list(subscriptionId, Object.keys(options).length > 0 ? options : undefined);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `listing deliveries for webhook subscription '${subscriptionId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "get_webhook_delivery", "Get a single webhook delivery including the full request payload and response body.", {
+        subscriptionId: zod_1.z.string().describe("The webhook subscription UUID"),
+        deliveryId: zod_1.z.string().describe("The delivery UUID"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ subscriptionId, deliveryId }) {
+        try {
+            const result = yield sdk.webhookSubscriptions.deliveries.get(subscriptionId, deliveryId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `getting webhook delivery '${deliveryId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "retry_webhook_delivery", "Replay a previously recorded webhook delivery. Queues a new delivery row pointing at the original via replayedFrom; the retry worker picks it up within ~1 second. The original payload and signature are reused.", {
+        deliveryId: zod_1.z.string().describe("The delivery UUID to replay"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ deliveryId }) {
+        try {
+            const result = yield sdk.webhookSubscriptions.deliveries.retry(deliveryId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `replaying webhook delivery '${deliveryId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    (0, _register_js_1.registerTool)(server, "cancel_webhook_delivery", "Cancel a webhook delivery that is currently in 'retrying' status. Flips the row to 'failed' with lastError set to 'Cancelled by user'. Returns 409 if the delivery is not retrying or is mid-dispatch.", {
+        deliveryId: zod_1.z.string().describe("The delivery UUID to cancel"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ deliveryId }) {
+        try {
+            const result = yield sdk.webhookSubscriptions.deliveries.cancel(deliveryId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: (0, _register_js_1.formatError)(error, `cancelling webhook delivery '${deliveryId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",
@@ -13,8 +13,7 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.json",
-    "prepublishOnly": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "mcp",
@@ -25,13 +24,13 @@
   "author": "Blueinit",
   "license": "ISC",
   "dependencies": {
-    "@centrali-io/centrali-sdk": "^4.4.8",
-    "@modelcontextprotocol/sdk": "^1.12.1"
+    "@centrali-io/centrali-sdk": "^5.3.0",
+    "@modelcontextprotocol/sdk": "^1.28.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.0",
     "@types/qs": "^6.14.0",
-    "typescript": "^5.8.3"
+    "typescript": "5.9.3"
   },
   "overrides": {
     "@hono/node-server": "^1.19.10",

package/src/index.ts

@@ -15,6 +15,7 @@ import { registerPageTools } from "./tools/pages.js";
 import { registerDescribeTools } from "./tools/describe.js";
 import { registerAuthProviderTools } from "./tools/auth-providers.js";
 import { registerServiceAccountTools } from "./tools/service-accounts.js";
+import { registerWebhookSubscriptionTools } from "./tools/webhook-subscriptions.js";
 import { registerStructureResources, registerCollectionResources } from "./resources/structures.js";
 
 function getRequiredEnv(name: string): string {
@@ -79,6 +80,7 @@ async function main() {
     clientId,
     isServiceAccount: true,
   });
+  registerWebhookSubscriptionTools(server, sdk);
   registerDescribeTools(server);
 
   // Register resources

package/src/tools/_register.ts

@@ -0,0 +1,53 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodRawShape } from "zod";
+
+export type ToolResult = {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: boolean;
+};
+
+/**
+ * Thin wrapper around `server.tool(...)` that severs the MCP SDK's deep
+ * Zod-shape → handler-arg type inference. Each direct call to `server.tool()`
+ * forces TypeScript to elaborate a ~10M-instantiation type graph (MCP SDK
+ * `ShapeOutput` generics over Zod raw shapes), which OOMs tsc at ~4 GB.
+ *
+ * This helper casts the schema and handler at the MCP boundary, so tsc never
+ * walks that graph. Runtime behavior is identical — the MCP SDK still
+ * validates the payload against the Zod schema before invoking the handler.
+ *
+ * Call sites annotate the arg shape explicitly via the `Args` generic so the
+ * handler body stays fully type-safe.
+ */
+export function registerTool<Args>(
+  server: McpServer,
+  name: string,
+  description: string,
+  schema: ZodRawShape,
+  handler: (args: Args) => Promise<ToolResult>
+): void {
+  (server.tool as any)(name, description, schema, handler);
+}
+
+export function formatError(error: unknown, context: string): string {
+  if (error && typeof error === "object") {
+    const e = error as Record<string, any>;
+    if ("message" in e) {
+      let msg = `Error ${context}`;
+      if ("code" in e || "status" in e) {
+        msg += `: [${e.code ?? e.status ?? "ERROR"}] ${e.message}`;
+      } else {
+        msg += `: ${e.message}`;
+      }
+      if (Array.isArray(e.fieldErrors) && e.fieldErrors.length > 0) {
+        msg +=
+          "\nField errors:\n" +
+          (e.fieldErrors as Array<{ field: string; message: string }>)
+            .map((f) => `  ${f.field}: ${f.message}`)
+            .join("\n");
+      }
+      return msg;
+    }
+  }
+  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/src/tools/auth-providers.ts

@@ -2,7 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import axios, { AxiosInstance } from "axios";
 import { z } from "zod";
-
+import { registerTool, formatError } from "./_register.js";
 /**
  * Ensures the SDK has a valid token by making a lightweight SDK call if needed.
  */
@@ -62,22 +62,6 @@ function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: str
   return client;
 }
 
-function formatError(error: unknown, context: string): string {
-  if (error && typeof error === "object") {
-    const e = error as Record<string, any>;
-    if (e.response?.data) {
-      const d = e.response.data;
-      const code = d.code ?? d.error?.code ?? e.response.status ?? "ERROR";
-      const message = d.message ?? d.error?.message ?? JSON.stringify(d);
-      return `Error ${context}: [${code}] ${message}`;
-    }
-    if ("message" in e) {
-      return `Error ${context}: ${e.message}`;
-    }
-  }
-  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
-}
-
 const ClaimMappingZod = z.object({
   attribute: z.string().describe("Attribute name used in policies (automatically prefixed with ext_). Must start with a letter, alphanumeric + underscores only. Example: 'role' becomes ext_role in policies."),
   jwtPath: z.string().describe("Dot-notation path to extract from the JWT payload. Examples: 'org_role', 'metadata.plan', 'organization.role'"),
@@ -91,7 +75,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── List ──────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_auth_providers",
     "List external auth providers configured in the workspace. These are identity providers (Clerk, Auth0, Okta, etc.) that can issue JWTs accepted by Centrali for BYOT (Bring Your Own Token) authorization.",
     {
@@ -116,7 +100,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Get ───────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_auth_provider",
     "Get details of an external auth provider by ID, including claim mappings and JWKS configuration.",
     {
@@ -139,7 +123,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Create ────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "create_auth_provider",
     "Create an external auth provider for BYOT (Bring Your Own Token). This lets your app's users authenticate with Clerk, Auth0, Okta, or any OIDC provider, and Centrali validates their JWTs and extracts claims for authorization policies. Call describe_auth_providers for the full setup guide.",
     {
@@ -179,7 +163,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Update ────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "update_auth_provider",
     "Update an external auth provider. Only include the fields you want to change. Use this to update claim mappings, allowed audiences, or deactivate a provider.",
     {
@@ -220,7 +204,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Delete ────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_auth_provider",
     "Delete an external auth provider. Tokens from this provider will no longer be accepted.",
     {
@@ -243,7 +227,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Test Claim Extraction ─────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "test_auth_provider",
     "Test claim extraction for an auth provider by passing a sample JWT. Decodes the token (without signature verification) and shows which claims would be extracted using the provider's configured mappings. Use this to validate your claim mappings before deploying.",
     {
@@ -267,7 +251,7 @@ export function registerAuthProviderTools(server: McpServer, sdk: CentraliSDK, c
 
   // ── Refresh JWKS ──────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "refresh_auth_provider_jwks",
     "Force refresh the cached JWKS (JSON Web Key Set) for an auth provider. Use this after your identity provider rotates its signing keys.",
     {