Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/businessunit-tools.ts:419-486 (handler)

  The handler function that lists Dataverse business units. It constructs an OData query with optional parameters for top, filter, orderby, and select, fetches from the Dataverse API, formats the results, and returns them.

  async (params: any) => {
    try {
      let query = 'businessunits?';
      const queryParams: string[] = [];
  
      // Select fields
      const selectFields = params.select || [
        'businessunitid', 'name', 'description', 'divisionname', 'emailaddress',
        'costcenter', 'isdisabled', 'createdon', 'modifiedon', 'parentbusinessunitid'
      ].join(',');
      queryParams.push(`$select=${selectFields}`);
  
      // Top
      queryParams.push(`$top=${params.top || 50}`);
  
      // Filter
      if (params.filter) {
        queryParams.push(`$filter=${encodeURIComponent(params.filter)}`);
      }
  
      // Order by
      if (params.orderby) {
        queryParams.push(`$orderby=${encodeURIComponent(params.orderby)}`);
      }
  
      // Expand parent business unit
      queryParams.push('$expand=parentbusinessunitid($select=businessunitid,name)');
  
      // Add count
      queryParams.push('$count=true');
  
      query += queryParams.join('&');
      const result = await client.get(query);
  
      const businessUnits = result.value?.map((bu: any) => ({
        businessUnitId: bu.businessunitid,
        name: bu.name,
        description: bu.description,
        divisionName: bu.divisionname,
        emailAddress: bu.emailaddress,
        costCenter: bu.costcenter,
        isDisabled: bu.isdisabled,
        createdOn: bu.createdon,
        modifiedOn: bu.modifiedon,
        parentBusinessUnitId: bu.parentbusinessunitid,
        parentBusinessUnitName: bu.parentbusinessunitid?.name
      })) || [];
  
      return {
        content: [
          {
            type: "text",
            text: `Found ${businessUnits.length} business units (Total: ${result['@odata.count'] || businessUnits.length}):\n\n${JSON.stringify(businessUnits, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error listing business units: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/businessunit-tools.ts:412-418 (schema)

  Input schema using Zod for validating tool parameters: top (number, optional), filter (string, optional), orderby (string, optional), select (string, optional).

    inputSchema: {
      top: z.number().min(1).max(5000).optional().describe("Maximum number of business units to return (default: 50)"),
      filter: z.string().optional().describe("OData filter expression"),
      orderby: z.string().optional().describe("OData orderby expression"),
      select: z.string().optional().describe("OData select expression to specify which fields to return")
    }
  },

• src/tools/businessunit-tools.ts:407-488 (registration)

  Registers the 'list_dataverse_businessunits' tool on the MCP server using server.registerTool, providing title, description, inputSchema, and the handler function.

    server.registerTool(
      "list_dataverse_businessunits",
      {
        title: "List Dataverse Business Units",
        description: "Retrieves a list of business units in the Dataverse environment with filtering and sorting options. Use this to discover available business units, understand organizational hierarchy, and find specific business units by criteria.",
        inputSchema: {
          top: z.number().min(1).max(5000).optional().describe("Maximum number of business units to return (default: 50)"),
          filter: z.string().optional().describe("OData filter expression"),
          orderby: z.string().optional().describe("OData orderby expression"),
          select: z.string().optional().describe("OData select expression to specify which fields to return")
        }
      },
      async (params: any) => {
        try {
          let query = 'businessunits?';
          const queryParams: string[] = [];
  
          // Select fields
          const selectFields = params.select || [
            'businessunitid', 'name', 'description', 'divisionname', 'emailaddress',
            'costcenter', 'isdisabled', 'createdon', 'modifiedon', 'parentbusinessunitid'
          ].join(',');
          queryParams.push(`$select=${selectFields}`);
  
          // Top
          queryParams.push(`$top=${params.top || 50}`);
  
          // Filter
          if (params.filter) {
            queryParams.push(`$filter=${encodeURIComponent(params.filter)}`);
          }
  
          // Order by
          if (params.orderby) {
            queryParams.push(`$orderby=${encodeURIComponent(params.orderby)}`);
          }
  
          // Expand parent business unit
          queryParams.push('$expand=parentbusinessunitid($select=businessunitid,name)');
  
          // Add count
          queryParams.push('$count=true');
  
          query += queryParams.join('&');
          const result = await client.get(query);
  
          const businessUnits = result.value?.map((bu: any) => ({
            businessUnitId: bu.businessunitid,
            name: bu.name,
            description: bu.description,
            divisionName: bu.divisionname,
            emailAddress: bu.emailaddress,
            costCenter: bu.costcenter,
            isDisabled: bu.isdisabled,
            createdOn: bu.createdon,
            modifiedOn: bu.modifiedon,
            parentBusinessUnitId: bu.parentbusinessunitid,
            parentBusinessUnitName: bu.parentbusinessunitid?.name
          })) || [];
  
          return {
            content: [
              {
                type: "text",
                text: `Found ${businessUnits.length} business units (Total: ${result['@odata.count'] || businessUnits.length}):\n\n${JSON.stringify(businessUnits, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error listing business units: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }