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
export TAVILY_API_KEY="tvly-..."
npx @reneturcios/researchsearch search "composting basics"
Or run the container image:
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
# 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:
npx -y @reneturcios/researchsearch mcp
MCP client configuration:
{
"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
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.