guardian-mcp-server

Instructions

Implementation Reference

• src/tools/guardian-search-by-author.ts:5-90 (handler)

  The core handler function that executes the tool logic: parses input params, constructs Guardian search query for articles by author, filters results by byline match, and formats output 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, used in the handler for parsing args.

  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:21-39 (registration)

  Tool registration function that maps the 'guardian_search_by_author' name to the handler function, used by the MCP server.

  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:307-350 (registration)

  MCP tool listing registration including name, description, and input schema for the ListToolsRequest, advertised to MCP clients.

  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/guardian-search-by-author.ts:3-3 (helper)

  Import of helper function used for date validation in the handler.

  import { validateDate } from '../utils/formatters.js';