# HackerNews MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](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**