@centrali-io/centrali-mcp 3.1.4 → 3.1.5

package/dist/tools/records.js

@@ -11,6 +11,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerRecordTools = registerRecordTools;
 const zod_1 = require("zod");
+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)}`;
+}
 function registerRecordTools(server, sdk) {
     server.tool("query_records", "Query records from a structure with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).", {
         recordSlug: zod_1.z
@@ -53,7 +75,7 @@ function registerRecordTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error querying records from '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `querying records from '${recordSlug}'`),
                     },
                 ],
                 isError: true,
@@ -82,7 +104,7 @@ function registerRecordTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error getting record '${id}' from '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `getting record '${id}' from '${recordSlug}'`),
                     },
                 ],
                 isError: true,
@@ -110,7 +132,7 @@ function registerRecordTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error creating record in '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `creating record in '${recordSlug}'`),
                     },
                 ],
                 isError: true,
@@ -137,7 +159,7 @@ function registerRecordTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error updating record '${id}' in '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `updating record '${id}' in '${recordSlug}'`),
                     },
                 ],
                 isError: true,
@@ -170,9 +192,78 @@ function registerRecordTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error deleting record '${id}' from '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `deleting record '${id}' from '${recordSlug}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("upsert_record", "Create or update a record atomically. Matches on the provided fields to find an existing record — updates it if found, creates it if not. Returns the record and whether it was 'created' or 'updated'.", {
+        recordSlug: zod_1.z.string().describe("The structure's record slug"),
+        match: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.any())
+            .describe("Fields to match on when looking for an existing record (e.g. { sku: 'WIDGET-001' })"),
+        data: zod_1.z
+            .record(zod_1.z.string(), zod_1.z.any())
+            .describe("Full record data to create or update with"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, match, data }) {
+        try {
+            const result = yield sdk.upsertRecord(recordSlug, { match, data });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ operation: result.operation, record: result.data }, null, 2),
                     },
                 ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    { type: "text", text: formatError(error, `upserting record in '${recordSlug}'`) },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("get_records_by_ids", "Fetch multiple records by their IDs in a single request. Returns an array of records.", {
+        recordSlug: zod_1.z.string().describe("The structure's record slug"),
+        ids: zod_1.z.array(zod_1.z.string()).describe("Array of record IDs (UUIDs) to fetch"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, ids }) {
+        try {
+            const result = yield sdk.getRecordsByIds(recordSlug, ids);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    { type: "text", text: formatError(error, `fetching records by IDs from '${recordSlug}'`) },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("restore_record", "Restore a soft-deleted record by ID. Only works on records deleted without hard=true.", {
+        recordSlug: zod_1.z.string().describe("The structure's record slug"),
+        id: zod_1.z.string().describe("The record ID (UUID) to restore"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug, id }) {
+        try {
+            yield sdk.restoreRecord(recordSlug, id);
+            return {
+                content: [
+                    { type: "text", text: `Record '${id}' restored in '${recordSlug}'.` },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    { type: "text", text: formatError(error, `restoring record '${id}' in '${recordSlug}'`) },
+                ],
                 isError: true,
             };
         }

package/dist/tools/search.js

@@ -11,6 +11,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSearchTools = registerSearchTools;
 const zod_1 = require("zod");
+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)}`;
+}
 function registerSearchTools(server, sdk) {
     server.tool("search_records", "Full-text search across records in the workspace. Powered by Meilisearch. Optionally filter by structure(s) and limit results.", {
         query: zod_1.z.string().describe("The search query string"),
@@ -41,7 +63,7 @@ function registerSearchTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error searching records: ${error.message}`,
+                        text: formatError(error, "searching records"),
                     },
                 ],
                 isError: true,

package/dist/tools/smart-queries.js

@@ -11,6 +11,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerSmartQueryTools = registerSmartQueryTools;
 const zod_1 = require("zod");
+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)}`;
+}
 function registerSmartQueryTools(server, sdk) {
     server.tool("list_smart_queries", "List smart queries. Smart queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by structure slug.", {
         recordSlug: zod_1.z
@@ -33,7 +55,7 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error listing smart queries: ${error.message}`,
+                        text: formatError(error, "listing smart queries"),
                     },
                 ],
                 isError: true,
@@ -64,7 +86,7 @@ function registerSmartQueryTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error executing smart query '${queryId}': ${error.message}`,
+                        text: formatError(error, `executing smart query '${queryId}'`),
                     },
                 ],
                 isError: true,

package/dist/tools/structures.js

@@ -11,6 +11,28 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerStructureTools = registerStructureTools;
 const zod_1 = require("zod");
+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)}`;
+}
 function registerStructureTools(server, sdk) {
     server.tool("list_structures", "List all data structures (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each structure.", {
         page: zod_1.z.number().optional().describe("Page number (1-indexed)"),
@@ -29,7 +51,7 @@ function registerStructureTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error listing structures: ${error.message}`,
+                        text: formatError(error, "listing structures"),
                     },
                 ],
                 isError: true,
@@ -54,7 +76,7 @@ function registerStructureTools(server, sdk) {
                 content: [
                     {
                         type: "text",
-                        text: `Error getting structure '${recordSlug}': ${error.message}`,
+                        text: formatError(error, `getting structure '${recordSlug}'`),
                     },
                 ],
                 isError: true,

package/dist/tools/validation.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+export declare function registerValidationTools(server: McpServer, sdk: CentraliSDK): void;

package/dist/tools/validation.js

@@ -0,0 +1,173 @@
+"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.registerValidationTools = registerValidationTools;
+const zod_1 = require("zod");
+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)}`;
+}
+function registerValidationTools(server, sdk) {
+    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: zod_1.z.string().describe("The structure's record slug to scan"),
+        validationTypes: zod_1.z
+            .array(zod_1.z.enum(["typo", "format", "duplicate", "semantic", "type"]))
+            .optional()
+            .describe("Specific validation types to run. If omitted, all types are run."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ structureSlug, validationTypes }) {
+        try {
+            const options = validationTypes ? { validationTypes } : undefined;
+            const result = yield sdk.validation.triggerScan(structureSlug, options);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            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: zod_1.z
+            .string()
+            .optional()
+            .describe("Filter suggestions to a specific structure"),
+        status: zod_1.z
+            .enum(["pending", "accepted", "rejected", "auto-applied"])
+            .optional()
+            .describe("Filter by suggestion status (default: all)"),
+        issueType: zod_1.z
+            .enum(["typo", "format", "duplicate", "semantic", "type"])
+            .optional()
+            .describe("Filter by issue type"),
+        minConfidence: zod_1.z
+            .number()
+            .optional()
+            .describe("Minimum confidence score (0-1). Use 0.9 for high-confidence suggestions only."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ structureSlug, status, issueType, minConfidence }) {
+        try {
+            const options = {};
+            if (structureSlug)
+                options.structureSlug = structureSlug;
+            if (status)
+                options.status = status;
+            if (issueType)
+                options.issueType = issueType;
+            if (minConfidence !== undefined)
+                options.minConfidence = minConfidence;
+            const result = yield sdk.validation.listSuggestions(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: 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: zod_1.z
+            .string()
+            .optional()
+            .describe("Filter summary to a specific structure. If omitted, returns workspace-wide summary."),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ structureSlug }) {
+        try {
+            const result = yield sdk.validation.getSummary(structureSlug);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            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: zod_1.z.string().describe("The suggestion ID (UUID) to accept"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ suggestionId }) {
+        try {
+            const result = yield sdk.validation.accept(suggestionId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            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: zod_1.z.string().describe("The suggestion ID (UUID) to reject"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ suggestionId }) {
+        try {
+            const result = yield sdk.validation.reject(suggestionId);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: formatError(error, `rejecting suggestion '${suggestionId}'`),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "3.1.4",
+  "version": "3.1.5",
   "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": "^3.1.0",
+    "@centrali-io/centrali-sdk": "^3.1.4",
     "@modelcontextprotocol/sdk": "^1.12.1"
   },
   "devDependencies": {

package/src/index.ts

@@ -8,6 +8,9 @@ import { registerRecordTools } from "./tools/records.js";
 import { registerSearchTools } from "./tools/search.js";
 import { registerComputeTools } from "./tools/compute.js";
 import { registerSmartQueryTools } from "./tools/smart-queries.js";
+import { registerOrchestrationTools } from "./tools/orchestrations.js";
+import { registerInsightTools } from "./tools/insights.js";
+import { registerValidationTools } from "./tools/validation.js";
 import { registerStructureResources } from "./resources/structures.js";
 
 function getRequiredEnv(name: string): string {
@@ -43,6 +46,9 @@ async function main() {
   registerSearchTools(server, sdk);
   registerComputeTools(server, sdk);
   registerSmartQueryTools(server, sdk);
+  registerOrchestrationTools(server, sdk);
+  registerInsightTools(server, sdk);
+  registerValidationTools(server, sdk);
 
   // Register resources
   registerStructureResources(server, sdk);

package/src/resources/structures.ts

@@ -1,6 +1,27 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 
+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 registerStructureResources(
   server: McpServer,
   sdk: CentraliSDK
@@ -15,23 +36,27 @@ export function registerStructureResources(
       mimeType: "application/json",
     },
     async (uri) => {
-      const result = await sdk.structures.list({ limit: 100 });
-      const summary = (result.data || []).map((s) => ({
-        name: s.name,
-        recordSlug: s.recordSlug,
-        description: s.description || "",
-        propertyCount: s.properties?.length || 0,
-        status: s.status,
-      }));
-      return {
-        contents: [
-          {
-            uri: uri.href,
-            mimeType: "application/json",
-            text: JSON.stringify(summary, null, 2),
-          },
-        ],
-      };
+      try {
+        const result = await sdk.structures.list({ limit: 100 });
+        const summary = (result.data || []).map((s) => ({
+          name: s.name,
+          recordSlug: s.recordSlug,
+          description: s.description || "",
+          propertyCount: s.properties?.length || 0,
+          status: s.status,
+        }));
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify(summary, null, 2),
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        throw new Error(formatError(error, "listing structures resource"));
+      }
     }
   );
 
@@ -40,15 +65,19 @@ export function registerStructureResources(
     "structure-schema",
     new ResourceTemplate("centrali://structures/{slug}", {
       list: async () => {
-        const result = await sdk.structures.list({ limit: 100 });
-        return {
-          resources: (result.data || []).map((s) => ({
-            uri: `centrali://structures/${s.recordSlug}`,
-            name: s.name,
-            description: s.description || `Schema for ${s.name}`,
-            mimeType: "application/json",
-          })),
-        };
+        try {
+          const result = await sdk.structures.list({ limit: 100 });
+          return {
+            resources: (result.data || []).map((s) => ({
+              uri: `centrali://structures/${s.recordSlug}`,
+              name: s.name,
+              description: s.description || `Schema for ${s.name}`,
+              mimeType: "application/json",
+            })),
+          };
+        } catch (error: unknown) {
+          throw new Error(formatError(error, "listing structure schemas"));
+        }
       },
     }),
     {
@@ -56,16 +85,20 @@ export function registerStructureResources(
       mimeType: "application/json",
     },
     async (uri, { slug }) => {
-      const result = await sdk.structures.getBySlug(slug as string);
-      return {
-        contents: [
-          {
-            uri: uri.href,
-            mimeType: "application/json",
-            text: JSON.stringify(result.data, null, 2),
-          },
-        ],
-      };
+      try {
+        const result = await sdk.structures.getBySlug(slug as string);
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify(result.data, null, 2),
+            },
+          ],
+        };
+      } catch (error: unknown) {
+        throw new Error(formatError(error, `getting structure schema for '${slug}'`));
+      }
     }
   );
 }