NYTimes MCP

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