get_most_popular
Retrieve New York Times articles ranked by popularity across viewed, shared, or emailed categories within specific time periods.
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-147 (handler)Core handler function that fetches the most popular articles from the NYT API endpoint `/mostpopular/v2/{popularity_type}/{time_period}.json` using the shared NytClient and formats 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-77 (registration)MCP tool registration using `@mcp.tool()` decorator. This is the entrypoint handler for the MCP tool, which delegates to `tools.get_most_popular`.@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 definitions (Literal) for the `popularity_type` and `time_period` parameters used by the tool.type PopularityType = Literal["viewed", "shared", "emailed"] type PopularityPeriod = Literal["1", "7", "30"]
- src/nytimes_mcp/utils.py:61-85 (helper)Helper function `format_popular_response` that processes the raw NYT most popular API response into a formatted dictionary with `articles` array containing essential 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