Dataverse MCP Server

Instructions

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
        };
      }
    }
  );