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