guardian-mcp-server

Instructions

Implementation Reference

• src/tools/guardian-topic-trends.ts:17-151 (handler)

  The core handler function that implements the guardian_topic_trends tool. It validates input, generates time periods, performs Guardian API searches for each topic/period, calculates trends, percentages, strengths, correlations, and seasonal patterns, then formats a comprehensive report.
  export async function guardianTopicTrends(client: GuardianClient, args: any): Promise<string> { const params = TopicTrendsParamsSchema.parse(args); const fromDate = validateDate(params.from_date); const toDate = validateDate(params.to_date); if (!fromDate || !toDate) { throw new Error('Invalid date format. Use YYYY-MM-DD format.'); } const interval = params.interval || 'quarter'; // Generate time periods const periods = generateTimePeriods(fromDate, toDate, interval); let result = `Topic Trends Analysis (${fromDate} to ${toDate})\n`; result += `Comparing: ${params.topics.join(', ')}\n\n`; const topicData: TopicTrendData[] = []; // Analyze each topic for (const topic of params.topics) { const topicTrend: TopicTrendData = { topic: topic, periods: [], totalArticles: 0, trend: 'stable', trendStrength: 0 }; for (const period of periods) { const searchParams: Record<string, any> = { q: `"${topic}"`, 'from-date': period.start, 'to-date': period.end, 'page-size': 1, // We only need the count 'show-fields': 'headline' }; try { const response = await client.search(searchParams); const count = response.response.total; topicTrend.periods.push({ period: period.label, count: count, percentage: 0 // Will calculate after getting all data }); topicTrend.totalArticles += count; // Rate limiting delay await new Promise(resolve => setTimeout(resolve, 100)); } catch (error) { topicTrend.periods.push({ period: period.label, count: 0, percentage: 0 }); } } // Calculate percentages and trend topicTrend.periods.forEach(p => { p.percentage = topicTrend.totalArticles > 0 ? (p.count / topicTrend.totalArticles) * 100 : 0; }); topicTrend.trend = calculateTrend(topicTrend.periods.map(p => p.count)); topicTrend.trendStrength = calculateTrendStrength(topicTrend.periods.map(p => p.count)); topicData.push(topicTrend); } // Display overall statistics result += `**Overall Statistics**\n`; topicData.forEach(topic => { const trendIcon = getTrendIcon(topic.trend, topic.trendStrength); result += `• ${topic.topic}: ${topic.totalArticles} articles ${trendIcon}\n`; }); result += '\n'; // Show period-by-period breakdown result += `**Period Breakdown**\n`; periods.forEach((period, index) => { result += `\n**${period.label}**\n`; // Sort topics by count for this period const periodData = topicData .map(topic => ({ topic: topic.topic, count: topic.periods[index].count })) .sort((a, b) => b.count - a.count); periodData.forEach((data, rank) => { const rankIcon = rank === 0 ? '🥇' : rank === 1 ? '🥈' : rank === 2 ? '🥉' : ' '; result += `${rankIcon} ${data.topic}: ${data.count} articles\n`; }); }); // Comparative analysis result += `\n**Comparative Analysis**\n`; // Find the dominant topic const dominantTopic = topicData.reduce((prev, current) => prev.totalArticles > current.totalArticles ? prev : current ); result += `• Most Covered: "${dominantTopic.topic}" (${dominantTopic.totalArticles} articles)\n`; // Find the fastest growing const fastestGrowing = topicData .filter(t => t.trend === 'increasing') .sort((a, b) => b.trendStrength - a.trendStrength)[0]; if (fastestGrowing) { result += `• Fastest Growing: "${fastestGrowing.topic}" (${fastestGrowing.trendStrength.toFixed(1)}% increase)\n`; } // Find correlations (topics that trend together) const correlations = findCorrelations(topicData); if (correlations.length > 0) { result += `• Correlated Topics: ${correlations.join(', ')}\n`; } // Seasonal patterns if (interval === 'quarter' || interval === 'month') { const seasonalInsights = analyzeSeasonalPatterns(topicData, interval); if (seasonalInsights) { result += `• Seasonal Pattern: ${seasonalInsights}\n`; } } return result; }
• src/types/guardian.ts:168-173 (schema)

  Zod validation schema for the tool's input parameters, used in the handler for parsing and validation.
  export const TopicTrendsParamsSchema = z.object({ topics: z.array(z.string()).min(1).max(5), from_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), to_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), interval: z.enum(['month', 'quarter', 'year']).optional(), });
• src/tools/index.ts:36-36 (registration)

  Registers the guardianTopicTrends handler function under the 'guardian_topic_trends' key in the tools registry returned by registerTools.
  guardian_topic_trends: (args) => guardianTopicTrends(client, args),
• src/index.ts:458-489 (registration)

  MCP tool registration in the ListTools response, including name, description, and input schema matching the zod schema.
  { name: 'guardian_topic_trends', description: 'Compare trends of multiple topics over time with correlation analysis', inputSchema: { type: 'object', properties: { topics: { type: 'array', items: { type: 'string', }, description: 'List of topics/keywords to compare (max 5)', minItems: 1, maxItems: 5, }, from_date: { type: 'string', description: 'Start date (YYYY-MM-DD)', }, to_date: { type: 'string', description: 'End date (YYYY-MM-DD)', }, interval: { type: 'string', description: 'Time interval for comparison', enum: ['month', 'quarter', 'year'], }, }, required: ['topics', 'from_date', 'to_date'], }, },
• src/tools/guardian-topic-trends.ts:159-214 (helper)

  Helper function to generate time periods based on interval for trend analysis.
  function generateTimePeriods(fromDate: string, toDate: string, interval: string): TimePeriod[] { const periods: TimePeriod[] = []; const start = new Date(fromDate); const end = new Date(toDate); let current = new Date(start); while (current <= end) { let periodEnd = new Date(current); let label = ''; switch (interval) { case 'month': periodEnd = new Date(current.getFullYear(), current.getMonth() + 1, 0); if (periodEnd > end) periodEnd = new Date(end); label = current.toLocaleDateString('en-US', { month: 'long', year: 'numeric' }); break; case 'quarter': const quarter = Math.floor(current.getMonth() / 3) + 1; periodEnd = new Date(current.getFullYear(), quarter * 3, 0); if (periodEnd > end) periodEnd = new Date(end); label = `Q${quarter} ${current.getFullYear()}`; break; case 'year': periodEnd = new Date(current.getFullYear(), 11, 31); if (periodEnd > end) periodEnd = new Date(end); label = current.getFullYear().toString(); break; } periods.push({ start: current.toISOString().substring(0, 10), end: periodEnd.toISOString().substring(0, 10), label: label }); // Move to next period switch (interval) { case 'month': current.setMonth(current.getMonth() + 1); current.setDate(1); break; case 'quarter': current.setMonth(current.getMonth() + 3); current.setDate(1); break; case 'year': current.setFullYear(current.getFullYear() + 1); current.setMonth(0); current.setDate(1); break; } } return periods; }