guardian-mcp-server

Instructions

Implementation Reference

• src/tools/guardian-lookback.ts:5-42 (handler)

  The core handler function that implements the guardian_lookback tool logic: validates params, constructs search query for a date range ordered by newest, fetches from Guardian API, and formats the response.

  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 for validating input parameters to the guardian_lookback tool.

  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/tools/index.ts:21-39 (registration)

  Registers all tools including guardian_lookback, mapping the tool name to the handler function with the Guardian client.

  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:174-200 (registration)

  MCP protocol registration of the guardian_lookback tool, including its name, description, and input schema for the ListTools handler.

    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'],
    },
  },