@centrali-io/centrali-mcp 5.1.2 → 5.3.0

package/README.md

@@ -101,6 +101,7 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `describe_navigation` | Navigation configuration reference |
 | `describe_auth_providers` | Auth provider reference (BYOT setup, claim mappings) |
 | `describe_service_accounts` | Service account & IAM reference (SA setup, roles, groups, permissions) |
+| `describe_webhooks` | Outbound webhook reference (subscription shape, signature, retry/replay) |
 
 ### Collections
 | Tool | Description |
@@ -254,6 +255,20 @@ After connecting, call `describe_centrali` first — it returns the full capabil
 | `update_group` | Update a group |
 | `delete_group` | Delete a group |
 
+### Webhook Subscriptions
+| Tool | Description |
+|------|-------------|
+| `list_webhook_subscriptions` | List all outbound webhook subscriptions |
+| `get_webhook_subscription` | Get a subscription by ID (secret not included) |
+| `create_webhook_subscription` | Create a subscription — response returns the `whsec_` signing secret once |
+| `update_webhook_subscription` | Update name, URL, events, recordSlugs, or active flag |
+| `delete_webhook_subscription` | Delete a subscription (delivery history retained) |
+| `rotate_webhook_subscription_secret` | Regenerate the signing secret (immediate cutover) |
+| `list_webhook_deliveries` | List delivery history for a subscription (trimmed rows) |
+| `get_webhook_delivery` | Get a single delivery with full payload and response body |
+| `retry_webhook_delivery` | Replay a delivery — reuses the original payload and signature |
+| `cancel_webhook_delivery` | Cancel a retrying delivery (flips to failed with distinctive marker) |
+
 ### Publishable Keys (Frontend)
 | Tool | Description |
 |------|-------------|

package/dist/index.js

@@ -25,6 +25,7 @@ const pages_js_1 = require("./tools/pages.js");
 const describe_js_1 = require("./tools/describe.js");
 const auth_providers_js_1 = require("./tools/auth-providers.js");
 const service_accounts_js_1 = require("./tools/service-accounts.js");
+const webhook_subscriptions_js_1 = require("./tools/webhook-subscriptions.js");
 const structures_js_2 = require("./resources/structures.js");
 function getRequiredEnv(name) {
     const value = process.env[name];
@@ -82,6 +83,7 @@ function main() {
             clientId,
             isServiceAccount: true,
         });
+        (0, webhook_subscriptions_js_1.registerWebhookSubscriptionTools)(server, sdk);
         (0, describe_js_1.registerDescribeTools)(server);
         // Register resources
         (0, structures_js_2.registerCollectionResources)(server, sdk);

package/dist/tools/_register.d.ts

@@ -0,0 +1,24 @@
+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 declare function registerTool<Args>(server: McpServer, name: string, description: string, schema: ZodRawShape, handler: (args: Args) => Promise<ToolResult>): void;
+export declare function formatError(error: unknown, context: string): string;

package/dist/tools/_register.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+exports.formatError = formatError;
+/**
+ * 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.
+ */
+function registerTool(server, name, description, schema, handler) {
+    server.tool(name, description, schema, handler);
+}
+function formatError(error, context) {
+    var _a, _b;
+    if (error && typeof error === "object") {
+        const e = error;
+        if ("message" in e) {
+            let msg = `Error ${context}`;
+            if ("code" in e || "status" in e) {
+                msg += `: [${(_b = (_a = e.code) !== null && _a !== void 0 ? _a : e.status) !== null && _b !== void 0 ? _b : "ERROR"}] ${e.message}`;
+            }
+            else {
+                msg += `: ${e.message}`;
+            }
+            if (Array.isArray(e.fieldErrors) && e.fieldErrors.length > 0) {
+                msg +=
+                    "\nField errors:\n" +
+                        e.fieldErrors
+                            .map((f) => `  ${f.field}: ${f.message}`)
+                            .join("\n");
+            }
+            return msg;
+        }
+    }
+    return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/dist/tools/auth-providers.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAuthProviderTools = registerAuthProviderTools;
 const axios_1 = __importDefault(require("axios"));
 const zod_1 = require("zod");
+const _register_js_1 = require("./_register.js");
 /**
  * Ensures the SDK has a valid token by making a lightweight SDK call if needed.
  */
@@ -69,22 +70,6 @@ function createIamClient(sdk, centraliUrl, workspaceId) {
     }));
     return client;
 }
-function formatError(error, context) {
-    var _a, _b, _c, _d, _e, _f, _g, _h;
-    if (error && typeof error === "object") {
-        const e = error;
-        if ((_a = e.response) === null || _a === void 0 ? void 0 : _a.data) {
-            const d = e.response.data;
-            const code = (_e = (_d = (_b = d.code) !== null && _b !== void 0 ? _b : (_c = d.error) === null || _c === void 0 ? void 0 : _c.code) !== null && _d !== void 0 ? _d : e.response.status) !== null && _e !== void 0 ? _e : "ERROR";
-            const message = (_h = (_f = d.message) !== null && _f !== void 0 ? _f : (_g = d.error) === null || _g === void 0 ? void 0 : _g.message) !== null && _h !== void 0 ? _h : 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 = zod_1.z.object({
     attribute: zod_1.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: zod_1.z.string().describe("Dot-notation path to extract from the JWT payload. Examples: 'org_role', 'metadata.plan', 'organization.role'"),
@@ -95,7 +80,7 @@ const ClaimMappingZod = zod_1.z.object({
 function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
     const getClient = () => createIamClient(sdk, centraliUrl, workspaceId);
     // ── List ──────────────────────────────────────────────────────────
-    server.tool("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.", {
+    (0, _register_js_1.registerTool)(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.", {
         includeInactive: zod_1.z.boolean().optional().describe("Include inactive providers (default: false)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ includeInactive }) {
         try {
@@ -109,13 +94,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, "listing auth providers") }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, "listing auth providers") }],
                 isError: true,
             };
         }
     }));
     // ── Get ───────────────────────────────────────────────────────────
-    server.tool("get_auth_provider", "Get details of an external auth provider by ID, including claim mappings and JWKS configuration.", {
+    (0, _register_js_1.registerTool)(server, "get_auth_provider", "Get details of an external auth provider by ID, including claim mappings and JWKS configuration.", {
         providerId: zod_1.z.string().describe("The provider ID (UUID)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ providerId }) {
         try {
@@ -126,13 +111,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `getting auth provider '${providerId}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `getting auth provider '${providerId}'`) }],
                 isError: true,
             };
         }
     }));
     // ── Create ────────────────────────────────────────────────────────
-    server.tool("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.", {
+    (0, _register_js_1.registerTool)(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.", {
         name: zod_1.z.string().describe("Display name (e.g., 'Production Clerk')"),
         slug: zod_1.z.string().describe("URL-safe unique slug (lowercase, hyphens allowed, e.g., 'production-clerk')"),
         providerType: zod_1.z.enum(["oidc", "clerk", "auth0", "keycloak", "okta", "custom"]).describe("Identity provider type. Use 'clerk', 'auth0', 'okta', or 'keycloak' for built-in support, 'oidc' for any OIDC-compliant provider, or 'custom' for a custom JWT issuer."),
@@ -165,13 +150,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `creating auth provider '${name}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `creating auth provider '${name}'`) }],
                 isError: true,
             };
         }
     }));
     // ── Update ────────────────────────────────────────────────────────
-    server.tool("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.", {
+    (0, _register_js_1.registerTool)(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.", {
         providerId: zod_1.z.string().describe("The provider ID (UUID) to update"),
         name: zod_1.z.string().optional().describe("Updated display name"),
         jwksUrl: zod_1.z.string().optional().describe("Updated JWKS URL"),
@@ -207,13 +192,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `updating auth provider '${providerId}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `updating auth provider '${providerId}'`) }],
                 isError: true,
             };
         }
     }));
     // ── Delete ────────────────────────────────────────────────────────
-    server.tool("delete_auth_provider", "Delete an external auth provider. Tokens from this provider will no longer be accepted.", {
+    (0, _register_js_1.registerTool)(server, "delete_auth_provider", "Delete an external auth provider. Tokens from this provider will no longer be accepted.", {
         providerId: zod_1.z.string().describe("The provider ID (UUID) to delete"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ providerId }) {
         try {
@@ -224,13 +209,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `deleting auth provider '${providerId}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `deleting auth provider '${providerId}'`) }],
                 isError: true,
             };
         }
     }));
     // ── Test Claim Extraction ─────────────────────────────────────────
-    server.tool("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.", {
+    (0, _register_js_1.registerTool)(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.", {
         providerId: zod_1.z.string().describe("The provider ID (UUID) to test against"),
         token: zod_1.z.string().describe("A sample JWT token from your identity provider"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ providerId, token }) {
@@ -242,13 +227,13 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `testing auth provider '${providerId}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `testing auth provider '${providerId}'`) }],
                 isError: true,
             };
         }
     }));
     // ── Refresh JWKS ──────────────────────────────────────────────────
-    server.tool("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.", {
+    (0, _register_js_1.registerTool)(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.", {
         providerId: zod_1.z.string().describe("The provider ID (UUID)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ providerId }) {
         try {
@@ -259,7 +244,7 @@ function registerAuthProviderTools(server, sdk, centraliUrl, workspaceId) {
         }
         catch (error) {
             return {
-                content: [{ type: "text", text: formatError(error, `refreshing JWKS for auth provider '${providerId}'`) }],
+                content: [{ type: "text", text: (0, _register_js_1.formatError)(error, `refreshing JWKS for auth provider '${providerId}'`) }],
                 isError: true,
             };
         }