HackerNews MCP Server

🚀 Model Context Protocol server for interacting with HackerNews

Enable AI agents and developers to search, retrieve, and analyze HackerNews content through the Model Context Protocol (MCP). This server provides tools for advanced search, front page retrieval, detailed post access with comment trees, and user profile lookups.

✨ Features

🔍 Advanced Search - Find posts with keyword search, filters (author, date, points, comments), and flexible sorting
📰 Front Page Access - Retrieve current HackerNews front page content with pagination
💬 Full Comment Trees - Access complete discussion threads with nested comment structure
👤 User Profiles - Look up user information including karma, account age, and bio
⚡ Rate Limiting - Automatic rate limiting respecting HN API constraints (10,000 req/hour)
🛡️ Type Safety - Built with TypeScript strict mode and comprehensive validation
📚 Well Documented - Complete API documentation and usage examples
✅ Thoroughly Tested - 90%+ test coverage with contract, integration, and unit tests

📦 Installation

Prerequisites

Node.js 22.0.0 or higher
npm 10.0.0 or higher

Install via npm

npm install -g hn-mcp-server

Install from Source

git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm link

🚀 Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "hn-mcp-server"]
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

After configuration, restart Claude Desktop. The HackerNews tools will be available in your conversations.

With VS Code + GitHub Copilot

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "hn-mcp-server"]
    }
  }
}

Test Installation

# Verify server starts
hn-mcp-server

# Or via npx
npx hn-mcp-server

The server will start and wait for MCP client connections via stdio.

💡 Usage Examples

Example 1: Search for AI/ML Posts

Natural Language (in Claude):

Search HackerNews for machine learning articles from the last month with more than 100 points

Example 2: Browse Front Page

Natural Language:

Show me what's currently on the HackerNews front page

Example 3: Read Discussion

Natural Language:

Get the full discussion for HackerNews post 39381647 including all comments

Example 4: Research a User

Natural Language:

Tell me about the HackerNews user 'pg'

Example 5: Advanced Filtering

Natural Language:

Find Show HN posts by user 'todsacerdoti' from 2024 with at least 50 points

For more detailed examples, see the Quickstart Guide.

🛠️ Available Tools

`search_posts`

Search HackerNews posts with advanced filtering options.

Parameters:

query (string, optional) - Search keywords
tags (array, optional) - Content type filters: story, comment, poll, show_hn, ask_hn, front_page
author (string, optional) - Filter by username
storyId (number, optional) - Filter comments by story ID
minPoints, maxPoints (number, optional) - Points thresholds
minComments, maxComments (number, optional) - Comment count thresholds
dateAfter, dateBefore (string, optional) - Date range filters (ISO 8601)
sortByDate (boolean, optional) - Sort by date (true) or relevance (false, default)
page (number, optional) - Page number (0-indexed, default: 0)
hitsPerPage (number, optional) - Results per page (1-100, default: 20)

`get_front_page`

Retrieve current HackerNews front page posts.

Parameters:

page (number, optional) - Page number (0-indexed, default: 0)
hitsPerPage (number, optional) - Results per page (1-30, default: 30)

`get_post`

Get full details of a specific post including comment tree.

Parameters:

postId (string, required) - HackerNews post ID

`get_user`

Retrieve user profile information.

Parameters:

username (string, required) - HackerNews username (1-15 characters)

⚙️ Configuration

Rate Limiting

The server automatically respects HackerNews API's rate limit of 10,000 requests per hour per IP address.

Tracks requests using token bucket algorithm
Logs warnings at 80%, 90%, 95% usage
Returns rate limit error when exceeded
Automatically refills tokens over time

Error Handling

All tools return structured errors:

{
  "error": "Human-readable error message",
  "type": "validation_error | not_found | api_error | rate_limit | unknown",
  "details": { "additional": "context" }
}

👨‍💻 Development

Setup

# Clone repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server

# Install dependencies
npm install

# Build
npm run build

Development Workflow

# Watch mode (auto-rebuild on changes)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Format code
npm run format

# Type check without building
npm run typecheck

Testing

The project follows Test-Driven Development (TDD) with three test layers:

Contract Tests: Validate external API response schemas
Integration Tests: Test tool workflows end-to-end with mocked APIs
Unit Tests: Test individual functions in isolation

Coverage Requirement: 90% minimum for lines, functions, branches, and statements.

# Run all tests
npm test

# View coverage report
npm run test:coverage
open coverage/index.html  # macOS
start coverage/index.html # Windows

Project Structure

src/
├── index.ts                # Main entry point, MCP server setup
├── types/                  # TypeScript type definitions
│   ├── hn-api.ts          # HackerNews API response types
│   └── mcp-tools.ts       # MCP tool schemas
├── tools/                  # MCP tool implementations
│   ├── search.ts          # search_posts tool
│   ├── front-page.ts      # get_front_page tool
│   ├── get-post.ts        # get_post tool
│   ├── get-user.ts        # get_user tool
│   └── index.ts           # Tool registry
├── services/               # Business logic
│   ├── hn-api-client.ts   # HackerNews API client
│   └── rate-limiter.ts    # Rate limiting
└── lib/                    # Utilities
    ├── validation.ts       # Input validation helpers
    └── error-handler.ts    # Error handling utilities

tests/
├── contract/               # API contract tests
├── integration/            # Tool integration tests
└── unit/                   # Unit tests

Code Style

Language: TypeScript 5.x with strict mode enabled
Linter: Biome (no ESLint or Prettier)
Formatting: 2-space indentation, 100-character line width, double quotes
Type Safety: No any types, explicit return types on exported functions

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Follow TDD: Write tests first, then implementation
Ensure tests pass: npm test
Ensure linting passes: npm run lint
Maintain coverage: Keep at 90%+
Commit changes: git commit -m "Add my feature"
Push to branch: git push origin feature/my-feature
Open a Pull Request

Development Principles

This project follows strict quality standards documented in .specify/memory/constitution.md:

Code Quality First: TypeScript strict mode, no any types
Test-Driven Development: Tests before implementation
Documentation-First: Complete docs for all features
Latest Stable Versions: Up-to-date dependencies
Reuse Over Reinvention: Leverage existing libraries

📚 Documentation

Feature Specification - Detailed requirements and user stories
Implementation Plan - Technical design and architecture
Research Documentation - Technical decisions and rationale
Data Model - Entity schemas and validation rules
Quickstart Guide - Usage examples and reference
Tool Contracts - MCP tool definitions

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

HackerNews - Community and content
HN Algolia API - Search API powering this server
Model Context Protocol - MCP specification and SDK
Anthropic - Claude and MCP development

🐛 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
HN API Docs: hn.algolia.com/api
MCP Docs: modelcontextprotocol.io

Built with ❤️ using TypeScript, MCP SDK, and Biome

HackerNews MCP Server

🚀 Model Context Protocol server for interacting with HackerNews

✨ Features

🔍 Advanced Search - Find posts with keyword search, filters (author, date, points, comments), and flexible sorting
📰 Front Page Access - Retrieve current HackerNews front page content with pagination
💬 Full Comment Trees - Access complete discussion threads with nested comment structure
👤 User Profiles - Look up user information including karma, account age, and bio
⚡ Rate Limiting - Automatic rate limiting respecting HN API constraints (10,000 req/hour)
🛡️ Type Safety - Built with TypeScript strict mode and comprehensive validation
📚 Well Documented - Complete API documentation and usage examples
✅ Thoroughly Tested - 90%+ test coverage with contract, integration, and unit tests

📋 Table of Contents

Installation
Quick Start
Usage Examples
Available Tools
Configuration
Development
Contributing
License

📦 Installation

Prerequisites

Node.js 22.0.0 or higher
npm 10.0.0 or higher

Install via npm

npm install -g hn-mcp-server

Install from Source

git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm link

🚀 Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "hn-mcp-server"]
    }
  }
}

Config file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

After configuration, restart Claude Desktop. The HackerNews tools will be available in your conversations.

With VS Code + GitHub Copilot

Add to your VS Code settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "hn-mcp-server"]
    }
  }
}

Test Installation

# Verify server starts
hn-mcp-server

# Or via npx
npx hn-mcp-server

The server will start and wait for MCP client connections via stdio.

💡 Usage Examples

Example 1: Search for AI/ML Posts

Natural Language (in Claude):

Search HackerNews for machine learning articles from the last month with more than 100 points

Example 2: Browse Front Page

Natural Language:

Show me what's currently on the HackerNews front page

Example 3: Read Discussion

Natural Language:

Get the full discussion for HackerNews post 39381647 including all comments

Example 4: Research a User

Natural Language:

Tell me about the HackerNews user 'pg'

Example 5: Advanced Filtering

Natural Language:

Find Show HN posts by user 'todsacerdoti' from 2024 with at least 50 points

For more detailed examples, see the Quickstart Guide.

🛠️ Available Tools

`search_posts`

Search HackerNews posts with advanced filtering options.

Parameters:

query (string, optional) - Search keywords
tags (array, optional) - Content type filters: story, comment, poll, show_hn, ask_hn, front_page
author (string, optional) - Filter by username
storyId (number, optional) - Filter comments by story ID
minPoints, maxPoints (number, optional) - Points thresholds
minComments, maxComments (number, optional) - Comment count thresholds
dateAfter, dateBefore (string, optional) - Date range filters (ISO 8601)
sortByDate (boolean, optional) - Sort by date (true) or relevance (false, default)
page (number, optional) - Page number (0-indexed, default: 0)
hitsPerPage (number, optional) - Results per page (1-100, default: 20)

`get_front_page`

Retrieve current HackerNews front page posts.

Parameters:

page (number, optional) - Page number (0-indexed, default: 0)
hitsPerPage (number, optional) - Results per page (1-30, default: 30)

`get_post`

Get full details of a specific post including comment tree.

Parameters:

postId (string, required) - HackerNews post ID

`get_user`

Retrieve user profile information.

Parameters:

username (string, required) - HackerNews username (1-15 characters)

⚙️ Configuration

Rate Limiting

The server automatically respects HackerNews API's rate limit of 10,000 requests per hour per IP address.

Tracks requests using token bucket algorithm
Logs warnings at 80%, 90%, 95% usage
Returns rate limit error when exceeded
Automatically refills tokens over time

Error Handling

All tools return structured errors:

{
  "error": "Human-readable error message",
  "type": "validation_error | not_found | api_error | rate_limit | unknown",
  "details": { "additional": "context" }
}

👨‍💻 Development

Setup

# Clone repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server

# Install dependencies
npm install

# Build
npm run build

Development Workflow

# Watch mode (auto-rebuild on changes)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Fix lint issues
npm run lint:fix

# Format code
npm run format

# Type check without building
npm run typecheck

Testing

The project follows Test-Driven Development (TDD) with three test layers:

Contract Tests: Validate external API response schemas
Integration Tests: Test tool workflows end-to-end with mocked APIs
Unit Tests: Test individual functions in isolation

Coverage Requirement: 90% minimum for lines, functions, branches, and statements.

# Run all tests
npm test

# View coverage report
npm run test:coverage
open coverage/index.html  # macOS
start coverage/index.html # Windows

Project Structure

src/
├── index.ts                # Main entry point, MCP server setup
├── types/                  # TypeScript type definitions
│   ├── hn-api.ts          # HackerNews API response types
│   └── mcp-tools.ts       # MCP tool schemas
├── tools/                  # MCP tool implementations
│   ├── search.ts          # search_posts tool
│   ├── front-page.ts      # get_front_page tool
│   ├── get-post.ts        # get_post tool
│   ├── get-user.ts        # get_user tool
│   └── index.ts           # Tool registry
├── services/               # Business logic
│   ├── hn-api-client.ts   # HackerNews API client
│   └── rate-limiter.ts    # Rate limiting
└── lib/                    # Utilities
    ├── validation.ts       # Input validation helpers
    └── error-handler.ts    # Error handling utilities

tests/
├── contract/               # API contract tests
├── integration/            # Tool integration tests
└── unit/                   # Unit tests

Code Style

Language: TypeScript 5.x with strict mode enabled
Linter: Biome (no ESLint or Prettier)
Formatting: 2-space indentation, 100-character line width, double quotes
Type Safety: No any types, explicit return types on exported functions

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/my-feature
Follow TDD: Write tests first, then implementation
Ensure tests pass: npm test
Ensure linting passes: npm run lint
Maintain coverage: Keep at 90%+
Commit changes: git commit -m "Add my feature"
Push to branch: git push origin feature/my-feature
Open a Pull Request

Development Principles

This project follows strict quality standards documented in .specify/memory/constitution.md:

Code Quality First: TypeScript strict mode, no any types
Test-Driven Development: Tests before implementation
Documentation-First: Complete docs for all features
Latest Stable Versions: Up-to-date dependencies
Reuse Over Reinvention: Leverage existing libraries

📚 Documentation

Feature Specification - Detailed requirements and user stories
Implementation Plan - Technical design and architecture
Research Documentation - Technical decisions and rationale
Data Model - Entity schemas and validation rules
Quickstart Guide - Usage examples and reference
Tool Contracts - MCP tool definitions

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

HackerNews - Community and content
HN Algolia API - Search API powering this server
Model Context Protocol - MCP specification and SDK
Anthropic - Claude and MCP development

🐛 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
HN API Docs: hn.algolia.com/api
MCP Docs: modelcontextprotocol.io

Built with ❤️ using TypeScript, MCP SDK, and Biome