# supragents-mcp

A read-only research MCP server: Hacker News, Reddit, and Product Hunt in one
`npx` command. It works with zero API keys, Hacker News and Reddit's public
search both work out of the box. Add a free Reddit app for heavier Reddit use,
or a Product Hunt developer token to unlock `producthunt_top`.

No tracking, no accounts required to start, no dependencies beyond the MCP
SDK and `zod`, everything else uses Node's built-in `fetch`.

## Install

Nothing to install by hand, `npx` fetches it on first use. Add it to your
project's `.mcp.json`:

```json
{
  "mcpServers": {
    "supragents": {
      "command": "npx",
      "args": ["-y", "supragents-mcp"]
    }
  }
}
```

Restart Claude Code (or start a fresh session) and the tools below are
available immediately, no keys needed for Hacker News or basic Reddit use.

## Tools

| Tool | Params | What it does |
|---|---|---|
| `hn_search` | `query` (required), `limit?` (1-25, default 10) | Search Hacker News stories by relevance via the Algolia HN Search API. |
| `hn_front_page` | `limit?` (1-25, default 15) | Get the current Hacker News front page. |
| `hn_thread` | `id` (required), `max_comments?` (1-25, default 20) | Get a story and its top comments, flattened, HTML stripped. |
| `reddit_search` | `query` (required), `subreddit?`, `sort?` (`relevance`/`hot`/`top`/`new`/`comments`), `limit?` (1-25, default 15) | Search Reddit posts by keyword, optionally scoped to a subreddit. |
| `reddit_top` | `subreddit` (required), `timeframe?` (`hour`/`day`/`week`/`month`/`year`/`all`, default `week`), `limit?` (1-25, default 15) | Top posts from a subreddit over a timeframe. |
| `reddit_comments` | `post_url_or_id` (required), `limit?` (1-25, default 20) | A post plus its top-level comments, by URL or id. |
| `producthunt_top` | `topic?`, `limit?` (1-25, default 10) | Top Product Hunt posts, optionally by topic. Requires `PRODUCTHUNT_ACCESS_TOKEN`. |
| `market_research` | `topic` (required), `limit_per_source?` (1-25, default 10) | Runs `hn_search` + `reddit_search` (+ `producthunt_top` if configured) in parallel, merges results tagged by source, sorted by engagement. Returns `sources_used` and `sources_skipped`, a failure in one source never fails the whole call. |

Every result is capped at 25 items, and any HTML in text fields (comment
bodies, selftext, titles) is stripped to plain text before it's returned.

## Environment variables (all optional)

| Variable | Unlocks | How to get it |
|---|---|---|
| `REDDIT_CLIENT_ID` + `REDDIT_CLIENT_SECRET` | Reliable Reddit access via OAuth (app-only, no user login). Without these, Reddit tools fall back to the public `.json` endpoints, which Reddit sometimes rate-limits. | [reddit.com/prefs/apps](https://www.reddit.com/prefs/apps): create a "script" app, copy the client id and secret. |
| `PRODUCTHUNT_ACCESS_TOKEN` | `producthunt_top` (and Product Hunt's slice of `market_research`) | [producthunt.com/v2/oauth/applications](https://www.producthunt.com/v2/oauth/applications): create an application, generate a Developer Token. |

If a Reddit call hits a public-endpoint block (HTTP 403/429), the tool
returns an error result with the exact setup steps above instead of failing
silently. If `PRODUCTHUNT_ACCESS_TOKEN` is missing, `producthunt_top` returns
a helpful error pointing back here instead of a raw 401.

### Example with all env vars set

```json
{
  "mcpServers": {
    "supragents": {
      "command": "npx",
      "args": ["-y", "supragents-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your-client-id",
        "REDDIT_CLIENT_SECRET": "your-client-secret",
        "PRODUCTHUNT_ACCESS_TOKEN": "your-developer-token"
      }
    }
  }
}
```

## REST mode (`--serve`)

MCP over stdio is the primary interface, that's what Claude Code speaks and
what the sections above assume. `--serve` is a separate mode for everything
outside Claude Code: shell scripts, cron jobs, n8n, or any other tool that
wants to call these same tools over plain HTTP instead.

```bash
npx supragents-mcp --serve        # binds 127.0.0.1:8787
npx supragents-mcp --serve 9000   # custom port
```

It exposes the exact same 8 tools, same handlers, same env vars, just over
HTTP instead of stdio:

| Route | What it does |
|---|---|
| `GET /health` | `{ status, name, version, tools }` |
| `GET /tools` | Lists every tool with its title, description, and JSON Schema for its arguments |
| `POST /tools/{name}` | Calls a tool. JSON body is the tool's arguments (e.g. `{"query": "claude code"}` for `hn_search`). Returns the tool's JSON result on success, or a JSON error body on failure |

```bash
curl http://127.0.0.1:8787/health
curl http://127.0.0.1:8787/tools
curl -X POST http://127.0.0.1:8787/tools/hn_search \
  -H 'content-type: application/json' \
  -d '{"query": "claude code"}'
```

Binds to `127.0.0.1` by default, not `0.0.0.0`, so it's not reachable from
outside your machine unless you put something in front of it on purpose.

## Development

```bash
npm install
npm test
```

Tests are pure unit tests over the URL builders, HTML stripping, the Reddit
OAuth/public fallback decision, and the `market_research` merge logic (all
with injected fetchers, no live network calls), one test that spawns the
server binary and does a real MCP `initialize` + `tools/list` round trip
over stdio, and REST-mode tests covering route parsing, the unknown-tool 404,
and one end-to-end spawn of `--serve` against an ephemeral port.

## License

MIT