guardian_lookback
Retrieve top stories from The Guardian archives by specifying a date or date range, with options to filter by section and adjust the number of results.
Instructions
Find top stories from a specific date or date range
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Specific date (YYYY-MM-DD) or start of range | |
| end_date | No | End date for range (YYYY-MM-DD) | |
| page_size | No | Number of results (default: 20) | |
| section | No | Filter by section |
Implementation Reference
- src/tools/guardian-lookback.ts:5-42 (handler)The core handler function implementing the guardian_lookback tool. Parses args with LookbackParamsSchema, validates dates, constructs Guardian search API parameters ordered by 'newest', fetches results, and formats them with truncation.export async function guardianLookback(client: GuardianClient, args: any): Promise<string> { const params = LookbackParamsSchema.parse(args); const fromDate = validateDate(params.date); if (!fromDate) { throw new Error(`Invalid date format: ${params.date}. Use YYYY-MM-DD format.`); } const searchParams: Record<string, any> = { 'from-date': fromDate, 'order-by': 'newest', 'page-size': params.page_size || 20, 'show-fields': 'headline,standfirst,byline,publication,firstPublicationDate' }; if (params.end_date) { const toDate = validateDate(params.end_date); if (!toDate) { throw new Error(`Invalid end_date format: ${params.end_date}. Use YYYY-MM-DD format.`); } searchParams['to-date'] = toDate; } else { // If no end date, use the same date searchParams['to-date'] = fromDate; } if (params.section) { searchParams.section = params.section; } const response = await client.search(searchParams); const articles = response.response.results; const pagination = response.response; // For search results, default to truncated content for performance const formatOptions = { truncate: true, maxLength: 500 }; return formatArticleResponse(articles, pagination, formatOptions); }
- src/types/guardian.ts:93-98 (schema)Zod schema used internally by the handler for input validation: requires 'date' in YYYY-MM-DD, optional 'end_date', 'section', 'page_size'.export const LookbackParamsSchema = z.object({ date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/), end_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(), section: z.string().optional(), page_size: z.number().min(1).max(200).optional(), });
- src/index.ts:176-199 (schema)Input schema for guardian_lookback tool as exposed in MCP ListTools response.inputSchema: { type: 'object', properties: { date: { type: 'string', description: 'Specific date (YYYY-MM-DD) or start of range', }, end_date: { type: 'string', description: 'End date for range (YYYY-MM-DD)', }, section: { type: 'string', description: 'Filter by section', }, page_size: { type: 'integer', description: 'Number of results (default: 20)', minimum: 1, maximum: 200, }, }, required: ['date'], },
- src/tools/index.ts:26-26 (registration)Registration of the guardian_lookback tool handler in the registerTools function, wrapping the imported guardianLookback.guardian_lookback: (args) => guardianLookback(client, args),
- src/index.ts:173-200 (registration)MCP tool registration/declaration including name, description, and input schema in the ListTools response.{ name: 'guardian_lookback', description: 'Find top stories from a specific date or date range', inputSchema: { type: 'object', properties: { date: { type: 'string', description: 'Specific date (YYYY-MM-DD) or start of range', }, end_date: { type: 'string', description: 'End date for range (YYYY-MM-DD)', }, section: { type: 'string', description: 'Filter by section', }, page_size: { type: 'integer', description: 'Number of results (default: 20)', minimum: 1, maximum: 200, }, }, required: ['date'], }, },