HackerNews MCP Server

# API Reference Complete reference documentation for all HackerNews MCP Server tools. ## Table of Contents - [search-posts](#search-posts) - [get-front-page](#get-front-page) - [get-latest-posts](#get-latest-posts) - [get-item](#get-item) - [get-user](#get-user) --- ## search-posts Search HackerNews for stories, comments, and other content by keyword with advanced filtering options. ### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `query` | string | Yes | - | Search query text (minimum 1 character) | | `tags` | string[] | No | `undefined` | Filter by content type/tags | | `numericFilters` | string[] | No | `undefined` | Numeric range filters | | `page` | number | No | `0` | Page number (0-indexed) | | `hitsPerPage` | number | No | `20` | Results per page (1-1000) | ### Tags - `story` - Story posts - `comment` - Comments - `poll` - Polls - `pollopt` - Poll options - `show_hn` - Show HN posts - `ask_hn` - Ask HN posts - `front_page` - Currently on front page - `author_USERNAME` - Posts by specific author (e.g., `author_pg`) ### Numeric Filters Format: `field OPERATOR value` **Operators**: `<`, `<=`, `=`, `>=`, `>` **Fields**: - `points` - Number of upvotes - `num_comments` - Number of comments - `created_at_i` - Unix timestamp **Examples**: - `points>=100` - At least 100 points - `created_at_i>1640000000` - Posted after January 1, 2022 - `num_comments>=50` - At least 50 comments ### Response ```typescript { hits: HNItem[]; // Array of matching items nbHits: number; // Total number of hits across all pages page: number; // Current page number (0-indexed) nbPages: number; // Total number of pages hitsPerPage: number; // Items per page processingTimeMS: number; // Query processing time query: string; // The search query used params: string; // URL-encoded parameters } ``` ### Examples **Basic search:** ```json { "query": "AI" } ``` **Search with filters:** ```json { "query": "Python", "tags": ["story"], "numericFilters": ["points>=100"], "page": 0, "hitsPerPage": 20 } ``` **Search by author:** ```json { "query": "", "tags": ["author_pg"], "numericFilters": ["created_at_i>1640000000"] } ``` ### Error Conditions - **Validation Error** (400): Empty query, invalid page, hitsPerPage out of range - **Rate Limit** (429): Exceeded 10,000 requests/hour - **API Error** (500): HackerNews API failure --- ## get-front-page Retrieve posts currently on the HackerNews front page. ### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `page` | number | No | `0` | Page number (0-indexed) | | `hitsPerPage` | number | No | `30` | Results per page (1-1000) | ### Response Same structure as `search-posts` response. All items will have `front_page` tag. ### Examples **Get first page:** ```json {} ``` **Get with custom page size:** ```json { "hitsPerPage": 50 } ``` **Get second page:** ```json { "page": 1 } ``` ### Notes - Posts are sorted by HackerNews ranking algorithm - Front page typically contains 30 items - Pagination available but most users only need page 0 --- ## get-latest-posts Retrieve the most recent HackerNews posts sorted by date. ### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `tags` | string[] | No | `undefined` | Filter by content type | | `page` | number | No | `0` | Page number (0-indexed) | | `hitsPerPage` | number | No | `20` | Results per page (1-1000) | ### Response Same structure as `search-posts` response. Results sorted by creation date (newest first). ### Examples **Get all latest posts:** ```json {} ``` **Get latest stories:** ```json { "tags": ["story"] } ``` **Get latest comments:** ```json { "tags": ["comment"] } ``` **Monitor Show HN:** ```json { "tags": ["show_hn"], "hitsPerPage": 50 } ``` ### Use Cases - Monitor new submissions in real-time - Track latest comments across HackerNews - Find newest Show HN projects - Discover fresh content before it trends --- ## get-item Retrieve detailed information about a specific HackerNews item by ID, including the complete nested comment tree. ### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `itemId` | string | Yes | - | HackerNews item ID | ### Response ```typescript { id: string; // Item ID created_at: string; // ISO 8601 timestamp created_at_i: number; // Unix timestamp type: string; // 'story', 'comment', 'poll', 'pollopt' author: string; // Username title: string | null; // Title (for stories) url: string | null; // URL (for link posts) text: string | null; // Text content points: number | null; // Upvote count parent_id: number | null; // Parent item ID story_id: number; // Root story ID options: number[]; // Poll options (for polls) children: ItemResult[]; // Nested children (recursive) } ``` ### Examples **Get story with comments:** ```json { "itemId": "38456789" } ``` **Get specific comment:** ```json { "itemId": "38456790" } ``` ### Notes - **Nested Comments**: Returns complete comment tree (all levels) - **Performance**: Large threads (>500 comments) may take 2-3 seconds - **Deleted Items**: Returns error if item has been deleted - **Recursion**: Children array contains full nested structure ### Comment Tree Structure Comments are nested recursively: ```mermaid flowchart TB story[Story (id: 123)] story --> commentA[Comment A\n(id: 124, parent_id: 123)] commentA --> replyA1[Reply A1\n(id: 125, parent_id: 124)] commentA --> replyA2[Reply A2\n(id: 126, parent_id: 124)] story --> commentB[Comment B\n(id: 127, parent_id: 123)] commentB --> replyB1[Reply B1\n(id: 128, parent_id: 127)] ``` --- ## get-user Retrieve public profile information for a HackerNews user. ### Input Parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `username` | string | Yes | - | HackerNews username | ### Response ```typescript { username: string; // Username karma: number; // Karma score (total upvotes) about?: string; // Bio/about text (may contain HTML) created?: number; // Account creation date (Unix timestamp) } ``` ### Examples **Get famous user:** ```json { "username": "pg" } ``` **Check moderator:** ```json { "username": "dang" } ``` ### Validation Rules - **Format**: Alphanumeric characters and underscores only - **Case-Sensitive**: Exact username match required - **Existence**: Returns error if user doesn't exist ### Use Cases - Check user reputation (karma) - Read user bio and background - Verify account age - Validate user exists before searching their posts --- ## Error Responses All tools return errors in a consistent format: ```typescript { type: 'validation' | 'api' | 'network' | 'not_found' | 'rate_limit'; message: string; details?: any; statusCode?: number; } ``` ### Error Types **Validation Error** (400) - Invalid input parameters - Missing required fields - Values out of acceptable range **API Error** (500) - HackerNews API failure - Unexpected response format - Service unavailable **Network Error** (504) - Request timeout (>5 seconds) - Network connectivity issues - DNS resolution failure **Not Found** (404) - Item doesn't exist - User doesn't exist - Deleted content **Rate Limit** (429) - Exceeded 10,000 requests/hour - Too many requests from same IP - Retry after waiting --- ## Rate Limiting The HackerNews API has a rate limit of **10,000 requests per hour per IP address**. ### Best Practices 1. **Cache Results**: Store frequently accessed data locally 2. **Batch Requests**: Combine searches when possible 3. **Monitor Usage**: Track request counts in your application 4. **Implement Backoff**: Wait before retrying on 429 errors ### Rate Limit Response ```json { "type": "rate_limit", "message": "Rate limit exceeded: 10,000 requests per hour maximum. Please try again later.", "statusCode": 429 } ``` **Recovery**: - Wait at least 60 seconds before retry - Implement exponential backoff - Reduce request frequency --- ## Performance Guidelines ### Expected Response Times | Operation | Target | Typical | |-----------|--------|---------| | search-posts | <2s | 300-800ms | | get-front-page | <2s | 200-500ms | | get-latest-posts | <2s | 300-800ms | | get-item (small) | <1s | 200-500ms | | get-item (large) | <3s | 1-2.5s | | get-user | <1s | 200-400ms | ### Optimization Tips 1. **Pagination**: Use smaller `hitsPerPage` values for faster responses 2. **Filtering**: Apply tags and numeric filters at API level 3. **Caching**: Cache front page and popular items 4. **Timeouts**: Default 5s timeout, adjust if needed --- ## Data Freshness - **Real-Time**: Latest posts and search results reflect current state - **No Caching**: Server always fetches fresh data from HackerNews API - **Consistency**: Results match what's visible on news.ycombinator.com - **Delay**: Typically <1 second between HN update and API availability --- ## Additional Resources - [HackerNews Algolia API Documentation](https://hn.algolia.com/api) - [Quick Start Guide](../README.md#usage) - [GitHub Repository](https://github.com/yourusername/hn-mcp-server)