get_most_popular
Retrieve New York Times articles by popularity type (viewed, shared, or emailed) and time period (1, 7, or 30 days) to analyze trending content.
Instructions
Get the most popular New York Times articles.
Args: type: Type of popularity - "viewed", "shared", or "emailed" (default: "viewed") time_period: Time period in days - "1", "7", or "30" (default: "1") Use the 'nyt://reference/popular-types' resource for available options.
Returns: Formatted response with articles array containing title, abstract, url, and published_date
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| popularity_type | No | viewed | |
| time_period | No | 1 |
Implementation Reference
- src/nytimes_mcp/tools.py:126-146 (handler)Core handler function implementing the logic to fetch most popular NYT articles from the API endpoint and format the response using format_popular_response.async def get_most_popular( popularity_type: PopularityType = "viewed", time_period: PopularityPeriod = "1", ) -> dict: """ Get the most popular New York Times articles. Args: popularity_type: Type of popularity - "viewed", "shared", or "emailed" (default: "viewed") time_period: Time period in days - "1", "7", or "30" (default: "1") Returns: Formatted response with articles array containing title, abstract, url, and published_date """ client = get_client() response = await client.make_nyt_request( f"mostpopular/v2/{popularity_type}/{time_period}.json", {}, ) return format_popular_response(response)
- src/nytimes_mcp/server.py:60-76 (registration)Registers the get_most_popular tool with the FastMCP server using the @mcp.tool() decorator. The function signature and docstring define the tool's input schema. Delegates to the implementation in tools.py.@mcp.tool() async def get_most_popular( popularity_type: tools.PopularityType = "viewed", time_period: tools.PopularityPeriod = "1", ) -> dict: """ Get the most popular New York Times articles. Args: type: Type of popularity - "viewed", "shared", or "emailed" (default: "viewed") time_period: Time period in days - "1", "7", or "30" (default: "1") Use the 'nyt://reference/popular-types' resource for available options. Returns: Formatted response with articles array containing title, abstract, url, and published_date """ return await tools.get_most_popular(popularity_type, time_period)
- src/nytimes_mcp/tools.py:27-28 (schema)Type aliases using Literal for input validation of popularity_type and time_period parameters.type PopularityType = Literal["viewed", "shared", "emailed"] type PopularityPeriod = Literal["1", "7", "30"]
- src/nytimes_mcp/utils.py:61-84 (helper)Helper utility to format the raw API response into a structured output with articles list containing key fields.def format_popular_response(response: dict[str, Any]) -> dict[str, Any]: """ Format most popular response to extract essential fields. Args: response: Raw NYT most popular API response Returns: Formatted response with articles array and num_results """ if "results" in response: return { "articles": [ { "title": article.get("title", ""), "abstract": article.get("abstract", ""), "url": article.get("url", ""), "published_date": article.get("published_date", ""), } for article in response["results"] ], "num_results": len(response["results"]), } return response