hacker-news
# api-to-mcp
Turn any REST API into an MCP server, **about 10 lines per endpoint**. The example wraps the public Hacker News API (no key needed), so you can ask Claude, Cursor or any MCP app things like *"What did HN think about MCP this year?"*
Built in the video **"Turn Any API Into an MCP Server in 15 Minutes"** from The Build Receipt.
## The pattern
```ts
export const searchStories: ApiTool<typeof SEARCH_SHAPE> = {
name: "hn_search",
description: "Search Hacker News stories by keyword…", // the AI reads this to decide when to call it
input: { query: z.string().min(1), limit: z.number().int().max(20).default(5) },
url: ({ query, limit }) => `https://hn.algolia.com/api/v1/search?…&query=${encodeURIComponent(query)}`,
map: (json) => /* trim the response to what the AI needs */,
};
```
`registerApiTool(server, searchStories)` does the rest: input validation, a 10-second timeout, and errors returned to the AI instead of crashing the server.
**The `map` function is the important part.** Raw API responses are full of fields the AI doesn't need, and every extra field costs context. Trim them.
## Run it
```bash
npm install
npm test # 6 unit tests against saved real API responses (offline)
npm run live # starts the server like an AI app would and calls the live API
```
## Connect it
```bash
npm run build
claude mcp add hacker-news -- node "$(pwd)/dist/src/server.js"
```
Or in Claude Desktop / Cursor's MCP config:
```json
{ "mcpServers": { "hacker-news": { "command": "node", "args": ["/ABSOLUTE/PATH/dist/src/server.js"] } } }
```
## Wrap your own API
1. Copy `src/hn.ts` to `src/yourapi.ts`.
2. One `ApiTool` object per endpoint.
3. Register it in `src/server.ts`.
4. If the API needs a key, read it from an environment variable in `url` or add a header in `fetchJson`. Never hard-code it.
MIT License
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: hn_search is keyword-based discovery, while hn_story is a direct fetch by id. An agent can easily choose between them based on whether it has an id or a query.
Both tools use the same hn_ prefix followed by a short noun/verb (search, story). The pattern is predictable and consistent.
Two tools is very thin for a Hacker News integration; only keyword search and single-story fetch are exposed. Whole categories of common operations are absent, making the surface feel under-scoped.
Core reading is covered (search + fetch a story), but there is no way to retrieve comments, list top/new/best stories, or look up users. These are significant gaps for the stated Hacker News domain, leaving agents with dead ends.