@mirsella/browser-mcp 2.0.7 → 2.1.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/.codex-plugin/plugin.json +1 -1
- package/.mcp.json +3 -0
- package/CONTRIBUTING.md +40 -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,39 @@ 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. Build the baseline from a
|
|
97
|
+
recorded commit in a separate source directory and copy the two release
|
|
98
|
+
binaries to `<root>/bin/before` and `<root>/bin/after`. Keep each build's own
|
|
99
|
+
browser skill. Start `bun scripts/browser-model-eval.ts site --root=<root>`
|
|
100
|
+
under a known PID or held lock; stop and collect it when the experiment ends.
|
|
101
|
+
|
|
102
|
+
Generate temporary project MCP configuration with `config --root=<root>
|
|
103
|
+
--condition=before` (then `after`) and merge it without overwriting existing
|
|
104
|
+
configuration. Generate each prompt with `prompt --run=before-1
|
|
105
|
+
--skill=<baseline-skill-path>`, repeating for `before-2`, `after-1`, and
|
|
106
|
+
`after-2`. Use separate model conversations with the same provider, model and
|
|
107
|
+
effort. Run both baseline cases before switching configuration. The adapter
|
|
108
|
+
preserves trusted OpenCode session metadata; the model never supplies routing.
|
|
109
|
+
|
|
110
|
+
Save final answers to `<root>/answers.json` as objects containing `run`,
|
|
111
|
+
`answer`, `elapsedSeconds`, and `thread`, then run `score --root=<root>`.
|
|
112
|
+
Scoring checks one correct order and all reported facts and confirmation data.
|
|
113
|
+
Traces retain tool calls, errors, text bytes, structured bytes, and total MCP
|
|
114
|
+
response bytes. These byte counts are not tokenizer counts or provider billing.
|
|
115
|
+
Inspect the agent traces for forbidden tools or source access before accepting
|
|
116
|
+
a result. Exclude setup failures explicitly. Restore project configuration and
|
|
117
|
+
stop only the experiment's adapters, workers and browsers afterward. Two cases
|
|
118
|
+
per version are a smoke test, not a statistical reliability estimate.
|
|
119
|
+
|
|
80
120
|
## Releases
|
|
81
121
|
|
|
82
122
|
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
|