# researchsearch

researchsearch is a research desk for the web, powered by the Tavily
API. It searches with ranked, content-bearing results (and an optional
generated answer), pulls the clean text out of specific pages, crawls
a site page by page under limits you set, and maps a site's structure
so you can see what is there before you read it. It works from the
command line or as an MCP server for agents.

A Tavily API key is required. Put it in the `TAVILY_API_KEY`
environment variable; without it, every operation stops with an error
that names the missing variable, before any request is made.

## Install

```bash
export TAVILY_API_KEY="tvly-..."
npx @reneturcios/researchsearch search "composting basics"
```

Or run the container image:

```bash
docker run -i -e TAVILY_API_KEY="tvly-..." ghcr.io/cloudcorprecords/researchsearch
```

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

## CLI

```bash
# Search; results print as JSON
researchsearch search "composting basics"
researchsearch search "rate decision" --topic news --days 3 --max-results 5 --answer

# Extract the clean content of one or more pages
researchsearch extract https://example.com/article
researchsearch extract https://example.com/a https://example.com/b --depth advanced

# Crawl a site from a starting page
researchsearch crawl https://example.com --max-depth 2 --limit 25
researchsearch crawl https://example.com --instructions "Focus on the guides"

# Map a site's structure (URLs only, no page content)
researchsearch map https://example.com --max-depth 1 --limit 50

researchsearch --version
```

Exit codes: `0` on success, `1` when an operation fails (a missing
`TAVILY_API_KEY`, an HTTP error from the service, an unreachable host),
`2` for usage errors.

## MCP server

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

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

MCP client configuration:

```json
{
  "mcpServers": {
    "researchsearch": {
      "command": "npx",
      "args": ["-y", "@reneturcios/researchsearch", "mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-..."
      }
    }
  }
}
```

### Tools

| Tool | Input | What it returns |
| --- | --- | --- |
| `tavily-search` | `query` (string, required), `search_depth`, `topic`, `days`, `max_results`, `include_answer`, `include_raw_content`, `include_domains`, `exclude_domains` (all optional) | Ranked results with content excerpts and scores, plus a generated answer and raw page content when requested. |
| `tavily-extract` | `urls` (string array, required), `extract_depth`, `include_images`, `query` (optional) | The clean extracted content of each page, with failures reported separately. |
| `tavily-crawl` | `url` (string, required), `max_depth`, `max_breadth`, `limit`, `instructions`, `extract_depth` (optional) | The pages visited from the starting URL, each with its extracted content. |
| `tavily-map` | `url` (string, required), `max_depth`, `max_breadth`, `limit`, `instructions` (optional) | The list of URLs reachable from the starting page, without page content. |

Each tool is one call to the matching Tavily API endpoint. Only the
parameters you set are sent — unset optionals are omitted so the
service applies its own defaults — and each response is the service's
JSON, passed back unchanged.

## 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`.