@centrali-io/centrali-mcp 3.1.4 → 3.1.5

package/src/tools/compute.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 registerComputeTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "list_functions",
@@ -24,12 +45,12 @@ export function registerComputeTools(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 functions: ${error.message}`,
+              text: formatError(error, "listing functions"),
             },
           ],
           isError: true,
@@ -64,12 +85,12 @@ export function registerComputeTools(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 triggers: ${error.message}`,
+              text: formatError(error, "listing triggers"),
             },
           ],
           isError: true,
@@ -104,12 +125,12 @@ export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
             },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error invoking trigger '${triggerId}': ${error.message}`,
+              text: formatError(error, `invoking trigger '${triggerId}'`),
             },
           ],
           isError: true,

package/src/tools/insights.ts

@@ -0,0 +1,198 @@
+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 registerInsightTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "list_insights",
+    "List anomaly insights detected by Centrali's AI analysis. Insights flag unusual patterns in your data such as spikes, drops, or outliers.",
+    {
+      structureSlug: z
+        .string()
+        .optional()
+        .describe(
+          "Filter insights by structure slug. If omitted, returns insights for all structures."
+        ),
+      status: z
+        .enum(["active", "acknowledged", "dismissed"])
+        .optional()
+        .describe("Filter by insight status"),
+      severity: z
+        .enum(["critical", "high", "medium", "low"])
+        .optional()
+        .describe("Filter by severity level"),
+    },
+    async ({ structureSlug, status, severity }) => {
+      try {
+        const options: Record<string, any> = {};
+        if (structureSlug) options.structureSlug = structureSlug;
+        if (status) options.status = status;
+        if (severity) options.severity = severity;
+
+        const result = await sdk.anomalyInsights.list(
+          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 insights") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_insight",
+    "Get full details of a single anomaly insight by ID.",
+    {
+      insightId: z.string().describe("The insight ID (UUID)"),
+    },
+    async ({ insightId }) => {
+      try {
+        const result = await sdk.anomalyInsights.get(insightId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, `getting insight '${insightId}'`) },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "acknowledge_insight",
+    "Mark an anomaly insight as acknowledged (reviewed/handled). The insight remains visible but is flagged as addressed.",
+    {
+      insightId: z.string().describe("The insight ID (UUID) to acknowledge"),
+    },
+    async ({ insightId }) => {
+      try {
+        const result = await sdk.anomalyInsights.acknowledge(insightId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `acknowledging insight '${insightId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "dismiss_insight",
+    "Dismiss an anomaly insight, marking it as a false positive or not relevant.",
+    {
+      insightId: z.string().describe("The insight ID (UUID) to dismiss"),
+    },
+    async ({ insightId }) => {
+      try {
+        const result = await sdk.anomalyInsights.dismiss(insightId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, `dismissing insight '${insightId}'`) },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_insights_summary",
+    "Get a summary of anomaly insights in the workspace — counts by status and severity. 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.anomalyInsights.getSummary(structureSlug);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, "getting insights summary") },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "trigger_anomaly_analysis",
+    "Trigger AI-powered anomaly analysis for a structure. Starts a background analysis to detect unusual patterns. Check list_insights after the scan completes.",
+    {
+      structureSlug: z.string().describe("The structure's record slug to analyze"),
+    },
+    async ({ structureSlug }) => {
+      try {
+        const result = await sdk.anomalyInsights.triggerAnalysis(structureSlug);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(
+                error,
+                `triggering anomaly analysis for '${structureSlug}'`
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/orchestrations.ts

@@ -0,0 +1,209 @@
+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 registerOrchestrationTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "list_orchestrations",
+    "List all orchestrations in the workspace. Orchestrations are multi-step workflows that chain compute functions together.",
+    {
+      offset: z.number().optional().describe("Number of results to skip (for pagination)"),
+      limit: z.number().optional().describe("Results per page"),
+      status: z
+        .enum(["draft", "active", "paused"])
+        .optional()
+        .describe("Filter by orchestration status"),
+    },
+    async ({ offset, limit, status }) => {
+      try {
+        const options: Record<string, any> = {};
+        if (offset !== undefined) options.offset = offset;
+        if (limit !== undefined) options.limit = limit;
+        if (status) options.status = status;
+
+        const result = await sdk.orchestrations.list(
+          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 orchestrations") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_orchestration",
+    "Get full details of a single orchestration by ID, including its step definitions.",
+    {
+      orchestrationId: z.string().describe("The orchestration ID (UUID)"),
+    },
+    async ({ orchestrationId }) => {
+      try {
+        const result = await sdk.orchestrations.get(orchestrationId);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(error, `getting orchestration '${orchestrationId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "trigger_orchestration",
+    "Trigger an orchestration run. Creates a new run instance and starts executing the workflow. Optionally pass input data to the run.",
+    {
+      orchestrationId: z.string().describe("The orchestration ID (UUID) to trigger"),
+      input: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe("Input data passed to the first step of the orchestration"),
+      correlationId: z
+        .string()
+        .optional()
+        .describe("Optional correlation ID for tracing this run"),
+    },
+    async ({ orchestrationId, input, correlationId }) => {
+      try {
+        const options: { input?: Record<string, any>; correlationId?: string } = {};
+        if (input) options.input = input;
+        if (correlationId) options.correlationId = correlationId;
+
+        const result = await sdk.orchestrations.trigger(
+          orchestrationId,
+          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, `triggering orchestration '${orchestrationId}'`),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "list_orchestration_runs",
+    "List all runs for an orchestration. Runs represent individual executions of the workflow.",
+    {
+      orchestrationId: z.string().describe("The orchestration ID (UUID)"),
+      offset: z.number().optional().describe("Number of results to skip (for pagination)"),
+      limit: z.number().optional().describe("Results per page"),
+      status: z
+        .enum(["pending", "running", "waiting", "completed", "failed"])
+        .optional()
+        .describe("Filter by run status"),
+    },
+    async ({ orchestrationId, offset, limit, status }) => {
+      try {
+        const options: Record<string, any> = {};
+        if (offset !== undefined) options.offset = offset;
+        if (limit !== undefined) options.limit = limit;
+        if (status) options.status = status;
+
+        const result = await sdk.orchestrations.listRuns(
+          orchestrationId,
+          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 runs for orchestration '${orchestrationId}'`
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_orchestration_run",
+    "Get details of a specific orchestration run. Set includeSteps=true to see step-by-step execution history.",
+    {
+      orchestrationId: z.string().describe("The orchestration ID (UUID)"),
+      runId: z.string().describe("The run ID (UUID)"),
+      includeSteps: z
+        .boolean()
+        .optional()
+        .describe("Include step execution history in the response (default: false)"),
+    },
+    async ({ orchestrationId, runId, includeSteps }) => {
+      try {
+        const result = await sdk.orchestrations.getRun(
+          orchestrationId,
+          runId,
+          includeSteps
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: formatError(
+                error,
+                `getting run '${runId}' for orchestration '${orchestrationId}'`
+              ),
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/records.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 registerRecordTools(server: McpServer, sdk: CentraliSDK) {
   server.tool(
     "query_records",
@@ -54,12 +75,12 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK) {
             { type: "text", text: JSON.stringify(result, null, 2) },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
         return {
           content: [
             {
               type: "text",
-              text: `Error querying records from '${recordSlug}': ${error.message}`,
+              text: formatError(error, `querying records from '${recordSlug}'`),
             },
           ],
           isError: true,
@@ -88,12 +109,12 @@ export function registerRecordTools(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 record '${id}' from '${recordSlug}': ${error.message}`,
+              text: formatError(error, `getting record '${id}' from '${recordSlug}'`),
             },
           ],
           isError: true,
@@ -121,12 +142,12 @@ export function registerRecordTools(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 creating record in '${recordSlug}': ${error.message}`,
+              text: formatError(error, `creating record in '${recordSlug}'`),
             },
           ],
           isError: true,
@@ -153,12 +174,12 @@ export function registerRecordTools(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 updating record '${id}' in '${recordSlug}': ${error.message}`,
+              text: formatError(error, `updating record '${id}' in '${recordSlug}'`),
             },
           ],
           isError: true,
@@ -193,14 +214,102 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK) {
             },
           ],
         };
-      } catch (error: any) {
+      } catch (error: unknown) {
+        return {
+          content: [
+            {
+              type: "text",
+              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: z.string().describe("The structure's record slug"),
+      match: z
+        .record(z.string(), z.any())
+        .describe("Fields to match on when looking for an existing record (e.g. { sku: 'WIDGET-001' })"),
+      data: z
+        .record(z.string(), z.any())
+        .describe("Full record data to create or update with"),
+    },
+    async ({ recordSlug, match, data }) => {
+      try {
+        const result = await sdk.upsertRecord(recordSlug, { match, data });
         return {
           content: [
             {
               type: "text",
-              text: `Error deleting record '${id}' from '${recordSlug}': ${error.message}`,
+              text: JSON.stringify(
+                { operation: result.operation, record: result.data },
+                null,
+                2
+              ),
             },
           ],
+        };
+      } catch (error: unknown) {
+        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: z.string().describe("The structure's record slug"),
+      ids: z.array(z.string()).describe("Array of record IDs (UUIDs) to fetch"),
+    },
+    async ({ recordSlug, ids }) => {
+      try {
+        const result = await sdk.getRecordsByIds(recordSlug, ids);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        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: z.string().describe("The structure's record slug"),
+      id: z.string().describe("The record ID (UUID) to restore"),
+    },
+    async ({ recordSlug, id }) => {
+      try {
+        await sdk.restoreRecord(recordSlug, id);
+        return {
+          content: [
+            { type: "text", text: `Record '${id}' restored in '${recordSlug}'.` },
+          ],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [
+            { type: "text", text: formatError(error, `restoring record '${id}' in '${recordSlug}'`) },
+          ],
           isError: true,
         };
       }