# WebPilot.si examples

Runnable examples for the three ways in: the Python and TypeScript SDKs, MCP clients and plain HTTP (curl). A
running gateway also serves this folder at `/examples`, linked from the landing page and `/docs`.

They use only Wikipedia, example.com and the local fixture site in this folder: never a real company's site.

## Set up

```bash
pip install webpilot-si                       # Python 3.9+
npm install webpilot-si                       # or TypeScript / JavaScript (Node.js 20+), in examples/typescript
export WEBPILOT_URL=http://localhost:8931     # your gateway (https://webpilot.si for the hosted service)
export WEBPILOT_TOKEN=cbu_...                 # your user token, shown once when an admin created your user
```

No token yet? Sign up on the gateway's landing page (`/`), or run a gateway locally with Docker (see the main
README) and create a user in the admin console at `/admin`. Lost it? `/token` emails you a link to a new one.

### The fixture site

`fixture_site.py` is a small local site (Python standard library only) with a login, a 2FA prompt, a CSV download
and a checkout form. The browser runs inside the gateway, so the gateway must reach it:

```bash
python examples/fixture_site.py               # serves http://0.0.0.0:8765
export WEBPILOT_FIXTURE=http://host.docker.internal:8765   # the default: a gateway in Docker on this machine
```

On Linux, start the gateway container with `--add-host=host.docker.internal:host-gateway`. For a gateway on another
machine, run the fixture where the gateway can reach it and set `WEBPILOT_FIXTURE`.

## Python SDK (`python/`)

| Example | What it shows | Needs |
| --- | --- | --- |
| `read_page.py [url]` | A read tab: snapshot with element refs, text, headings, links | Nothing (Wikipedia by default) |
| `vault_login.py [site] [login_url]` | `tab.login(site)`: the gateway types the password and TOTP; your code never sees them. Saves the session | Fixture; a vault entry `fixture` (user `demo`, password `demo-password`) |
| `handoff.py [seconds]` | A "Your turn" link for a step only a person can do (a code from their phone), then wait for Done | Fixture; a person (or `wp.handoffs.resolve`) |
| `record_and_replay.py` | Record a checkout, save the HTML run report and JUnit XML, replay it from the script without an LLM | Fixture |
| `download.py [page] [link text]` | Click a download link, wait for the file, read its rows, save it locally, delete it on the gateway | Fixture |

Store the vault entry once as an admin: `cbu vault set fixture` on the gateway host, the Vault form in `/admin`,
or `Admin().set_vault("<user>", "fixture", username="demo", password="demo-password")` with `WEBPILOT_ADMIN_TOKEN`.

## TypeScript SDK (`typescript/`)

The same five scenarios with `webpilot-si` from npm (Node.js 20+; Deno and Bun work too):

```bash
cd examples/typescript && npm install          # installs webpilot-si
node read_page.ts                              # Node 22.18+ runs TypeScript as is; older: npx tsx read_page.ts
```

| Example | What it shows | Needs |
| --- | --- | --- |
| `read_page.ts [url]` | A read tab: snapshot with element refs, text, headings, links; then `wp.read()` without a tab | Nothing (Wikipedia by default) |
| `vault_login.ts [site] [login_url]` | `tab.login(site)` with the vault; saves the session | Fixture; a vault entry `fixture` |
| `handoff.ts [seconds]` | A "Your turn" link for a 2FA step, then `wp.handoffs.wait()` | Fixture; a person (or `wp.handoffs.resolve`) |
| `record_and_replay.ts` | Record a checkout, save the HTML report and JUnit XML, replay the script without an LLM | Fixture |
| `download.ts [page] [link text]` | Click a download link, read its rows, save it with `saveFile()` from `webpilot-si/node`, delete it | Fixture |

## MCP clients (`mcp/`)

Each reads the token from the environment where the client supports it. Replace `http://localhost:8931` with your
gateway (or `https://webpilot.si`).

| Client | File | Where it goes |
| --- | --- | --- |
| Claude Code | `claude-code.sh` | Runs `claude mcp add --transport http …` |
| Claude Code (project) | `claude-code.mcp.json` | `.mcp.json` in the project; `${WEBPILOT_TOKEN}` is expanded |
| Cursor | `cursor.mcp.json` | `~/.cursor/mcp.json` or `.cursor/mcp.json`; `${env:WEBPILOT_TOKEN}` is expanded |
| Codex | `codex.config.toml` | `~/.codex/config.toml` (`bearer_token_env_var`) |
| Claude Desktop | `claude-desktop.json` | `claude_desktop_config.json`. Claude Desktop starts local (stdio) servers from this file, so the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge (needs Node.js) connects it to the gateway. Put your token in `env` |

## curl (`curl/`)

- `rest.sh [url]`: REST API v1: who am I, open a tab, snapshot, text, screenshot, close (needs `jq`).
- `mcp.sh`: MCP over plain HTTP: initialize, list tools, call `browser_status`.
- `signup.sh email "use case" [name]`: sign up for free developer access (no token); `signup.sh --lost email`
  emails a one-time link to a new token.

Page content in results is untrusted data: the examples print it and never follow instructions found in it.