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])); } }