@centrali-io/centrali-mcp 3.1.4 → 3.1.5

package/src/tools/search.ts

@@ -2,6 +2,27 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import { z } from "zod";
 
+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)}`;
+}
+
 export function registerSearchTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "search_records",
@@ -34,12 +55,12 @@ export function registerSearchTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result.data, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error searching records: ${error.message}`,
+              text: formatError(error, "searching records"),
             },
           ],
           isError: true,

package/src/tools/smart-queries.ts

@@ -2,6 +2,27 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import { z } from "zod";
 
+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)}`;
+}
+
 export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "list_smart_queries",
@@ -24,12 +45,12 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result.data, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error listing smart queries: ${error.message}`,
+              text: formatError(error, "listing smart queries"),
             },
           ],
           isError: true,
@@ -66,12 +87,12 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result.data, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error executing smart query '${queryId}': ${error.message}`,
+              text: formatError(error, `executing smart query '${queryId}'`),
             },
           ],
           isError: true,

package/src/tools/structures.ts

@@ -2,6 +2,27 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import { z } from "zod";
 
+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)}`;
+}
+
 export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "list_structures",
@@ -18,12 +39,12 @@ export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result.data, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error listing structures: ${error.message}`,
+              text: formatError(error, "listing structures"),
             },
           ],
           isError: true,
@@ -48,12 +69,12 @@ export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result.data, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error getting structure '${recordSlug}': ${error.message}`,
+              text: formatError(error, `getting structure '${recordSlug}'`),
             },
           ],
           isError: true,

package/src/tools/validation.ts

@@ -0,0 +1,193 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK, ListValidationSuggestionsOptions } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+
+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)}`;
+}
+
+export function registerValidationTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "trigger_validation_scan",
+    "Trigger an AI-powered data quality scan on a structure. 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.",
+    {
+      structureSlug: z.string().describe("The structure's record slug to scan"),
+      validationTypes: z
+        .array(z.enum(["typo", "format", "duplicate", "semantic", "type"]))
+        .optional()
+        .describe("Specific validation types to run. If omitted, all types are run."),
+    },
+    async ({ structureSlug, validationTypes }) => {
+      try {
+        const options = validationTypes ? { validationTypes } : undefined;
+        const result = await sdk.validation.triggerScan(structureSlug, options);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(
+                error,
+                `triggering validation scan for '${structureSlug}'`
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "list_validation_suggestions",
+    "List data quality suggestions generated by validation scans. Each suggestion identifies an issue in a record and proposes a fix.",
+    {
+      structureSlug: z
+        .string()
+        .optional()
+        .describe("Filter suggestions to a specific structure"),
+      status: z
+        .enum(["pending", "accepted", "rejected", "auto-applied"])
+        .optional()
+        .describe("Filter by suggestion status (default: all)"),
+      issueType: z
+        .enum(["typo", "format", "duplicate", "semantic", "type"])
+        .optional()
+        .describe("Filter by issue type"),
+      minConfidence: z
+        .number()
+        .optional()
+        .describe(
+          "Minimum confidence score (0-1). Use 0.9 for high-confidence suggestions only."
+        ),
+    },
+    async ({ structureSlug, status, issueType, minConfidence }) => {
+      try {
+        const options: ListValidationSuggestionsOptions = {};
+        if (structureSlug) options.structureSlug = structureSlug;
+        if (status) options.status = status;
+        if (issueType) options.issueType = issueType;
+        if (minConfidence !== undefined) options.minConfidence = minConfidence;
+
+        const result = await sdk.validation.listSuggestions(
+          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 validation suggestions"),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_validation_summary",
+    "Get a summary of data quality across the workspace — counts of pending, accepted, and rejected suggestions. Optionally filter by structure.",
+    {
+      structureSlug: z
+        .string()
+        .optional()
+        .describe(
+          "Filter summary to a specific structure. If omitted, returns workspace-wide summary."
+        ),
+    },
+    async ({ structureSlug }) => {
+      try {
+        const result = await sdk.validation.getSummary(structureSlug);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, "getting validation summary") },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "accept_validation_suggestion",
+    "Accept a data quality suggestion and apply the fix to the record. The suggested correction is written to the record automatically.",
+    {
+      suggestionId: z.string().describe("The suggestion ID (UUID) to accept"),
+    },
+    async ({ suggestionId }) => {
+      try {
+        const result = await sdk.validation.accept(suggestionId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `accepting suggestion '${suggestionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "reject_validation_suggestion",
+    "Reject a data quality suggestion, marking it as incorrect or not applicable. The record is left unchanged.",
+    {
+      suggestionId: z.string().describe("The suggestion ID (UUID) to reject"),
+    },
+    async ({ suggestionId }) => {
+      try {
+        const result = await sdk.validation.reject(suggestionId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `rejecting suggestion '${suggestionId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}