Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/role-tools.ts:41-89 (handler)

  The asynchronous handler function that implements the core logic for the 'create_dataverse_role' tool. It constructs role data, handles business unit association (defaulting to root if not provided), posts to the 'roles' endpoint via DataverseClient, extracts the role ID from response, and returns formatted success or error content.

    async (params) => {
      try {
        const roleData: any = {
          name: params.name,
          description: params.description || '',
          appliesto: params.appliesTo,
          isautoassigned: params.isAutoAssigned ? 1 : 0,
          isinherited: parseInt(params.isInherited),
          summaryofcoretablepermissions: params.summaryOfCoreTablePermissions
        };
  
        // If businessUnitId is provided, use it; otherwise, get the root business unit
        if (params.businessUnitId) {
          roleData['businessunitid@odata.bind'] = `/businessunits(${params.businessUnitId})`;
        } else {
          // Get the root business unit
          const businessUnits = await client.get('businessunits?$filter=parentbusinessunitid eq null&$select=businessunitid');
          
          if (businessUnits.value && businessUnits.value.length > 0) {
            roleData['businessunitid@odata.bind'] = `/businessunits(${businessUnits.value[0].businessunitid})`;
          }
        }
  
        const response = await client.post('roles', roleData);
        
        // The response might have the ID in different formats
        const roleId = response.roleid || response.id || response['@odata.id']?.split('(')[1]?.split(')')[0] || 'Created successfully';
        
        return {
          content: [
            {
              type: "text",
              text: `Successfully created security role '${params.name}'.\n\nRole ID: ${roleId}\n\nResponse: ${JSON.stringify(response, null, 2)}`
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error creating security role: ${error instanceof Error ? error.message : 'Unknown error'}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/tools/role-tools.ts:28-40 (schema)

  The tool metadata including title, description, and Zod inputSchema defining parameters: name (required), description, businessUnitId, appliesTo, isAutoAssigned, isInherited, summaryOfCoreTablePermissions.

  {
    title: "Create Dataverse Security Role",
    description: "Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.",
    inputSchema: {
      name: z.string().max(100).describe("Name of the security role"),
      description: z.string().max(2000).optional().describe("Description of the security role"),
      businessUnitId: z.string().optional().describe("Business unit ID to associate the role with (defaults to root business unit)"),
      appliesTo: z.string().max(2000).optional().describe("Personas/Licenses the security role applies to"),
      isAutoAssigned: z.boolean().default(false).describe("Whether the role is auto-assigned based on user license"),
      isInherited: z.enum(['0', '1']).default('1').describe("0 = Team privileges only, 1 = Direct User access level and Team privileges"),
      summaryOfCoreTablePermissions: z.string().max(2000).optional().describe("Summary of Core Table Permissions of the Role")
    }
  },

• src/tools/role-tools.ts:25-90 (registration)

  The createRoleTool function that registers the 'create_dataverse_role' tool with the MCP server, including schema and handler.

  export function createRoleTool(server: McpServer, client: DataverseClient) {
    server.registerTool(
      "create_dataverse_role",
      {
        title: "Create Dataverse Security Role",
        description: "Creates a new security role in Dataverse to define permissions and access levels for users and teams. Security roles control what users can see and do within the system. Use this to establish custom permission sets for different user types or job functions.",
        inputSchema: {
          name: z.string().max(100).describe("Name of the security role"),
          description: z.string().max(2000).optional().describe("Description of the security role"),
          businessUnitId: z.string().optional().describe("Business unit ID to associate the role with (defaults to root business unit)"),
          appliesTo: z.string().max(2000).optional().describe("Personas/Licenses the security role applies to"),
          isAutoAssigned: z.boolean().default(false).describe("Whether the role is auto-assigned based on user license"),
          isInherited: z.enum(['0', '1']).default('1').describe("0 = Team privileges only, 1 = Direct User access level and Team privileges"),
          summaryOfCoreTablePermissions: z.string().max(2000).optional().describe("Summary of Core Table Permissions of the Role")
        }
      },
      async (params) => {
        try {
          const roleData: any = {
            name: params.name,
            description: params.description || '',
            appliesto: params.appliesTo,
            isautoassigned: params.isAutoAssigned ? 1 : 0,
            isinherited: parseInt(params.isInherited),
            summaryofcoretablepermissions: params.summaryOfCoreTablePermissions
          };
  
          // If businessUnitId is provided, use it; otherwise, get the root business unit
          if (params.businessUnitId) {
            roleData['businessunitid@odata.bind'] = `/businessunits(${params.businessUnitId})`;
          } else {
            // Get the root business unit
            const businessUnits = await client.get('businessunits?$filter=parentbusinessunitid eq null&$select=businessunitid');
            
            if (businessUnits.value && businessUnits.value.length > 0) {
              roleData['businessunitid@odata.bind'] = `/businessunits(${businessUnits.value[0].businessunitid})`;
            }
          }
  
          const response = await client.post('roles', roleData);
          
          // The response might have the ID in different formats
          const roleId = response.roleid || response.id || response['@odata.id']?.split('(')[1]?.split(')')[0] || 'Created successfully';
          
          return {
            content: [
              {
                type: "text",
                text: `Successfully created security role '${params.name}'.\n\nRole ID: ${roleId}\n\nResponse: ${JSON.stringify(response, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error creating security role: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }

• src/index.ts:180-180 (registration)

  The call to createRoleTool in the main index.ts that performs the actual registration of the tool during server initialization.

  createRoleTool(server, dataverseClient);