hacker-news-mcp

Lightweight Model Context Protocol (MCP) server that exposes Hacker News data as tools. Built with TypeScript and the @modelcontextprotocol/sdk. The server fetches top/new/best stories, story details (including comments), user profiles and supports search through the HN Algolia API.

Features

• Exposes MCP tools:
  • get-news — fetch top/new/best stories (returns first 10)
  • get-news-detail — fetch story metadata and first 10 comments
  • get-user-details — fetch user profile and recent activity
  • search-news — search Hacker News via Algolia and format results
• Written in TypeScript. Uses axios for HTTP requests and zod for input validation.

Project structure (important files)

• src/index.ts — MCP server registration and tool handlers
• src/helper.ts — HTTP helpers that call the Hacker News Firebase API and Algolia
• src/utils.ts — utility helpers (timestamp formatting)
• build/ — compiled JavaScript output after npm run build
• package.json — scripts and dependencies

Requirements

• Node.js 18+ (or recent LTS)
• npm

Quick start

1. Install dependencies

   npm install

2. Build (TypeScript -> JavaScript)

   npm run build

   This compiles src/ into build/ and sets execute permission on build/index.js.

3. Run

   • Production: run the compiled build

     node build/index.js

   • Development: the repository includes a dev script that uses nodemon. Note: the dev script is configured to run ./index.js; ensure you have a run target that makes sense for your workflow (for example run the compiled file or run ts-node). Example dev run using the compiled file:

     npm run build && nodemon build/index.js

4. Server transport

   The server uses StdioServerTransport by default. This means it expects to communicate over STDIO (useful when launched by an MCP client that connects via stdio). If you need another transport, modify src/index.ts.

Tools (inputs & outputs)

• get-news

  • Input: { "newsType": "top" | "new" | "best" }
  • Output: { result: [ { id, time, title, url, by } ] }

• get-news-detail

  • Input: { "storyId": number }
  • Output: { result: { title, time, id, url, by, comments: [ { id, time, text, by } ] } }

• get-user-details

  • Input: { "userId": string }
  • Output: { result: { id, about, created, activity: [ { type, ... } ] } }

• search-news

  • Input: { "searchQuery": string }
  • Output: { result: [ { title, url, story_id, createdAt } ] }

All outputs are returned as both plain text (stringified JSON) and as structuredContent suitable for MCP clients.

Environment & configuration

• A .env file is supported via dotenv if you want to inject configuration. Currently there are no required environment variables in the code, but keep .env for future credentials or toggles.

Development notes & best practices

• Keep network calls resilient: the helpers currently fetch the first 10 items and return null on failure. Consider adding retries, timeouts and better error payloads for production.
• Validate edge cases: stories may not have kids (comments) or url. Helper functions assume certain fields exist — add guards to avoid runtime errors.
• Tests: add unit tests for helper.ts functions by mocking axios calls.
• Linting & formatting: add ESLint + Prettier for consistent style.

Contributing

1. Fork the repository
2. Create a branch for your feature/fix
3. Open a PR with a clear description and tests where applicable

License

See package.json (currently set to ISC). Adjust the license file as needed.

Contact

Open an issue or PR in the repository for questions or improvements.