unbrowse 9.0.5 → 9.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +160 -265
- package/package.json +1 -1
- package/runtime/cli.js +1443 -578
- package/runtime/mcp.js +1391 -754
- package/vendor/kuri/darwin-arm64/libkuri_ffi.dylib +0 -0
- package/vendor/kuri/darwin-x64/libkuri_ffi.dylib +0 -0
- package/vendor/kuri/linux-arm64/libkuri_ffi.so +0 -0
- package/vendor/kuri/linux-x64/kuri +0 -0
- package/vendor/kuri/linux-x64/libkuri_ffi.so +0 -0
- package/vendor/kuri/manifest.json +7 -7
- package/vendor/kuri/win-x64/kuri.exe +0 -0
package/README.md
CHANGED
|
@@ -1,341 +1,236 @@
|
|
|
1
1
|
# Unbrowse
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
> "mcpServers": {
|
|
8
|
-
> "unbrowse": {
|
|
9
|
-
> "command": "npx",
|
|
10
|
-
> "args": ["-y", "unbrowse", "mcp"]
|
|
11
|
-
> }
|
|
12
|
-
> }
|
|
13
|
-
> }
|
|
14
|
-
> ```
|
|
15
|
-
>
|
|
16
|
-
> Then run `npx unbrowse setup` once. The SKILL.md in this directory is loadable via `find-skills` / `/find-skills`; reading it gives an agent the same map (resolve + execute + browse-session) without an MCP host.
|
|
17
|
-
|
|
18
|
-
This package installs the `unbrowse` CLI.
|
|
19
|
-
|
|
20
|
-
Unbrowse is a local Model Context Protocol (MCP) server and CLI that turns websites into reusable API routes for agents. It learns callable routes from explicit browsing sessions, keeps credentials local, and shares only sanitized route metadata when you publish.
|
|
3
|
+
**Turn any website into reusable, indexed API routes for agents.** Teach a route once by
|
|
4
|
+
browsing; replay it on every later call — a replay is ~30× faster and ~90× cheaper than a
|
|
5
|
+
fresh browser session ([peer-reviewed: 3.6× mean / 5.4× median speedup over Playwright
|
|
6
|
+
across 94 live domains](https://unbrowse.ai/whitepaper)).
|
|
21
7
|
|
|
22
8
|
One agent learns a site once. Every later agent gets the fast path.
|
|
23
9
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
>
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
Unbrowse implements the Model Context Protocol over stdio. `unbrowse mcp` is the MCP server entrypoint.
|
|
30
|
-
|
|
31
|
-
- Protocol: JSON-RPC 2.0 MCP over stdio
|
|
32
|
-
- Handshake: `initialize`, `notifications/initialized`, `ping`
|
|
33
|
-
- Capability surface today: `tools/list` and `tools/call`
|
|
34
|
-
- Current MCP shape: tools only. No `resources/*` or `prompts/*` methods yet.
|
|
35
|
-
- Runtime model: the MCP server fronts the local Unbrowse runtime on `http://localhost:6969`; hosts talk standard MCP, and Unbrowse uses the local HTTP runtime behind the scenes.
|
|
36
|
-
|
|
37
|
-
Core MCP tools:
|
|
38
|
-
|
|
39
|
-
- Discovery: `unbrowse_health`, `unbrowse_search`, `unbrowse_resolve`, `unbrowse_execute`, `unbrowse_feedback`
|
|
40
|
-
- Auth/cache: `unbrowse_login`, `unbrowse_skills`, `unbrowse_skill`, `unbrowse_sessions`
|
|
41
|
-
- Browser capture: `unbrowse_go`, `unbrowse_snap`, `unbrowse_click`, `unbrowse_fill`, `unbrowse_type`, `unbrowse_press`, `unbrowse_select`, `unbrowse_scroll`, `unbrowse_submit`, `unbrowse_screenshot`, `unbrowse_text`, `unbrowse_markdown`, `unbrowse_cookies`, `unbrowse_eval`, `unbrowse_sync`, `unbrowse_close`
|
|
42
|
-
|
|
43
|
-
Typical MCP host config:
|
|
44
|
-
|
|
45
|
-
```json
|
|
46
|
-
{
|
|
47
|
-
"mcpServers": {
|
|
48
|
-
"unbrowse": {
|
|
49
|
-
"command": "npx",
|
|
50
|
-
"args": ["-y", "unbrowse", "mcp"]
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## Quick start
|
|
10
|
+
> **Two primary surfaces: the Skill and the CLI.** `SKILL.md` (shipped in this package) gives
|
|
11
|
+
> any skill-aware agent the full map — load it and the agent drives the CLI directly. The CLI
|
|
12
|
+
> is the runtime everything else calls. **MCP is legacy** — still supported (see the bottom of
|
|
13
|
+
> this file), but no longer the recommended path.
|
|
57
14
|
|
|
58
15
|
```bash
|
|
59
|
-
|
|
60
|
-
|
|
16
|
+
npm install -g unbrowse
|
|
17
|
+
unbrowse setup # one-time: registration, browser engine, local credentials
|
|
61
18
|
```
|
|
62
19
|
|
|
63
|
-
That installer now follows the Kuri pattern: detect platform, download the matching release tarball, install `unbrowse` into `~/.local/bin`, then run `unbrowse setup`.
|
|
64
|
-
|
|
65
20
|
```bash
|
|
66
|
-
#
|
|
67
|
-
|
|
68
|
-
unbrowse
|
|
21
|
+
# the load-bearing two-call path: is there a known route? then run it.
|
|
22
|
+
unbrowse resolve --intent "top stories" --url "https://news.ycombinator.com"
|
|
23
|
+
unbrowse execute --skill <id> --endpoint <id>
|
|
69
24
|
```
|
|
70
25
|
|
|
71
|
-
|
|
26
|
+
---
|
|
72
27
|
|
|
73
|
-
|
|
28
|
+
## What the client does
|
|
74
29
|
|
|
75
|
-
|
|
30
|
+
Unbrowse is a **local, stateless CLI**. Each invocation runs an in-process runtime — there is
|
|
31
|
+
**no background daemon and no port** to manage. A separate browser broker (Kuri) is spawned
|
|
32
|
+
only when a task actually needs a live browser. Credentials and sensitive inputs never leave
|
|
33
|
+
your machine; only sanitized route metadata is shared when you publish.
|
|
76
34
|
|
|
77
|
-
|
|
35
|
+
### The agent contract — two calls, then browse only on a miss
|
|
78
36
|
|
|
79
|
-
|
|
37
|
+
1. **`resolve`** — "is there an indexed route for this intent + URL?" Returns a ranked
|
|
38
|
+
shortlist of endpoints (you pick one) or an honest cache miss.
|
|
39
|
+
2. **`execute`** — runs the one endpoint you picked and returns the real data.
|
|
40
|
+
3. **browse** (`go → snap → act → sync/close`) — the escalation. When `resolve` misses, drive
|
|
41
|
+
a real browser; passive capture indexes the route so the next caller skips to resolve +
|
|
42
|
+
execute.
|
|
80
43
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
```
|
|
44
|
+
Two calls for a known route — never one, never three. When a call can't complete, the response
|
|
45
|
+
carries an honest `next_step` (e.g. `open_browse_session`, `auth_required`) instead of a bare
|
|
46
|
+
error. Three execution paths, fastest first:
|
|
85
47
|
|
|
86
|
-
|
|
87
|
-
|
|
48
|
+
1. **Skill cache** — instant (<200 ms): a route already learned locally.
|
|
49
|
+
2. **Shared route graph** — sub-second: a route another agent already mined.
|
|
50
|
+
3. **Browser session** — full traversal: the source of truth for a new site.
|
|
88
51
|
|
|
89
|
-
|
|
52
|
+
### Reads
|
|
90
53
|
|
|
91
54
|
```bash
|
|
92
|
-
|
|
55
|
+
unbrowse resolve --intent "get stock price" --url "https://finance.example.com"
|
|
56
|
+
unbrowse execute --skill <id> --endpoint <id> --pretty
|
|
57
|
+
unbrowse fetch https://api.github.com/repos/oven-sh/bun # one-shot URL → content
|
|
58
|
+
unbrowse run "https://site.com" "list the items" # resolve → execute → capture-on-miss
|
|
93
59
|
```
|
|
94
60
|
|
|
95
|
-
|
|
61
|
+
### Writes — agent-native, intent-first
|
|
96
62
|
|
|
97
|
-
|
|
63
|
+
You express **intent**, not an HTTP verb. The method is inferred from the intent and whether a
|
|
64
|
+
body is present; an explicit `--method` always overrides.
|
|
98
65
|
|
|
99
66
|
```bash
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
67
|
+
# verb inferred from intent ("create" → POST, "update" → PATCH, "delete" → DELETE):
|
|
68
|
+
unbrowse execute --url "https://api.example.com/posts" \
|
|
69
|
+
--intent "create a post" --body '{"title":"hello","userId":1}'
|
|
70
|
+
|
|
71
|
+
# or explicit:
|
|
72
|
+
unbrowse execute --url "https://api.example.com/posts/1" --method PUT --body '{...}'
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
- **Mutation safety.** A write is a deliberate action: POST/PUT/PATCH/DELETE only fire when you
|
|
76
|
+
ask for them; `--dry-run` previews without side effects; policy-sensitive domains require an
|
|
77
|
+
extra confirmation. Reads (GET) auto-execute.
|
|
78
|
+
- **Sensitive inputs stay local.** A field that looks like a secret (password, token, api_key…)
|
|
79
|
+
reaches the *target* in clear but is never written to disk or shared in clear — a redacted
|
|
80
|
+
placeholder is stored in its place, so a saved or published route keeps its shape without ever
|
|
81
|
+
leaking the value.
|
|
82
|
+
- **Created-resource chaining (`--session`).** Pass `--session <id>` and a write's created id is
|
|
83
|
+
remembered, then auto-fills a matching field on a later call in the same session. State
|
|
84
|
+
persists to disk, so a *separate* CLI invocation with the same `--session` inherits it (the
|
|
85
|
+
stateless binary gets state the way it gets cookies).
|
|
86
|
+
- **Cross-route suggestions.** If a call needs a value no local route can supply, the response
|
|
87
|
+
names which *other* indexed route produces it — so an agent can chain across sites.
|
|
88
|
+
|
|
89
|
+
### Browse (escalation for JS-heavy / first-time sites)
|
|
108
90
|
|
|
109
91
|
```bash
|
|
110
|
-
unbrowse
|
|
92
|
+
unbrowse go "https://site.com/booking"
|
|
93
|
+
unbrowse snap --filter interactive # accessibility snapshot with @eN refs
|
|
94
|
+
unbrowse click e5
|
|
95
|
+
unbrowse fill e8 "2 adults"
|
|
96
|
+
unbrowse submit --wait-for "/time-selection"
|
|
97
|
+
unbrowse close # checkpoints + indexes the learned route
|
|
111
98
|
```
|
|
112
99
|
|
|
113
|
-
|
|
100
|
+
Treat each successful `submit` as a dependency boundary — trust the returned `url` /
|
|
101
|
+
`session_id` / next-step hints over guessed downstream URLs. `sync` records which request chain
|
|
102
|
+
unlocked the next page, so future agents replay the real flow.
|
|
114
103
|
|
|
115
|
-
|
|
104
|
+
### Auth for gated sites
|
|
116
105
|
|
|
117
106
|
```bash
|
|
118
|
-
|
|
119
|
-
git pull --ff-only
|
|
120
|
-
./setup --host off
|
|
107
|
+
unbrowse auth-capture --url "https://x.com/login" # sign in once; the session stays local
|
|
121
108
|
```
|
|
122
109
|
|
|
123
|
-
|
|
110
|
+
Sign-in works from your existing browser session or an interactive login window. Auth material
|
|
111
|
+
is stored encrypted locally, reused only by your local runtime, and discarded when a site
|
|
112
|
+
rejects it. The marketplace receives route metadata, never your session.
|
|
124
113
|
|
|
125
|
-
|
|
126
|
-
cd ~/unbrowse
|
|
127
|
-
git pull --ff-only
|
|
128
|
-
./setup --host mcp
|
|
129
|
-
```
|
|
114
|
+
### Keeping current
|
|
130
115
|
|
|
131
|
-
|
|
116
|
+
The client **auto-updates in the background** for global npm installs (a detached
|
|
117
|
+
`npm i -g unbrowse@latest`, throttled, effective next run — it never blocks the command you
|
|
118
|
+
ran). Opt out with `UNBROWSE_NO_AUTO_UPDATE=1`. Check/upgrade manually any time:
|
|
132
119
|
|
|
133
120
|
```bash
|
|
134
|
-
|
|
121
|
+
unbrowse upgrade
|
|
135
122
|
```
|
|
136
123
|
|
|
137
|
-
|
|
124
|
+
---
|
|
138
125
|
|
|
139
|
-
|
|
140
|
-
Public companion docs: [docs.unbrowse.ai](https://docs.unbrowse.ai)
|
|
126
|
+
## Command reference
|
|
141
127
|
|
|
142
|
-
|
|
128
|
+
**Agent path:** `resolve` · `execute` · `run` · `fetch` · `search` · `explain`
|
|
129
|
+
**Browse session:** `go` · `snap` · `click` · `fill` · `type` · `press` · `select` · `scroll` ·
|
|
130
|
+
`submit` · `screenshot` · `text` · `markdown` · `eval` · `back` · `forward` · `sync` · `close` ·
|
|
131
|
+
`inspect` · `capture`
|
|
132
|
+
**Auth & sessions:** `auth-capture` / `login` · `auth-inventory` · `sessions` · `cookies`
|
|
133
|
+
**Routes & marketplace:** `skills` · `skill` · `spec` · `feedback` · `annotate` · `review` ·
|
|
134
|
+
`index` · `publish` · `cleanup-stale`
|
|
135
|
+
**Account & ops:** `setup` · `upgrade` · `health` · `account` · `settings` · `config` · `stats` ·
|
|
136
|
+
`billing` · `dashboard` · `wallet`
|
|
143
137
|
|
|
144
|
-
|
|
138
|
+
Run `unbrowse <command> --help` for flags. `unbrowse health` is a quick local check.
|
|
145
139
|
|
|
146
|
-
|
|
147
|
-
- Prebuilds the packaged CLI runtime and installs the stable `unbrowse` shim for the repo bootstrap path.
|
|
148
|
-
- Verifies the bundled Kuri binary, or builds it from the vendored Kuri source when working from repo source with Zig installed.
|
|
149
|
-
- Registers the Open Code `/unbrowse` command when Open Code is present.
|
|
150
|
-
- Runs the first-use flow: ToS, agent registration/API-key caching, wallet detection, and Crossmint `lobster.cash` encouragement.
|
|
151
|
-
- Starts the local Unbrowse server unless `--no-start` is passed.
|
|
140
|
+
---
|
|
152
141
|
|
|
153
|
-
##
|
|
142
|
+
## Quick start (alternatives)
|
|
154
143
|
|
|
155
144
|
```bash
|
|
156
|
-
|
|
157
|
-
unbrowse
|
|
158
|
-
unbrowse resolve --intent "get trending searches" --url "https://google.com" --pretty
|
|
159
|
-
unbrowse login --url "https://calendar.google.com"
|
|
160
|
-
unbrowse skills
|
|
161
|
-
unbrowse search --intent "get stock prices"
|
|
145
|
+
# one-line install from the latest GitHub release (binary-first):
|
|
146
|
+
curl -fsSL https://unbrowse.ai/install.sh | sh
|
|
162
147
|
```
|
|
163
148
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
- Do not jump straight to guessed downstream URLs like `/date-selection.html` or `/payment.html` unless the current session already reached them through the real page flow.
|
|
171
|
-
- Use `unbrowse_submit` for the actual transition, then trust the returned `url`, `session_id`, and any next-step hints over your own assumptions.
|
|
172
|
-
- `unbrowse_sync` after a good transition so the route graph records which request chain unlocked the next page.
|
|
173
|
-
- If a page later returns `abandonedCart`, `session_expired`, or a wrong audience/product variant, restart from the last known good upstream step and walk forward again.
|
|
174
|
-
|
|
175
|
-
The dependency graph is not just API-to-API. On JS-heavy checkout flows it also captures browser-state prerequisites: selected product, resident/non-resident audience, date, slot, auth, and cart state. Future agents should reason from those prerequisites before calling deeper steps.
|
|
176
|
-
|
|
177
|
-
## Demo notes
|
|
149
|
+
`unbrowse setup` runs the first-time bootstrap: ToS acceptance, agent registration + API-key
|
|
150
|
+
caching (in `~/.unbrowse/config.json`), browser-engine verification, and wallet detection. If a
|
|
151
|
+
wallet is configured it becomes the contributor/payout and paid-route spending wallet —
|
|
152
|
+
Crossmint `lobster.cash` is encouraged during setup (`LOBSTER_WALLET_ADDRESS`); other providers
|
|
153
|
+
use `AGENT_WALLET_ADDRESS` / `AGENT_WALLET_PROVIDER`.
|
|
178
154
|
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
155
|
+
The npm package is binary-first: install downloads the prebuilt Bun-compiled CLI for your
|
|
156
|
+
platform (no TypeScript runtime shipped). Works with Claude Code, Open Code, Cursor, Codex,
|
|
157
|
+
Windsurf, and any host that can call a local CLI or load a skill.
|
|
182
158
|
|
|
183
|
-
|
|
159
|
+
Public docs: [docs.unbrowse.ai](https://docs.unbrowse.ai) · Discord:
|
|
160
|
+
[discord.gg/VWugEeFNsG](https://discord.gg/VWugEeFNsG)
|
|
184
161
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
## Docs
|
|
188
|
-
|
|
189
|
-
The synced skill repo also carries the public docs set:
|
|
190
|
-
|
|
191
|
-
- [Quickstart](https://docs.unbrowse.ai/guides/quickstart)
|
|
192
|
-
- [Agent workflow](https://docs.unbrowse.ai/for-agents/how-an-agent-uses-unbrowse)
|
|
193
|
-
- [Integration surfaces](https://docs.unbrowse.ai/for-developers/integration-surfaces)
|
|
194
|
-
- [Payment model](https://docs.unbrowse.ai/HOW_UNBROWSE_PAYS)
|
|
195
|
-
|
|
196
|
-
Whitepaper companion docs:
|
|
197
|
-
|
|
198
|
-
- [Whitepaper companion index](https://docs.unbrowse.ai/whitepaper/)
|
|
199
|
-
- [For Technical Readers](https://docs.unbrowse.ai/whitepaper/for-technical-readers)
|
|
200
|
-
- [For Investors](https://docs.unbrowse.ai/whitepaper/for-investors)
|
|
162
|
+
---
|
|
201
163
|
|
|
202
164
|
## How it works
|
|
203
165
|
|
|
204
|
-
When an agent asks for something, Unbrowse
|
|
166
|
+
When an agent asks for something, Unbrowse searches the shared marketplace for an existing
|
|
167
|
+
route. If one exists with enough confidence, it executes immediately. If not, it opens a local
|
|
168
|
+
browser session, learns reusable route metadata, and publishes it only after the configured
|
|
169
|
+
checkpoint. Every learned route becomes discoverable by every future agent; reliability
|
|
170
|
+
scoring, feedback, schema-drift detection, and verification keep good paths hot and broken ones
|
|
171
|
+
out of the way.
|
|
205
172
|
|
|
206
|
-
|
|
173
|
+
**Resolution priority:** route cache (5-min TTL) → marketplace semantic search (composite of
|
|
174
|
+
embedding similarity, reliability, freshness, verification) → local browser capture → DOM
|
|
175
|
+
extraction for static/SSR sites.
|
|
207
176
|
|
|
208
|
-
###
|
|
177
|
+
### The marketplace flywheel
|
|
209
178
|
|
|
210
|
-
|
|
179
|
+
Every new user makes the platform more valuable for the next — like Waze, but for the web's
|
|
180
|
+
APIs. Routes live in a shared marketplace at `beta-api.unbrowse.ai`; routes published by any
|
|
181
|
+
agent are discoverable by all. A verification loop runs safe (GET) endpoints periodically;
|
|
182
|
+
routes with repeated failures auto-deprecate.
|
|
211
183
|
|
|
212
|
-
|
|
213
|
-
2. **Marketplace search** — semantic vector search ranked by composite score: 40% embedding similarity + 30% reliability + 15% freshness + 15% verification status
|
|
214
|
-
3. **Local browser session** — the runtime observes allowed requests, indexes reusable route metadata, and can publish a new skill after review
|
|
215
|
-
4. **DOM fallback** — if no API endpoints are found (static/SSR sites), structured data is extracted from rendered HTML
|
|
184
|
+
---
|
|
216
185
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
## The marketplace flywheel
|
|
220
|
-
|
|
221
|
-
Every new user makes the platform more valuable for the next one — like Waze, but for the web's APIs.
|
|
186
|
+
## Configuration
|
|
222
187
|
|
|
223
188
|
```
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
189
|
+
~/.unbrowse/config.json # API key, agent id, registration
|
|
190
|
+
~/.unbrowse/vault/ # encrypted local credential store
|
|
191
|
+
~/.unbrowse/skill-cache/ # local route (skill) manifest cache
|
|
192
|
+
~/.unbrowse/yield-sessions/ # per-session created-resource state (--session)
|
|
193
|
+
~/.unbrowse/profiles/<domain>/ # per-domain browser profiles
|
|
194
|
+
~/.unbrowse/logs/ # daily logs
|
|
227
195
|
```
|
|
228
196
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
## Authentication for gated sites
|
|
240
|
-
|
|
241
|
-
For most sites, sign-in works from your existing local browser session or from an interactive login window. Sessions stay on your machine and are reused only by your local runtime.
|
|
242
|
-
|
|
243
|
-
| Strategy | How it works | When to use |
|
|
244
|
-
| ------------------- | -------------------------------------------------- | ---------------------------------------------------- |
|
|
245
|
-
| Local session reuse | Uses your existing local browser session | Default — works if you're logged in via your browser |
|
|
246
|
-
| Yolo mode | Opens Chrome with your real profile | Sites with complex auth (OAuth popups, 2FA) |
|
|
247
|
-
| Interactive login | Opens a headed browser for manual login | Fallback when auto-resolve has no cookies |
|
|
248
|
-
|
|
249
|
-
Authentication material stays local, is stored encrypted, and is automatically refreshed or discarded when a site rejects it. The marketplace receives route metadata, not your private session.
|
|
250
|
-
|
|
251
|
-
## Mutation safety
|
|
252
|
-
|
|
253
|
-
Non-GET endpoints (POST, PUT, DELETE) require explicit confirmation:
|
|
254
|
-
|
|
255
|
-
- `dry_run: true` — preview what would execute without side effects
|
|
256
|
-
- `confirm_unsafe: true` — explicit user consent to proceed
|
|
257
|
-
- `confirm_third_party_terms: true` — extra explicit confirmation for policy-sensitive domains/actions such as X write endpoints
|
|
197
|
+
| Variable | Default | Description |
|
|
198
|
+
| --- | --- | --- |
|
|
199
|
+
| `UNBROWSE_API_URL` | `https://beta-api.unbrowse.ai` | Marketplace / backend URL |
|
|
200
|
+
| `UNBROWSE_CONFIG_DIR` | `~/.unbrowse` | Local config + cache directory |
|
|
201
|
+
| `UNBROWSE_NO_AUTO_UPDATE` | — | Set to `1` to disable background auto-update |
|
|
202
|
+
| `UNBROWSE_AGENT_EMAIL` | — | Email-style agent name for headless registration |
|
|
203
|
+
| `UNBROWSE_TOS_ACCEPTED` | — | Accept ToS non-interactively |
|
|
204
|
+
| `UNBROWSE_URL` | — | Point the CLI at an external compatibility server (unset = in-process) |
|
|
205
|
+
| `HEADLESS` | `true` | Set `false` to show the browser window (dev/auth flows) |
|
|
258
206
|
|
|
259
|
-
|
|
207
|
+
(`unbrowse setup` registers with the marketplace and caches credentials on first run; headless
|
|
208
|
+
setups can pass `UNBROWSE_AGENT_EMAIL` + `UNBROWSE_TOS_ACCEPTED`.)
|
|
260
209
|
|
|
261
|
-
|
|
210
|
+
---
|
|
262
211
|
|
|
263
|
-
|
|
212
|
+
## Legacy: MCP server
|
|
264
213
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
| POST | `/v1/skills/:id/execute` | Execute a specific skill |
|
|
269
|
-
| POST | `/v1/auth/login` | Interactive browser login |
|
|
270
|
-
| POST | `/v1/auth/import` | Import a local browser session |
|
|
271
|
-
| POST | `/v1/search` | Semantic search across all domains |
|
|
272
|
-
| POST | `/v1/search/domain` | Semantic search scoped to a domain |
|
|
273
|
-
| POST | `/v1/feedback` | Submit feedback (affects reliability scores) |
|
|
274
|
-
| POST | `/v1/skills/:id/verify` | Health check skill endpoints |
|
|
275
|
-
| POST | `/v1/skills/:id/issues` | Report a broken skill |
|
|
276
|
-
| GET | `/v1/skills` | List all marketplace skills |
|
|
277
|
-
| GET | `/v1/stats/summary` | Platform stats |
|
|
278
|
-
| GET | `/health` | Health check |
|
|
214
|
+
Unbrowse still implements the Model Context Protocol over stdio for hosts that prefer it, but
|
|
215
|
+
**the Skill + CLI are the primary path now.** `unbrowse mcp` is the stdio entrypoint; it drives
|
|
216
|
+
the same in-process runtime (no daemon, no port).
|
|
279
217
|
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
- [Integration surfaces](https://docs.unbrowse.ai/for-developers/integration-surfaces)
|
|
287
|
-
- [Payment model](https://docs.unbrowse.ai/HOW_UNBROWSE_PAYS)
|
|
288
|
-
|
|
289
|
-
## Configuration
|
|
290
|
-
|
|
291
|
-
### Runtime directories
|
|
292
|
-
|
|
293
|
-
```
|
|
294
|
-
~/.unbrowse/config.json # API key, agent ID, registration
|
|
295
|
-
~/.unbrowse/vault/ # Encrypted local credential store
|
|
296
|
-
~/.unbrowse/skill-cache/ # Local skill manifest cache
|
|
297
|
-
~/.unbrowse/profiles/<domain>/ # Per-domain Chrome profiles
|
|
298
|
-
~/.unbrowse/logs/unbrowse-YYYY-MM-DD.log # Daily logs
|
|
299
|
-
```
|
|
300
|
-
|
|
301
|
-
### Environment variables
|
|
302
|
-
|
|
303
|
-
| Variable | Default | Description |
|
|
304
|
-
| -------------------------- | ----------------------- | ---------------------------- |
|
|
305
|
-
| `PORT` | `6969` | Server port |
|
|
306
|
-
| `HOST` | `127.0.0.1` | Server bind address |
|
|
307
|
-
| `UNBROWSE_URL` | `http://localhost:6969` | Base URL for API calls |
|
|
308
|
-
| `UNBROWSE_API_KEY` | auto-generated | API key override |
|
|
309
|
-
| `UNBROWSE_AGENT_EMAIL` | — | Preferred email-style agent name for registration |
|
|
310
|
-
| `UNBROWSE_TOS_ACCEPTED` | — | Accept ToS non-interactively |
|
|
311
|
-
| `UNBROWSE_NON_INTERACTIVE` | — | Skip readline prompts |
|
|
312
|
-
|
|
313
|
-
## System layout
|
|
314
|
-
|
|
315
|
-
```
|
|
316
|
-
src/
|
|
317
|
-
├── index.ts # Fastify server entrypoint (port 6969)
|
|
318
|
-
├── api/routes.ts # HTTP route definitions
|
|
319
|
-
├── orchestrator/ # Intent resolution pipeline
|
|
320
|
-
├── execution/ # Skill/endpoint execution + retry logic
|
|
321
|
-
├── capture/ # Local browser session recording
|
|
322
|
-
├── route-indexing/ # Captured requests → reusable route metadata
|
|
323
|
-
├── extraction/ # DOM structured data extraction
|
|
324
|
-
├── marketplace/ # Backend API client (beta-api.unbrowse.ai)
|
|
325
|
-
├── client/ # Agent registration & config management
|
|
326
|
-
├── auth/ # Interactive login + local session reuse
|
|
327
|
-
├── vault/ # Encrypted credential storage
|
|
328
|
-
├── transform/ # Field projection + schema drift detection
|
|
329
|
-
├── verification/ # Periodic endpoint health checks
|
|
330
|
-
├── ratelimit/ # Request throttling
|
|
331
|
-
├── types/ # TypeScript type definitions
|
|
332
|
-
├── domain.ts # Domain utilities
|
|
333
|
-
└── logger.ts # Logging
|
|
218
|
+
```json
|
|
219
|
+
{
|
|
220
|
+
"mcpServers": {
|
|
221
|
+
"unbrowse": { "command": "npx", "args": ["-y", "unbrowse", "mcp"] }
|
|
222
|
+
}
|
|
223
|
+
}
|
|
334
224
|
```
|
|
335
225
|
|
|
336
|
-
|
|
226
|
+
Then `npx unbrowse setup` once. Tools mirror the CLI: `unbrowse_resolve`, `unbrowse_execute`,
|
|
227
|
+
`unbrowse_search`, the browse chain (`unbrowse_go`, `unbrowse_snap`, `unbrowse_click`,
|
|
228
|
+
`unbrowse_fill`, `unbrowse_submit`, `unbrowse_sync`, `unbrowse_close`, …), and
|
|
229
|
+
`unbrowse_skills` / `unbrowse_sessions`. A generic template is published at
|
|
230
|
+
[`/mcp.json`](https://www.unbrowse.ai/mcp.json). The same two-call contract applies:
|
|
231
|
+
`unbrowse_resolve` first, then `unbrowse_execute`; escalate to the browse chain on a miss.
|
|
337
232
|
|
|
338
|
-
|
|
233
|
+
---
|
|
339
234
|
|
|
340
235
|
## License
|
|
341
236
|
|