mcp-hn

Instructions

Implementation Reference

• src/mcp_hn/hn.py:190-212 (handler)

  Primary handler function implementing the get_story_info tool logic: fetches raw story data and formats it into a structured dict with title, url, author, points, and nested comments up to depth 2.

  def get_story_info(story_id: int) -> Dict:
      """
      Fetches detailed information about a specific story including comments.
  
      Args:
          story_id: The ID of the story to fetch
  
      Returns:
          Dict containing full story details:
          {
              "id": int,          # Story ID
              "title": str,       # Story title
              "url": str,         # Story URL (may be null for text posts)
              "author": str,      # Author username
              "points": int,      # Points (may be null)
              "comments": list    # Nested list of comment dictionaries
          }
  
      Raises:
          requests.exceptions.RequestException: If the API request fails
      """
      story = _get_story_info(story_id)
      return _format_story_details(story, basic=False)

• src/mcp_hn/hn.py:25-41 (helper)

  Core helper function that performs the HTTP request to the Hacker News Algolia API to retrieve raw story information.

  def _get_story_info(story_id: int) -> Dict:
      """
      Fetches detailed information about a Hacker News story.
  
      Args:
          story_id: The ID of the story to fetch
  
      Returns:
          Dict: Raw story data from the HN API including title, author, points, url and comments
  
      Raises:
          requests.exceptions.RequestException: If the API request fails
      """
      url = f"{BASE_API_URL}/items/{story_id}"
      response = requests.get(url)
      response.raise_for_status()
      return response.json()

• src/mcp_hn/hn.py:43-83 (helper)

  Helper function to format story details, handling both IDs and dicts, and optionally expanding comments with recursive formatting.

  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

• src/mcp_hn/server.py:76-88 (schema)

  JSON Schema definition for the tool input: requires a single 'story_id' integer property.

  types.Tool(
      name="get_story_info",
      description="Get detailed story info from Hacker News, including the comments",
      inputSchema={
          "type": "object",
          "properties": {
              "story_id": {
                  "type": "integer",
                  "description": "Story ID",
              },
          },
      },
  ),

• src/mcp_hn/server.py:109-112 (registration)

  MCP server registration and dispatch logic for the tool: parses input, calls the handler, and returns JSON-formatted result.

  elif name == "get_story_info":
      story_id = int(arguments.get("story_id"))
      output = json.dumps(hn.get_story_info(story_id), indent=2)
      return [types.TextContent(type="text", text=output)]