Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/businessunit-tools.ts:639-682 (handler)

  The core handler function that executes the tool logic. It constructs the appropriate Dataverse API endpoint based on whether subsidiary teams are included, fetches the data, formats it with team type labels, and returns a formatted text response or error.

  async (params: any) => {
    try {
      let endpoint: string;
      
      if (params.includeSubsidiaryTeams) {
        // Use the RetrieveSubsidiaryTeamsBusinessUnit function
        endpoint = `RetrieveSubsidiaryTeamsBusinessUnit(BusinessUnitId=${params.businessUnitId})`;
      } else {
        // Get teams directly associated with the business unit
        endpoint = `teams?$filter=businessunitid/businessunitid eq ${params.businessUnitId}&$select=teamid,name,teamtype,businessunitid&$expand=businessunitid($select=name)`;
      }
  
      const result = await client.get(endpoint);
      const teams = params.includeSubsidiaryTeams ? result : result.value;
  
      const formattedTeams = (Array.isArray(teams) ? teams : teams?.value || []).map((team: any) => ({
        teamId: team.teamid,
        name: team.name,
        teamType: team.teamtype,
        teamTypeLabel: getTeamTypeLabel(team.teamtype),
        businessUnitId: team.businessunitid,
        businessUnitName: team.businessunitid?.name
      }));
  
      return {
        content: [
          {
            type: "text",
            text: `Found ${formattedTeams.length} ${params.includeSubsidiaryTeams ? 'subsidiary ' : ''}teams for business unit:\n\n${JSON.stringify(formattedTeams, null, 2)}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error retrieving business unit teams: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ],
        isError: true
      };
    }
  }

• src/tools/businessunit-tools.ts:631-638 (schema)

  The tool schema defining title, description, and input validation using Zod for businessUnitId (required string) and includeSubsidiaryTeams (optional boolean, default false).

  {
    title: "Get Business Unit Teams",
    description: "Retrieves all teams associated with a specific business unit, with option to include teams from subsidiary business units. Use this to understand team organization and business unit relationships.",
    inputSchema: {
      businessUnitId: z.string().describe("Unique identifier of the business unit"),
      includeSubsidiaryTeams: z.boolean().optional().default(false).describe("Whether to include teams from subsidiary business units")
    }
  },

• src/tools/businessunit-tools.ts:629-683 (registration)

  The server.registerTool call that registers the tool with its name, schema, and handler function within the getBusinessUnitTeamsTool setup function.

  server.registerTool(
    "get_businessunit_teams",
    {
      title: "Get Business Unit Teams",
      description: "Retrieves all teams associated with a specific business unit, with option to include teams from subsidiary business units. Use this to understand team organization and business unit relationships.",
      inputSchema: {
        businessUnitId: z.string().describe("Unique identifier of the business unit"),
        includeSubsidiaryTeams: z.boolean().optional().default(false).describe("Whether to include teams from subsidiary business units")
      }
    },
    async (params: any) => {
      try {
        let endpoint: string;
        
        if (params.includeSubsidiaryTeams) {
          // Use the RetrieveSubsidiaryTeamsBusinessUnit function
          endpoint = `RetrieveSubsidiaryTeamsBusinessUnit(BusinessUnitId=${params.businessUnitId})`;
        } else {
          // Get teams directly associated with the business unit
          endpoint = `teams?$filter=businessunitid/businessunitid eq ${params.businessUnitId}&$select=teamid,name,teamtype,businessunitid&$expand=businessunitid($select=name)`;
        }
  
        const result = await client.get(endpoint);
        const teams = params.includeSubsidiaryTeams ? result : result.value;
  
        const formattedTeams = (Array.isArray(teams) ? teams : teams?.value || []).map((team: any) => ({
          teamId: team.teamid,
          name: team.name,
          teamType: team.teamtype,
          teamTypeLabel: getTeamTypeLabel(team.teamtype),
          businessUnitId: team.businessunitid,
          businessUnitName: team.businessunitid?.name
        }));
  
        return {
          content: [
            {
              type: "text",
              text: `Found ${formattedTeams.length} ${params.includeSubsidiaryTeams ? 'subsidiary ' : ''}teams for business unit:\n\n${JSON.stringify(formattedTeams, null, 2)}`
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving business unit teams: ${error instanceof Error ? error.message : 'Unknown error'}`
            }
          ],
          isError: true
        };
      }
    }
  );

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

  Invocation of the getBusinessUnitTeamsTool function during server initialization, which triggers the actual tool registration.

  getBusinessUnitTeamsTool(server, dataverseClient);

• src/tools/businessunit-tools.ts:687-695 (helper)

  Helper utility function that converts numerical team type values to human-readable labels, used in the handler to enrich team data.

  function getTeamTypeLabel(teamType: number): string {
    switch (teamType) {
      case 0: return 'Owner';
      case 1: return 'Access';
      case 2: return 'Security Group';
      case 3: return 'Office Group';
      default: return 'Unknown';
    }
  }