search_stories

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