@centrali-io/centrali-mcp 5.2.0 → 5.3.0

package/src/tools/insights.ts

@@ -1,32 +1,18 @@
 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";
 
-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 InsightStatus = "active" | "acknowledged" | "dismissed";
+type InsightSeverity = "info" | "warning" | "critical";
 
 export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<{
+    recordSlug?: string;
+    status?: InsightStatus;
+    severity?: InsightSeverity;
+  }>(
+    server,
     "list_insights",
     "List anomaly insights detected by Centrali's AI analysis. Insights flag unusual patterns in your data such as spikes, drops, or outliers.",
     {
@@ -67,7 +53,8 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ insightId: string }>(
+    server,
     "get_insight",
     "Get full details of a single anomaly insight by ID.",
     {
@@ -90,7 +77,8 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ insightId: string }>(
+    server,
     "acknowledge_insight",
     "Mark an anomaly insight as acknowledged (reviewed/handled). The insight remains visible but is flagged as addressed.",
     {
@@ -116,7 +104,8 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ insightId: string }>(
+    server,
     "dismiss_insight",
     "Dismiss an anomaly insight, marking it as a false positive or not relevant.",
     {
@@ -139,7 +128,8 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ recordSlug?: string }>(
+    server,
     "get_insights_summary",
     "Get a summary of anomaly insights in the workspace — counts by status and severity. Optionally filter by collection.",
     {
@@ -167,7 +157,8 @@ export function registerInsightTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<{ recordSlug: string }>(
+    server,
     "trigger_anomaly_analysis",
     "Trigger AI-powered anomaly analysis for a collection. Starts a background analysis to detect unusual patterns. Check list_insights after the scan completes.",
     {

package/src/tools/orchestrations.ts

@@ -1,32 +1,9 @@
 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)}`;
-}
-
+import { registerTool, formatError } from "./_register.js";
 export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<any>(server, 
     "list_orchestrations",
     "List all orchestrations in the workspace. Orchestrations are multi-step workflows that chain compute functions together.",
     {
@@ -59,7 +36,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_orchestration",
     "Get full details of a single orchestration by ID, including its step definitions.",
     {
@@ -85,7 +62,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "trigger_orchestration",
     "Trigger an orchestration run. Creates a new run instance and starts executing the workflow. Optionally pass input data to the run.",
     {
@@ -126,7 +103,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "list_orchestration_runs",
     "List all runs for an orchestration. Runs represent individual executions of the workflow.",
     {
@@ -169,7 +146,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_orchestration_run",
     "Get details of a specific orchestration run. Set includeSteps=true to see step-by-step execution history.",
     {
@@ -207,7 +184,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_orchestration",
     "Create a new orchestration workflow. Orchestrations chain compute functions together in multi-step workflows.",
     {
@@ -244,7 +221,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_orchestration",
     "Update an existing orchestration by ID. Only include the fields you want to change.",
     {
@@ -291,7 +268,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_orchestration",
     "Delete an orchestration by ID. This also deletes all runs associated with the orchestration.",
     {
@@ -322,7 +299,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "activate_orchestration",
     "Activate an orchestration. Active orchestrations can be triggered by scheduled events, record events, and webhooks.",
     {
@@ -348,7 +325,7 @@ export function registerOrchestrationTools(server: McpServer, sdk: CentraliSDK)
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "pause_orchestration",
     "Pause an orchestration. Paused orchestrations cannot be triggered by any mechanism.",
     {

package/src/tools/pages.ts

@@ -1,30 +1,9 @@
 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";
 import axios, { AxiosInstance } from "axios";
 
-function formatError(error: unknown, context: string): string {
-  if (axios.isAxiosError(error) && error.response?.data) {
-    const body = error.response.data;
-    const status = error.response.status;
-    const message = body.message || body.error || error.message;
-    return `Error ${context}: [${status}] ${message}`;
-  }
-  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}`;
-      }
-      return msg;
-    }
-  }
-  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
-}
-
 /**
  * Derives the pages API base URL from the CENTRALI_URL.
  * Pattern: https://centrali.io -> https://api.centrali.io/pages
@@ -122,7 +101,7 @@ export function registerPageTools(
 
   // ── Page CRUD ──────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_pages",
     "List all pages in the workspace. Pages are pre-built UI views (lists, detail views, forms, dashboards) that surface data from collections.",
     {
@@ -153,7 +132,7 @@ export function registerPageTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_page",
     "Get a page by its ID. Returns the page metadata including name, slug, type, and description.",
     {
@@ -174,7 +153,7 @@ export function registerPageTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_page",
     `Create a new page in the workspace. A page is a UI view backed by data from collections. Specify the page type: 'list' for data tables, 'detail' for single-record views, 'form' for data entry, 'dashboard' for metrics and charts.
 
@@ -202,7 +181,7 @@ Navigate-to-page actions can use config.useQueryParams: true to pass selected ro
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_page",
     "Update a page's metadata (name, slug, description). Does not modify the page definition — use save_page_draft for that.",
     {
@@ -233,7 +212,7 @@ Navigate-to-page actions can use config.useQueryParams: true to pass selected ro
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_page",
     "Soft-delete a page by its ID. The page will no longer be accessible but can potentially be restored.",
     {
@@ -256,7 +235,7 @@ Navigate-to-page actions can use config.useQueryParams: true to pass selected ro
 
   // ── Drafts & Versions ─────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "save_page_draft",
     `Save or update the draft definition for a page. The definition describes the page's layout: sections, blocks, data sources, actions, and presentation. This does NOT publish the page — use publish_page after saving.
 
@@ -305,7 +284,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_page_draft",
     "Get the current draft version of a page, including its full definition (sections, blocks, data sources).",
     {
@@ -326,7 +305,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "list_page_versions",
     "List all versions of a page. Each version captures a snapshot of the page definition at a point in time.",
     {
@@ -355,7 +334,7 @@ Common patterns:
 
   // ── Publishing ────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "validate_page",
     "Run validation checks on a page's current draft to determine if it is ready to publish. Returns a list of issues (errors and warnings) that must be resolved before publishing.",
     {
@@ -376,7 +355,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "publish_page",
     "Publish the current draft of a page, making it accessible at its runtime URL. Validates the draft first — if there are errors, publishing is rejected with details. Returns the publication record and the public runtime URL.",
     {
@@ -397,7 +376,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "unpublish_page",
     "Unpublish a page, making it no longer accessible at its runtime URL. The page definition is preserved and can be re-published later.",
     {
@@ -420,7 +399,7 @@ Common patterns:
 
   // ── Access Policy ─────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "set_page_access_policy",
     "Set the access policy for a page. Controls who can view the published page: 'public' (anyone), 'authenticated' (logged-in users), or 'role-gated' (users with specific roles).",
     {
@@ -453,7 +432,7 @@ Common patterns:
 
   // ── Theme ─────────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_page_theme",
     "Get the workspace theme configuration used by published pages. Includes primary color, accent color, optional logo URL, and font family.",
     {},
@@ -472,7 +451,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "set_page_theme",
     "Set the workspace theme for published pages. Controls the visual branding of all published pages.",
     {
@@ -502,7 +481,7 @@ Common patterns:
 
   // ── Navigation ────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_navigation",
     "Get the workspace navigation configuration. Controls the sidebar/nav shell that wraps published pages.",
     {},
@@ -521,7 +500,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "set_navigation",
     "Set the workspace navigation configuration. Defines the sidebar items, branding, and grouping for the page navigation shell.",
     {
@@ -546,7 +525,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_navigation",
     "Delete the workspace navigation configuration. Pages revert to standalone rendering without a sidebar/nav shell.",
     {},
@@ -567,7 +546,7 @@ Common patterns:
 
   // ── Assembly (AI-assisted page generation) ────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "generate_starter_pages",
     "Generate page proposals from collection IDs. Uses guided assembly to create page definitions (list, detail, form, dashboard) tailored to the data schema. Returns proposals that can be reviewed and accepted.",
     {
@@ -597,7 +576,7 @@ Common patterns:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "accept_page_proposal",
     "Accept a generated page proposal and create the page with its initial draft definition. Use after reviewing proposals from generate_starter_pages.",
     {

package/src/tools/records.ts

@@ -2,28 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CentraliSDK } from "@centrali-io/centrali-sdk";
 import axios, { AxiosInstance } from "axios";
 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)}`;
-}
-
+import { registerTool, formatError } from "./_register.js";
 /**
  * Ensures the SDK has a valid token.
  */
@@ -82,7 +61,7 @@ function createRecordsClient(sdk: CentraliSDK, centraliUrl: string, workspaceId:
 }
 
 export function registerRecordTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
-  server.tool(
+  registerTool<any>(server, 
     "query_records",
     "Query records from a collection with optional filters, sorting, pagination, and date range filtering. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100). Use dateWindow for date range queries.",
     {
@@ -168,7 +147,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_record",
     "Get a single record by its ID from a collection. Optionally expand reference fields.",
     {
@@ -202,7 +181,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_record",
     "Create a new record in a collection. Pass the record data as a JSON object with field names matching the collection's properties.",
     {
@@ -235,7 +214,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_record",
     "Update an existing record by ID. Only include the fields you want to change.",
     {
@@ -267,7 +246,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_record",
     "Delete a record by ID. Performs a soft delete by default (can be restored). Set hard=true for permanent deletion.",
     {
@@ -307,7 +286,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "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'.",
     {
@@ -345,7 +324,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_records_by_ids",
     "Fetch multiple records by their IDs in a single request. Returns an array of records.",
     {
@@ -369,7 +348,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "restore_record",
     "Restore a soft-deleted record by ID. Only works on records deleted without hard=true.",
     {
@@ -397,7 +376,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
 
   // ── Bulk Operations (1 aggregate event per operation) ───────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "bulk_create_records",
     `Bulk create multiple records in a collection. All records are created in a single transaction. Publishes ONE aggregate 'records_bulk_created' event (not one per record). Use this when downstream triggers should process all records together as a batch. Max 1000 records per call. For individual events per record, use batch_create_records instead.`,
     {
@@ -422,7 +401,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "bulk_update_records",
     `Bulk update multiple records with the same data. All records are updated in a single transaction. Publishes ONE aggregate 'records_bulk_updated' event (not one per record). Use this when all records need the same change and downstream triggers should process them together. For different data per record or individual events, use batch_update_records instead.`,
     {
@@ -448,7 +427,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "bulk_delete_records",
     `Bulk delete multiple records. All records are deleted in a single transaction. Publishes ONE aggregate 'records_bulk_deleted' event (not one per record). Use this when downstream triggers should process all deletions together. For individual events per deletion, use batch_delete_records instead.`,
     {
@@ -485,7 +464,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
 
   // ── Batch Operations (1 event per record) ──────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "batch_create_records",
     `Create multiple records individually. Each record gets its own 'record_created' event. Use this when downstream triggers (functions, webhooks, orchestrations) should process each record separately. Supports partial failure — some records can succeed even if others fail. For a single aggregate event, use bulk_create_records instead.`,
     {
@@ -516,7 +495,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "batch_update_records",
     `Update multiple records individually with different data per record. Each record gets its own 'record_updated' event. Use this when each record needs different changes and downstream triggers should process each update separately. For the same change applied to all records with a single event, use bulk_update_records instead.`,
     {
@@ -548,7 +527,7 @@ export function registerRecordTools(server: McpServer, sdk: CentraliSDK, central
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "batch_delete_records",
     `Delete multiple records individually. Each record gets its own 'record_deleted' event. Use this when downstream triggers should process each deletion separately. For a single aggregate event, use bulk_delete_records instead.`,
     {

package/src/tools/search.ts

@@ -1,30 +1,15 @@
 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)}`;
-}
+import { registerTool, formatError } from "./_register.js";
 
 export function registerSearchTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<{
+    query: string;
+    collections?: string | string[];
+    limit?: number;
+  }>(
+    server,
     "search_records",
     "Full-text search across records in the workspace. Powered by Meilisearch. Optionally filter by collection(s) and limit results.",
     {