Content
# Tool List
MCP Server for web search and condensed research. Accepts a query, gathers content from open sources, filters it through embedding, and returns a markdown report. Connects to any MCP client and provides two tools: `search` for quick search and `research` for full pipeline.
## Tools
### `search`
Search without scraping and LLM — returns a list of results with title, URL, and snippet. Suitable for cases where only search engine output is needed.
| Parameter | Type | Default | Description |
|---|---|---|---|
| `query` | string | — | Search query |
| `max_results` | int (1–20) | 5 | Number of results |
### `research`
Full pipeline: search → scraping → embedding filtering → report from Grok.
| Parameter | Type | Default | Description |
|---|---|---|---|
| `query` | string | — | Research topic |
| `depth` | `quick` / `standard` | `quick` | `quick` — one search query; `standard` — Grok forms three refining queries |
| `max_words` | int (100–2000) | 500 | Target report volume |
| `language` | string | `english` | Report language |
---
## `research` Pipeline
```
query
│
├─ depth="standard" ──► Grok forms 3 refining search queries
│ depth="quick" ──► [query]
│
└─ in parallel for each query:
├─ search via Tavily, fallback to DDG on failure
├─ scraping of found pages
└─ embedding filtering: selection of relevant fragments
│
└─ Grok forms a report based on collected context
ResearchReport(report, sources, elapsed_seconds, cost_usd, partial, stats)
```
Artifacts of each run are saved in the `research/` directory: one file per scraped page and the final report.
---
## Architecture
```
MCP Client
│ MCP (stdio)
▼
MCP Server ──► Grok API / Tavily / DDG / scraping (HTTPS)
│ TCP loopback
▼
Embedding Daemon (model in GPU/RAM)
```
**MCP Server** implements the main logic: query planning, search, scraping, and Grok interaction. Runs during the MCP client session.
**Embedding Daemon** is separated into a distinct process since the model occupies about 2 GB and reloading it on each call is time-consuming. The daemon starts automatically on the first request, holds the model in memory between queries, unloads it after an idle period, and then exits.
---
## Requirements
### Full-featured GPU
For embedding, [`intfloat/multilingual-e5-large`](https://huggingface.co/intfloat/multilingual-e5-large) is used: ~2.2 GB on disk and 2.5–3 GB VRAM. Operation without a GPU is supported but significantly slower: a typical report takes ~1 minute on a graphics card versus ~16 minutes on a CPU. On Apple Silicon, MPS-backend is used automatically.
### [uv — Python package manager](https://docs.astral.sh/uv/getting-started/installation/)
Used for dependency installation and server launch. Automatically fetches the required Python version (3.11+) and manages the virtual environment.
### [Grok API Token](https://console.x.ai)
LLM provider for query planning and report formation. Among tested providers, it shows the best quality of work with current information. Passed in the `GROK_API_KEY` variable.
### [Tavily API Token](https://app.tavily.com)
Primary search engine: returns page content without separate scraping, noticeably faster and better than DDG fallback. Not required but highly recommended. Passed in the `TAVILY_API_KEY` variable.
---
## Installation
1. Copy the release to the target machine and navigate to its root.
2. Create `.env` based on `.env.example` and fill in the keys:
```
GROK_API_KEY=... # required
TAVILY_API_KEY=... # optional, recommended
```
If this step is skipped, the installer will create a file from the template and suggest filling it manually.
3. Run the installer for your OS. It will install dependencies, download the embedding model (~2.2 GB), and generate `mcp.json` with the absolute path to the build:
- Linux: `tools/linux/install.sh`
- macOS: `tools/mac/install.sh`
- Windows: `tools\win\install.ps1`
4. Connect `mcp.json` to the MCP client: either as a separate configuration file or by merging the `mcpServers.urb-research` section with an existing config.
