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

---

📋 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:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Follow TDD: Write tests first, then implementation
4. Ensure tests pass: npm test
5. Ensure linting passes: npm run lint
6. Maintain coverage: Keep at 90%+
7. Commit changes: git commit -m "Add my feature"
8. Push to branch: git push origin feature/my-feature
9. 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