@mirsella/browser-mcp 2.0.6 → 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.
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "browser",
3
- "version": "2.0.6",
3
+ "version": "2.1.0",
4
4
  "description": "Shared Chromium profile with isolated conversation tabs for Codex and OpenCode.",
5
5
  "author": {
6
6
  "name": "mirsella"
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
@@ -264,6 +325,7 @@ action. Explicitly disabled or disconnected MCP entries stay disabled.
264
325
 
265
326
  - A headed startup error mentioning `DISPLAY` or `WAYLAND_DISPLAY` means no graphical session could be found. Set `OPENCODE_BROWSER_HEADLESS=true` when running without one.
266
327
  - A profile or socket lease error means another live package process owns it or a stale process is still running. Do not bypass the locks.
328
+ - If startup reports that the profile is already open in another local process, that browser may have been opened without remote debugging. Save your work, close it gracefully, and retry the MCP action. MCP will start the same profile with remote debugging enabled. To leave that browser running, use a separate `OPENCODE_BROWSER_PROFILE` or `--profile` instead. Never delete Chromium's `SingletonLock` or kill the existing browser automatically.
267
329
  - A process on the configured CDP port must belong to the exact managed browser generation. Stop it or choose another port.
268
330
  - If downstream startup fails, verify that `bunx` is available to OpenCode.
269
331
  - The plugin refuses to replace an unrelated `mcp.servers.browser` entry.
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 preserves structured output where upstream tools
40
- provide it, but it cannot prevent prompt injection.
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. URLs, bodies, and other headers can still appear in tool output.
58
- These settings do not disable browser telemetry or prevent websites from
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mirsella/browser-mcp",
3
- "version": "2.0.6",
3
+ "version": "2.1.0",
4
4
  "description": "Session-isolated browser automation over MCP and Chrome DevTools Protocol",
5
5
  "type": "module",
6
6
  "exports": {
@@ -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 the browser tools when the task requires rendered state, authentication,
9
- client-side behavior, layout, accessibility, console output, or network traffic.
10
-
11
- OpenCode and Codex expose two compact tools: `help` and `dispatch`. OpenCode
12
- names them `browser_help` and `browser_dispatch`; Codex namespaces them under
13
- this plugin's browser MCP server.
14
-
15
- - `browser_help` lists action names or loads the current schema for one action.
16
- - `browser_dispatch` executes an action with `{ action, arguments }`.
17
-
18
- For compact `browser_dispatch`, put every action-specific field inside `arguments`,
19
- not beside it. For example, use `{ "action": "navigate_page", "arguments": { "url": "https://example.com" } }`.
20
-
21
- Common actions include `navigate_page`, `take_snapshot`, `click`, `fill_form`,
22
- `take_screenshot`, `evaluate_script`, `list_console_messages`, and
23
- `list_network_requests`. Call `browser_help` for an action before using it when
24
- its exact arguments are not already clear. Do not guess argument shapes.
25
-
26
- Direct `browser_*` action tools may appear when compact tools are disabled. Use
27
- them directly with the same workflow.
28
-
29
- The host injects conversation identity automatically. Never add hidden routing
30
- fields. Browser tabs belong to the conversation; Codex subagents share their
31
- parent conversation's tabs, so coordinate concurrent work using separate pages.
32
-
33
- ## Workflow
34
-
35
- 1. Reuse the current page by default. Use `navigate_page` to change URLs or reload after code or deployment changes. Use `new_page` only when simultaneous pages are necessary (max 5 owned pages per session; extra `new_page` calls fail, so `close_page` a finished page first), and close temporary pages when finished.
36
- 2. Navigate, then inspect the page before interacting.
37
- 3. Use the latest snapshot to identify elements and references. Refresh it after navigation or meaningful DOM changes.
38
- 4. Perform the smallest interaction needed, then inspect the result.
39
- 5. Verify consequential actions from visible state or relevant diagnostics.
40
-
41
- Use screenshots when visual appearance, responsive layout, rendering, or image output matters. Prefer snapshots for locating elements and understanding page structure.
42
-
43
- Inspect console messages for client-side exceptions and warnings. Inspect network requests when diagnosing API failures, redirects, authentication, caching, or unexpected response data.
44
-
45
- Do not claim an interaction succeeded solely because a tool call returned without an error; verify its observable result.
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.
Binary file