# websearch_tool

Web search tool with two interfaces sharing one core. Serper primary, DuckDuckGo fallback (on error or empty results).

## Install

```bash
uv pip install -e .   # or: pip install -e .
export SERPER_API_KEY=<your-key>
```

## HTTP API

```bash
uvicorn websearch.http_api:app --port 8000
curl "http://127.0.0.1:8000/search?q=anthropic+claude&num=5"
```

| Endpoint | Params | Response |
|----------|--------|----------|
| `GET /search` | `q` (str), `num` (1-50, default 10) | `{query, source, results[]}` |
| `GET /health` | — | `{status}` |

`source` is `serper` or `ddg`. Each result has `title`, `url`, `snippet`.

## MCP Server

```bash
python -m websearch.mcp_server   # stdio transport
```

Exposes one tool: `web_search(query: str, num: int = 10)`.

MCP client config:

```json
{
  "mcpServers": {
    "websearch": {
      "command": "python",
      "args": ["-m", "websearch.mcp_server"],
      "env": { "SERPER_API_KEY": "<your-key>" }
    }
  }
}
```

## Library

```python
from websearch import search
resp = search("anthropic claude", num=5)   # reads SERPER_API_KEY from env
```