# answersearch

answersearch puts Perplexity's models within reach of a terminal or
an agent. You can put a question to a search-grounded model and get an
answer with its sources, pull ranked web results on their own, hand a
hard problem to the reasoning model, or commission a slower, deeper
research pass that reads widely before it writes. It runs as a small
CLI or as an MCP server, and it needs a Perplexity API key.

## Setup

Get a key from the Perplexity API portal and export it:

```bash
export PERPLEXITY_API_KEY=<redacted>
```

Without the variable set, every command and tool call fails with an
error that names `PERPLEXITY_API_KEY` — nothing is sent anywhere.

## Install

```bash
npx @reneturcios/answersearch ask "what changed in the latest Node LTS?"
```

Or run the container image:

```bash
docker run -i -e PERPLEXITY_API_KEY ghcr.io/cloudcorprecords/answersearch
```

The container defaults to the MCP server (see below). Pass CLI
arguments to use it as a CLI instead.

## CLI

```bash
# Conversational answer grounded in live web search (sonar-pro)
answersearch ask "who won the marathon last weekend?"

# Ranked search results only, with optional budgets
answersearch search "composting basics" --max-results 5 --max-tokens 4000 --max-tokens-per-page 512

# Step-by-step reasoning (sonar-reasoning-pro)
answersearch reason "prove that the square root of two is irrational"

# Deep, multi-source research (sonar-deep-research) — this one takes a while
answersearch research "compare the failure modes of lithium and sodium batteries"

answersearch --version
```

Successful calls print the API's JSON response. Exit codes: `0` on
success, `1` when the API call fails (including a missing key), `2`
for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/answersearch mcp
```

MCP client configuration:

```json
{
  "mcpServers": {
    "answersearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/answersearch", "mcp"],
      "env": { "PERPLEXITY_API_KEY": "your-key-here" }
    }
  }
}
```

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `perplexity_ask` | `messages` (array of `{role, content}`, required) | Conversational answer with live web search, via the `sonar-pro` model on the chat-completions endpoint. |
| `perplexity_search` | `query` (string, required), `max_results`, `max_tokens`, `max_tokens_per_page` (integers, optional) | Direct call to the Search API; returns its ranked results and metadata as returned upstream. |
| `perplexity_reason` | `messages` (required, same shape) | Analytical reasoning via `sonar-reasoning-pro`. |
| `perplexity_research` | `messages` (required, same shape) | Deep research via `sonar-deep-research`; expect a longer wait than the other tools. |

Tool results are the upstream JSON, pretty-printed as text. Upstream
failures (bad key, quota, HTTP errors) come back as tool errors
carrying the status and the API's own message.

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx
```

## License

MIT — see `LICENSE`.