# hn-mcp

MCP server for Hacker News research. Gives AI agents structured access to HN
stories, discussions, and the full 47M-item archive.

Works with Claude Code, ChatGPT, Cursor, and any MCP-compatible client.

## Tools

### `search` -- find stories and comments

```json
{ "query": "rust vs go backend", "min_points": 50 }
{ "query": "react", "type": "comment", "author": "gaearon" }
{ "query": "bitcoin", "date_from": "2017-01", "date_to": "2017-12" }
```

Uses Algolia for fast, ranked full-text search. Specify `date_from`/`date_to`
to search the local archive instead (DuckDB over Parquet, 2006-present).

### `browse` -- current front-page listings

```json
{ "list": "top", "count": 30 }
{ "list": "show" }
```

Lists: top, new, best, ask, show, job.

### `thread` -- read a full discussion

```json
{ "id": 27016630 }
{ "id": 27016630, "max_comments": 0 }
```

Returns the story and its full comment tree (threaded, not flat). Comments are
fetched in parallel. Default limit: 200 comments, depth 8.

### `user` -- look up a user

```json
{ "username": "pg" }
```

Returns karma, account age, about text, and recent submission IDs.

## Data Sources

| Source | Coverage | Speed | Used by |
|--------|----------|-------|---------|
| Algolia API | Indexed stories + comments | Fast | `search` |
| Firebase API | Real-time items, users, lists | Fast | `browse`, `thread`, `user` |
| Local Parquet + DuckDB | 47M+ items, 2006-present | Slower | `search` (with date range) |

## Deploy

```bash
npm install
npm run build
npm start
# listening on http://localhost:8787/mcp
```

With Docker:

```bash
docker compose up -d
```

The Docker setup binds `./data` as the Parquet archive directory. To download
the historical archive:

```bash
bash scripts/sync-data.sh
```

This fetches monthly Parquet shards from HuggingFace (~12 GB total). It skips
files already downloaded and re-downloads the current month.

### Production (nginx + certbot)

Copy `hn-mcp.conf` to `/etc/nginx/sites-enabled/`, update `server_name`, then:

```bash
certbot --nginx -d your-domain.com
```

## Connect

```bash
# Claude Code (local)
claude mcp add hn-research --url http://localhost:8787/mcp

# Claude Code (remote)
claude mcp add hn-research --url https://your-domain.com/mcp

# Cursor / VS Code -- add to .cursor/mcp.json or .vscode/mcp.json:
# { "mcpServers": { "hn-research": { "url": "http://localhost:8787/mcp" } } }
```

## Environment

| Var | Default | Description |
|-----|---------|-------------|
| `PORT` | `8787` | HTTP server port |
| `HN_DATA_DIR` | `/data/parquet` | Path to Parquet archive files |

## License

MIT