HackerNews MCP Server

# Feature Specification: HackerNews MCP Server **Feature Branch**: `001-hackernews-mcp-server` **Created**: October 12, 2025 **Status**: Draft **Input**: User description: "Create an HackerNews MCP server for interacting with HackerNews API at https://hn.algolia.com/api . Users should be able to search posts, find latest posts, find posts on the front page, and all other capabilities exposed by the api." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Search Posts by Keyword (Priority: P1) A developer wants to search HackerNews for posts containing specific keywords or topics to gather information, find discussions, or research trends. They need to filter results by content type (stories, comments, polls) and sort by relevance or date. **Why this priority**: This is the core functionality that provides the most immediate value. Search is the primary way users discover content on HackerNews, making it essential for any API integration. **Independent Test**: Can be fully tested by executing a search query with various keywords and verifying that relevant results are returned. Delivers immediate value by allowing content discovery without any other features. **Acceptance Scenarios**: 1. **Given** I want to find stories about "AI", **When** I search for posts with query "AI" and tag "story", **Then** I receive a list of story posts matching the search term sorted by relevance 2. **Given** I want to find recent comments about "Python", **When** I search for posts with query "Python", tag "comment", and sort by date, **Then** I receive comments containing "Python" ordered by most recent first 3. **Given** I want to find posts from a specific author, **When** I search with author filter "pg", **Then** I receive all posts created by that author 4. **Given** I want to search within specific time range, **When** I apply numeric filters for created_at_i timestamps, **Then** I receive only posts created within that time period 5. **Given** I want to paginate through many results, **When** I specify page number and hits per page, **Then** I receive the requested page of results with pagination metadata --- ### User Story 2 - View Front Page Posts (Priority: P1) A developer wants to retrieve posts currently on the HackerNews front page to display trending content, build dashboards, or monitor popular discussions in real-time. **Why this priority**: Front page content represents the most popular and timely discussions. This is a key use case for many applications that surface trending HackerNews content. **Independent Test**: Can be fully tested by requesting front page posts and verifying they match what's currently on HackerNews homepage. Delivers standalone value for applications showing trending content. **Acceptance Scenarios**: 1. **Given** I want to see what's trending on HackerNews, **When** I request posts with "front_page" tag, **Then** I receive the list of posts currently on the front page 2. **Given** I want to display front page stories only (no comments), **When** I request posts with "front_page" and "story" tags, **Then** I receive only story posts from the front page 3. **Given** I want to check front page updates periodically, **When** I make repeated requests over time, **Then** I receive updated front page content reflecting current state --- ### User Story 3 - Get Latest Posts (Priority: P1) A developer wants to retrieve the most recent posts (stories, comments, polls) to monitor new content, track discussions in real-time, or build notification systems. **Why this priority**: Accessing latest content is essential for real-time monitoring, notifications, and staying current with HackerNews activity. This is a fundamental building block for many use cases. **Independent Test**: Can be fully tested by requesting latest posts sorted by date and verifying they are ordered correctly. Delivers value for real-time monitoring applications independently. **Acceptance Scenarios**: 1. **Given** I want to see newest stories, **When** I request search by date with "story" tag, **Then** I receive stories ordered by creation date with most recent first 2. **Given** I want to monitor new comments, **When** I request search by date with "comment" tag, **Then** I receive comments ordered by creation date with most recent first 3. **Given** I want latest posts of any type, **When** I request search by date without type filters, **Then** I receive all recent posts (stories, comments, polls) sorted by date 4. **Given** I want to track new posts since a specific time, **When** I apply numeric filter for created_at_i greater than timestamp, **Then** I receive only posts created after that time --- ### User Story 4 - Retrieve Individual Items (Priority: P2) A developer wants to fetch complete details for a specific post, comment, or poll by its ID to display full content, including nested comment threads and all metadata. **Why this priority**: Essential for viewing complete post details and comment trees, but depends on having item IDs from search/listing operations. Important for deep-linking and showing full discussions. **Independent Test**: Can be fully tested by requesting a known item ID and verifying all details and nested children are returned correctly. Delivers value for applications showing detailed post views. **Acceptance Scenarios**: 1. **Given** I have a story ID, **When** I request that item by ID, **Then** I receive the complete story with title, URL, author, points, text, and all nested comments 2. **Given** I have a comment ID, **When** I request that item by ID, **Then** I receive the comment with text, author, points, and all nested reply comments 3. **Given** an item has deeply nested children, **When** I retrieve it, **Then** I receive the complete comment tree with all levels of nesting preserved --- ### User Story 5 - Get User Information (Priority: P3) A developer wants to retrieve profile information for a HackerNews user to display author details, karma scores, and bio information alongside their posts. **Why this priority**: Useful for enriching user interfaces with author information, but not critical for core content discovery functionality. Nice-to-have for complete user experience. **Independent Test**: Can be fully tested by requesting a known username and verifying profile data is returned. Delivers value for applications showing author information independently. **Acceptance Scenarios**: 1. **Given** I want to show author details, **When** I request user information by username, **Then** I receive username, karma score, and about/bio text 2. **Given** I want to display multiple authors, **When** I request information for several usernames, **Then** I receive complete profile data for each user --- ### User Story 6 - Filter and Refine Search Results (Priority: P2) A developer wants to apply advanced filters (points threshold, comment count, URL matching, specific tags) to narrow down search results to highly relevant content. **Why this priority**: Enhances search capabilities with powerful filtering, but basic search (P1) already provides core value. These refinements are important for power users and specialized use cases. **Independent Test**: Can be fully tested by applying various filters to searches and verifying results match filter criteria. Delivers value for applications needing precise content filtering. **Acceptance Scenarios**: 1. **Given** I want highly-ranked posts only, **When** I search with numeric filter "points>=100", **Then** I receive only posts with 100 or more points 2. **Given** I want active discussions, **When** I search with numeric filter "num_comments>=50", **Then** I receive only posts with 50 or more comments 3. **Given** I want to search URLs only, **When** I restrict searchable attributes to "url" field, **Then** search only matches against URLs, not titles or content 4. **Given** I want stories OR polls, **When** I search with OR tags "(story,poll)", **Then** I receive items matching either type 5. **Given** I want comments on a specific story, **When** I search with tags "comment,story_ID", **Then** I receive all comments belonging to that story --- ### Edge Cases - What happens when a search query returns no results? System should return empty results array with appropriate metadata - What happens when an invalid item ID is requested? System should handle gracefully with clear error message - What happens when a non-existent username is queried? System should return appropriate error or null response - How does the system handle rate limits (10,000 requests/hour per IP)? Should provide clear rate limit information and handle 429 status codes - What happens with malformed query parameters? System should validate inputs and provide helpful error messages - How are special characters in search queries handled? System should properly encode/escape special characters - What happens when requesting page numbers beyond available pages? System should return empty results or last available page - How are null/missing fields in API responses handled? System should gracefully handle optional fields - What happens during API downtime or network failures? System should provide clear error messages and retry guidance ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST provide capability to search posts by full-text query across HackerNews content - **FR-002**: System MUST support filtering search results by content type using tags (story, comment, poll, pollopt, show_hn, ask_hn, front_page) - **FR-003**: System MUST support filtering by author using author tag format (author_username) - **FR-004**: System MUST support sorting search results by relevance (default) or by date (most recent first) - **FR-005**: System MUST support numeric filtering on created_at_i (timestamp), points, and num_comments fields using comparison operators (<, <=, =, >, >=) - **FR-006**: System MUST support pagination with configurable page number and hits per page parameters - **FR-007**: System MUST support combining multiple tags with AND logic (default) and OR logic (using parentheses) - **FR-008**: System MUST provide capability to retrieve front page posts using front_page tag - **FR-009**: System MUST provide capability to retrieve latest posts sorted by date using search_by_date endpoint - **FR-010**: System MUST provide capability to retrieve individual items by ID with complete details and nested children - **FR-011**: System MUST include nested comment threads in item responses with full hierarchy preserved - **FR-012**: System MUST provide capability to retrieve user profile information by username - **FR-013**: System MUST support restricting searches to specific attributes (e.g., URL-only searches) - **FR-014**: System MUST handle rate limiting (10,000 requests/hour per IP) and communicate limits to users - **FR-015**: System MUST return structured response data including hits, pagination metadata (page, nbPages, hitsPerPage, nbHits), and query information - **FR-016**: System MUST handle API errors gracefully with clear error messages - **FR-017**: System MUST validate input parameters before making API requests - **FR-018**: System MUST support time-range queries using numeric filters on timestamps ### Key Entities - **Post/Item**: Represents any HackerNews item (story, comment, poll, etc.) with attributes including ID, created_at timestamp, author, title, URL, text content, points, parent_id, and nested children array - **Story**: A type of post representing submitted links or text posts with attributes including title, URL, points, author, and comment count - **Comment**: A type of post representing user comments with attributes including text, author, points, parent_id, and nested reply comments - **Poll/PollOpt**: A type of post representing polls and poll options - **User**: Represents a HackerNews user profile with attributes including username, karma score, and about/bio text - **Search Result**: Contains array of matching items/posts plus pagination metadata (page number, total pages, hits per page, total hits) and query information - **Tag**: Filter criteria for post types and characteristics (story, comment, poll, front_page, author_, story_) - **Numeric Filter**: Filter criteria for numerical fields (created_at_i, points, num_comments) using comparison operators ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Users can successfully execute text searches and receive relevant results in under 2 seconds for 95% of queries - **SC-002**: Users can retrieve front page posts and latest posts with 100% accuracy reflecting current HackerNews state - **SC-003**: Users can fetch individual items by ID with complete nested comment threads (up to any depth) in under 3 seconds - **SC-004**: Users can retrieve user profile information for any valid username in under 1 second - **SC-005**: System successfully handles all documented API endpoint capabilities including search, search_by_date, items, and users - **SC-006**: System properly handles pagination for large result sets, allowing navigation through all available pages - **SC-007**: System applies all filter types (tags, numeric filters, attribute restrictions) correctly with 100% accuracy - **SC-008**: Users receive clear, actionable error messages for invalid requests, missing resources, and rate limit violations - **SC-009**: System handles rate limiting gracefully, tracking request counts and providing clear feedback when approaching or exceeding limits - **SC-010**: 95% of users can accomplish their primary task (search, retrieve front page, get latest, fetch item details) successfully on first attempt - **SC-011**: System maintains compatibility with all documented HackerNews API features and parameters - **SC-012**: API integration passes all acceptance scenarios defined in user stories without failures ## Assumptions *(mandatory)* - The HackerNews Algolia API at https://hn.algolia.com/api will remain available and maintain its current interface - API rate limits (10,000 requests/hour per IP) are enforced at the source and apply to the MCP server's usage - Users of the MCP server have network connectivity to reach the HackerNews API - The MCP (Model Context Protocol) server framework is available and functional for building the integration - Standard HTTP/REST request libraries are available for making API calls - JSON parsing capabilities are available for handling API responses - Error handling will follow standard HTTP status code conventions (200 OK, 400 Bad Request, 404 Not Found, 429 Rate Limit, 500 Server Error) - Time-based operations use Unix timestamps (seconds since epoch) as documented in the API - The API returns data in JSON format as documented - Network latency and API response times are reasonable (under 3 seconds for most requests) - Users understand basic HackerNews concepts (stories, comments, points, karma, front page) ## Dependencies *(if applicable)* - **External API**: HackerNews Algolia API (https://hn.algolia.com/api) must be accessible and operational - **API Documentation**: Relies on documented API behavior at https://hn.algolia.com/api remaining accurate - **Network Connectivity**: Requires reliable internet connection to reach external API - **MCP Framework**: Depends on Model Context Protocol server framework/specification being available ## Out of Scope *(if applicable)* - **Content Creation**: This server is read-only; it does not support posting stories, submitting comments, or voting - **Authentication**: No user authentication or authorization (API is public and read-only) - **Data Persistence**: No local caching or database storage of HackerNews content - **Real-time Updates**: No WebSocket or push notification support for live updates - **Content Moderation**: No filtering of inappropriate content beyond what the API provides - **Analytics**: No usage tracking, metrics collection, or analytics dashboards - **Rate Limit Management**: No request queuing, throttling, or distributed rate limit coordination across multiple clients - **Data Transformation**: Minimal transformation of API responses; returns data in format provided by API - **Alternative APIs**: Only supports HackerNews Algolia API, not the official HackerNews Firebase API - **Historical Archives**: Limited to data available through the API (no access to deleted or archived content not in API)