# Hacker News MCP

An [MCP](https://modelcontextprotocol.io/) server that exposes Hacker News data as tools for AI agents. Built on [Cloudflare Workers](https://workers.cloudflare.com/) with the [Agents SDK](https://developers.cloudflare.com/agents/).

Data comes from the [Hacker News Firebase API](https://github.com/HackerNews/API).

## Tools

| Tool | Description |
| --- | --- |
| `get-item` | Get any item by ID (story, comment, job, poll, or poll option) |
| `get-top-stories` | Top stories (optional `limit`, default 30) |
| `get-new-stories` | Newest stories |
| `get-best-stories` | Best stories |
| `get-ask-stories` | Ask HN stories |
| `get-show-stories` | Show HN stories |
| `get-job-stories` | Job postings |
| `get-user` | User profile by username |
| `get-comments` | Top-level comments for a story (`id` required, optional `limit`) |

## Setup

```bash
npm install
```

## Development

```bash
npm run dev
```

Starts a local Worker with Wrangler. Point your MCP client at the local endpoint once it's running.

## Deploy

```bash
npm run deploy
```

Deploys to Cloudflare Workers. After deploy, connect your MCP client to the Worker URL.

## Project structure

```
src/
  main.ts              # MCP server entrypoint
  tools/               # Individual tool handlers
  utils/registerTools.ts
wrangler.jsonc         # Cloudflare Workers config
```

## Contributing

1. Fork the repository and create a branch from `main`.
2. Install dependencies with `npm install`.
3. Make your changes and verify them locally with `npm run dev`.
4. Open a pull request describing what you changed and why.

Bug reports and feature ideas are welcome via [GitHub Issues](https://github.com/Dhanush-git/hacker-news-mcp/issues).