get_dataverse_role
Retrieve detailed security role information including properties, business unit associations, and configuration settings to inspect role definitions and understand permission structures in Microsoft Dataverse.
Instructions
Retrieves detailed information about a specific security role including its properties, business unit association, and configuration settings. Use this to inspect role definitions and understand permission structures.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| roleId | Yes | ID of the role to retrieve |
Implementation Reference
- src/tools/role-tools.ts:102-143 (handler)The main handler function for the 'get_dataverse_role' tool. It queries the Dataverse API for the specified role ID, extracts relevant properties, formats them into a JSON object, and returns the information as text content. Handles errors by returning an error message.async (params) => { try { const role = await client.get(`roles(${params.roleId})?$select=roleid,name,description,appliesto,isautoassigned,isinherited,summaryofcoretablepermissions,businessunitid,createdon,modifiedon,createdby,modifiedby,ismanaged,iscustomizable,canbedeleted`); const roleInfo = { roleId: role.roleid, name: role.name, description: role.description, appliesTo: role.appliesto, isAutoAssigned: role.isautoassigned === 1, isInherited: role.isinherited, summaryOfCoreTablePermissions: role.summaryofcoretablepermissions, businessUnitId: role.businessunitid, createdOn: role.createdon, modifiedOn: role.modifiedon, createdBy: role.createdby, modifiedBy: role.modifiedby, isManaged: role.ismanaged, isCustomizable: role.iscustomizable, canBeDeleted: role.canbedeleted }; return { content: [ { type: "text", text: `Security role information:\n\n${JSON.stringify(roleInfo, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving security role: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } }
- src/tools/role-tools.ts:98-100 (schema)The input schema for the tool, defining a single required string parameter 'roleId' for the security role GUID.inputSchema: { roleId: z.string().describe("ID of the role to retrieve") }
- src/tools/role-tools.ts:92-145 (registration)The exported getRoleTool function that performs the server.registerTool call to register the 'get_dataverse_role' tool, including its metadata, schema, and inline handler.export function getRoleTool(server: McpServer, client: DataverseClient) { server.registerTool( "get_dataverse_role", { title: "Get Dataverse Security Role", description: "Retrieves detailed information about a specific security role including its properties, business unit association, and configuration settings. Use this to inspect role definitions and understand permission structures.", inputSchema: { roleId: z.string().describe("ID of the role to retrieve") } }, async (params) => { try { const role = await client.get(`roles(${params.roleId})?$select=roleid,name,description,appliesto,isautoassigned,isinherited,summaryofcoretablepermissions,businessunitid,createdon,modifiedon,createdby,modifiedby,ismanaged,iscustomizable,canbedeleted`); const roleInfo = { roleId: role.roleid, name: role.name, description: role.description, appliesTo: role.appliesto, isAutoAssigned: role.isautoassigned === 1, isInherited: role.isinherited, summaryOfCoreTablePermissions: role.summaryofcoretablepermissions, businessUnitId: role.businessunitid, createdOn: role.createdon, modifiedOn: role.modifiedon, createdBy: role.createdby, modifiedBy: role.modifiedby, isManaged: role.ismanaged, isCustomizable: role.iscustomizable, canBeDeleted: role.canbedeleted }; return { content: [ { type: "text", text: `Security role information:\n\n${JSON.stringify(roleInfo, null, 2)}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error retrieving security role: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } } ); }
- src/index.ts:181-181 (registration)Invocation of getRoleTool in the main server initialization to register all role-related tools on the MCP server.getRoleTool(server, dataverseClient);