# 🌐 Agent Browser API

**A universal, fully working headless-browser for AI agents.** Give *any* agent — Zapier Agents, Custom GPTs, Claude, Cursor, LangChain, CrewAI, n8n, Make, or your own code — a **real Chromium browser**: JavaScript rendering, web search, clicking, typing, form filling, dropdowns, screenshots, table & data extraction, and PDF generation.

> 🇮🇳 **Hindi TL;DR:** Yeh ek real browser hai jo **koi bhi AI agent** use kar sakta hai — 3 tarike: simple REST API, OpenAPI import (Custom GPT), ya native MCP (Claude/Cursor/ChatGPT). Deploy karo, API key set karo, ho gaya. ✅ 26/26 tests passing.

## 🔌 Works with ANY agent — three ways to connect

| Mode | For | How |
|---|---|---|
| **REST API** | Zapier Agents, n8n, Make, LangChain, CrewAI, any code | `POST /v1/browse {"url": "..."}` with `X-API-Key` header. Auto-discover via `GET /v1/tools` (OpenAI function format). |
| **OpenAPI** | OpenAI Custom GPTs (Actions), API tooling | Import [`/openapi.yaml`](openapi.yaml) — every endpoint documented. |
| **MCP** 🆕 | Claude Desktop/Code, Cursor, Windsurf, ChatGPT, VS Code, n8n MCP | Point your MCP client at `https://YOUR-URL/mcp` (Streamable HTTP) — 22 browser tools appear natively. |

Full copy-paste guides per platform: **[INTEGRATIONS.md](INTEGRATIONS.md)** · Zapier specifics: **[ZAPIER_SETUP.md](ZAPIER_SETUP.md)**

## ✨ Features

| Capability | Endpoint | What it does |
|---|---|---|
| 📖 Browse | `POST /v1/browse` | Renders any page (JS included) → clean **Markdown** + title + links + metadata. LLM-ready. |
| 🔍 Search | `POST /v1/search` | Web search via Brave/Bing/DDG with auto-fallback. No search API key needed. |
| 📸 Screenshot | `POST /v1/screenshot` | PNG of page, **full page**, or a **single element**; custom viewport; binary or base64. |
| 🧲 Extract | `POST /v1/extract` | Structured data via CSS selectors → JSON. |
| 📊 Tables | `POST /v1/tables` | All data tables on a page → JSON (headers + rows), layout/hidden tables skipped. |
| 🖱️ Elements | `POST /v1/elements` | Visible links/buttons/inputs with **ready-to-use CSS selectors** — agents can *see* what's clickable. |
| 📄 PDF | `POST /v1/pdf` | Render any page to PDF (portrait/landscape). |
| 🧭 Sessions | `POST /v1/sessions` + actions | Stateful multi-step flows: `goto`, `click`, `type`, `fill`, `press`, `select`, `scroll`, `navigate` (back/forward/reload), `wait`, `evaluate`, `content`, `elements`, `screenshot`. |
| 🤝 MCP | `POST /mcp` | All of the above as native MCP tools (screenshots returned as real images). |

Plus: API-key auth, CORS, rate limiting, SSRF guard, session auto-expiry + LRU eviction, stealth basics, SPA settle waits, output truncation for LLM context safety, helpful error `hint`s, `/llms.txt`, and a full [OpenAPI spec](openapi.yaml).

## 🚀 Quick start

### Deploy free (Render) — recommended

1. Fork/push this repo to GitHub.
2. Go to [render.com](https://render.com) → **New → Blueprint** → pick this repo (`render.yaml` auto-detected).
3. Copy the generated `API_KEY` from the service's Environment tab.
4. Live at `https://your-service.onrender.com` 🎉

Also works on Railway, Fly.io, or any Docker host.

### Docker

```bash
docker build -t agent-browser .
docker run -p 8080:8080 -e API_KEY=your-secret-key agent-browser
```

### Run locally

```bash
npm install            # installs deps + Chromium
API_KEY=your-secret-key npm start
# → agent-browser v2.0.0 listening on :8080
```

## 🧪 Try it

```bash
BASE=http://localhost:8080; KEY=your-secret-key

# Read a JS-heavy page as markdown
curl -X POST $BASE/v1/browse -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com"}'

# Search the web
curl -X POST $BASE/v1/search -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"query":"best CRM for startups","limit":5}'

# Extract every table on a page as JSON
curl -X POST $BASE/v1/tables -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.scrapethissite.com/pages/forms/"}'

# Multi-step: search Wikipedia interactively
SID=$(curl -s -X POST $BASE/v1/sessions -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://en.wikipedia.org"}' | jq -r .sessionId)
curl -X POST $BASE/v1/sessions/$SID/fill -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"fields":{"input[name=search]":"Artificial intelligence"}}'
curl -X POST $BASE/v1/sessions/$SID/press -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"key":"Enter"}'
curl $BASE/v1/sessions/$SID/content -H "X-API-Key: $KEY"
curl -X DELETE $BASE/v1/sessions/$SID -H "X-API-Key: $KEY"
```

Run the full smoke-test suite: `npm test` — **26 checks** covering every endpoint *and* a real MCP client round-trip.

## ⚙️ Configuration (env vars)

| Variable | Default | Description |
|---|---|---|
| `API_KEY` | *(empty = auth off, dev only!)* | Required key for all non-public endpoints. |
| `PORT` | `8080` | HTTP port. |
| `MAX_SESSIONS` | `10` | Max concurrent stateful sessions (LRU eviction). |
| `SESSION_TTL_MS` | `600000` | Idle session expiry (10 min). |
| `NAV_TIMEOUT_MS` | `30000` | Navigation timeout. |
| `RATE_LIMIT_PER_MIN` | `120` | Requests/min per API key or IP (`0` = off). |
| `CORS_ORIGIN` | `*` | Allowed CORS origin. |
| `ALLOW_PRIVATE_URLS` | `false` | Allow browsing private/internal addresses (SSRF guard off). |

## 🔒 Security notes

- **Always set `API_KEY` in production** (Render blueprint generates one automatically).
- Only `http`/`https` URLs are allowed; localhost/private/metadata addresses are **blocked by default**.
- Run behind HTTPS (Render/Railway give you TLS for free).
- `evaluate` runs arbitrary JS *inside the sandboxed page* — keep your API key secret.
- Public (no key) endpoints are read-only info: `/`, `/health`, `/openapi.yaml`, `/llms.txt`, `/v1/tools`.

## 📁 Project structure

```
src/server.js         # Express API: auth, CORS, rate limit, routes
src/actions.js        # Shared high-level actions (used by REST + MCP)
src/browser.js        # Chromium lifecycle, sessions, TTL/LRU, SSRF guard
src/extract.js        # HTML → markdown, CSS extraction, tables, elements
src/search.js         # Multi-engine web search with fallback
src/mcp.js            # MCP server (Streamable HTTP, 22 tools)
src/tools-manifest.js # GET /v1/tools (OpenAI function format)
openapi.yaml          # Full API specification
test/run-tests.sh     # 26-check smoke-test suite (incl. MCP round-trip)
Dockerfile            # Production image (Playwright base, version-pinned)
render.yaml           # One-click Render deploy
```

## License

MIT