@mirsella/browser-mcp 2.0.7 → 2.1.1
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/.codex-plugin/plugin.json +1 -1
- package/.mcp.json +3 -0
- package/CONTRIBUTING.md +82 -0
- package/README.md +61 -0
- package/SECURITY.md +21 -4
- package/package.json +1 -1
- package/plugin/browser-routing.ts +2 -1
- package/skills/browser-automation/SKILL.md +39 -38
- package/vendor/browser-mcp +0 -0
package/.mcp.json
CHANGED
|
@@ -27,6 +27,9 @@
|
|
|
27
27
|
"OPENCODE_BROWSER_MAX_PAGES",
|
|
28
28
|
"OPENCODE_BROWSER_STARTUP_SECONDS",
|
|
29
29
|
"OPENCODE_BROWSER_OPERATION_SECONDS",
|
|
30
|
+
"OPENCODE_BROWSER_SECRETS_FILE",
|
|
31
|
+
"OPENCODE_BROWSER_RECORDING",
|
|
32
|
+
"OPENCODE_BROWSER_FFMPEG",
|
|
30
33
|
"OPENCODE_BROWSER_DOWNSTREAM_COMMAND"
|
|
31
34
|
],
|
|
32
35
|
"startup_timeout_sec": 40,
|
package/CONTRIBUTING.md
CHANGED
|
@@ -30,6 +30,13 @@ cleanup, persistence, profile locking, or process shutdown:
|
|
|
30
30
|
cargo test --release --test e2e -- --ignored --nocapture --test-threads=1
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
For a headless Linux terminal, wrap the real-browser command in `xvfb-run -a`
|
|
34
|
+
to exercise headed handoffs and window placement. The compact workflow case
|
|
35
|
+
covers tab selection, UID lifetime, filtered snapshots, diffs, batch failure
|
|
36
|
+
boundaries and human handoffs. `actions::tests::context_budgets_and_pinned_schema_dialect`
|
|
37
|
+
prints static schema/help byte counts; these are not model-success measurements.
|
|
38
|
+
The public pinned tool-schema fixture comes from Chrome DevTools MCP 1.6.0.
|
|
39
|
+
|
|
33
40
|
The real-browser cases share Bunx's installation cache and run serially. Adapter
|
|
34
41
|
and tool-call concurrency is exercised within each case.
|
|
35
42
|
|
|
@@ -77,6 +84,81 @@ npm pack --dry-run
|
|
|
77
84
|
- Window layout is best-effort presentation. Stable target ownership remains
|
|
78
85
|
authoritative, and layout repair must not move, claim, or close tabs.
|
|
79
86
|
|
|
87
|
+
## Model browser evaluation
|
|
88
|
+
|
|
89
|
+
`scripts/browser-model-eval.ts` provides a local dummy shop, a transparent MCP
|
|
90
|
+
trace adapter, prompts, configuration, and an independent scorer. It exercises
|
|
91
|
+
a 221-product catalog, popup details, form entry, discount arithmetic, and a
|
|
92
|
+
checkout that fails its first valid submission. No money or external account
|
|
93
|
+
is involved. `bun test tests/model-eval.test.ts` checks the fixture's rejection
|
|
94
|
+
and retry behavior.
|
|
95
|
+
|
|
96
|
+
Use a fresh `.scratch/` directory per experiment. Record the source commit,
|
|
97
|
+
binary checksum, browser version, provider, exact model, and reasoning
|
|
98
|
+
setting. For source comparisons, give each checkout its own Cargo build
|
|
99
|
+
directory and reuse the shared Kache cache. Keep each condition's browser
|
|
100
|
+
skill.
|
|
101
|
+
|
|
102
|
+
Start `bun scripts/browser-model-eval.ts site --root=<root> --port=0` under a
|
|
103
|
+
known PID or held lock. Its `site.json` records the listening URL and PID. The
|
|
104
|
+
browser origin exposes no scoring endpoint. The host scorer reads order state
|
|
105
|
+
from files in the experiment directory; agents must not read those files.
|
|
106
|
+
|
|
107
|
+
Run names have a condition label and seed, such as `ours-current-1`,
|
|
108
|
+
`ours-guidance-2`, or `browser-use-1`. Seeds 1 and 2 select paired fixture
|
|
109
|
+
cases. Generate temporary project configuration with `config --root=<root>
|
|
110
|
+
--labels=ours-current,ours-guidance --condition=ours-guidance --seed=1
|
|
111
|
+
--ours-current=<binary> --ours-guidance=<binary>`. Merge it without
|
|
112
|
+
overwriting existing configuration. Each run gets its own profile and an
|
|
113
|
+
allocated CDP port. Restore the configuration and collect the fixture process
|
|
114
|
+
when finished.
|
|
115
|
+
|
|
116
|
+
For browser-use 1.0.0, install `browser-use==1.0.0` in a task-local Python
|
|
117
|
+
virtual environment. Keep the interpreter's virtual-environment path; do not
|
|
118
|
+
resolve its symlink. Write a JSON argv array containing that Python
|
|
119
|
+
executable, `scripts/browser-use-eval.py`, `--profile`, a fresh profile path,
|
|
120
|
+
`--ipc`, and a short task-local IPC path. Pass its path as
|
|
121
|
+
`--command=<argv.json> --backend=browser-use` to `config` or `mcp`.
|
|
122
|
+
External-command configurations require `--seed=1` or `--seed=2` to avoid
|
|
123
|
+
sharing one profile between active trials. The wrapper runs the official MCP
|
|
124
|
+
implementation with local headless Chromium and explicitly stops its browser.
|
|
125
|
+
Use a separate command file and profile for each seed. This dependency is for
|
|
126
|
+
evaluation only and is not part of the published server.
|
|
127
|
+
|
|
128
|
+
Generate each task with `prompt --root=<root> --run=ours-guidance-1
|
|
129
|
+
--port=<fixture-port> --skill=<condition-skill>`. Omit `--skill` for a server
|
|
130
|
+
that supplies its own packaged instructions. Page JavaScript, DOM operations
|
|
131
|
+
and normal page requests through the assigned browser MCP are permitted for
|
|
132
|
+
every condition. Host file/network access, fixture implementation (including
|
|
133
|
+
inline script contents), scoring data and other tools are forbidden. A
|
|
134
|
+
code-based server may use host code to orchestrate its browser helpers and
|
|
135
|
+
process observed page data, but cannot use it as a shortcut to the fixture's
|
|
136
|
+
private state.
|
|
137
|
+
|
|
138
|
+
Use separate model conversations with the same provider, model, reasoning,
|
|
139
|
+
harness and budgets. Counterbalance condition order across seeds. Compare the
|
|
140
|
+
current and candidate guidance on the same server binary before attributing
|
|
141
|
+
any difference to a runtime change. Test multi-harness routing separately from
|
|
142
|
+
single-agent task quality.
|
|
143
|
+
|
|
144
|
+
Save final answers to `<root>/answers.json` as objects containing `run`,
|
|
145
|
+
`answer`, `elapsedSeconds`, `thread`, optional provider `usage`, and `valid`.
|
|
146
|
+
Set `valid: true` only after inspecting the agent trace for forbidden tools,
|
|
147
|
+
source or oracle access. Run `score --root=<root>
|
|
148
|
+
--runs=ours-current-1,ours-guidance-1,browser-use-1`. A passing score requires
|
|
149
|
+
that audit, a complete trace of issued tool calls within the 50-call and
|
|
150
|
+
10-minute budgets, one correct order, all facts, and matching receipt data.
|
|
151
|
+
Setup failures and unaudited trials do not establish reliability.
|
|
152
|
+
|
|
153
|
+
The adapter records run identities independently of tool names and navigation,
|
|
154
|
+
so Python `browser_exec` calls and compact `dispatch` calls use the same
|
|
155
|
+
scorer. Reports include tool responses, client request bytes, initialization
|
|
156
|
+
and catalog response bytes, images, errors and supplied provider usage. Byte
|
|
157
|
+
counts are not tokens or billing. Include task/skill inputs and provider
|
|
158
|
+
token/cache/reasoning usage when available; do not infer total context or cost
|
|
159
|
+
from response bytes. Two paired cases are a smoke test, not a statistical
|
|
160
|
+
reliability estimate.
|
|
161
|
+
|
|
80
162
|
## Releases
|
|
81
163
|
|
|
82
164
|
Push the versioned source commit to `main` for 2.x, or to
|
package/README.md
CHANGED
|
@@ -169,6 +169,67 @@ Settings:
|
|
|
169
169
|
}
|
|
170
170
|
```
|
|
171
171
|
|
|
172
|
+
## Agent workflow and context
|
|
173
|
+
|
|
174
|
+
The initial MCP catalog remains two tools. Help returns one short signature and
|
|
175
|
+
argument schema. Structured upstream data is validated internally, then the
|
|
176
|
+
agent receives one readable copy plus any images. Text is limited to 32 KiB with
|
|
177
|
+
an explicit truncation notice. Network and console lists default to 50 entries.
|
|
178
|
+
|
|
179
|
+
- `list_pages` exposes stable session-local handles such as `p1`. `select_page`
|
|
180
|
+
changes current; optional `page` on scoped actions targets another owned page
|
|
181
|
+
without changing current. Closed handles fail rather than selecting another tab.
|
|
182
|
+
- `take_snapshot` adds `find`, `within`, `interactive`, `diff`, and `maxLines`
|
|
183
|
+
(default 300, maximum 2000). Search includes ancestors. Diff requires compatible
|
|
184
|
+
document/worker/verbosity state; an unavailable baseline is explicitly reported
|
|
185
|
+
and replaced with a bounded full view. Baselines use at most 2 MiB per session.
|
|
186
|
+
- Inline snapshot UIDs include a worker namespace. Old-worker references fail
|
|
187
|
+
before execution. Saved snapshot files retain upstream UIDs and are diagnostic
|
|
188
|
+
exports; obtain actionable references from an inline snapshot.
|
|
189
|
+
- Compact-only `batch` runs up to 8 known actions under one session lock and
|
|
190
|
+
deadline. All arguments, explicit pages and existing UIDs are checked first.
|
|
191
|
+
Only the final step may return a snapshot. It stops on the first error and
|
|
192
|
+
reports completed/not-run counts. Actions are never replayed automatically.
|
|
193
|
+
- `handoff` with `mode: "start"` focuses an exact headed page for user work and
|
|
194
|
+
returns immediately. End the turn, request the user's work, then finish only
|
|
195
|
+
after confirmation. Automation on that page pauses and normal idle cleanup is
|
|
196
|
+
delayed for at most 24 hours. Explicit session release still closes owned tabs.
|
|
197
|
+
- `status` observes existing state without starting a browser or worker.
|
|
198
|
+
`browser-mcp doctor` checks local configuration without starting services.
|
|
199
|
+
|
|
200
|
+
Ordinary action errors retain a healthy, reconciled worker and its element
|
|
201
|
+
references. Transport failures, interrupted calls and failed reconciliation still
|
|
202
|
+
replace the worker. New pages default to background; per-session window placement
|
|
203
|
+
may briefly activate an existing anchor window.
|
|
204
|
+
|
|
205
|
+
Recording is explicitly enabled with `--recording` or
|
|
206
|
+
`OPENCODE_BROWSER_RECORDING=true`. It requires `ffmpeg`; `--ffmpeg` or
|
|
207
|
+
`OPENCODE_BROWSER_FFMPEG` selects its executable. Only then do `screencast_start`
|
|
208
|
+
and `screencast_stop` appear. Artifacts are assigned under the conversation
|
|
209
|
+
workspace's `.scratch/browser-mcp/`. Stop recording before cleanup. Worker loss
|
|
210
|
+
can leave an incomplete file. Recordings use WebM. The encoder launcher rounds
|
|
211
|
+
padding to even dimensions to fix the pinned recorder's odd-viewport failure;
|
|
212
|
+
recording operations stop waiting after 30 seconds and report an incomplete
|
|
213
|
+
recording. There is no automatic or rolling capture.
|
|
214
|
+
|
|
215
|
+
Optional `--secrets-file` / `OPENCODE_BROWSER_SECRETS_FILE` enables `fill_secret`.
|
|
216
|
+
The existing file must be a same-user, nonsymlink, regular file with mode `0600`,
|
|
217
|
+
at most 64 KiB. No store is created. Its format is:
|
|
218
|
+
|
|
219
|
+
```json
|
|
220
|
+
{"account_password":{"value":"example-placeholder","origins":["https://example.com"]}}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Each name has a nonempty single-line value up to 4096 bytes and exact HTTPS
|
|
224
|
+
origins. `fill_secret` takes a name, an editable inline-snapshot UID and optional
|
|
225
|
+
page handle. It checks the top-level origin in the same synchronous function as
|
|
226
|
+
insertion and returns no value. Treat recordings and exported artifacts as
|
|
227
|
+
sensitive; see [SECURITY.md](SECURITY.md).
|
|
228
|
+
|
|
229
|
+
HAR export is deferred: the current worker does not expose the timing data needed
|
|
230
|
+
for an accurate HAR. Use paginated network lists and `get_network_request` with
|
|
231
|
+
`requestFilePath` / `responseFilePath` for focused diagnostics instead.
|
|
232
|
+
|
|
172
233
|
## Architecture
|
|
173
234
|
|
|
174
235
|
```mermaid
|
package/SECURITY.md
CHANGED
|
@@ -36,8 +36,8 @@ The optional per-session window layout is visual organization only and does not
|
|
|
36
36
|
create another security boundary.
|
|
37
37
|
|
|
38
38
|
Browser content is untrusted input. Pages can include text designed to alter an
|
|
39
|
-
agent's behavior. The broker
|
|
40
|
-
|
|
39
|
+
agent's behavior. The broker validates structured output internally before formatting bounded
|
|
40
|
+
model-facing text, but it cannot prevent prompt injection.
|
|
41
41
|
|
|
42
42
|
## Operational guidance
|
|
43
43
|
|
|
@@ -54,10 +54,27 @@ provide it, but it cannot prevent prompt injection.
|
|
|
54
54
|
|
|
55
55
|
The downstream worker runs with usage statistics and CrUX requests disabled.
|
|
56
56
|
It also disables update checks and redacts headers that upstream classifies as
|
|
57
|
-
sensitive.
|
|
58
|
-
|
|
57
|
+
sensitive. The broker also masks common sensitive-name URL parameters, headers,
|
|
58
|
+
JSON/form fields, and configured secret values in model-facing network output.
|
|
59
|
+
This is heuristic redaction, not a guarantee that arbitrary secrets are removed.
|
|
60
|
+
Exported files, screenshots, recordings, DOM evaluation and unexpected encodings
|
|
61
|
+
can reveal values. These settings do not disable browser telemetry or prevent websites from
|
|
59
62
|
making network requests.
|
|
60
63
|
|
|
64
|
+
## Optional secrets and recordings
|
|
65
|
+
|
|
66
|
+
Secrets are loaded only from an explicitly configured, bounded, private file.
|
|
67
|
+
Insertion requires an exact allowed HTTPS top-level origin and editable element.
|
|
68
|
+
Origin checks and insertion run together; there is no origin check followed by a
|
|
69
|
+
separate navigation-sensitive insertion. Pages on an allowed origin can read the
|
|
70
|
+
value through their own scripts. Same-user CDP access can also read it.
|
|
71
|
+
|
|
72
|
+
The broker suppresses secret-fill results, removes the worker's `DEBUG`
|
|
73
|
+
environment variable and scrubs known values from model text and diagnostics.
|
|
74
|
+
These measures do not make browser content or exported artifacts safe to share.
|
|
75
|
+
No credential manager, secret creation or automatic recording is enabled.
|
|
76
|
+
Recording requires explicit opt-in and stores files in the workspace.
|
|
77
|
+
|
|
61
78
|
## Supported versions
|
|
62
79
|
|
|
63
80
|
Security fixes are provided for the latest published release. Reports against
|
package/package.json
CHANGED
|
@@ -11,7 +11,8 @@ const skills = fileURLToPath(new URL("../skills/", import.meta.url));
|
|
|
11
11
|
const directTools = `click close_page drag emulate evaluate_script fill fill_form get_console_message
|
|
12
12
|
get_network_request handle_dialog hover lighthouse_audit list_console_messages list_network_requests
|
|
13
13
|
list_pages navigate_page new_page performance_analyze_insight performance_start_trace performance_stop_trace
|
|
14
|
-
press_key resize_page take_heapsnapshot take_screenshot take_snapshot type_text upload_file wait_for
|
|
14
|
+
press_key resize_page take_heapsnapshot take_screenshot take_snapshot type_text upload_file wait_for
|
|
15
|
+
status select_page handoff batch fill_secret screencast_start screencast_stop`
|
|
15
16
|
.split(/\s+/).map(name => `browser_${name}`);
|
|
16
17
|
|
|
17
18
|
function partialPolicy(agents: Array<{ permissions: readonly { action: string }[] }>) {
|
|
@@ -5,41 +5,42 @@ description: Use browser automation to inspect or interact with websites, test r
|
|
|
5
5
|
|
|
6
6
|
# Browser Automation
|
|
7
7
|
|
|
8
|
-
Use
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
OpenCode
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
`
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
8
|
+
Use these tools for rendered state, authentication, interaction, accessibility,
|
|
9
|
+
layout, screenshots, console output and network traffic.
|
|
10
|
+
|
|
11
|
+
OpenCode exposes `browser_help` and `browser_dispatch`; Codex namespaces `help`
|
|
12
|
+
and `dispatch` under this plugin. First call help without an action to discover
|
|
13
|
+
available names; use only listed actions. Help also loads one argument schema.
|
|
14
|
+
Dispatch takes `{ "action": "navigate_page", "arguments": { "url": "https://example.com" } }`.
|
|
15
|
+
Put every action field inside `arguments`. Load help when a signature is unclear.
|
|
16
|
+
Direct action tools, when present, use the same workflow. `batch` is compact-only.
|
|
17
|
+
|
|
18
|
+
The host supplies conversation identity. Never add routing fields. Codex
|
|
19
|
+
subagents share their parent's tabs; coordinate using explicit `page` handles.
|
|
20
|
+
|
|
21
|
+
1. Reuse the current page. Open `new_page` only for simultaneous work (default cap 5), and close temporary pages when done. New pages default to background.
|
|
22
|
+
2. Inspect before acting. `take_snapshot` supports `find`, `within` a UID, `interactive`, `diff`, and `maxLines` (default 300, maximum 2000). Search or scope large pages instead of repeatedly requesting the full tree. Diff cannot be combined with filters.
|
|
23
|
+
3. Copy UIDs exactly. They include a worker prefix; refresh after navigation, worker replacement or missing elements. File exports are diagnostic dumps with upstream UIDs; obtain actionable UIDs from an inline snapshot.
|
|
24
|
+
4. Prefer `fill_form` for several inputs: `arguments: {"elements":[{"uid":"<snapshot UID>","value":"text"}]}`. Values are strings; use the displayed option text for selects. Load help before guessing other argument shapes. Use `batch` for up to 8 already-understood steps, with a snapshot only on the last step. It stops on error; inspect completed/not-run counts and never replay a partially completed batch blindly.
|
|
25
|
+
5. Verify the observable result. A successful tool call alone does not prove the intended effect. Input actions omit snapshots unless requested; inspect when the result matters. When the visible confirmation supplies the requested facts, stop. An order ID and total in a confirmation are receipt data; a separate page labelled "Receipt" is unnecessary. Use `wait_for` for an expected change, not a guessed extra section or success screen.
|
|
26
|
+
|
|
27
|
+
`list_pages` shows session-local `p1`, `p2`, etc. `select_page` changes current;
|
|
28
|
+
`page` on scoped actions targets an owned page without changing current. Unknown
|
|
29
|
+
or closed handles fail. Selecting does not focus the window unless requested.
|
|
30
|
+
|
|
31
|
+
Scroll with `press_key` (`PageDown`, `PageUp`, `Home`, `End`). Use screenshots for visual work. Console and network lists default to 50 entries;
|
|
32
|
+
paginate or narrow them. Export large request/response bodies to workspace files.
|
|
33
|
+
Text responses are bounded to 32 KiB; truncation is explicit. Images remain intact.
|
|
34
|
+
|
|
35
|
+
For login or other user work, `handoff` start focuses the exact headed page and
|
|
36
|
+
pauses automation on it. End the turn and request the user's work. Finish only
|
|
37
|
+
after confirmation, then take a fresh snapshot. Other owned pages remain usable.
|
|
38
|
+
|
|
39
|
+
`status` observes without launching a browser or worker. CLI `doctor` diagnoses
|
|
40
|
+
configuration. Ordinary action errors retain healthy workers; interrupted actions
|
|
41
|
+
may have happened and are never replayed automatically.
|
|
42
|
+
|
|
43
|
+
`fill_secret`, when configured, accepts a secret name and input UID; it checks an
|
|
44
|
+
allowed HTTPS top-level origin and returns no value. Do not read the filled value.
|
|
45
|
+
Recording tools appear only when explicitly enabled; stop recordings before
|
|
46
|
+
cleanup. There is no automatic capture, HAR export, or rolling recorder.
|
package/vendor/browser-mcp
CHANGED
|
Binary file
|