Skip to main content
Glama
README.md
# 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

A3.6/5.0

Scored across 2 tools

Disambiguation5/5

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.

Naming Consistency5/5

Both tools use the same hn_ prefix followed by a short noun/verb (search, story). The pattern is predictable and consistent.

Tool Count2/5

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.

Completeness2/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues