mcp-hn

Instructions

Implementation Reference

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

  Primary implementation of the get_story_info tool. Fetches raw story data via _get_story_info and formats it including nested comments using _format_story_details with basic=False.
  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/server.py:109-112 (handler)

  MCP server dispatch handler for get_story_info tool. Extracts story_id from arguments, calls hn.get_story_info, and returns JSON-formatted result as TextContent.
  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)]
• src/mcp_hn/server.py:76-88 (schema)

  Input JSON Schema for the get_story_info tool, defining story_id as required integer.
  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/hn.py:25-42 (helper)

  Helper function to fetch raw story data from Hacker News API, used by get_story_info.
  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-84 (helper)

  Helper function to format story details, including recursively fetching and formatting comments when basic=False, used by get_story_info.
  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