@cyanheads/hn-mcp-server
by cyanheads
README.md
<div align="center">
<h1>@cyanheads/hn-mcp-server</h1>
<p><b>Browse Hacker News feeds, threads, and user profiles with full-text search via MCP. STDIO or Streamable HTTP.</b>
<div>4 Tools</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/hn-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/hn-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/hn-mcp-server/releases/latest/download/hn-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=hn-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvaG4tbWNwLXNlcnZlciJdfQ==) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22hn-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/hn-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**Public Hosted Server:** [https://hn.caseyjhand.com/mcp](https://hn.caseyjhand.com/mcp)
</div>
---
## Overview
Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Search API. Browse ranked feeds, read full comment threads, look up user profiles, and search stories, comments, polls, and jobs by keyword or by type, author, parent story, date, or score. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
### Tools
| Tool | Description |
|:---|:---|
| `hn_get_stories` | Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count |
| `hn_get_thread` | Get an item and its comment tree as a threaded discussion, with depth and comment-count controls and a cursor to page through long threads |
| `hn_get_user` | Fetch a user profile with karma, about, and optionally a page of resolved submissions |
| `hn_search_content` | Search stories, comments, polls, and jobs via Algolia by keyword, by filters alone, or both — type, author, parent story, date range, and minimum points |
## Capability reference
### `hn_get_stories` <sub>tool</sub>
- Six feed types: `top`, `new`, `best`, `ask`, `show`, `jobs`; `count` (1–100, default 30) and `offset` for pagination
- Returns id, type, title, url, domain, score, author, timestamp, comment count, and body text — each field omitted (not null) when HN doesn't provide it
- Enrichment reports `total`, `offset`, and `hasMore`; while more stories remain, `truncated` is set and `notice` names the next `offset`, and a `notice` explains empty pages (empty feed, offset past end, or every item on the page deleted/flagged). The last page carries no truncation
- Items whose fetch failed after retries are listed in `failedIds` with a `notice` naming the retry; a page where every item failed returns the classified upstream error instead of an empty list
---
### `hn_get_thread` <sub>tool</sub>
- `itemId` plus `depth` (0–10, default 3; 0 returns the item with no comments) and `maxComments` (1–200, default 50) capping one response across all levels, alongside a fixed 64,000-byte text budget that cuts only between comments
- Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
- Resumable: a response stopped by `maxComments`, the byte budget, or an upstream rate limit returns `nextCursor`; passing it back as `cursor` with the same `itemId` continues at the next unseen comment. The cursor carries the unvisited comments themselves, so re-ranked replies cannot shift it, and the server keeps no session state. A cursor passed with a different `itemId` fails with `invalid_cursor`
- The root carries its relationships and state: `parent` for a comment, `poll` for a poll option, `parts` and resolved `options` (text and votes, at every depth) for a poll, and `deleted`/`dead` markers. The `content[]` heading names the type — a title, `Comment by <author>`, `Poll option by <author> on poll <id>` — and marks a deleted or dead root
- Flat comment list carries `depth`/`parentId` for tree reconstruction, plus `childCount` and an `isOp` flag when the comment author matches the root item's author
- `truncated` and `truncationReason` (`count`, `size`, `rate_limited`, or `depth` when replies lie below the depth limit) are set only while comments remain unread — never on a terminal page, including a thread that loads in full at exactly the cap. `notice` reports deleted/dead comments omitted during traversal and the next step: the cursor, or a larger `depth` or a comment id as `itemId`
- Comments and poll options whose fetch failed after retries are listed in `failedIds`, and `notice` names them with the retry; failed comments ride in `nextCursor`, so paging on retries them rather than skipping them. The root item is still returned, and a failure is never passed off as a `maxComments`/`depth` limit
---
### `hn_get_user` <sub>tool</sub>
- `username` is case-sensitive and trimmed; `includeSubmissions` (default false) resolves recent submissions, with `submissionCount` (1–50, default 10) and `submissionOffset` paging through a long history
- Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
- A comment submission carries its `parent` and a poll-option submission its `poll`, so either links back to what it answered
- Enrichment echoes `submissionOffset` and the offset to send next, or a notice when the requested offset is past the end of the history
- Submissions whose fetch failed after retries are listed in `failedIds` with a `notice` naming the retry; a window where every submission failed returns the classified upstream error
---
### `hn_search_content` <sub>tool</sub>
- Free-text `query` plus `tags` (`story`/`comment`/`poll`/`job`/`ask_hn`/`show_hn`/`front_page`), `author`, `storyId`, `dateRange`, and `minPoints` filters; `sort` by relevance or date; `count` (1–50, default 30) and `page` for pagination
- `query` is optional when a filter is set — list Ask HN, Show HN, polls, or jobs on their own, or pass a story's `storyId` with `tags: "comment"` to search within one thread. No query and no filter fails with `missing_query_or_filter`
- `dateRange` bounds take ISO 8601 (`YYYY`, `YYYY-MM`, `YYYY-MM-DD`, or a date-time with optional offset), read as UTC and both exclusive; an empty or out-of-order range fails with `invalid_date_range`
- `minPoints` applies to stories and polls — comments and jobs carry no points, so pairing it with `tags: "comment"` or `"job"` fails with `min_points_unscored_type`
- `view: "compact"` drops the two body-text fields (`text`, `highlights.text`), which otherwise repeat a long comment twice per hit — pass a hit id to `hn_get_thread` to read the body
- Highlight metadata (`highlights.title`, `highlights.text`, `matchedWords`) shows which terms matched and where
- Enrichment reports `totalHits`, `page`, and the actual reachable `totalPages` — not derived from `totalHits`, since broad queries report far more hits than Algolia will serve. While more pages remain, `truncated` is set and `notice` names the next `page`; a page past the end gets a notice naming the last valid page (or `page: 0` past Algolia's 1,000-hit ceiling)
## Features
Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.
HN-specific:
- Two upstream APIs: HN's Firebase API for feeds, items, and users; Algolia's HN Search API for full-text search
- Concurrent batch fetching with configurable parallelism for item resolution (`HN_CONCURRENCY_LIMIT`)
- HTML bodies stripped to plain text — entities decoded once, code blocks kept verbatim, each link rendered once as its full URL — while titles, which are not HTML though some carry entities, are entity-decoded and never tag-stripped
- Server-level `instructions` forwarded to LLM clients on `initialize` — item types, ID reuse across tools, case-sensitive usernames, field sparsity
- No API keys required — both upstream APIs are public
Agent-friendly output:
- Graceful partial failure — an item whose fetch fails after retries is reported by ID in `failedIds`, apart from deleted, dead, or nonexistent items, rather than silently shrinking the result; `hn_get_thread` also counts the deleted and dead comments it drops, and a rate-limited item stops the batch instead of sending every remaining item through its own retry ladder
- Discriminated output contracts — typed error reasons (`item_not_found`, `upstream_rate_limited`, `upstream_html`, …) with per-reason recovery text (a rate limit passes on the upstream's `Retry-After` as `retryAfter`), and a `depth`/`parentId` pair on every comment so callers reconstruct the tree without guessing nesting
- Pagination provenance — every paged listing echoes the offset it used (`offset`, `submissionOffset`, `page`) plus the exact next-offset value in `notice`, and `hn_get_thread` returns a self-contained `nextCursor`, so an agent can resume without recomputing state
- Response shaping — HTML stripping, URL normalization, and domain extraction remove upstream markup noise; `hn_search_content`'s `view: "compact"` drops the two body-text fields that otherwise duplicate a hit's full text
- Fenced upstream text — in `content[]`, every line of a body is block-quoted and titles are escaped only where they could break the surrounding Markdown, so a comment cannot pass for a server-authored line
## Getting started
### Public Hosted Instance
A public instance is available at `https://hn.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:
```json
{
"mcpServers": {
"hn-mcp-server": {
"type": "streamable-http",
"url": "https://hn.caseyjhand.com/mcp"
}
}
}
```
### Self-Hosted / Local
Add to your MCP client configuration file:
```json
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/hn-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with npx (no Bun required):
```json
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/hn-mcp-server"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
Or with Docker:
```json
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/hn-mcp-server:latest"
]
}
}
}
```
### Prerequisites
- [Bun v1.4.0](https://bun.sh/) or higher (or Node.js >= 24)
### Installation
```sh
git clone https://github.com/cyanheads/hn-mcp-server.git
cd hn-mcp-server
bun install
```
## Configuration
All configuration is via environment variables. No API keys required — HN APIs are public.
| Variable | Description | Default |
|:---------|:------------|:--------|
| `HN_CONCURRENCY_LIMIT` | Max concurrent HTTP requests for batch item fetches (integer, 1–50). | `10` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
| `MCP_HTTP_HOST` | HTTP server host. | `localhost` |
| `MCP_SESSION_MODE` | HTTP session handling: `stateful`, `stateless`, or `auto` (resolves to `stateful`). The server declares `stateless` in source, and the published Docker image and `.env.example` set it too; a meaningful env value still overrides. | `stateless` |
| `MCP_LOG_LEVEL` | Log level: `debug`, `info`, `notice`, `warning`, `error`. | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<project-root>/logs` |
See [`.env.example`](./.env.example) for the full list of optional overrides.
## Running the server
### Local development
- **Dev mode (auto-reload):**
```sh
MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts # stdio
MCP_TRANSPORT_TYPE=http bun --watch src/index.ts # HTTP
```
- **Build and run:**
```sh
bun run rebuild
bun run start:stdio # or start:http
```
- **Run checks and tests:**
```sh
bun run devcheck # Lint, format, typecheck, security
bun run test # Vitest test suite
```
### Docker
```sh
docker build -t hn-mcp-server .
docker run --rm -p 3010:3010 hn-mcp-server
```
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/hn-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.
## Project structure
| Directory | Purpose |
|:----------|:--------|
| `src/index.ts` | `createApp()` entry point — registers tools and inits the HN service. |
| `src/config/` | Server-specific environment variable parsing and validation with Zod. |
| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
| `src/services/hn/` | HN Firebase + Algolia API client and domain types. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for request-scoped logging
- All tools are read-only — no auth scopes required
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
## Contributing
Issues are welcome. Run checks before submitting:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessSlow