guardian_search_by_author
Search The Guardian's archives by a specific author, filtering articles by date, section, keywords, and sorting by relevance or publication date.
Instructions
Search Guardian articles by specific author/journalist
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| author | Yes | Author name to search for | |
| from_date | No | Start date (YYYY-MM-DD format) | |
| order_by | No | Sort order: 'newest', 'oldest', 'relevance' (default: 'newest') | |
| page | No | Page number (default: 1) | |
| page_size | No | Results per page, max 200 (default: 20) | |
| query | No | Additional search terms within author's articles | |
| section | No | Filter by section ID | |
| to_date | No | End date (YYYY-MM-DD format) |
Implementation Reference
- Main handler function that searches Guardian API for articles by author, filters by byline match, handles parameters like date range, section, pagination, and formats a detailed markdown response with article details.export async function guardianSearchByAuthor(client: GuardianClient, args: any): Promise<string> { const params = SearchByAuthorParamsSchema.parse(args); // Build search parameters - we'll search for the author name in the byline const searchParams: Record<string, any> = { 'show-fields': 'headline,standfirst,byline,publication,firstPublicationDate,wordcount', 'order-by': params.order_by || 'newest', 'page-size': params.page_size || 20, page: params.page || 1 }; // Combine author search with optional query if (params.query) { searchParams.q = `"${params.author}" ${params.query}`; } else { searchParams.q = `"${params.author}"`; } if (params.section) { searchParams.section = params.section; } if (params.from_date) { const fromDate = validateDate(params.from_date); if (!fromDate) { throw new Error(`Invalid from_date format: ${params.from_date}. Use YYYY-MM-DD format.`); } searchParams['from-date'] = fromDate; } if (params.to_date) { const toDate = validateDate(params.to_date); if (!toDate) { throw new Error(`Invalid to_date format: ${params.to_date}. Use YYYY-MM-DD format.`); } searchParams['to-date'] = toDate; } const response = await client.search(searchParams); const articles = response.response.results; // Filter to only articles where the author name appears in the byline const authorArticles = articles.filter(article => { const byline = article.fields?.byline || ''; return byline.toLowerCase().includes(params.author.toLowerCase()); }); if (authorArticles.length > 0) { const pagination = response.response; let result = `Found ${authorArticles.length} article(s) by ${params.author}:\n\n`; authorArticles.forEach((article, index) => { result += `**${index + 1}. ${article.webTitle || 'Untitled'}**\n`; if (article.fields) { const { fields } = article; if (fields.byline) { result += `By: ${fields.byline}\n`; } if (fields.firstPublicationDate) { const pubDate = fields.firstPublicationDate.substring(0, 10); result += `Published: ${pubDate}\n`; } if (fields.wordcount) { result += `Word count: ${fields.wordcount}\n`; } if (fields.standfirst) { result += `Summary: ${fields.standfirst}\n`; } } result += `Section: ${article.sectionName || 'Unknown'}\n`; result += `URL: ${article.webUrl || 'N/A'}\n\n`; }); if (pagination.pages > 1) { result += `\nPagination: Page ${pagination.currentPage} of ${pagination.pages}\n`; } return result; } else { return `No articles found by author '${params.author}'.`; } }
- src/types/guardian.ts:123-132 (schema)Zod schema defining and validating the input parameters for the guardian_search_by_author tool, matching the MCP inputSchema.export const SearchByAuthorParamsSchema = z.object({ author: z.string(), query: z.string().optional(), section: z.string().optional(), from_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), to_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), order_by: z.enum(['newest', 'oldest', 'relevance']).optional(), page_size: z.number().min(1).max(200).optional(), page: z.number().min(1).optional(), });
- src/tools/index.ts:31-31 (registration)Registration of the tool handler in the registerTools function, mapping 'guardian_search_by_author' to the guardianSearchByAuthor implementation.guardian_search_by_author: (args) => guardianSearchByAuthor(client, args),
- src/index.ts:307-350 (schema)MCP tool schema definition registered in ListToolsRequestHandler, providing the input schema, description, and name for the guardian_search_by_author tool.name: 'guardian_search_by_author', description: 'Search Guardian articles by specific author/journalist', inputSchema: { type: 'object', properties: { author: { type: 'string', description: 'Author name to search for', }, query: { type: 'string', description: "Additional search terms within author's articles", }, section: { type: 'string', description: 'Filter by section ID', }, from_date: { type: 'string', description: 'Start date (YYYY-MM-DD format)', }, to_date: { type: 'string', description: 'End date (YYYY-MM-DD format)', }, order_by: { type: 'string', description: "Sort order: 'newest', 'oldest', 'relevance' (default: 'newest')", enum: ['newest', 'oldest', 'relevance'], }, page_size: { type: 'integer', description: 'Results per page, max 200 (default: 20)', minimum: 1, maximum: 200, }, page: { type: 'integer', description: 'Page number (default: 1)', minimum: 1, }, }, required: ['author'], },
- src/tools/index.ts:10-10 (registration)Import of the guardianSearchByAuthor handler function used in tool registration.import { guardianSearchByAuthor } from './guardian-search-by-author.js';