# gander 🦢

*Take a gander at the web — a distraction-free terminal browser and MCP server for humans and AI agents.*

![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

`gander` fetches a web page, strips away the navigation/ads/scripts, and gives you
just the readable content — as formatted text in your terminal, as an interactive
TUI you can scroll and click through, or as tools an AI agent can call over the
**Model Context Protocol (MCP)**.

## Why

Most "AI-friendly" browsing today means shipping a full headless Chromium instance.
`gander` takes the opposite bet: read the web the way a text browser like `lynx`
always has, but with modern content extraction and a first-class MCP server so
any MCP-compatible agent can browse readable web content without a GPU or a
rendering engine in sight.

## Install

```bash
git clone https://github.com/abdulkhaliqfarah/gander.git
cd gander
uv venv && source .venv/bin/activate
uv pip install -e .
```

## Usage

### Read a page from the command line

```bash
gander view https://example.com/some-article
gander view https://example.com/some-article --json   # structured output
```

### Browse interactively

```bash
gander tui                       # opens with an empty address bar
gander tui https://example.com   # opens directly on a page
```

Keybindings: `o` open URL · `b` back · `f` forward · `j`/`k` scroll · `g`/`G` top/bottom · `q` quit.
Select any link in the right-hand panel and press Enter to follow it.

### Run as an MCP server

```bash
gander mcp
```

This starts a stdio MCP server exposing two tools:

| Tool | Description |
| --- | --- |
| `browse_url(url)` | Fetch a URL, return title, markdown content, and links |
| `search_in_page(url, query)` | Fetch a URL, return snippets matching a search query |

Add it to your MCP client config (e.g. Claude Desktop, VS Code):

```json
{
  "mcpServers": {
    "gander": {
      "command": "gander",
      "args": ["mcp"]
    }
  }
}
```

## How it works

1. **Fetch** — `httpx` retrieves the raw HTML.
2. **Extract** — [`trafilatura`](https://github.com/adbar/trafilatura) pulls out the
   main readable content as markdown, and `lxml` collects every link on the page
   (resolved to absolute URLs).
3. **Present** — as `rich`-formatted terminal output, a `textual` TUI, or MCP tool
   responses, depending on how you run it.

## Development

```bash
uv pip install -e ".[dev]"
pytest
ruff check .
```

## License

MIT © Abdulkhaliq Farah — see [LICENSE](LICENSE).