guardian-mcp-server

Instructions

Implementation Reference

• src/tools/guardian-browse-section.ts:5-26 (handler)

  The main handler function that parses input args using BrowseSectionParamsSchema, constructs Guardian API search parameters for a specific section and recent days, calls client.search(), and formats the article response with truncation.

  export async function guardianBrowseSection(client: GuardianClient, args: any): Promise<string> {
    const params = BrowseSectionParamsSchema.parse(args);
  
    const daysBack = params.days_back || 7;
    const fromDate = calculateDateFromDaysBack(daysBack);
  
    const searchParams: Record<string, any> = {
      section: params.section,
      'from-date': fromDate,
      'order-by': 'newest',
      'page-size': params.page_size || 20,
      'show-fields': 'headline,standfirst,byline,publication,firstPublicationDate'
    };
  
    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:100-104 (schema)

  Zod schema for validating input parameters: requires 'section', optional 'days_back' (1-365), 'page_size' (1-200). Used in handler for runtime validation.

  export const BrowseSectionParamsSchema = z.object({
    section: z.string(),
    days_back: z.number().min(1).max(365).optional(),
    page_size: z.number().min(1).max(200).optional(),
  });

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

  Registration function that maps tool names to handler wrappers, including 'guardian_browse_section' at line 27.

  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:202-226 (registration)

  MCP protocol tool registration in ListToolsResponse, defining name, description, and inputSchema matching the Zod schema.

    name: 'guardian_browse_section',
    description: 'Browse recent articles from a specific Guardian section',
    inputSchema: {
      type: 'object',
      properties: {
        section: {
          type: 'string',
          description: 'Section ID (use guardian_get_sections to find valid IDs)',
        },
        days_back: {
          type: 'integer',
          description: 'How many days back to search (default: 7)',
          minimum: 1,
          maximum: 365,
        },
        page_size: {
          type: 'integer',
          description: 'Number of results, max 200 (default: 20)',
          minimum: 1,
          maximum: 200,
        },
      },
      required: ['section'],
    },
  },