What is Story Data?

When you retrieve stories from Hacker News through the MCP server, each story comes with a structured set of fields that provide comprehensive information about the submission. Understanding these fields helps you effectively interpret and work with the data returned by the server.

Core Story Fields

Identification and Metadata

Each story has a unique id that serves as its permanent identifier within Hacker News. This numeric value allows you to reference specific stories and retrieve their data reliably. The type field indicates the item type—for stories, this will typically be "story" but may also be "job" or "poll" depending on the submission.

Content Information

The title contains the headline of the submission, representing what users see when browsing Hacker News. For stories linking to external content, the url field provides the destination link. Text-based submissions that don't link elsewhere will have a text field containing the post body in HTML format. Not all stories have both—link submissions typically have a url but no text, while "Ask HN" posts usually have text but no external url.

Author and Timing

The by field identifies the username of the person who submitted the story. You can use this value to retrieve the user's profile for more information about the author. The time field contains a Unix timestamp indicating when the story was submitted, allowing you to determine recency and track submission patterns over time.

Community Engagement

The score represents the number of upvotes the story has received, indicating community interest and approval. Higher scores generally correlate with visibility on the front page. The descendants field shows the total number of comments in the entire discussion thread, including nested replies, giving you a sense of how much conversation the story has generated.

Comment Structure

The kids array contains the ids of direct comments on the story. These are top-level comments only—to retrieve nested replies, you'll need to fetch each comment individually, which will have its own kids array. An empty or missing kids field indicates no comments have been posted yet.

Working with Story Data

When requesting stories through the server, you might receive lists of story ids (for feeds like top or new stories) or complete story objects with all fields populated. The server handles the complexity of fetching this data from Hacker News APIs, returning it in a consistent, easy-to-parse format that you can immediately use for analysis, monitoring, or display purposes.