guardian_longread

Instructions

Implementation Reference

• src/tools/guardian-longread.ts:5-41 (handler)

  Main handler function that implements the guardian_longread tool logic: validates input, constructs search params for Long Read tag, calls GuardianClient.search, formats response.

  export async function guardianLongread(client: GuardianClient, args: any): Promise<string> {
    const params = LongReadParamsSchema.parse(args);
  
    // Search for Long Read articles using the specific tag
    const searchParams: Record<string, any> = {
      tag: 'news/series/the-long-read',
      'page-size': params.page_size || 10,
      page: params.page || 1,
      'show-fields': 'headline,standfirst,body,byline,thumbnail,publication,firstPublicationDate'
    };
  
    if (params.query) {
      searchParams.q = params.query;
    }
    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;
    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:85-91 (schema)

  Zod schema used for input validation in the handler: LongReadParamsSchema.

  export const LongReadParamsSchema = z.object({
    query: 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(),
    page_size: z.number().min(1).max(200).optional(),
    page: z.number().min(1).optional(),
  });

• src/tools/index.ts:21-39 (registration)

  Registration of all tool handlers including guardian_longread in the registerTools function, which maps tool names to handler wrappers.

  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:142-172 (schema)

  MCP protocol tool schema definition for guardian_longread provided in ListTools response.

    name: 'guardian_longread',
    description: 'Search specifically for articles from The Long Read series',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search terms within Long Read articles',
        },
        from_date: {
          type: 'string',
          description: 'Start date (YYYY-MM-DD format)',
        },
        to_date: {
          type: 'string',
          description: 'End date (YYYY-MM-DD format)',
        },
        page_size: {
          type: 'integer',
          description: 'Results per page, max 200 (default: 10)',
          minimum: 1,
          maximum: 200,
        },
        page: {
          type: 'integer',
          description: 'Page number (default: 1)',
          minimum: 1,
        },
      },
    },
  },