Dataverse MCP Server

Instructions

Implementation Reference

• src/tools/businessunit-tools.ts:582-625 (handler)

  Executes the tool logic: queries Dataverse API for users in the business unit (direct or subsidiary via special function), formats results, handles errors.

      try {
        let endpoint: string;
        
        if (params.includeSubsidiaryUsers) {
          // Use the RetrieveSubsidiaryUsersBusinessUnit function
          endpoint = `RetrieveSubsidiaryUsersBusinessUnit(BusinessUnitId=${params.businessUnitId})`;
        } else {
          // Get users directly associated with the business unit
          endpoint = `systemusers?$filter=businessunitid/businessunitid eq ${params.businessUnitId}&$select=systemuserid,fullname,domainname,businessunitid,isdisabled&$expand=businessunitid($select=name)`;
        }
  
        const result = await client.get(endpoint);
        const users = params.includeSubsidiaryUsers ? result : result.value;
  
        const formattedUsers = (Array.isArray(users) ? users : users?.value || []).map((user: any) => ({
          userId: user.systemuserid,
          fullName: user.fullname,
          domainName: user.domainname,
          businessUnitId: user.businessunitid,
          businessUnitName: user.businessunitid?.name,
          isDisabled: user.isdisabled
        }));
  
        return {
          content: [
            {
              type: "text",
              text: `Found ${formattedUsers.length} ${params.includeSubsidiaryUsers ? 'subsidiary ' : ''}users for business unit:\n\n${JSON.stringify(formattedUsers, null, 2)}`
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error retrieving business unit users: ${error instanceof Error ? error.message : 'Unknown error'}`
            }
          ],
          isError: true
        };
      }
    }
  );

• src/tools/businessunit-tools.ts:574-580 (schema)

  Input schema using Zod validation for businessUnitId (required GUID) and optional includeSubsidiaryUsers flag.

    title: "Get Business Unit Users",
    description: "Retrieves all users associated with a specific business unit, with option to include users from subsidiary business units. Use this to understand user assignments and organizational membership.",
    inputSchema: {
      businessUnitId: z.string().describe("Unique identifier of the business unit"),
      includeSubsidiaryUsers: z.boolean().optional().default(false).describe("Whether to include users from subsidiary business units")
    }
  },

• src/tools/businessunit-tools.ts:571-626 (registration)

  Registers the 'get_businessunit_users' tool on the MCP server within the getBusinessUnitUsersTool function.

    server.registerTool(
      "get_businessunit_users",
      {
        title: "Get Business Unit Users",
        description: "Retrieves all users associated with a specific business unit, with option to include users from subsidiary business units. Use this to understand user assignments and organizational membership.",
        inputSchema: {
          businessUnitId: z.string().describe("Unique identifier of the business unit"),
          includeSubsidiaryUsers: z.boolean().optional().default(false).describe("Whether to include users from subsidiary business units")
        }
      },
      async (params: any) => {
        try {
          let endpoint: string;
          
          if (params.includeSubsidiaryUsers) {
            // Use the RetrieveSubsidiaryUsersBusinessUnit function
            endpoint = `RetrieveSubsidiaryUsersBusinessUnit(BusinessUnitId=${params.businessUnitId})`;
          } else {
            // Get users directly associated with the business unit
            endpoint = `systemusers?$filter=businessunitid/businessunitid eq ${params.businessUnitId}&$select=systemuserid,fullname,domainname,businessunitid,isdisabled&$expand=businessunitid($select=name)`;
          }
  
          const result = await client.get(endpoint);
          const users = params.includeSubsidiaryUsers ? result : result.value;
  
          const formattedUsers = (Array.isArray(users) ? users : users?.value || []).map((user: any) => ({
            userId: user.systemuserid,
            fullName: user.fullname,
            domainName: user.domainname,
            businessUnitId: user.businessunitid,
            businessUnitName: user.businessunitid?.name,
            isDisabled: user.isdisabled
          }));
  
          return {
            content: [
              {
                type: "text",
                text: `Found ${formattedUsers.length} ${params.includeSubsidiaryUsers ? 'subsidiary ' : ''}users for business unit:\n\n${JSON.stringify(formattedUsers, null, 2)}`
              }
            ]
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error retrieving business unit users: ${error instanceof Error ? error.message : 'Unknown error'}`
              }
            ],
            isError: true
          };
        }
      }
    );
  }

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

  Calls the registration function during server initialization to register the tool.

  getBusinessUnitUsersTool(server, dataverseClient);