get_stories
Retrieve Hacker News stories by type (top, new, ask_hn, show_hn) without comments. Specify story type and quantity to fetch content.
Instructions
Get stories from Hacker News. The options are top, new, ask_hn, show_hn for types of stories. This doesn't include the comments. Use get_story_info to get the comments.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| story_type | No | Type of stories to get, one of: `top`, `new`, `ask_hn`, `show_hn` | |
| num_stories | No | Number of stories to get |
Implementation Reference
- src/mcp_hn/hn.py:115-157 (handler)Core implementation of the get_stories tool. Fetches Hacker News stories of specified type using Algolia API, validates input, maps to API endpoints, retrieves data, formats using _format_story_details, and returns list of stories.def get_stories(story_type: str, num_stories: int = DEFAULT_NUM_STORIES): """ Fetches and formats a list of Hacker News stories of the specified type. Args: story_type: Category of stories to fetch. Must be one of: - "top": Front page stories - "new": Most recent stories - "ask_hn": Ask HN posts - "show_hn": Show HN posts num_stories: Number of stories to return (default: 10) Returns: List[Dict]: List of story dictionaries, each containing: { "id": int, # Story ID "title": str, # Story title "url": str, # Story URL "author": str, # Author username "points": int, # Points (may be null) } Raises: ValueError: If story_type is not one of the valid options requests.exceptions.RequestException: If the API request fails """ story_type = story_type.lower().strip() if story_type not in ["top", "new", "ask_hn", "show_hn"]: raise ValueError("story_type must be one of: top, new, ask_hn, show_hn") # Map story type to appropriate API parameters api_params = { "top": {"endpoint": "search", "tags": "front_page"}, "new": {"endpoint": "search_by_date", "tags": "story"}, "ask_hn": {"endpoint": "search", "tags": "ask_hn"}, "show_hn": {"endpoint": "search", "tags": "show_hn"} } params = api_params[story_type] url = f"{BASE_API_URL}/{params['endpoint']}?tags={params['tags']}&hitsPerPage={num_stories}" response = requests.get(url) response.raise_for_status() return [_format_story_details(story) for story in response.json()["hits"]]
- src/mcp_hn/server.py:22-34 (schema)JSON Schema defining the input parameters for the get_stories tool: story_type (string, enum-like via description) and optional num_stories (integer). Used for validation in MCP.inputSchema={ "type": "object", "properties": { "story_type": { "type": "string", "description": "Type of stories to get, one of: `top`, `new`, `ask_hn`, `show_hn`", }, "num_stories": { "type": "integer", "description": "Number of stories to get", }, }, },
- src/mcp_hn/server.py:19-35 (registration)MCP tool registration for get_stories in the server's list_tools handler, including name, description, and input schema.types.Tool( name="get_stories", description="Get stories from Hacker News. The options are `top`, `new`, `ask_hn`, `show_hn` for types of stories. This doesn't include the comments. Use `get_story_info` to get the comments.", inputSchema={ "type": "object", "properties": { "story_type": { "type": "string", "description": "Type of stories to get, one of: `top`, `new`, `ask_hn`, `show_hn`", }, "num_stories": { "type": "integer", "description": "Number of stories to get", }, }, }, ),
- src/mcp_hn/server.py:98-102 (helper)Dispatch logic in the MCP server's call_tool handler that extracts arguments, calls the hn.get_stories implementation, and formats output as JSON.if name == "get_stories": story_type = arguments.get("story_type", "top") num_stories = arguments.get("num_stories", DEFAULT_NUM_STORIES) output = hn.get_stories(story_type, num_stories) return [types.TextContent(type="text", text=json.dumps(output, indent=2))]