@centrali-io/centrali-mcp 5.2.0 → 5.4.0

package/src/tools/service-accounts.ts

@@ -2,7 +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";
-
+import { registerTool, formatError } from "./_register.js";
 /**
  * Ensures the SDK has a valid token by making a lightweight SDK call if needed.
  */
@@ -62,22 +62,6 @@ function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: str
   return client;
 }
 
-function formatError(error: unknown, context: string): string {
-  if (error && typeof error === "object") {
-    const e = error as Record<string, any>;
-    if (e.response?.data) {
-      const d = e.response.data;
-      const code = d.code ?? d.error?.code ?? e.response.status ?? "ERROR";
-      const message = d.message ?? d.error?.message ?? JSON.stringify(d);
-      return `Error ${context}: [${code}] ${message}`;
-    }
-    if ("message" in e) {
-      return `Error ${context}: ${e.message}`;
-    }
-  }
-  return `Error ${context}: ${error instanceof Error ? error.message : String(error)}`;
-}
-
 export interface CurrentIdentityContext {
   clientId?: string;
   userId?: string;
@@ -99,7 +83,7 @@ export function registerServiceAccountTools(
 
   // ── Identity ─────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "get_current_identity",
     "Get the current authenticated MCP identity. In stdio/service-account mode, returns the MCP service account. In hosted OAuth mode, fetches the authenticated user's profile, roles, and groups from IAM.",
     {},
@@ -178,7 +162,7 @@ export function registerServiceAccountTools(
 
   // ── Service Account CRUD ─────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_service_accounts",
     "List all service accounts in the workspace. Service accounts are machine identities used for backend-to-backend API access (client_credentials flow).",
     {
@@ -203,7 +187,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_service_account",
     "Get details of a specific service account by its numeric ID. Returns name, clientId, description, and revocation status. Does NOT return the clientSecret (it's only shown once at creation time).",
     {
@@ -224,7 +208,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_service_account",
     "Create a new service account (machine identity). Returns the clientId and clientSecret — the secret is ONLY shown once, so store it securely. Use the credentials with OAuth2 client_credentials flow to get access tokens.",
     {
@@ -258,7 +242,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_service_account_name",
     "Update the display name of a service account.",
     {
@@ -280,7 +264,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_service_account_description",
     "Update the description of a service account.",
     {
@@ -302,7 +286,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_service_account",
     "Permanently delete a service account. This is irreversible — all tokens are invalidated immediately. Note: the service account must not be revoked (revoke prevents deletion).",
     {
@@ -325,7 +309,7 @@ export function registerServiceAccountTools(
 
   // ── Secret Rotation & Revocation ─────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "rotate_service_account_secret",
     "Rotate the client secret of a service account. The old secret is immediately invalidated. Returns the new clientSecret — store it securely, it's only shown once.",
     {
@@ -356,7 +340,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "revoke_service_account",
     "Revoke a service account. All existing tokens are invalidated and no new tokens can be issued. This cannot be undone.",
     {
@@ -379,7 +363,7 @@ export function registerServiceAccountTools(
 
   // ── Dev Token Generation ─────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "generate_dev_token",
     "Generate a short-lived development token for a service account. Useful for testing and local development without the full OAuth2 client_credentials flow. The token has limited TTL.",
     {
@@ -413,7 +397,7 @@ export function registerServiceAccountTools(
 
   // ── Permission Introspection ─────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "scan_service_account_permissions",
     "Scan all permissions for a service account. Returns a full access matrix showing every resource and action with Allow/Deny decisions and reasons. Use this to audit what a service account can and cannot do.",
     {
@@ -439,7 +423,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "simulate_service_account_permission",
     "Simulate an authorization check for a service account against a specific resource and action. Returns the decision (Allow/Deny), evaluation trace, and suggestions for granting access if denied.",
     {
@@ -490,7 +474,7 @@ export function registerServiceAccountTools(
     })),
   }).describe("The remediation option object from generate_remediation — pass the full option object exactly as returned");
 
-  server.tool(
+  registerTool<any>(server, 
     "generate_remediation",
     "Generate remediation options for granting a service account access to a specific resource and actions. Returns multiple options: assign an existing role, join a group, or create a minimal new policy. Use after scan_service_account_permissions or simulate_service_account_permission shows Deny.",
     {
@@ -520,7 +504,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "preview_remediation",
     "Preview what changes would be made by applying a specific remediation option. Shows what would be created or modified without actually making changes. Call generate_remediation first to get the options.",
     {
@@ -553,7 +537,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "apply_remediation",
     "Apply a remediation option to actually grant access. Creates roles, policies, or group assignments as needed. After applying, the service account will have the requested permissions. The response includes a verification check confirming the access was granted.",
     {
@@ -589,7 +573,7 @@ export function registerServiceAccountTools(
 
   // ── Service Account ↔ Roles ──────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_service_account_roles",
     "List all roles assigned to a service account.",
     {
@@ -610,7 +594,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "assign_role_to_service_account",
     "Assign a role to a service account. The service account inherits all permissions defined in the role.",
     {
@@ -632,7 +616,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "remove_role_from_service_account",
     "Remove a role from a service account. The service account loses all permissions from this role.",
     {
@@ -656,7 +640,7 @@ export function registerServiceAccountTools(
 
   // ── Service Account ↔ Groups ─────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_service_account_groups",
     "List all groups a service account belongs to.",
     {
@@ -677,7 +661,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "add_service_account_to_group",
     "Add a service account to a group. The service account inherits all roles assigned to the group.",
     {
@@ -699,7 +683,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "remove_service_account_from_group",
     "Remove a service account from a group. The service account loses all permissions inherited through this group.",
     {
@@ -723,7 +707,7 @@ export function registerServiceAccountTools(
 
   // ── Role CRUD ────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_roles",
     "List all roles in the workspace. Roles are named labels assigned to users and service accounts.",
     {
@@ -748,7 +732,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_role",
     "Get details of a role including its permissions.",
     {
@@ -769,7 +753,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_role",
     "Create a new role. Roles are named labels assigned to users and service accounts. They do NOT contain permissions directly — to grant access, create a policy that targets the role as a principal. Role names are immutable after creation.",
     {
@@ -793,7 +777,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_role",
     "Update a role's description. Role names are immutable. Roles are named labels assigned to users/service accounts — they do NOT contain permissions directly. To grant access, create a policy that references the role.",
     {
@@ -817,7 +801,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_role",
     "Delete a role. Service accounts assigned to this role will lose the label.",
     {
@@ -840,7 +824,7 @@ export function registerServiceAccountTools(
 
   // ── Group CRUD ───────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_groups",
     "List all groups in the workspace. Groups bundle service accounts together and can have roles assigned to them.",
     {
@@ -865,7 +849,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_group",
     "Get details of a group.",
     {
@@ -886,7 +870,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_group",
     "Create a new group. Groups let you assign roles to multiple service accounts at once.",
     {
@@ -910,7 +894,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_group",
     "Update a group's description. Group names are immutable and cannot be changed after creation.",
     {
@@ -934,7 +918,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_group",
     "Delete a group. Service accounts in this group lose permissions inherited through it.",
     {
@@ -959,7 +943,7 @@ export function registerServiceAccountTools(
 
   const getPkClient = () => createIamClient(sdk, centraliUrl, workspaceId, "publishable-keys");
 
-  server.tool(
+  registerTool<any>(server, 
     "list_publishable_keys",
     "List all publishable keys in the workspace. Publishable keys are frontend-safe API keys for browser/client-side apps — they grant scoped, read-mostly access to specific collections, records, triggers, and files.",
     {
@@ -984,7 +968,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_publishable_key",
     "Get details of a publishable key including its scopes and usage stats.",
     {
@@ -1005,7 +989,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_publishable_key",
     "Create a publishable key for frontend/client-side use. Returns the full key value (pk_live_...) — it's safe to embed in client code but only shown in full once. Scopes control what the key can access. Always use least-privilege: only grant the specific collections, actions, and triggers the frontend needs.",
     {
@@ -1037,7 +1021,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_publishable_key",
     "Update a publishable key's label or scopes. When updating scopes, the new scopes replace all existing ones.",
     {
@@ -1063,7 +1047,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "revoke_publishable_key",
     "Revoke a publishable key. The key immediately stops working. This cannot be undone — create a new key if needed.",
     {
@@ -1092,7 +1076,7 @@ export function registerServiceAccountTools(
   const getPermissionsClient = () => createIamClient(sdk, centraliUrl, workspaceId, "access/permissions");
   const getResourcesClient = () => createIamClient(sdk, centraliUrl, workspaceId, "access/resources");
 
-  server.tool(
+  registerTool<any>(server, 
     "list_policies",
     "List all access control policies in the workspace. Policies define who can do what — they bind roles/groups/principals to permissions with optional conditions.",
     {
@@ -1112,7 +1096,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_policy",
     "Get the full definition of an access control policy by ID.",
     {
@@ -1128,7 +1112,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_policy",
     "Create an access control policy. Policies grant or deny actions on resources to principals (users, service accounts, groups, roles).",
     {
@@ -1144,7 +1128,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_policy",
     "Update an existing access control policy by ID.",
     {
@@ -1161,7 +1145,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_policy",
     "Delete an access control policy by ID. This immediately revokes the access it granted. Use this to undo apply_remediation.",
     {
@@ -1179,7 +1163,7 @@ export function registerServiceAccountTools(
 
   // ── Permissions CRUD ───────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_permissions",
     "List all permission definitions in the workspace. Permissions are resource + action pairs (e.g., 'workspace::records' + 'create').",
     {
@@ -1199,7 +1183,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_permission",
     "Create a new permission definition. Permissions bind actions to a resource within a policy. Required fields: name, resourceId (UUID from list_resources), actions (string array), policyId (UUID from list_policies or create_policy).",
     {
@@ -1215,7 +1199,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_permission",
     "Delete a permission definition by ID.",
     {
@@ -1233,7 +1217,7 @@ export function registerServiceAccountTools(
 
   // ── Resources ──────────────────────────────────────────────────────
 
-  server.tool(
+  registerTool<any>(server, 
     "list_resources",
     "List all protected resource definitions in the workspace. Resources are the things permissions act on (e.g., 'workspace::records', 'workspace::functions').",
     {
@@ -1253,7 +1237,7 @@ export function registerServiceAccountTools(
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_resource",
     "Get details of a protected resource definition by ID.",
     {

package/src/tools/smart-queries.ts

@@ -1,30 +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 registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<any>(server, 
     "list_smart_queries",
     "List smart queries. Smart queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by collection record slug.",
     {
@@ -59,7 +38,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "execute_smart_query",
     "Execute a smart query by ID and return the results. Smart queries can have parameterized variables using {{variableName}} syntax.",
     {
@@ -101,7 +80,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_smart_query",
     "Get a smart query by ID. Returns the full query definition including filters, sort, and variable declarations.",
     {
@@ -130,7 +109,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_smart_query",
     "Create a new smart query for a collection. Smart queries are reusable, parameterized queries with filter, sort, and variable support.",
     {
@@ -166,7 +145,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_smart_query",
     "Update an existing smart query. Only include the fields you want to change.",
     {
@@ -206,7 +185,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_smart_query",
     "Delete a smart query by ID.",
     {
@@ -238,7 +217,7 @@ export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "test_smart_query",
     "Test execute a query definition without saving it. Useful for validating query syntax and previewing results before creating a smart query.",
     {

package/src/tools/structures.ts

@@ -2,45 +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 (e.response?.data) {
-      const d = e.response.data;
-      const code = d.code ?? d.errorCode ?? d.error?.code ?? e.response.status ?? "ERROR";
-      const message = d.message ?? d.error?.message ?? JSON.stringify(d);
-      let msg = `Error ${context}: [${code}] ${message}`;
-      // Include extra context from error response (e.g. classification details)
-      if (d.classification) {
-        msg += `\nClassification: ${JSON.stringify(d.classification)}`;
-      }
-      if (d.criticalChanges) {
-        msg += `\nCritical changes: ${JSON.stringify(d.criticalChanges)}`;
-      }
-      if (d.suggestion) {
-        msg += `\nSuggestion: ${d.suggestion}`;
-      }
-      return msg;
-    }
-    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.
  */
@@ -99,7 +61,7 @@ function createDataClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: st
 }
 
 export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
-  server.tool(
+  registerTool<any>(server, 
     "list_structures",
     "[DEPRECATED: use list_collections instead] List all data structures (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each structure.",
     {
@@ -128,7 +90,7 @@ export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_structure",
     "[DEPRECATED: use get_collection instead] Get the full schema definition for a specific structure by its record slug. Returns properties, types, constraints, and configuration.",
     {
@@ -162,7 +124,7 @@ export function registerStructureTools(server: McpServer, sdk: CentraliSDK) {
 export function registerCollectionTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string) {
   const getCollectionsClient = () => createDataClient(sdk, centraliUrl, workspaceId, "collections");
 
-  server.tool(
+  registerTool<any>(server, 
     "list_collections",
     "List all data collections (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each collection.",
     {
@@ -191,7 +153,7 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK, cen
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_collection",
     "Get the full schema definition for a specific collection by its record slug. Returns properties, types, constraints, and configuration.",
     {
@@ -221,7 +183,7 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK, cen
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "create_collection",
     "Create a new data collection (schema). Define the name, recordSlug, description, and properties (fields) for the collection.",
     {
@@ -283,7 +245,7 @@ export function registerCollectionTools(server: McpServer, sdk: CentraliSDK, cen
   // update_collection handles everything automatically. For breaking or
   // critical changes, analyze first to understand what's needed.
 
-  server.tool(
+  registerTool<any>(server, 
     "analyze_collection_update",
     `Analyze proposed schema changes BEFORE applying them. Returns whether migration is needed, what changes are breaking/critical, suggested fixes, and estimated duration.
 
@@ -351,7 +313,7 @@ RESPONSE FIELDS:
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "preview_collection_migration",
     `Preview the effect of migration fixes on sample records BEFORE applying them. Shows before/after snapshots so you can verify fixes are correct.
 
@@ -382,7 +344,7 @@ WHEN TO USE: After analyze_collection_update returns suggestedFixes, call this t
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "update_collection",
     `Update a collection's schema using the safe upgrade endpoint. This handles both simple updates and complex migrations.
 
@@ -487,7 +449,7 @@ Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAl
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "get_collection_upgrade_progress",
     "Check the progress of an async collection migration/upgrade job. Call this after update_collection returns status='in_progress'.",
     {
@@ -510,7 +472,7 @@ Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAl
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "delete_collection",
     "Delete a collection by ID. This permanently removes the collection schema and all its records.",
     {
@@ -541,7 +503,7 @@ Each fix is an object with: { fieldName, fixType, value?, expression?, applyToAl
     }
   );
 
-  server.tool(
+  registerTool<any>(server, 
     "explore_collections",
     "Get a compact overview of ALL collections in the workspace with their field names, types, and constraints. Returns everything in one call — no need to list collections and then get each one separately.",
     {