What is Story Data?

When you interact with Hacker News through the MCP server, stories are the primary content type you'll encounter. Each story represents a submission to Hacker News—whether it's a link to an external article, a question posed to the community, or a "Show HN" post showcasing a project. Understanding the data structure of stories helps you make better queries and interpret the information returned by the server.

Core Story Fields

Every story retrieved from the Hacker News MCP server contains a consistent set of fields that describe its content and metadata:

ID: A unique numeric identifier for each story. This ID is permanent and used to reference specific stories in queries or when retrieving associated comments.

Title: The headline or subject line of the story, exactly as submitted by the user. This is typically what you see when browsing Hacker News.

URL: For link submissions, this field contains the destination URL. Text-only posts (like "Ask HN" or "Show HN" posts) may not have a URL field or it may point back to Hacker News itself.

Score: The current point total reflecting community votes. Higher scores indicate stories that have resonated with the community. Scores change over time as users vote.

Author (or "by"): The Hacker News username of the person who submitted the story. You can use this to query additional information about the submitter.

Time: A Unix timestamp indicating when the story was submitted. This helps you understand the age and recency of content.

Type: Identifies the item as a "story" (as opposed to a comment or other item type).

Descendants: The total number of comments on the story, including nested replies. This gives you a sense of discussion volume.

Kids: An array of comment IDs representing top-level comments on the story. Use these IDs to retrieve the actual comment threads.

Using Story Data Effectively

When requesting stories from the server, you'll typically receive these fields in a structured format. For example, asking for "top stories" returns an array of story objects, each containing these fields. You can then drill down into specific stories using their IDs to access comments, or research authors by querying their profiles.

Understanding that some stories are links while others are text-based discussions helps you interpret missing or Hacker News-pointing URLs. Similarly, recognizing that scores and comment counts reflect real-time data means these values can change between queries.

By familiarizing yourself with these fields, you'll be able to craft more precise queries and better understand the responses from the Hacker News MCP server.