# Hacker News MCP Server

A Model Context Protocol (MCP) server for Hacker News, enabling LLMs to browse stories, inspect items, and look up user profiles via the official HN Firebase API.

## Features

- **Story Feeds**: Fetch Top, New, Best, Ask HN, Show HN, and Job stories.
- **Detailed Inspection**: Get full details for any item (story, comment, job, poll) and user profiles.
- **Live Updates**: Access recently changed items and the current max item ID.
- **Optimized for LLMs**:
  - Responses formatted in clear Markdown (or JSON when needed).
  - Built-in character limit to prevent context overflow.
  - Pagination (`limit` / `offset`) on all list-based tools.
- **Modern Stack**: TypeScript + official MCP SDK + Zod schema validation.

## Available Tools

| Tool | Description |
|---|---|
| `hn_get_top_stories` | Top stories (paginated) |
| `hn_get_new_stories` | Newest stories (paginated) |
| `hn_get_best_stories` | Best stories (paginated) |
| `hn_get_ask_stories` | Ask HN stories (paginated) |
| `hn_get_show_stories` | Show HN stories (paginated) |
| `hn_get_job_stories` | Job stories (paginated) |
| `hn_get_item` | Full details for a specific item ID |
| `hn_get_user` | User profile by username |
| `hn_get_updates` | Recently updated item & profile IDs |
| `hn_get_max_item` | Current largest item ID on HN |

All list tools accept `limit` (1–500, default 20), `offset` (default 0), and `response_format` (`markdown` or `json`).

## Getting Started

### Prerequisites

- Node.js 18+ **or** Bun

### Quick Run (no install)

```bash
# npx
npx -y @fritzprix/hn-mcp

# bunx
bunx @fritzprix/hn-mcp
```

### Global Install

```bash
npm install -g @fritzprix/hn-mcp
hn-mcp
```

### From Source

```bash
git clone https://github.com/fritzprix/hn-mcp.git
cd hn-mcp
npm install
npm run build
npm start
```

## MCP Client Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "@fritzprix/hn-mcp"]
    }
  }
}
```

### Other MCP Clients (Cursor, Windsurf, etc.)

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "npx",
      "args": ["-y", "@fritzprix/hn-mcp"]
    }
  }
}
```

## Development

```bash
npm run dev    # run with tsx (no build needed)
npm run build  # compile TypeScript → dist/
npm run watch  # watch mode
```

## License

MIT