Overview

When working with the Hacker News MCP Server, you'll encounter two primary data structures: stories and comments. Understanding how these structures are organized will help you effectively retrieve and interpret Hacker News content through your AI assistant.

Story Data Structure

Stories represent the submissions that appear on Hacker News—links to external articles, Show HN posts, Ask HN questions, and text-based discussions. Each story contains several key fields:

Identification and Content: Every story has a unique numeric ID that serves as its permanent identifier. Stories include a title, and may contain a URL pointing to external content or text for self-posts and questions.

Metadata: The story structure includes the username of the person who submitted it, the submission timestamp, and the current score (based on community upvotes). You'll also find the number of comments the story has received, which helps gauge discussion activity.

Type Information: Stories are categorized by type—such as "story" for standard submissions, "ask" for questions, "show" for project showcases, or "job" for hiring posts. This categorization helps you filter for specific content types.

When you request top stories, new stories, or best stories, the server returns a list of story IDs. You can then retrieve detailed information for individual stories as needed.

Comment Data Structure

Comments represent community responses and discussions on stories. The comment structure differs from stories in important ways:

Hierarchical Nature: Comments are organized in a tree structure. Each comment has a parent—either the story itself or another comment—creating nested discussion threads. The comment structure includes an array of child comment IDs, allowing you to traverse the entire conversation tree.

Content and Attribution: Like stories, comments include a unique ID, the author's username, and a timestamp. The main content is stored as HTML text, which may include formatting and links as written by the author.

Discussion Context: Each comment references its parent item, helping you understand the conversation flow. This parent-child relationship is crucial for reconstructing threaded discussions as they appear on Hacker News.

Working with These Structures

When querying the server, you'll typically start with story lists to identify content of interest, then drill down into specific stories and their comment threads. The hierarchical nature of comments means you may need to make multiple requests to fully explore a discussion—first retrieving the story, then its top-level comments, and finally nested replies.

Understanding these structures enables you to ask more precise questions and better interpret the results your AI assistant provides from Hacker News data.