Hacker MCP Server POC
Lightweight Model Context Protocol (MCP) server that exposes Hacker News data as tools. Built with TypeScript and the @modelcontextprotocol/sdk.
Ask AI about Hacker MCP Server POC
Powered by Claude Β· Grounded in docs
I know everything about Hacker MCP Server POC. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 commentsget-user-detailsβ fetch user profile and recent activitysearch-newsβ search Hacker News via Algolia and format results
- Written in TypeScript. Uses
axiosfor HTTP requests andzodfor input validation.
Project structure (important files)
src/index.tsβ MCP server registration and tool handlerssrc/helper.tsβ HTTP helpers that call the Hacker News Firebase API and Algoliasrc/utils.tsβ utility helpers (timestamp formatting)build/β compiled JavaScript output afternpm run buildpackage.jsonβ scripts and dependencies
Requirements
- Node.js 18+ (or recent LTS)
- npm
Quick start
-
Install dependencies
npm install
-
Build (TypeScript -> JavaScript)
npm run build
This compiles
src/intobuild/and sets execute permission onbuild/index.js. -
Run
-
Production: run the compiled build
node build/index.js
-
Development: the repository includes a
devscript that uses nodemon. Note: thedevscript 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
-
-
Server transport
The server uses
StdioServerTransportby 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, modifysrc/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
.envfile is supported viadotenvif you want to inject configuration. Currently there are no required environment variables in the code, but keep.envfor future credentials or toggles.
Development notes & best practices
- Keep network calls resilient: the helpers currently fetch the first 10 items and return
nullon failure. Consider adding retries, timeouts and better error payloads for production. - Validate edge cases: stories may not have
kids(comments) orurl. Helper functions assume certain fields exist β add guards to avoid runtime errors. - Tests: add unit tests for
helper.tsfunctions by mockingaxioscalls. - Linting & formatting: add ESLint + Prettier for consistent style.
Contributing
- Fork the repository
- Create a branch for your feature/fix
- 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.
