guardian-mcp-server

Instructions

Implementation Reference

• src/tools/guardian-author-profile.ts:14-187 (handler)

  The core handler function that implements the guardian_author_profile tool. It validates input, determines date range, searches for author articles using GuardianClient, computes statistics (articles, sections, monthly output, word count, tags, headlines), analyzes patterns, and returns a formatted profile report.
  export async function guardianAuthorProfile(client: GuardianClient, args: any): Promise<string> { const params = AuthorProfileParamsSchema.parse(args); // Handle analysis period - can be year or date range let fromDate: string; let toDate: string; if (params.analysis_period && !params.from_date && !params.to_date) { // Handle year format like "2024" const year = params.analysis_period; if (/^\d{4}$/.test(year)) { fromDate = `${year}-01-01`; toDate = `${year}-12-31`; } else { throw new Error('analysis_period must be a 4-digit year (e.g., "2024")'); } } else if (params.from_date && params.to_date) { fromDate = validateDate(params.from_date) || params.from_date; toDate = validateDate(params.to_date) || params.to_date; } else { // Default to last year const now = new Date(); fromDate = `${now.getFullYear() - 1}-01-01`; toDate = `${now.getFullYear() - 1}-12-31`; } if (!validateDate(fromDate) || !validateDate(toDate)) { throw new Error('Invalid date format. Use YYYY-MM-DD format.'); } let result = `Author Profile: ${params.author} (${fromDate} to ${toDate})\n\n`; // Search for all articles by the author in the period const searchParams: Record<string, any> = { q: `"${params.author}"`, 'from-date': fromDate, 'to-date': toDate, 'page-size': 200, // Get as many as possible for analysis 'show-fields': 'headline,byline,firstPublicationDate,wordcount,standfirst', 'show-tags': 'keyword,type', 'order-by': 'newest' }; const response = await client.search(searchParams); const allArticles = response.response.results; // Filter to only articles where the author name appears in the byline const authorArticles = allArticles.filter(article => { const byline = article.fields?.byline || ''; return byline.toLowerCase().includes(params.author.toLowerCase()); }); if (authorArticles.length === 0) { return `No articles found for author "${params.author}" in the specified period.`; } const stats: AuthorStats = { totalArticles: authorArticles.length, sectionCoverage: {}, monthlyOutput: {}, averageWordCount: 0, topTags: {}, recentHeadlines: [] }; // Analyze the articles let totalWords = 0; let wordCountArticles = 0; authorArticles.forEach(article => { // Section coverage const section = article.sectionName || 'Unknown'; stats.sectionCoverage[section] = (stats.sectionCoverage[section] || 0) + 1; // Monthly output if (article.fields?.firstPublicationDate) { const date = new Date(article.fields.firstPublicationDate); const monthKey = date.toLocaleDateString('en-US', { month: 'long', year: 'numeric' }); stats.monthlyOutput[monthKey] = (stats.monthlyOutput[monthKey] || 0) + 1; } // Word count analysis if (article.fields?.wordcount && !isNaN(Number(article.fields.wordcount))) { totalWords += Number(article.fields.wordcount); wordCountArticles++; } // Tag analysis if (article.tags) { article.tags.forEach(tag => { if (tag.type === 'keyword') { stats.topTags[tag.webTitle] = (stats.topTags[tag.webTitle] || 0) + 1; } }); } // Recent headlines (first 5) if (stats.recentHeadlines.length < 5) { stats.recentHeadlines.push(article.webTitle || 'Untitled'); } }); stats.averageWordCount = wordCountArticles > 0 ? Math.round(totalWords / wordCountArticles) : 0; // Format the results result += `**Publishing Statistics**\n`; result += `• Total Articles: ${stats.totalArticles}\n`; result += `• Average Word Count: ${stats.averageWordCount} words\n`; const avgPerMonth = (stats.totalArticles / 12).toFixed(1); result += `• Average Output: ${avgPerMonth} articles per month\n\n`; // Section coverage result += `**Section Coverage**\n`; const sortedSections = Object.entries(stats.sectionCoverage) .sort(([,a], [,b]) => b - a) .slice(0, 8); sortedSections.forEach(([section, count]) => { const percentage = ((count / stats.totalArticles) * 100).toFixed(1); result += `• ${section}: ${count} articles (${percentage}%)\n`; }); result += '\n'; // Monthly activity (show top 6 months) result += `**Most Active Months**\n`; const sortedMonths = Object.entries(stats.monthlyOutput) .sort(([,a], [,b]) => b - a) .slice(0, 6); sortedMonths.forEach(([month, count]) => { result += `• ${month}: ${count} articles\n`; }); result += '\n'; // Top topics/tags result += `**Top Topics**\n`; const sortedTags = Object.entries(stats.topTags) .sort(([,a], [,b]) => b - a) .slice(0, 10); sortedTags.forEach(([tag, count]) => { result += `• ${tag}: ${count} articles\n`; }); result += '\n'; // Recent work result += `**Recent Headlines**\n`; stats.recentHeadlines.forEach((headline, index) => { result += `${index + 1}. ${headline}\n`; }); // Writing patterns analysis result += `\n**Writing Patterns**\n`; // Determine writing style based on word count if (stats.averageWordCount < 400) { result += `• Style: Brief news reporting (avg. ${stats.averageWordCount} words)\n`; } else if (stats.averageWordCount < 800) { result += `• Style: Standard journalism (avg. ${stats.averageWordCount} words)\n`; } else { result += `• Style: Long-form analysis (avg. ${stats.averageWordCount} words)\n`; } // Specialization analysis const topSection = sortedSections[0]; if (topSection && (topSection[1] / stats.totalArticles) > 0.5) { result += `• Specialization: ${topSection[0]} specialist (${((topSection[1] / stats.totalArticles) * 100).toFixed(1)}% coverage)\n`; } else { result += `• Specialization: Multi-section correspondent\n`; } return result; }
• src/types/guardian.ts:161-166 (schema)

  Zod schema used for input validation in the handler. Defines required 'author' and optional date parameters.
  export const AuthorProfileParamsSchema = z.object({ author: z.string(), analysis_period: z.string().optional(), // Can be year like "2024" or date range from_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), to_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), });
• src/tools/index.ts:21-40 (registration)

  Tool registration in the registerTools function that maps 'guardian_author_profile' to the handler.
  export function registerTools(client: GuardianClient): Record<string, ToolHandler> { return { guardian_search: (args) => guardianSearch(client, args), guardian_get_article: (args) => guardianGetArticle(client, args), guardian_longread: (args) => guardianLongread(client, args), guardian_lookback: (args) => guardianLookback(client, args), guardian_browse_section: (args) => guardianBrowseSection(client, args), guardian_get_sections: (args) => guardianGetSections(client, args), guardian_search_tags: (args) => guardianSearchTags(client, args), guardian_search_by_length: (args) => guardianSearchByLength(client, args), guardian_search_by_author: (args) => guardianSearchByAuthor(client, args), guardian_find_related: (args) => guardianFindRelated(client, args), guardian_get_article_tags: (args) => guardianGetArticleTags(client, args), guardian_content_timeline: (args) => guardianContentTimeline(client, args), guardian_author_profile: (args) => guardianAuthorProfile(client, args), guardian_topic_trends: (args) => guardianTopicTrends(client, args), guardian_top_stories_by_date: (args) => guardianTopStoriesByDate(client, args), guardian_recommend_longreads: (args) => guardianRecommendLongreads(client, args), }; }
• src/index.ts:432-457 (registration)

  MCP protocol tool registration including name, description, and input schema definition in the ListTools response.
  { name: 'guardian_author_profile', description: 'Generate comprehensive profile analysis for a Guardian journalist', inputSchema: { type: 'object', properties: { author: { type: 'string', description: 'Author/journalist name to analyze', }, analysis_period: { type: 'string', description: 'Year to analyze (e.g., "2024") or use from_date/to_date', }, from_date: { type: 'string', description: 'Start date (YYYY-MM-DD) - alternative to analysis_period', }, to_date: { type: 'string', description: 'End date (YYYY-MM-DD) - alternative to analysis_period', }, }, required: ['author'], }, },