# HackerNews MCP Server
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
[](https://www.typescriptlang.org/)
> **š 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)](https://modelcontextprotocol.io). 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](#-installation)
- [Quick Start](#-quick-start)
- [Usage Examples](#-usage-examples)
- [Available Tools](#-available-tools)
- [Configuration](#-configuration)
- [Development](#-development)
- [Contributing](#-contributing)
- [License](#-license)
---
## š¦ Installation
### Prerequisites
- **Node.js** 22.0.0 or higher
- **npm** 10.0.0 or higher
### Install via npm
```bash
npm install -g hn-mcp-server
```
### Install from Source
```bash
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`:
```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`:
```json
{
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "npx",
"args": ["-y", "hn-mcp-server"]
}
}
}
```
### Test Installation
```bash
# 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](./specs/001-hn-mcp-server/quickstart.md).
---
## š ļø 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:
```json
{
"error": "Human-readable error message",
"type": "validation_error | not_found | api_error | rate_limit | unknown",
"details": { "additional": "context" }
}
```
---
## šØāš» Development
### Setup
```bash
# 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
```bash
# 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.
```bash
# 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`](./.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](./specs/001-hn-mcp-server/spec.md)** - Detailed requirements and user stories
- **[Implementation Plan](./specs/001-hn-mcp-server/plan.md)** - Technical design and architecture
- **[Research Documentation](./specs/001-hn-mcp-server/research.md)** - Technical decisions and rationale
- **[Data Model](./specs/001-hn-mcp-server/data-model.md)** - Entity schemas and validation rules
- **[Quickstart Guide](./specs/001-hn-mcp-server/quickstart.md)** - Usage examples and reference
- **[Tool Contracts](./specs/001-hn-mcp-server/contracts/tools.json)** - MCP tool definitions
---
## š License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
---
## š Acknowledgments
- **[HackerNews](https://news.ycombinator.com/)** - Community and content
- **[HN Algolia API](https://hn.algolia.com/api)** - Search API powering this server
- **[Model Context Protocol](https://modelcontextprotocol.io)** - MCP specification and SDK
- **[Anthropic](https://www.anthropic.com/)** - Claude and MCP development
---
## š Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/hn-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/hn-mcp-server/discussions)
- **HN API Docs**: [hn.algolia.com/api](https://hn.algolia.com/api)
- **MCP Docs**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
---
**Built with ā¤ļø using TypeScript, MCP SDK, and Biome**
