Audiense Insights MCP Server

Instructions

Implementation Reference

• src/reportSummary.ts:93-158 (handler)

  Core handler function that generates the comprehensive report summary by fetching report info, top insights, and top influencers for each segment.

  export async function generateReportSummary(reportId: string): Promise<ReportSummaryResponse | null> {
      const insightTypes = ['bio_keyword', 'country', 'age', 'city', 'language', 'gender', 'interest'];
      
      try {
          // Fetch the report info
          const reportInfo = await getReportInfo(reportId);
          
          if (!reportInfo) {
              console.error(`Failed to retrieve report info for ID: ${reportId}`);
              return null;
          }
  
          if (reportInfo.status === "pending") {
              return {
                  title: reportInfo.title,
                  status: reportInfo.status,
                  message: "Report is still processing. Try again later."
              };
          }
  
          if (!reportInfo.segments || reportInfo.segments.length === 0) {
              return {
                  title: reportInfo.title,
                  status: reportInfo.status,
                  message: "Report has no segments to analyze."
              };
          }
  
          // Get the full audience ID for influencer comparison
          const fullAudienceId = reportInfo.full_audience?.audience_influencers_id;
  
          // Process all segments in parallel
          const segmentPromises = reportInfo.segments.map(async segment => {
              const segmentInfluencersId = segment.audience_influencers_id;
              
              // Only attempt to get influencers if we have valid IDs
              const influencers = fullAudienceId && segmentInfluencersId ? 
                  await getTopInfluencers(segmentInfluencersId, fullAudienceId) : 
                  null;
              const insights = await getTopInsights(segment.id, insightTypes);
          
              return {
                  id: segment.id,
                  title: segment.title,
                  size: segment.size,
                  insights,
                  influencers
              };
          });
  
          const segments = await Promise.all(segmentPromises);
  
          // Return the complete report summary
          return {
              id: reportId,
              title: reportInfo.title,
              segmentation_type: reportInfo.segmentation_type,
              full_audience_size: reportInfo.full_audience?.size,
              segments,
              links: reportInfo.links
          };
      } catch (error) {
          console.error(`Error generating report summary for ${reportId}:`, error);
          return null;
      }
  }

• src/index.ts:358-398 (registration)

  MCP tool registration for 'report-summary', including description, input schema, and thin wrapper handler that calls generateReportSummary and formats the response.

  server.tool(
      "report-summary",
      "Generates a comprehensive summary of an Audiense report, including segment details, top insights, and influencers.",
      {
          report_id: z.string().describe("The ID of the intelligence report to summarize."),
      },
      async ({ report_id }) => {
          const data = await generateReportSummary(report_id);
  
          if (!data) {
              return {
                  content: [
                      {
                          type: "text",
                          text: `Failed to generate summary for report ID: ${report_id}.`,
                      },
                  ],
              };
          }
  
          if (data.message) {
              return {
                  content: [
                      {
                          type: "text",
                          text: data.message,
                      },
                  ],
              };
          }
  
          return {
              content: [
                  {
                      type: "text",
                      text: JSON.stringify(data, null, 2)
                  }
              ]
          };
      }
  );

• src/index.ts:361-363 (schema)

  Zod input schema defining the required 'report_id' parameter as a string.

  {
      report_id: z.string().describe("The ID of the intelligence report to summarize."),
  },

• src/types.ts:57-66 (schema)

  TypeScript interface defining the structure of the report summary response.

  export type ReportSummaryResponse = {
      id?: string;
      title: string;
      status?: string;
      segmentation_type?: string;
      full_audience_size?: number;
      segments?: SegmentSummary[];
      links?: { app?: string; public?: string };
      message?: string;
  };

• src/reportSummary.ts:11-40 (helper)

  Helper function to fetch and rank top insights (e.g., demographics) for an audience segment.

  async function getTopInsights(
      audienceId: string,
      insightTypes: string[],
      topCount: number = 5
  ): Promise<Record<string, InsightValue[] | null>> {
      try {
          const insightsData = await getAudienceInsights(audienceId, insightTypes);
          
          if (!insightsData || !insightsData.insights.length) {
              console.error(`No insights found for audience ${audienceId} and insight types ${insightTypes.join(',')}`);
              return Object.fromEntries(insightTypes.map(type => [type, null]));
          }
  
          // Process each insight type
          const result: Record<string, InsightValue[] | null> = {};
          
          for (const insight of insightsData.insights) {
              // Sort values by percentage (descending) and take top N
              result[insight.name] = insight.values
                  .sort((a, b) => parseFloat(b.value) - parseFloat(a.value))
                  .slice(0, topCount)
                  .map(v => ({ key: v.key, value: parseFloat(v.value) }));
          }
          
          return result;
      } catch (error) {
          console.error(`Error fetching insights for audience ${audienceId}:`, error);
          return Object.fromEntries(insightTypes.map(type => [type, null]));
      }
  }