list_dataverse_roles
Retrieve security roles from Dataverse with filtering options to discover available permissions, find custom roles, and understand permission structures across business units.
Instructions
Retrieves a list of security roles in the Dataverse environment with filtering options. Use this to discover available roles, find custom roles, or get an overview of permission structures. Supports filtering by business unit, custom/system roles, and managed/unmanaged status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| businessUnitId | No | Filter roles by business unit ID | |
| customOnly | No | Whether to list only custom (non-system) roles | |
| filter | No | OData filter expression | |
| includeManaged | No | Whether to include managed roles | |
| top | No | Maximum number of roles to return (default: 50) |
Implementation Reference
- src/tools/role-tools.ts:250-313 (handler)Handler implementation that constructs OData query for listing Dataverse security roles based on input parameters (businessUnitId, customOnly, includeManaged, top, filter), fetches from Dataverse API, formats results, and returns as text content.async (params) => { try { let queryParams: Record<string, any> = { $select: 'roleid,name,description,appliesto,isautoassigned,isinherited,businessunitid,ismanaged,iscustomizable,canbedeleted', $top: params.top || 50 }; const filters: string[] = []; if (params.businessUnitId) { filters.push(`businessunitid eq ${params.businessUnitId}`); } if (params.customOnly) { filters.push(`iscustomizable/Value eq true`); } if (!params.includeManaged) { filters.push(`ismanaged eq false`); } if (params.filter) { filters.push(params.filter); } if (filters.length > 0) { queryParams.$filter = filters.join(' and '); } const response = await client.get('roles', queryParams); const roles = response.value?.map((role: any) => ({ roleId: role.roleid, name: role.name, description: role.description, appliesTo: role.appliesto, isAutoAssigned: role.isautoassigned === 1, isInherited: role.isinherited, businessUnitId: role.businessunitid, isManaged: role.ismanaged, isCustomizable: role.iscustomizable, canBeDeleted: role.canbedeleted })) || []; return { content: [ { type: "text", text: `Found ${roles.length} security roles:\n\n${JSON.stringify(roles, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error listing security roles: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } }
- src/tools/role-tools.ts:242-248 (schema)Zod input schema defining optional parameters for filtering and limiting the list of Dataverse security roles.inputSchema: { businessUnitId: z.string().optional().describe("Filter roles by business unit ID"), customOnly: z.boolean().default(false).describe("Whether to list only custom (non-system) roles"), includeManaged: z.boolean().default(false).describe("Whether to include managed roles"), top: z.number().optional().describe("Maximum number of roles to return (default: 50)"), filter: z.string().optional().describe("OData filter expression") }
- src/tools/role-tools.ts:237-314 (registration)server.registerTool call that registers the 'list_dataverse_roles' MCP tool with its title, description, input schema, and handler function.server.registerTool( "list_dataverse_roles", { title: "List Dataverse Security Roles", description: "Retrieves a list of security roles in the Dataverse environment with filtering options. Use this to discover available roles, find custom roles, or get an overview of permission structures. Supports filtering by business unit, custom/system roles, and managed/unmanaged status.", inputSchema: { businessUnitId: z.string().optional().describe("Filter roles by business unit ID"), customOnly: z.boolean().default(false).describe("Whether to list only custom (non-system) roles"), includeManaged: z.boolean().default(false).describe("Whether to include managed roles"), top: z.number().optional().describe("Maximum number of roles to return (default: 50)"), filter: z.string().optional().describe("OData filter expression") } }, async (params) => { try { let queryParams: Record<string, any> = { $select: 'roleid,name,description,appliesto,isautoassigned,isinherited,businessunitid,ismanaged,iscustomizable,canbedeleted', $top: params.top || 50 }; const filters: string[] = []; if (params.businessUnitId) { filters.push(`businessunitid eq ${params.businessUnitId}`); } if (params.customOnly) { filters.push(`iscustomizable/Value eq true`); } if (!params.includeManaged) { filters.push(`ismanaged eq false`); } if (params.filter) { filters.push(params.filter); } if (filters.length > 0) { queryParams.$filter = filters.join(' and '); } const response = await client.get('roles', queryParams); const roles = response.value?.map((role: any) => ({ roleId: role.roleid, name: role.name, description: role.description, appliesTo: role.appliesto, isAutoAssigned: role.isautoassigned === 1, isInherited: role.isinherited, businessUnitId: role.businessunitid, isManaged: role.ismanaged, isCustomizable: role.iscustomizable, canBeDeleted: role.canbedeleted })) || []; return { content: [ { type: "text", text: `Found ${roles.length} security roles:\n\n${JSON.stringify(roles, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error listing security roles: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } } );