mcp-hn

Instructions

Implementation Reference

• src/mcp_hn/hn.py:159-188 (handler)

  Core implementation of the search_stories tool: queries HN Algolia API (/search or /search_by_date), fetches stories matching the query, formats them using _format_story_details, and returns the list.
  def search_stories(query: str, num_results: int = DEFAULT_NUM_STORIES, search_by_date: bool = False): """ Searches Hacker News stories using a query string. Args: query: Search terms to find in stories num_results: Number of results to return (default: 10) search_by_date: If True, sorts by date. If False, sorts by relevance/points/comments (default: False) Returns: List[Dict]: List of matching 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: requests.exceptions.RequestException: If the API request fails """ if search_by_date: url = f"{BASE_API_URL}/search_by_date?query={query}&hitsPerPage={num_results}&tags=story" else: url = f"{BASE_API_URL}/search?query={query}&hitsPerPage={num_results}&tags=story" print(url) response = requests.get(url) response.raise_for_status() return [_format_story_details(story) for story in response.json()["hits"]]
• src/mcp_hn/server.py:57-74 (schema)

  Input JSON schema for the search_stories tool, defining parameters: query (required string), search_by_date (boolean), num_results (integer).
  inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Search query", }, "search_by_date": { "type": "boolean", "description": "Search by date, defaults to False. If this is False, then we search by relevance, then points, then number of comments.", }, "num_results": { "type": "integer", "description": f"Number of results to get, defaults to {DEFAULT_NUM_STORIES}", }, }, "required": ["query"], },
• src/mcp_hn/server.py:54-75 (registration)

  Registers the search_stories tool in the list_tools() handler with name, description, and input schema.
  types.Tool( name="search_stories", description="Search stories from Hacker News. It is generally recommended to use simpler queries to get a broader set of results (less than 5 words). Very targetted queries may not return any results.", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "Search query", }, "search_by_date": { "type": "boolean", "description": "Search by date, defaults to False. If this is False, then we search by relevance, then points, then number of comments.", }, "num_results": { "type": "integer", "description": f"Number of results to get, defaults to {DEFAULT_NUM_STORIES}", }, }, "required": ["query"], }, ),
• src/mcp_hn/server.py:103-108 (handler)

  MCP server tool call handler: extracts arguments, calls hn.search_stories, JSON serializes the output, and returns as TextContent.
  elif name == "search_stories": query = arguments.get("query") search_by_date = arguments.get("search_by_date", False) num_results = arguments.get("num_results", DEFAULT_NUM_STORIES) output = json.dumps(hn.search_stories(query, num_results, search_by_date), indent=2) return [types.TextContent(type="text", text=output)]
• src/mcp_hn/hn.py:43-83 (helper)

  Helper function used by search_stories to format raw API story data into a standard dict with id, title, url, author, points (basic mode).
  def _format_story_details(story: Union[Dict, int], basic: bool = True) -> Dict: """ Formats a story's details into a standardized dictionary structure. Args: story: Either a story ID or dictionary containing story data basic: If True, excludes comments. If False, includes formatted comments to depth of 2 Returns: Dict with the following structure: { "id": int, # Story ID "title": str, # Story title if present "url": str, # Story URL if present "author": str, # Author username "points": int, # Points (may be null) "comments": list # List of comment dicts (only if basic=False) } The function handles both raw story IDs and story dictionaries, fetching additional data if needed. For non-basic requests, it ensures comments are properly formatted. """ if isinstance(story, int): story = _get_story_info(story) output = { "id": story["story_id"], "author": story["author"], } if "title" in story: output["title"] = story["title"] if "points" in story: output["points"] = story["points"] if "url" in story: output["url"] = story["url"] if not basic: if _validate_comments_is_list_of_dicts(story["children"]): story = _get_story_info(story["story_id"]) output["comments"] = [ _format_comment_details(child) for child in story["children"] ] return output