Data Structure Overview

The Hacker News MCP server returns data in structured formats that mirror the core entities of the Hacker News platform. Understanding these structures will help you interpret responses and build effective queries.

Story Objects

When you retrieve stories (top, new, or best), the server returns objects containing key metadata. Each story includes:

• ID: A unique numeric identifier for the story
• Title: The submission headline
• URL: The external link (if applicable)
• Score: Current upvote count
• Author: The submitting user's username
• Time: Unix timestamp of submission
• Descendants: Total number of comments in the thread

Stories may also include a text field for Ask HN or Show HN posts that contain body content rather than external links.

Comment Objects

Comments follow a hierarchical structure reflecting nested discussions. Each comment contains:

• ID: Unique identifier
• Parent: ID of the parent item (story or comment)
• Author: Username of the commenter
• Text: Comment content in HTML format
• Time: Unix timestamp
• Kids: Array of child comment IDs

To traverse a full discussion thread, you'll retrieve the parent story, then recursively fetch comments using the IDs in the kids array.

User Profiles

User objects provide information about community members:

• ID: The username
• Created: Account creation timestamp
• Karma: Accumulated points from upvotes
• About: Optional biographical text
• Submitted: Array of item IDs the user has posted

This structure enables you to explore a user's complete contribution history.

Response Formats

All responses are returned in JSON format with clean, predictable structures. The server handles API communication transparently, delivering data ready for immediate use.

Lists vs. Individual Items

When requesting feeds (top stories, new submissions), you'll receive arrays of item IDs. Use these IDs to fetch detailed information about specific items of interest. Individual item requests return complete objects with all available fields populated.

Handling Missing Data

Not all fields are present in every response. For example, job postings lack URLs, and some users don't provide biographical information. Your implementation should gracefully handle optional fields.

Timestamps and Formatting

All timestamps are Unix epoch times (seconds since January 1, 1970). You'll need to convert these to human-readable formats based on your requirements. Comment text includes HTML markup, which you may want to parse or strip depending on your use case.