hn-mcp-server

---

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 _tool

• 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 _tool

• 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 _tool

• 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 _tool

• 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: 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:

{
  "mcpServers": {
    "hn-mcp-server": {
      "type": "streamable-http",
      "url": "https://hn.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add to your MCP client configuration file:

{
  "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):

{
  "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:

{
  "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 or higher (or Node.js >= 24)

Installation

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 for the full list of optional overrides.

Running the server

Local development

• Dev mode (auto-reload):

  MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts   # stdio
  MCP_TRANSPORT_TYPE=http bun --watch src/index.ts    # HTTP
  

• Build and run:

  bun run rebuild
  bun run start:stdio   # or start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  

Docker

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 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:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.