NYTimes MCP

Instructions

Implementation Reference

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

  Core implementation of the search_articles tool, handling parameters, validation, API request to NYT article search endpoint, 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)

  FastMCP registration of the search_articles tool using @mcp.tool() decorator, defining the tool interface and delegating to the core handler in tools.py.
  @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:26-26 (schema)

  Type definition for SortOrder used in the search_articles tool's input schema for validation of the sort parameter.
  type SortOrder = Literal["best", "newest", "oldest", "relevance"]
• src/nytimes_mcp/utils.py:6-29 (helper)

  Utility function to format the raw NYT article search API response into a structured output with essential article fields.
  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