Tutorial: Hacker News - Gnist Context

Software

Data source: Hacker News API

Overview

Hacker News wraps Hacker News API, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-hn": {
      "url": "https://context.gnist.ai/mcp/hn/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`search_hn_discussions`

Full-text search over Hacker News stories. Searches the complete HN archive via the Algolia search index. Results are sorted by relevance. Args: query: Search terms. date_from: Filter results after this date — YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS (UTC). date_to: Filter results before this date — YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS (UTC). min_points: Minimum points (upvotes) a story must have. Default 0 (no filter). max_results: Maximum stories to return (1–100, default 25). Returns: Dictionary with 'count' and 'stories' list. Each story has title, url, author, points, num_comments, created_at, and hn_url.

Parameter	Type	Required	Description
`query`	string	required	Search terms.
`date_from`	any	optional	Filter results after this date — YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS (UTC).
`date_to`	any	optional	Filter results before this date — YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS (UTC).
`min_points`	integer	optional	Minimum points (upvotes) a story must have. Default 0 (no filter). (default: `0`)
`max_results`	integer	optional	Maximum stories to return (1–100, default 25). (default: `25`)

curl -X POST "https://context.gnist.ai/mcp/hn/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_hn_discussions", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hn/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'},
            'name': 'search_hn_discussions'}},
)
print(resp.json())

`get_hn_trending`

Get top Hacker News stories in a rolling time window, sorted by points. Args: hours_ago: How far back to look (1–168 hours, default 24). min_points: Minimum points threshold (default 10). max_results: Maximum stories to return (1–100, default 25). Returns: Dictionary with 'count' and 'stories' list sorted by points descending.

Parameter	Type	Required	Description
`hours_ago`	integer	optional	How far back to look (1–168 hours, default 24). (default: `24`)
`min_points`	integer	optional	Minimum points threshold (default 10). (default: `10`)
`max_results`	integer	optional	Maximum stories to return (1–100, default 25). (default: `25`)

curl -X POST "https://context.gnist.ai/mcp/hn/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_hn_trending", "arguments": {"hours_ago": 24}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hn/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'hours_ago': 24}, 'name': 'get_hn_trending'}},
)
print(resp.json())

`get_hn_story_thread`

Fetch a Hacker News story with its top comments. Args: story_id: The HN story ID (numeric, from the URL: news.ycombinator.com/item?id=<id>). max_comments: Maximum top-level comments to include (default 20). Returns: Story metadata plus a list of top comments sorted by score, each with text, author, points, and nested replies.

Parameter	Type	Required	Description
`story_id`	integer	required	The HN story ID (numeric, from the URL: news.ycombinator.com/item?id=<id>).
`max_comments`	integer	optional	Maximum top-level comments to include (default 20). (default: `20`)

curl -X POST "https://context.gnist.ai/mcp/hn/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_hn_story_thread", "arguments": {"story_id": 5}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hn/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'story_id': 5}, 'name': 'get_hn_story_thread'}},
)
print(resp.json())

`get_hn_author_activity`

Get recent submissions and comments by a Hacker News user. Args: username: HN username (case-sensitive). limit: Maximum stories and comments to return each (default 10). Returns: User profile (username, karma, created_at) with lists of recent stories and comments.

Parameter	Type	Required	Description
`username`	string	required	HN username (case-sensitive).
`limit`	integer	optional	Maximum stories and comments to return each (default 10). (default: `10`)

curl -X POST "https://context.gnist.ai/mcp/hn/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_hn_author_activity", "arguments": {"username": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hn/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'username': 'example'},
            'name': 'get_hn_author_activity'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/hn/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/hn/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_hn_discussions to find items, then get_hn_trending to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

Date range filtering
Use date range parameters to narrow results to a specific time window. Dates are typically in YYYY-MM-DD format.

FAQ

What data does Hacker News provide?

Hacker News stories, comments, and discussions from the tech community. It exposes 5 tools: search_hn_discussions, get_hn_trending, get_hn_story_thread, get_hn_author_activity, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Hacker News API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.