search_articles

Instructions

Implementation Reference

• src/nytimes_mcp/tools.py:31-76 (handler)

  Core handler function implementing the search_articles tool logic: parameter validation, NYT API request, and response formatting.

  async def search_articles(
      query: str,
      sort: SortOrder = "best",
      begin_date: str | None = None,
      end_date: str | None = None,
      page: int | None = None,
  ) -> dict:
      """
      Search New York Times articles by query, date range, and other criteria.
  
      Args:
          query: Search query string
          sort: Sort order - "best", "newest", "oldest", or "relevance" (default: "best")
          begin_date: Start date in YYYYMMDD format (optional)
          end_date: End date in YYYYMMDD format (optional)
          page: Page number for pagination (10 articles per page), 0-indexed, max=100 (optional)
  
      Returns:
          Formatted response with articles array containing headline, snippet, web_url, and pub_date
      """
      params = {
          "q": query.strip(),
          "sort": sort,
      }
  
      # Add optional date parameters only if specified
      if begin_date and len(begin_date) == 8:
          params["begin_date"] = begin_date
      elif begin_date:
          raise ValueError("begin_date must be in YYYYMMDD format.")
      if end_date and len(end_date) == 8:
          params["end_date"] = end_date
      elif end_date:
          raise ValueError("end_date must be in YYYYMMDD format.")
  
      # Only add page if it's greater than 0
      if page and page > 0 and page <= 100:
          params["page"] = str(page)
      elif page and page != 0:
          raise ValueError("Page number must be between 0 and 100.")
  
      client = get_client()
      response = await client.make_nyt_request("search/v2/articlesearch.json", params)
  
      return format_articles_response(response)

• src/nytimes_mcp/server.py:12-34 (registration)

  Tool registration using @mcp.tool() decorator, defines schema via type hints and docstring, thin wrapper delegating to tools.py implementation.

  @mcp.tool()
  async def search_articles(
      query: str,
      sort: tools.SortOrder = "best",
      begin_date: str | None = None,
      end_date: str | None = None,
      page: int | None = None,
  ) -> dict:
      """
      Search New York Times articles by query, date range, and other criteria.
  
      Args:
          query: Search query string
          sort: Sort order - "newest" or "oldest" (default: "newest")
          begin_date: Start date in YYYYMMDD format (optional)
          end_date: End date in YYYYMMDD format (optional)
          page: Page number for pagination, 0-indexed (optional)
  
      Returns:
          Formatted response with articles array containing headline, snippet, web_url, and pub_date
      """
      return await tools.search_articles(query, sort, begin_date, end_date, page)

• src/nytimes_mcp/tools.py:25-28 (schema)

  Type definitions (Literals) for tool parameters, specifically SortOrder used in search_articles.

  type NewsSource = Literal["nyt", "inyt", "all"]
  type SortOrder = Literal["best", "newest", "oldest", "relevance"]
  type PopularityType = Literal["viewed", "shared", "emailed"]
  type PopularityPeriod = Literal["1", "7", "30"]

• src/nytimes_mcp/utils.py:6-29 (helper)

  Helper function to format the NYT article search API response into a simplified structure used by search_articles.

  def format_articles_response(response: dict[str, Any]) -> dict[str, Any]:
      """
      Format article search response to extract essential fields.
  
      Args:
          response: Raw NYT article search API response
  
      Returns:
          Formatted response with articles array and total_hits
      """
      if "response" in response and "docs" in response["response"]:
          return {
              "articles": [
                  {
                      "headline": doc.get("headline", {}).get("main", ""),
                      "snippet": doc.get("snippet", ""),
                      "web_url": doc.get("web_url", ""),
                      "pub_date": doc.get("pub_date", ""),
                  }
                  for doc in response["response"]["docs"]
              ],
              "total_hits": response["response"].get("meta", {}).get("hits", 0),
          }
      return response

• src/nytimes_mcp/tools.py:17-23 (helper)

  Shared NYT client factory used by search_articles to make API requests.

  def get_client() -> NytClient:
      """Get or create the shared HTTP client."""
      global _nyt_client
      if _nyt_client is None:
          _nyt_client = NytClient()
      return _nyt_client