@centrali-io/centrali-mcp 5.2.0 → 5.4.0

package/src/tools/validation.ts

@@ -1,32 +1,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK, ListValidationSuggestionsOptions } from "@centrali-io/centrali-sdk";
 import { z } from "zod";
+import { registerTool, formatError } from "./_register.js";
 
-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)}`;
-}
+type ValidationIssueType = "typo" | "format" | "duplicate" | "semantic" | "type";
+type SuggestionStatus = "pending" | "accepted" | "rejected" | "auto-applied";
 
 export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<{
+    recordSlug: string;
+    validationTypes?: ValidationIssueType[];
+  }>(
+    server,
     "trigger_validation_scan",
     "Trigger an AI-powered data quality scan on a collection. Detects typos, format inconsistencies, duplicates, and other data issues. Returns a batchId — use get_validation_summary or list_validation_suggestions to see results after the scan completes.",
     {
@@ -60,7 +45,13 @@ export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{
+    recordSlug?: string;
+    status?: SuggestionStatus;
+    issueType?: ValidationIssueType;
+    minConfidence?: number;
+  }>(
+    server,
     "list_validation_suggestions",
     "List data quality suggestions generated by validation scans. Each suggestion identifies an issue in a record and proposes a fix.",
     {
@@ -111,7 +102,8 @@ export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ recordSlug?: string }>(
+    server,
     "get_validation_summary",
     "Get a summary of data quality across the workspace — counts of pending, accepted, and rejected suggestions. Optionally filter by collection.",
     {
@@ -139,7 +131,8 @@ export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ suggestionId: string }>(
+    server,
     "accept_validation_suggestion",
     "Accept a data quality suggestion and apply the fix to the record. The suggested correction is written to the record automatically.",
     {
@@ -165,7 +158,8 @@ export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ suggestionId: string }>(
+    server,
     "reject_validation_suggestion",
     "Reject a data quality suggestion, marking it as incorrect or not applicable. The record is left unchanged.",
     {

package/src/tools/webhook-subscriptions.ts

@@ -0,0 +1,363 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+import { registerTool, formatError } from "./_register.js";
+
+const RECORD_EVENT_VALUES = [
+  "record_created",
+  "record_updated",
+  "record_deleted",
+  "records_bulk_created",
+] as const;
+
+const DELIVERY_STATUS_VALUES = ["success", "failed", "retrying"] as const;
+
+type RecordEventValue = (typeof RECORD_EVENT_VALUES)[number];
+type DeliveryStatusValue = (typeof DELIVERY_STATUS_VALUES)[number];
+
+export function registerWebhookSubscriptionTools(server: McpServer, sdk: CentraliSDK) {
+  // ── Subscription CRUD ──────────────────────────────────────────
+
+  registerTool<Record<string, never>>(
+    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.",
+    {},
+    async () => {
+      try {
+        const result = await sdk.webhookSubscriptions.list();
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing webhook subscriptions") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ subscriptionId: string }>(
+    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: z.string().describe("The webhook subscription UUID"),
+    },
+    async ({ subscriptionId }) => {
+      try {
+        const result = await sdk.webhookSubscriptions.get(subscriptionId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, `getting webhook subscription '${subscriptionId}'`) },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{
+    name: string;
+    url: string;
+    events: RecordEventValue[];
+    recordSlugs?: string[];
+    active?: boolean;
+  }>(
+    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: z.string().describe("Display name for the subscription"),
+      url: z.string().describe("HTTPS URL that will receive POSTed event payloads"),
+      events: z
+        .array(z.enum(RECORD_EVENT_VALUES))
+        .describe("Record events to subscribe to: record_created, record_updated, record_deleted, records_bulk_created"),
+      recordSlugs: z
+        .array(z.string())
+        .optional()
+        .describe("Optional list of collection record slugs to scope the subscription to. Omit for all collections."),
+      active: z
+        .boolean()
+        .optional()
+        .describe("Whether the subscription is active on creation. Defaults to true."),
+    },
+    async ({ name, url, events, recordSlugs, active }) => {
+      try {
+        const input: Record<string, any> = { name, url, events };
+        if (recordSlugs !== undefined) input.recordSlugs = recordSlugs;
+        if (active !== undefined) input.active = active;
+
+        const result = await sdk.webhookSubscriptions.create(input as any);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, `creating webhook subscription '${name}'`) },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{
+    subscriptionId: string;
+    name?: string;
+    url?: string;
+    events?: RecordEventValue[];
+    recordSlugs?: string[];
+    active?: boolean;
+  }>(
+    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: z.string().describe("The webhook subscription UUID"),
+      name: z.string().optional().describe("Updated display name"),
+      url: z.string().optional().describe("Updated HTTPS URL"),
+      events: z
+        .array(z.enum(RECORD_EVENT_VALUES))
+        .optional()
+        .describe("Updated list of subscribed events"),
+      recordSlugs: z
+        .array(z.string())
+        .optional()
+        .describe("Updated collection scope. Pass [] to clear the restriction (subscribe to all collections). Omit to leave scope unchanged."),
+      active: z.boolean().optional().describe("Enable or disable the subscription"),
+    },
+    async ({ subscriptionId, name, url, events, recordSlugs, active }) => {
+      try {
+        const patch: Record<string, any> = {};
+        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 = await sdk.webhookSubscriptions.update(subscriptionId, patch);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `updating webhook subscription '${subscriptionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ subscriptionId: string }>(
+    server,
+    "delete_webhook_subscription",
+    "Delete a webhook subscription. Historical delivery records are retained but no new deliveries will be dispatched.",
+    {
+      subscriptionId: z.string().describe("The webhook subscription UUID"),
+    },
+    async ({ subscriptionId }) => {
+      try {
+        await sdk.webhookSubscriptions.delete(subscriptionId);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Webhook subscription '${subscriptionId}' deleted successfully.`,
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `deleting webhook subscription '${subscriptionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ subscriptionId: string }>(
+    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: z.string().describe("The webhook subscription UUID"),
+    },
+    async ({ subscriptionId }) => {
+      try {
+        const result = await sdk.webhookSubscriptions.rotateSecret(subscriptionId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `rotating secret for webhook subscription '${subscriptionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Delivery history + replay ──────────────────────────────────
+
+  registerTool<{
+    subscriptionId: string;
+    status?: DeliveryStatusValue;
+    since?: string;
+    until?: string;
+    limit?: number;
+    offset?: number;
+  }>(
+    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: z.string().describe("The webhook subscription UUID"),
+      status: z
+        .enum(DELIVERY_STATUS_VALUES)
+        .optional()
+        .describe("Filter deliveries by status"),
+      since: z
+        .string()
+        .optional()
+        .describe("ISO 8601 datetime — include deliveries created at or after this time"),
+      until: z
+        .string()
+        .optional()
+        .describe("ISO 8601 datetime — include deliveries created at or before this time"),
+      limit: z.number().optional().describe("Max rows to return (default 50)"),
+      offset: z.number().optional().describe("Number of rows to skip for pagination"),
+    },
+    async ({ subscriptionId, status, since, until, limit, offset }) => {
+      try {
+        const options: Record<string, any> = {};
+        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 = await 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: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `listing deliveries for webhook subscription '${subscriptionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ subscriptionId: string; deliveryId: string }>(
+    server,
+    "get_webhook_delivery",
+    "Get a single webhook delivery including the full request payload and response body.",
+    {
+      subscriptionId: z.string().describe("The webhook subscription UUID"),
+      deliveryId: z.string().describe("The delivery UUID"),
+    },
+    async ({ subscriptionId, deliveryId }) => {
+      try {
+        const result = await sdk.webhookSubscriptions.deliveries.get(subscriptionId, deliveryId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `getting webhook delivery '${deliveryId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ deliveryId: string }>(
+    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: z.string().describe("The delivery UUID to replay"),
+    },
+    async ({ deliveryId }) => {
+      try {
+        const result = await sdk.webhookSubscriptions.deliveries.retry(deliveryId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `replaying webhook delivery '${deliveryId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  registerTool<{ deliveryId: string }>(
+    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: z.string().describe("The delivery UUID to cancel"),
+    },
+    async ({ deliveryId }) => {
+      try {
+        const result = await sdk.webhookSubscriptions.deliveries.cancel(deliveryId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `cancelling webhook delivery '${deliveryId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}