compare-audience-influencers

Instructions

Implementation Reference

• src/audienseClient.ts:189-234 (handler)

  Core handler function that constructs the Audiense API endpoint for comparing audience influencers, fetches the data, and enriches the top 100 influencers with Twitter/X user details.

  export async function compareAudienceInfluencers(
      audience_influencers_id: string,
      baseline_audience_influencers_id: string,
      cursor?: number,
      count?: number,
      bio_keyword?: string,
      entity_type?: "person" | "brand",
      followers_min?: number,
      followers_max?: number,
      categories?: string[],
      countries?: string[]
  ): Promise<{ cursor: { next: number; prev: number }; influencers: any[] } | null> {
      const queryParams = new URLSearchParams();
  
      if (cursor !== undefined) queryParams.append("cursor", cursor.toString());
      if (count !== undefined) queryParams.append("count", count.toString());
      if (bio_keyword) queryParams.append("bio_keyword", bio_keyword);
      if (entity_type) queryParams.append("entity_type", entity_type);
      if (followers_min !== undefined) queryParams.append("followers_min", followers_min.toString());
      if (followers_max !== undefined) queryParams.append("followers_max", followers_max.toString());
      if (categories && categories.length > 0) queryParams.append("categories", categories.join(","));
      if (countries && countries.length > 0) queryParams.append("countries", countries.join(","));
  
      const endpoint = `/audience_influencers/${audience_influencers_id}/compared_to/${baseline_audience_influencers_id}?${queryParams.toString()}`;
  
      const data = await makeAudienseRequest<{ cursor: { next: number; prev: number }; influencers: { id: string; affinity: number; baseline_affinity: number; uniqueness: number }[] }>(endpoint);
  
      if (!data || !data.influencers.length) {
          return data;
      }
  
      // Get the first 100 influencers for enrichment
      const influencerIds = data.influencers.slice(0, 100).map((influencer) => influencer.id);
      const twitterData = await fetchTwitterUserDetails(influencerIds);
  
      // Merge Twitter details into influencer data
      const enrichedInfluencers = data.influencers.map((influencer) => ({
          ...influencer,
          twitter: twitterData[influencer.id] || null, // Add Twitter data if available
      }));
  
      return {
          cursor: data.cursor,
          influencers: enrichedInfluencers,
      };
  }

• src/index.ts:194-257 (registration)

  MCP server.tool registration for the 'compare-audience-influencers' tool, including description, input schema (Zod validation), and thin wrapper handler that calls the core compareAudienceInfluencers function and formats the MCP response.

  server.tool(
      "compare-audience-influencers",
      `Compares the influencers of an audience with a baseline audience. The baseline is determined as follows: 
      If the selection was the full audience and a single country represents more than 50% of the audience, that country is used as the baseline.
      Otherwise, the Global baseline is applied. If the selection was a specific segment, the full audience is used as the baseline.
      Each influencer comparison includes: 
          - Affinity (%) - The level of alignment between the influencer and the audience. Baseline Affinity (%)
          - The influencer’s affinity within the baseline audience. Uniqueness Score
          - A measure of how distinct the influencer is within the selected audience compared to the baseline.
      `,
      {
          audience_influencers_id: z.string().describe("The ID of the audience influencers."),
          baseline_audience_influencers_id: z.string().describe("The ID of the baseline audience influencers."),
          cursor: z.number().optional().describe("Cursor for pagination."),
          count: z.number().optional().describe("Number of items per page (default: 200)."),
          bio_keyword: z.string().optional().describe("Keyword to filter influencers by their biography."),
          entity_type: z.enum(["person", "brand"]).optional().describe("Filter by entity type (person or brand)."),
          followers_min: z.number().optional().describe("Minimum number of followers."),
          followers_max: z.number().optional().describe("Maximum number of followers."),
          categories: z.array(z.string()).optional().describe("Filter influencers by categories."),
          countries: z.array(z.string()).optional().describe("Filter influencers by country ISO codes."),
      },
      async ({ audience_influencers_id, baseline_audience_influencers_id, cursor, count, bio_keyword, entity_type, followers_min, followers_max, categories, countries }) => {
          const data = await compareAudienceInfluencers(
              audience_influencers_id,
              baseline_audience_influencers_id,
              cursor,
              count,
              bio_keyword,
              entity_type,
              followers_min,
              followers_max,
              categories,
              countries
          );
  
          if (!data || !data.influencers.length) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `No influencers found for comparison between ${audience_influencers_id} and ${baseline_audience_influencers_id}.`,
                      },
                  ],
              };
          }
  
          const influencersText = data.influencers
              .map(
                  (influencer) =>
                      `ID: ${influencer.id}\nAffinity: ${influencer.affinity}%\nBaseline Affinity: ${influencer.baseline_affinity}%\nUniqueness: ${influencer.uniqueness}%`
              )
              .join("\n\n");
  
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(data, null, 2),
                  },
              ],
          };
      }
  );

• src/index.ts:204-215 (schema)

  Zod schema for input parameters validation in the MCP tool registration.

  {
      audience_influencers_id: z.string().describe("The ID of the audience influencers."),
      baseline_audience_influencers_id: z.string().describe("The ID of the baseline audience influencers."),
      cursor: z.number().optional().describe("Cursor for pagination."),
      count: z.number().optional().describe("Number of items per page (default: 200)."),
      bio_keyword: z.string().optional().describe("Keyword to filter influencers by their biography."),
      entity_type: z.enum(["person", "brand"]).optional().describe("Filter by entity type (person or brand)."),
      followers_min: z.number().optional().describe("Minimum number of followers."),
      followers_max: z.number().optional().describe("Maximum number of followers."),
      categories: z.array(z.string()).optional().describe("Filter influencers by categories."),
      countries: z.array(z.string()).optional().describe("Filter influencers by country ISO codes."),
  },