@centrali-io/centrali-mcp 4.4.5 → 4.4.6

package/src/tools/service-accounts.ts

@@ -0,0 +1,1051 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import axios, { AxiosInstance } from "axios";
+import { z } from "zod";
+
+/**
+ * Ensures the SDK has a valid token by making a lightweight SDK call if needed.
+ */
+async function ensureToken(sdk: CentraliSDK): Promise<string | null> {
+  let token = sdk.getToken();
+  if (token) return token;
+  try {
+    await sdk.functions.list({ limit: 1 });
+  } catch {
+    // Ignore — we only need the token refresh side effect
+  }
+  return sdk.getToken();
+}
+
+/**
+ * Creates an axios instance for the IAM service account API.
+ */
+function createIamClient(sdk: CentraliSDK, centraliUrl: string, workspaceId: string, baseSuffix: string): AxiosInstance {
+  const url = new URL(centraliUrl);
+  const hostname = url.hostname.startsWith("api.")
+    ? url.hostname
+    : `api.${url.hostname}`;
+  const baseURL = `${url.protocol}//${hostname}/iam/workspace/${workspaceId}/api/v1/${baseSuffix}`;
+
+  const client = axios.create({ baseURL });
+
+  client.interceptors.request.use(async (config) => {
+    const token = await ensureToken(sdk);
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+    return config;
+  });
+
+  client.interceptors.response.use(
+    (response) => response,
+    async (error) => {
+      const originalRequest = error.config;
+      const isAuthError = error.response?.status === 401 || error.response?.status === 403;
+
+      if (isAuthError && !originalRequest._hasRetried) {
+        originalRequest._hasRetried = true;
+        try {
+          await sdk.functions.list({ limit: 1 });
+        } catch { /* token refresh side effect */ }
+
+        const token = sdk.getToken();
+        if (token) {
+          originalRequest.headers.Authorization = `Bearer ${token}`;
+          return client.request(originalRequest);
+        }
+      }
+      return Promise.reject(error);
+    }
+  );
+
+  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 function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK, centraliUrl: string, workspaceId: string, ownClientId?: string) {
+  const getSaClient = () => createIamClient(sdk, centraliUrl, workspaceId, "service-accounts");
+  const getRolesClient = () => createIamClient(sdk, centraliUrl, workspaceId, "roles");
+  const getGroupsClient = () => createIamClient(sdk, centraliUrl, workspaceId, "groups");
+
+  // ── Identity ─────────────────────────────────────────────────────
+
+  server.tool(
+    "get_current_identity",
+    "Get the current MCP service account's identity — its numeric ID, clientId, name, roles, and groups. Call this first when you need to check or fix your own permissions (e.g., after a 403 error). Returns the SA details needed for scan_service_account_permissions and generate_remediation.",
+    {},
+    async () => {
+      try {
+        const result = await getSaClient().get("/", { params: { pageSize: 100 } });
+        const accounts = result.data?.data ?? result.data ?? [];
+        const me = Array.isArray(accounts)
+          ? accounts.find((sa: any) => sa.clientId === ownClientId)
+          : null;
+
+        if (!me) {
+          return {
+            content: [{
+              type: "text",
+              text: JSON.stringify({
+                error: "Could not identify current service account",
+                clientId: ownClientId,
+                hint: "The service account may not have permission to list service accounts, or the clientId doesn't match any SA in this workspace.",
+              }, null, 2),
+            }],
+            isError: true,
+          };
+        }
+
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              id: me.id,
+              clientId: me.clientId,
+              name: me.name,
+              description: me.description,
+              revoked: me.revoked,
+              _hint: "Use this 'id' (numeric) with scan_service_account_permissions, simulate_service_account_permission, and generate_remediation to check or fix your own permissions.",
+            }, null, 2),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "getting current identity") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Service Account CRUD ─────────────────────────────────────────
+
+  server.tool(
+    "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).",
+    {
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Results per page (default: 20)"),
+    },
+    async ({ page, pageSize }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+        const result = await getSaClient().get("/", { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing service accounts") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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).",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        const result = await getSaClient().get(`/${serviceAccountId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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.",
+    {
+      name: z.string().describe("Display name for the service account (e.g., 'CI/CD Pipeline', 'Analytics Worker')"),
+      description: z.string().optional().describe("Optional description of what this service account is used for"),
+    },
+    async ({ name, description }) => {
+      try {
+        const input: Record<string, any> = { name };
+        if (description !== undefined) input.description = description;
+        const result = await getSaClient().post("/", input);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              {
+                ...result.data,
+                _warning: "IMPORTANT: The clientSecret is only shown once. Store it securely now — it cannot be retrieved later. Use rotate_service_account_secret to generate a new one if lost.",
+              },
+              null,
+              2
+            ),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `creating service account '${name}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_service_account_name",
+    "Update the display name of a service account.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      name: z.string().describe("New display name"),
+    },
+    async ({ serviceAccountId, name }) => {
+      try {
+        const result = await getSaClient().put(`/${serviceAccountId}/name`, { name });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating service account '${serviceAccountId}' name`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_service_account_description",
+    "Update the description of a service account.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      description: z.string().nullable().describe("New description (or null to clear)"),
+    },
+    async ({ serviceAccountId, description }) => {
+      try {
+        const result = await getSaClient().put(`/${serviceAccountId}/description`, { description });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating service account '${serviceAccountId}' description`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_service_account",
+    "Permanently delete a service account. This is irreversible — all tokens are invalidated immediately.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID to delete"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        await getSaClient().delete(`/${serviceAccountId}`);
+        return {
+          content: [{ type: "text", text: `Service account '${serviceAccountId}' deleted successfully.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `deleting service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Secret Rotation & Revocation ─────────────────────────────────
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/rotate`);
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              {
+                ...result.data,
+                _warning: "The old secret is now invalid. Store the new clientSecret securely — it cannot be retrieved later.",
+              },
+              null,
+              2
+            ),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `rotating secret for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "revoke_service_account",
+    "Revoke a service account. All existing tokens are invalidated and no new tokens can be issued. This cannot be undone.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID to revoke"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/revoke`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `revoking service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Dev Token Generation ─────────────────────────────────────────
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      ttlSeconds: z.number().describe("Token time-to-live in seconds (valid options depend on server config, typically 3600, 86400, 604800)"),
+    },
+    async ({ serviceAccountId, ttlSeconds }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/dev-token`, { ttlSeconds });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              {
+                ...result.data,
+                _note: "This is a short-lived token for development. For production, use the OAuth2 client_credentials flow with the clientId and clientSecret.",
+              },
+              null,
+              2
+            ),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `generating dev token for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Permission Introspection ─────────────────────────────────────
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      filter: z.enum(["all", "allowed", "denied"]).optional().describe("Filter results: 'all' (default), 'allowed' (only granted), 'denied' (only missing)"),
+      resourceCategory: z.string().optional().describe("Filter by resource category (e.g., 'workspace')"),
+    },
+    async ({ serviceAccountId, filter, resourceCategory }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (filter) params.filter = filter;
+        if (resourceCategory) params.resourceCategory = resourceCategory;
+        const result = await getSaClient().get(`/${serviceAccountId}/permissions/scan`, { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `scanning permissions for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      resource: z.string().describe("Resource identifier (e.g., 'workspace::records', 'workspace::compute-functions')"),
+      resourceCategory: z.string().describe("Resource category (e.g., 'workspace')"),
+      action: z.string().describe("Action to check (e.g., 'create', 'retrieve', 'update', 'delete', 'list', 'execute', 'manage')"),
+    },
+    async ({ serviceAccountId, resource, resourceCategory, action }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/permissions/simulate`, {
+          resource,
+          resourceCategory,
+          action,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `simulating permission for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Permission Remediation ────────────────────────────────────────
+
+  const getAccessClient = () => createIamClient(sdk, centraliUrl, workspaceId, "access/permissions");
+
+  const RemediationOptionZod = z.object({
+    optionId: z.string(),
+    type: z.enum(["role_assignment", "group_assignment", "create_new"]),
+    description: z.string(),
+    effort: z.enum(["low", "medium", "high"]),
+    recommended: z.boolean().optional(),
+    steps: z.array(z.object({
+      step: z.number(),
+      action: z.enum(["assign_role", "assign_group", "create_policy", "create_permission"]),
+      details: z.record(z.string(), z.unknown()),
+      humanReadable: z.string(),
+    })),
+    sideEffects: z.array(z.object({
+      type: z.enum(["grants_additional_access", "adds_to_group", "creates_resource"]),
+      description: z.string(),
+      details: z.record(z.string(), z.unknown()).optional(),
+    })),
+  }).describe("The remediation option object from generate_remediation — pass the full option object exactly as returned");
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      resource: z.string().describe("Resource identifier (e.g., 'workspace::records', 'workspace::compute-functions')"),
+      resourceCategory: z.string().describe("Resource category (e.g., 'workspace')"),
+      actions: z.array(z.string()).describe("Actions to grant (e.g., ['create', 'retrieve', 'list'])"),
+    },
+    async ({ serviceAccountId, resource, resourceCategory, actions }) => {
+      try {
+        const result = await getAccessClient().post("/remediation/generate", {
+          targetType: "service_account",
+          targetId: serviceAccountId,
+          resource,
+          resourceCategory,
+          actions,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `generating remediation for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      resource: z.string().describe("Resource identifier (same as used in generate_remediation)"),
+      resourceCategory: z.string().describe("Resource category (same as used in generate_remediation)"),
+      actions: z.array(z.string()).describe("Actions (same as used in generate_remediation)"),
+      option: RemediationOptionZod,
+    },
+    async ({ serviceAccountId, resource, resourceCategory, actions, option }) => {
+      try {
+        const result = await getAccessClient().post("/remediation/preview", {
+          targetType: "service_account",
+          targetId: serviceAccountId,
+          resource,
+          resourceCategory,
+          actions,
+          optionId: option.optionId,
+          option,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `previewing remediation for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      resource: z.string().describe("Resource identifier (same as used in generate_remediation)"),
+      resourceCategory: z.string().describe("Resource category (same as used in generate_remediation)"),
+      actions: z.array(z.string()).describe("Actions (same as used in generate_remediation)"),
+      option: RemediationOptionZod,
+    },
+    async ({ serviceAccountId, resource, resourceCategory, actions, option }) => {
+      try {
+        const result = await getAccessClient().post("/remediation/apply", {
+          targetType: "service_account",
+          targetId: serviceAccountId,
+          resource,
+          resourceCategory,
+          actions,
+          optionId: option.optionId,
+          option,
+          dryRun: false,
+        });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `applying remediation for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Service Account ↔ Roles ──────────────────────────────────────
+
+  server.tool(
+    "list_service_account_roles",
+    "List all roles assigned to a service account.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        const result = await getSaClient().get(`/${serviceAccountId}/roles`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `listing roles for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "assign_role_to_service_account",
+    "Assign a role to a service account. The service account inherits all permissions defined in the role.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      roleId: z.string().describe("The role ID (UUID) to assign"),
+    },
+    async ({ serviceAccountId, roleId }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/roles/${roleId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `assigning role '${roleId}' to service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "remove_role_from_service_account",
+    "Remove a role from a service account. The service account loses all permissions from this role.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      roleId: z.string().describe("The role ID (UUID) to remove"),
+    },
+    async ({ serviceAccountId, roleId }) => {
+      try {
+        await getSaClient().delete(`/${serviceAccountId}/roles/${roleId}`);
+        return {
+          content: [{ type: "text", text: `Role '${roleId}' removed from service account '${serviceAccountId}'.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `removing role '${roleId}' from service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Service Account ↔ Groups ─────────────────────────────────────
+
+  server.tool(
+    "list_service_account_groups",
+    "List all groups a service account belongs to.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+    },
+    async ({ serviceAccountId }) => {
+      try {
+        const result = await getSaClient().get(`/${serviceAccountId}/groups`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `listing groups for service account '${serviceAccountId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "add_service_account_to_group",
+    "Add a service account to a group. The service account inherits all roles assigned to the group.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      groupId: z.string().describe("The group ID (UUID) to add the service account to"),
+    },
+    async ({ serviceAccountId, groupId }) => {
+      try {
+        const result = await getSaClient().post(`/${serviceAccountId}/groups/${groupId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `adding service account '${serviceAccountId}' to group '${groupId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "remove_service_account_from_group",
+    "Remove a service account from a group. The service account loses all permissions inherited through this group.",
+    {
+      serviceAccountId: z.number().describe("The service account numeric ID"),
+      groupId: z.string().describe("The group ID (UUID) to remove the service account from"),
+    },
+    async ({ serviceAccountId, groupId }) => {
+      try {
+        await getSaClient().delete(`/${serviceAccountId}/groups/${groupId}`);
+        return {
+          content: [{ type: "text", text: `Service account '${serviceAccountId}' removed from group '${groupId}'.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `removing service account '${serviceAccountId}' from group '${groupId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Role CRUD ────────────────────────────────────────────────────
+
+  server.tool(
+    "list_roles",
+    "List all roles in the workspace. Roles bundle permissions that can be assigned to service accounts or groups.",
+    {
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Results per page (default: 20)"),
+    },
+    async ({ page, pageSize }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+        const result = await getRolesClient().get("/", { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing roles") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_role",
+    "Get details of a role including its permissions.",
+    {
+      roleId: z.string().describe("The role ID (UUID)"),
+    },
+    async ({ roleId }) => {
+      try {
+        const result = await getRolesClient().get(`/${roleId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting role '${roleId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "create_role",
+    "Create a new role with a set of permissions. Permissions are UUIDs from the IAM permission registry. Use scan_service_account_permissions to discover available resource/action pairs.",
+    {
+      name: z.string().describe("Role name (e.g., 'Data Reader', 'Compute Admin')"),
+      description: z.string().optional().describe("Optional description of the role's purpose"),
+      permissions: z.array(z.string()).optional().describe("Array of permission UUIDs to include in this role"),
+    },
+    async ({ name, description, permissions }) => {
+      try {
+        const input: Record<string, any> = { name };
+        if (description !== undefined) input.description = description;
+        if (permissions !== undefined) input.permissions = permissions;
+        const result = await getRolesClient().post("/", input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `creating role '${name}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_role",
+    "Update a role's name, description, or permissions.",
+    {
+      roleId: z.string().describe("The role ID (UUID) to update"),
+      name: z.string().optional().describe("Updated name"),
+      description: z.string().optional().describe("Updated description"),
+      permissions: z.array(z.string()).optional().describe("Updated permission UUIDs (replaces all existing)"),
+    },
+    async ({ roleId, name, description, permissions }) => {
+      try {
+        const input: Record<string, any> = {};
+        if (name !== undefined) input.name = name;
+        if (description !== undefined) input.description = description;
+        if (permissions !== undefined) input.permissions = permissions;
+        const result = await getRolesClient().put(`/${roleId}`, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating role '${roleId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_role",
+    "Delete a role. Service accounts and groups that had this role lose its permissions.",
+    {
+      roleId: z.string().describe("The role ID (UUID) to delete"),
+    },
+    async ({ roleId }) => {
+      try {
+        await getRolesClient().delete(`/${roleId}`);
+        return {
+          content: [{ type: "text", text: `Role '${roleId}' deleted successfully.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `deleting role '${roleId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Group CRUD ───────────────────────────────────────────────────
+
+  server.tool(
+    "list_groups",
+    "List all groups in the workspace. Groups bundle service accounts together and can have roles assigned to them.",
+    {
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Results per page (default: 20)"),
+    },
+    async ({ page, pageSize }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+        const result = await getGroupsClient().get("/", { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing groups") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_group",
+    "Get details of a group.",
+    {
+      groupId: z.string().describe("The group ID (UUID)"),
+    },
+    async ({ groupId }) => {
+      try {
+        const result = await getGroupsClient().get(`/${groupId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting group '${groupId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "create_group",
+    "Create a new group. Groups let you assign roles to multiple service accounts at once.",
+    {
+      name: z.string().describe("Group name (e.g., 'Backend Services', 'Analytics Pipeline')"),
+      description: z.string().optional().describe("Optional description"),
+    },
+    async ({ name, description }) => {
+      try {
+        const input: Record<string, any> = { name };
+        if (description !== undefined) input.description = description;
+        const result = await getGroupsClient().post("/", input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `creating group '${name}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_group",
+    "Update a group's name or description.",
+    {
+      groupId: z.string().describe("The group ID (UUID) to update"),
+      name: z.string().optional().describe("Updated name"),
+      description: z.string().optional().describe("Updated description"),
+    },
+    async ({ groupId, name, description }) => {
+      try {
+        const input: Record<string, any> = {};
+        if (name !== undefined) input.name = name;
+        if (description !== undefined) input.description = description;
+        const result = await getGroupsClient().put(`/${groupId}`, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating group '${groupId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_group",
+    "Delete a group. Service accounts in this group lose permissions inherited through it.",
+    {
+      groupId: z.string().describe("The group ID (UUID) to delete"),
+    },
+    async ({ groupId }) => {
+      try {
+        await getGroupsClient().delete(`/${groupId}`);
+        return {
+          content: [{ type: "text", text: `Group '${groupId}' deleted successfully.` }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `deleting group '${groupId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  // ── Publishable Keys ─────────────────────────────────────────────
+
+  const getPkClient = () => createIamClient(sdk, centraliUrl, workspaceId, "publishable-keys");
+
+  server.tool(
+    "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.",
+    {
+      page: z.number().optional().describe("Page number (default: 1)"),
+      pageSize: z.number().optional().describe("Results per page (default: 20)"),
+    },
+    async ({ page, pageSize }) => {
+      try {
+        const params: Record<string, any> = {};
+        if (page !== undefined) params.page = page;
+        if (pageSize !== undefined) params.pageSize = pageSize;
+        const result = await getPkClient().get("/", { params });
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, "listing publishable keys") }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_publishable_key",
+    "Get details of a publishable key including its scopes and usage stats.",
+    {
+      keyId: z.string().describe("The publishable key ID (UUID)"),
+    },
+    async ({ keyId }) => {
+      try {
+        const result = await getPkClient().get(`/${keyId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `getting publishable key '${keyId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "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.",
+    {
+      label: z.string().describe("Display label (e.g., 'React Dashboard', 'Marketing Site')"),
+      scopes: z.array(z.string()).describe("Scopes defining what this key can access. Format: 'resource:action:target'. Examples: 'records:list:products' (list products), 'records:retrieve:*' (read any collection), 'records:create:orders' (create orders), 'triggers:execute:send-email' (invoke a trigger), 'files:retrieve' (read files), 'collections:list' (list collection schemas). Write actions (create, execute) require explicit targets — no wildcards."),
+    },
+    async ({ label, scopes }) => {
+      try {
+        const result = await getPkClient().post("/", { label, scopes });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(
+              {
+                ...result.data,
+                _note: "The full key (pk_live_...) is safe to use in client-side code. It's scoped and rate-limited. Store it in your app's environment config.",
+              },
+              null,
+              2
+            ),
+          }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `creating publishable key '${label}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_publishable_key",
+    "Update a publishable key's label or scopes. When updating scopes, the new scopes replace all existing ones.",
+    {
+      keyId: z.string().describe("The publishable key ID (UUID) to update"),
+      label: z.string().optional().describe("Updated label"),
+      scopes: z.array(z.string()).optional().describe("Updated scopes (replaces all existing). Same format as create_publishable_key."),
+    },
+    async ({ keyId, label, scopes }) => {
+      try {
+        const input: Record<string, any> = {};
+        if (label !== undefined) input.label = label;
+        if (scopes !== undefined) input.scopes = scopes;
+        const result = await getPkClient().patch(`/${keyId}`, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `updating publishable key '${keyId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "revoke_publishable_key",
+    "Revoke a publishable key. The key immediately stops working. This cannot be undone — create a new key if needed.",
+    {
+      keyId: z.string().describe("The publishable key ID (UUID) to revoke"),
+    },
+    async ({ keyId }) => {
+      try {
+        const result = await getPkClient().delete(`/${keyId}`);
+        return {
+          content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+        };
+      } catch (error: unknown) {
+        return {
+          content: [{ type: "text", text: formatError(error, `revoking publishable key '${keyId}'`) }],
+          isError: true,
+        };
+      }
+    }
+  );
+}