mcp-hn

Instructions

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))]