@centrali-io/centrali-mcp 4.4.8-rc.8 → 4.4.8

package/dist/tools/describe.js

@@ -338,18 +338,46 @@ function registerDescribeTools(server) {
                             },
                             render_url: {
                                 method: "client.getFileRenderUrl(renderId, options?)",
-                                note: "Returns a URL that serves the file. Supports image transformations: width, height, fit ('cover'|'contain'|'fill'), format ('webp'|'png'|'jpeg'), quality (1-100).",
-                                example: "const url = centrali.getFileRenderUrl(renderId, { width: 200, height: 200, fit: 'cover', format: 'webp' });",
+                                important: "uploadFile() returns a renderId (string), NOT a URL. You MUST call getFileRenderUrl(renderId) to construct the actual URL for display.",
+                                url_pattern: "https://api.{domain}/storage/ws/{workspaceId}/api/v1/render/{renderId}",
+                                transforms: "Optional image transformations: width, height, fit ('cover'|'contain'|'fill'), format ('webp'|'png'|'jpeg'), quality (1-100).",
+                                public_vs_private: {
+                                    public: "If uploaded with isPublic=true, the render URL works without any auth — use directly in <img> tags.",
+                                    private: "If uploaded with isPublic=false (default), the render URL requires authentication. Pass a Bearer token (service account) or x-api-key (publishable key) in the request headers. For browser rendering of private images, use a server-side proxy route or a publishable key.",
+                                },
+                                example: [
+                                    "// Upload returns renderId, NOT a URL",
+                                    "const { data: renderId } = await centrali.uploadFile(file, '/root/shared/logos', true);",
+                                    "",
+                                    "// Build the render URL from the renderId",
+                                    "const url = centrali.getFileRenderUrl(renderId);",
+                                    "// => 'https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123'",
+                                    "",
+                                    "// With image transforms (thumbnail)",
+                                    "const thumbUrl = centrali.getFileRenderUrl(renderId, { width: 200, height: 200, fit: 'cover', format: 'webp' });",
+                                    "",
+                                    "// For private images in Next.js — proxy through an API route",
+                                    "// app/api/image/[renderId]/route.ts",
+                                    "export async function GET(req, { params }) {",
+                                    "  const centrali = new CentraliSDK({ baseUrl, workspaceId, clientId, clientSecret });",
+                                    "  const url = centrali.getFileRenderUrl(params.renderId);",
+                                    "  const resp = await fetch(url, {",
+                                    "    headers: { Authorization: `Bearer ${await centrali.getToken()}` }",
+                                    "  });",
+                                    "  return new Response(resp.body, { headers: { 'Content-Type': resp.headers.get('Content-Type') } });",
+                                    "}",
+                                ].join("\n"),
                             },
                             download_url: {
                                 method: "client.getFileDownloadUrl(renderId)",
-                                note: "Returns a URL that triggers a file download.",
+                                note: "Returns a URL that triggers a file download. Same auth rules as render URLs.",
                             },
                             tips: [
                                 "/root/shared always exists — upload there directly or create subfolders like /root/shared/logos",
                                 "Set isPublic=true for files that need to be accessible without auth (logos, avatars, public images)",
-                                "Store the renderId or full URL on a record field for easy retrieval",
+                                "Store the renderId on a record field — then use getFileRenderUrl() to build the URL when displaying",
                                 "Use image transformations for thumbnails instead of uploading multiple sizes",
+                                "For private images in browser apps: either use a server-side proxy route or a publishable key with storage scope",
                             ],
                         },
                         realtime: {
@@ -2188,23 +2216,29 @@ function registerDescribeTools(server) {
                             createdAt: "string — ISO 8601 timestamp",
                         },
                         permission_model: {
-                            description: "Permissions flow: Service Account → Roles → Permissions. Groups are optional bundles of SAs.",
+                            description: "Access control is attribute-based. The caller's groups, roles, and other attributes (from JWT claims) are evaluated against policy conditions using JSON-Logic.",
+                            evaluation_flow: "Request → extract groups/roles from JWT → find permissions for the requested resource + action → evaluate each permission's linked policy against caller attributes → first Allow wins, otherwise Deny",
                             role: {
-                                description: "A named bundle of permissions. Roles are assigned directly to SAs or inherited through groups.",
-                                shape: {
-                                    id: "UUID",
-                                    name: "string (e.g., 'Data Reader', 'Compute Admin')",
-                                    description: "string | null",
-                                    permissions: "string[] — permission UUIDs",
-                                },
+                                description: "A named label assigned to users and service accounts. Appears in JWT claims as an attribute. Policy conditions can check roles. Names are immutable after creation.",
+                                shape: { id: "UUID", name: "string — immutable", description: "string | null" },
                             },
                             group: {
-                                description: "A named bundle of service accounts. Roles assigned to a group are inherited by all SAs in it.",
-                                shape: {
-                                    id: "UUID",
-                                    name: "string (e.g., 'Backend Services')",
-                                    description: "string | null",
-                                },
+                                description: "A named label for organizing users and service accounts. Appears in JWT claims. Policy conditions check group membership to decide access. Groups may also optionally appear on permissions. Names are immutable after creation.",
+                                shape: { id: "UUID", name: "string — immutable", description: "string | null" },
+                            },
+                            permission: {
+                                description: "Links a resource + actions to a policy. When a request comes in, the system finds permissions matching the resource + action, then evaluates each permission's linked policy against the caller's attributes.",
+                                shape: { id: "UUID", name: "string", resourceId: "UUID (from resources)", actions: "string[]", policyId: "UUID (from policies)", priority: "number" },
+                            },
+                            policy: {
+                                description: "A reusable set of JSON-Logic rules with an effect (Allow/Deny). Policy conditions check caller attributes like groups, roles, user_id, ip_address, time of day, etc. Example: 'Allow if caller is in group engineering'.",
+                            },
+                            resource: {
+                                description: "A protected thing in the system (e.g., 'workspace::records', 'workspace::functions'). Has a category and a list of valid actions.",
+                            },
+                            granting_access: {
+                                workflow: "1. Ensure the SA is in the right group → 2. Create a policy with conditions that match (e.g., group membership check) → 3. Create a permission linking the resource + actions + policy",
+                                shortcut: "Use generate_remediation + apply_remediation to auto-generate the correct policy + permission + group assignment for a denied action",
                             },
                             permission_actions: [
                                 "create — create new resources",
@@ -2276,9 +2310,9 @@ function registerDescribeTools(server) {
                             },
                             roles: {
                                 list_roles: "List all roles",
-                                get_role: "Get role details with permissions",
-                                create_role: "Create role with permissions",
-                                update_role: "Update role name/description/permissions",
+                                get_role: "Get role details",
+                                create_role: "Create a named role (names are immutable)",
+                                update_role: "Update role description",
                                 delete_role: "Delete role",
                                 list_service_account_roles: "List roles assigned to a SA",
                                 assign_role_to_service_account: "Assign role to SA",

package/dist/tools/service-accounts.js

@@ -553,7 +553,7 @@ function registerServiceAccountTools(server, sdk, centraliUrl, workspaceId, ownC
         }
     }));
     // ── Role CRUD ────────────────────────────────────────────────────
-    server.tool("list_roles", "List all roles in the workspace. Roles bundle permissions that can be assigned to service accounts or groups.", {
+    server.tool("list_roles", "List all roles in the workspace. Roles are named labels assigned to users and service accounts.", {
         page: zod_1.z.number().optional().describe("Page number (default: 1)"),
         pageSize: zod_1.z.number().optional().describe("Results per page (default: 20)"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ page, pageSize }) {
@@ -591,17 +591,14 @@ function registerServiceAccountTools(server, sdk, centraliUrl, workspaceId, ownC
             };
         }
     }));
-    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: zod_1.z.string().describe("Role name (e.g., 'Data Reader', 'Compute Admin')"),
+    server.tool("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.", {
+        name: zod_1.z.string().describe("Role name (e.g., 'Data Reader', 'Compute Admin'). Cannot be changed after creation."),
         description: zod_1.z.string().optional().describe("Optional description of the role's purpose"),
-        permissions: zod_1.z.array(zod_1.z.string()).optional().describe("Array of permission UUIDs to include in this role"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, description, permissions }) {
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ name, description }) {
         try {
             const input = { name };
             if (description !== undefined)
                 input.description = description;
-            if (permissions !== undefined)
-                input.permissions = permissions;
             const result = yield getRolesClient().post("/", input);
             return {
                 content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
@@ -614,17 +611,14 @@ function registerServiceAccountTools(server, sdk, centraliUrl, workspaceId, ownC
             };
         }
     }));
-    server.tool("update_role", "Update a role's description or permissions. Role names are immutable and cannot be changed after creation.", {
+    server.tool("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.", {
         roleId: zod_1.z.string().describe("The role ID (UUID) to update"),
         description: zod_1.z.string().optional().describe("Updated description"),
-        permissions: zod_1.z.array(zod_1.z.string()).optional().describe("Updated permission UUIDs (replaces all existing)"),
-    }, (_a) => __awaiter(this, [_a], void 0, function* ({ roleId, description, permissions }) {
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ roleId, description }) {
         try {
             const input = {};
             if (description !== undefined)
                 input.description = description;
-            if (permissions !== undefined)
-                input.permissions = permissions;
             const result = yield getRolesClient().put(`/${roleId}`, input);
             return {
                 content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
@@ -637,7 +631,7 @@ function registerServiceAccountTools(server, sdk, centraliUrl, workspaceId, ownC
             };
         }
     }));
-    server.tool("delete_role", "Delete a role. Service accounts and groups that had this role lose its permissions.", {
+    server.tool("delete_role", "Delete a role. Service accounts assigned to this role will lose the label.", {
         roleId: zod_1.z.string().describe("The role ID (UUID) to delete"),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ roleId }) {
         try {
@@ -934,7 +928,7 @@ function registerServiceAccountTools(server, sdk, centraliUrl, workspaceId, ownC
         }
     }));
     server.tool("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).", {
-        permission: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe("Required: { name: string, resourceId: UUID, actions: string[], policyId: UUID }. Optional: description, groups (string[]), priority (number)."),
+        permission: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).describe("Required: { name: string, resourceId: UUID, actions: string[], policyId: UUID }. Optional: description, priority (number)."),
     }, (_a) => __awaiter(this, [_a], void 0, function* ({ permission }) {
         try {
             const result = yield getPermissionsClient().post("/", permission);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@centrali-io/centrali-mcp",
-  "version": "4.4.8-rc.8",
+  "version": "4.4.8",
   "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
   "main": "dist/index.js",
   "type": "commonjs",

package/src/tools/describe.ts

@@ -346,18 +346,46 @@ export function registerDescribeTools(server: McpServer) {
                 },
                 render_url: {
                   method: "client.getFileRenderUrl(renderId, options?)",
-                  note: "Returns a URL that serves the file. Supports image transformations: width, height, fit ('cover'|'contain'|'fill'), format ('webp'|'png'|'jpeg'), quality (1-100).",
-                  example: "const url = centrali.getFileRenderUrl(renderId, { width: 200, height: 200, fit: 'cover', format: 'webp' });",
+                  important: "uploadFile() returns a renderId (string), NOT a URL. You MUST call getFileRenderUrl(renderId) to construct the actual URL for display.",
+                  url_pattern: "https://api.{domain}/storage/ws/{workspaceId}/api/v1/render/{renderId}",
+                  transforms: "Optional image transformations: width, height, fit ('cover'|'contain'|'fill'), format ('webp'|'png'|'jpeg'), quality (1-100).",
+                  public_vs_private: {
+                    public: "If uploaded with isPublic=true, the render URL works without any auth — use directly in <img> tags.",
+                    private: "If uploaded with isPublic=false (default), the render URL requires authentication. Pass a Bearer token (service account) or x-api-key (publishable key) in the request headers. For browser rendering of private images, use a server-side proxy route or a publishable key.",
+                  },
+                  example: [
+                    "// Upload returns renderId, NOT a URL",
+                    "const { data: renderId } = await centrali.uploadFile(file, '/root/shared/logos', true);",
+                    "",
+                    "// Build the render URL from the renderId",
+                    "const url = centrali.getFileRenderUrl(renderId);",
+                    "// => 'https://api.centrali.io/storage/ws/my-workspace/api/v1/render/abc123'",
+                    "",
+                    "// With image transforms (thumbnail)",
+                    "const thumbUrl = centrali.getFileRenderUrl(renderId, { width: 200, height: 200, fit: 'cover', format: 'webp' });",
+                    "",
+                    "// For private images in Next.js — proxy through an API route",
+                    "// app/api/image/[renderId]/route.ts",
+                    "export async function GET(req, { params }) {",
+                    "  const centrali = new CentraliSDK({ baseUrl, workspaceId, clientId, clientSecret });",
+                    "  const url = centrali.getFileRenderUrl(params.renderId);",
+                    "  const resp = await fetch(url, {",
+                    "    headers: { Authorization: `Bearer ${await centrali.getToken()}` }",
+                    "  });",
+                    "  return new Response(resp.body, { headers: { 'Content-Type': resp.headers.get('Content-Type') } });",
+                    "}",
+                  ].join("\n"),
                 },
                 download_url: {
                   method: "client.getFileDownloadUrl(renderId)",
-                  note: "Returns a URL that triggers a file download.",
+                  note: "Returns a URL that triggers a file download. Same auth rules as render URLs.",
                 },
                 tips: [
                   "/root/shared always exists — upload there directly or create subfolders like /root/shared/logos",
                   "Set isPublic=true for files that need to be accessible without auth (logos, avatars, public images)",
-                  "Store the renderId or full URL on a record field for easy retrieval",
+                  "Store the renderId on a record field — then use getFileRenderUrl() to build the URL when displaying",
                   "Use image transformations for thumbnails instead of uploading multiple sizes",
+                  "For private images in browser apps: either use a server-side proxy route or a publishable key with storage scope",
                 ],
               },
               realtime: {
@@ -2485,23 +2513,29 @@ export function registerDescribeTools(server: McpServer) {
                 createdAt: "string — ISO 8601 timestamp",
               },
               permission_model: {
-                description: "Permissions flow: Service Account → Roles → Permissions. Groups are optional bundles of SAs.",
+                description: "Access control is attribute-based. The caller's groups, roles, and other attributes (from JWT claims) are evaluated against policy conditions using JSON-Logic.",
+                evaluation_flow: "Request → extract groups/roles from JWT → find permissions for the requested resource + action → evaluate each permission's linked policy against caller attributes → first Allow wins, otherwise Deny",
                 role: {
-                  description: "A named bundle of permissions. Roles are assigned directly to SAs or inherited through groups.",
-                  shape: {
-                    id: "UUID",
-                    name: "string (e.g., 'Data Reader', 'Compute Admin')",
-                    description: "string | null",
-                    permissions: "string[] — permission UUIDs",
-                  },
+                  description: "A named label assigned to users and service accounts. Appears in JWT claims as an attribute. Policy conditions can check roles. Names are immutable after creation.",
+                  shape: { id: "UUID", name: "string — immutable", description: "string | null" },
                 },
                 group: {
-                  description: "A named bundle of service accounts. Roles assigned to a group are inherited by all SAs in it.",
-                  shape: {
-                    id: "UUID",
-                    name: "string (e.g., 'Backend Services')",
-                    description: "string | null",
-                  },
+                  description: "A named label for organizing users and service accounts. Appears in JWT claims. Policy conditions check group membership to decide access. Groups may also optionally appear on permissions. Names are immutable after creation.",
+                  shape: { id: "UUID", name: "string — immutable", description: "string | null" },
+                },
+                permission: {
+                  description: "Links a resource + actions to a policy. When a request comes in, the system finds permissions matching the resource + action, then evaluates each permission's linked policy against the caller's attributes.",
+                  shape: { id: "UUID", name: "string", resourceId: "UUID (from resources)", actions: "string[]", policyId: "UUID (from policies)", priority: "number" },
+                },
+                policy: {
+                  description: "A reusable set of JSON-Logic rules with an effect (Allow/Deny). Policy conditions check caller attributes like groups, roles, user_id, ip_address, time of day, etc. Example: 'Allow if caller is in group engineering'.",
+                },
+                resource: {
+                  description: "A protected thing in the system (e.g., 'workspace::records', 'workspace::functions'). Has a category and a list of valid actions.",
+                },
+                granting_access: {
+                  workflow: "1. Ensure the SA is in the right group → 2. Create a policy with conditions that match (e.g., group membership check) → 3. Create a permission linking the resource + actions + policy",
+                  shortcut: "Use generate_remediation + apply_remediation to auto-generate the correct policy + permission + group assignment for a denied action",
                 },
                 permission_actions: [
                   "create — create new resources",
@@ -2573,9 +2607,9 @@ export function registerDescribeTools(server: McpServer) {
                 },
                 roles: {
                   list_roles: "List all roles",
-                  get_role: "Get role details with permissions",
-                  create_role: "Create role with permissions",
-                  update_role: "Update role name/description/permissions",
+                  get_role: "Get role details",
+                  create_role: "Create a named role (names are immutable)",
+                  update_role: "Update role description",
                   delete_role: "Delete role",
                   list_service_account_roles: "List roles assigned to a SA",
                   assign_role_to_service_account: "Assign role to SA",

package/src/tools/service-accounts.ts

@@ -682,7 +682,7 @@ export function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK,
 
   server.tool(
     "list_roles",
-    "List all roles in the workspace. Roles bundle permissions that can be assigned to service accounts or groups.",
+    "List all roles in the workspace. Roles are named labels assigned to users and service accounts.",
     {
       page: z.number().optional().describe("Page number (default: 1)"),
       pageSize: z.number().optional().describe("Results per page (default: 20)"),
@@ -728,17 +728,15 @@ export function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK,
 
   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.",
+    "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.",
     {
-      name: z.string().describe("Role name (e.g., 'Data Reader', 'Compute Admin')"),
+      name: z.string().describe("Role name (e.g., 'Data Reader', 'Compute Admin'). Cannot be changed after creation."),
       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 }) => {
+    async ({ name, description }) => {
       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) }],
@@ -754,17 +752,15 @@ export function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK,
 
   server.tool(
     "update_role",
-    "Update a role's description or permissions. Role names are immutable and cannot be changed after creation.",
+    "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.",
     {
       roleId: z.string().describe("The role ID (UUID) to update"),
       description: z.string().optional().describe("Updated description"),
-      permissions: z.array(z.string()).optional().describe("Updated permission UUIDs (replaces all existing)"),
     },
-    async ({ roleId, description, permissions }) => {
+    async ({ roleId, description }) => {
       try {
         const input: Record<string, any> = {};
         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) }],
@@ -780,7 +776,7 @@ export function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK,
 
   server.tool(
     "delete_role",
-    "Delete a role. Service accounts and groups that had this role lose its permissions.",
+    "Delete a role. Service accounts assigned to this role will lose the label.",
     {
       roleId: z.string().describe("The role ID (UUID) to delete"),
     },
@@ -1164,7 +1160,7 @@ export function registerServiceAccountTools(server: McpServer, sdk: CentraliSDK,
     "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).",
     {
-      permission: z.record(z.string(), z.any()).describe("Required: { name: string, resourceId: UUID, actions: string[], policyId: UUID }. Optional: description, groups (string[]), priority (number)."),
+      permission: z.record(z.string(), z.any()).describe("Required: { name: string, resourceId: UUID, actions: string[], policyId: UUID }. Optional: description, priority (number)."),
     },
     async ({ permission }) => {
       try {