# beacon

A zero-config **web search MCP server** for any MCP client (opencode, Claude Desktop, Cursor, etc.).

Gives your local models the ability to **search the web** and **read page content** — no API keys, no Docker, no setup beyond `pip install`.

## What it gives you

Two MCP tools:

| Tool | Description |
|------|-------------|
| `beacon_search(query, max_results=5)` | Web search via DuckDuckGo. Returns `{title, url, snippet}` hits. |
| `beacon_fetch(url, max_chars=8000)` | Fetches a URL and returns its main readable text (HTML-stripped, boilerplate removed). |

## Install

```bash
git clone <your-fork-url> beacon
cd beacon
python3 -m venv .venv
.venv/bin/pip install -e .
```

## Register with an MCP client

### opencode

Add to your `opencode.json`:

```json
{
  "mcp": {
    "beacon": {
      "type": "local",
      "command": ["/absolute/path/to/beacon/.venv/bin/beacon-mcp"]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "beacon": {
      "command": "/absolute/path/to/beacon/.venv/bin/beacon-mcp"
    }
  }
}
```

## Manual testing (CLI)

```bash
.venv/bin/beacon search "python async patterns"
.venv/bin/beacon fetch https://example.org
```

## Configuration (optional, via env vars)

| Variable | Default | Purpose |
|----------|---------|---------|
| `BEACON_TIMEOUT` | `15` | HTTP timeout (seconds) for fetch |
| `BEACON_USER_AGENT` | Firefox-like string | User-Agent for outbound requests |
| `BEACON_LOG_LEVEL` | `INFO` | Logging verbosity |

No state is written to disk. No database. No API keys required.

## Development

```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -v
```

## License

MIT.