@spaxe-dev/zen-mcp 0.0.0-stage → 0.3.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/README.md CHANGED
@@ -1,3 +1,920 @@
1
- # Temporary Holding Version
1
+ # Zen MCP
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![CI](https://github.com/spaxe-dev/zen-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/spaxe-dev/zen-mcp/actions/workflows/ci.yml)
4
+ [![Latest release](https://img.shields.io/github/v/release/spaxe-dev/zen-mcp)](https://github.com/spaxe-dev/zen-mcp/releases/latest)
5
+
6
+ An agent harness for [Zen Browser](https://zen-browser.app). Zen MCP gives an
7
+ MCP agent hands-on control of a real Zen window: native spaces, folders, tabs,
8
+ history, bookmarks, page reading, and questions that the user answers inside the
9
+ browser.
10
+
11
+ The point is that agents work *around* the user instead of taking over their
12
+ screen. A research job can open twenty tabs in a new space while the user keeps
13
+ reading, read them all in the background, ask a clarifying question in a small
14
+ corner card, and finish with a notification that jumps straight to the results.
15
+
16
+ ## What that looks like
17
+
18
+ > "Make a GitHub space and find all the PRs assigned to me that I haven't replied to."
19
+
20
+ The agent:
21
+
22
+ 1. creates a `GitHub` space without switching to it,
23
+ 2. searches history and bookmarks for the user's repositories,
24
+ 3. opens the PR list and each PR in the background (Zen stays on the current page),
25
+ 4. reads every tab through the agent bridge, without selecting anything,
26
+ 5. answers in the chat, then shows a card: **"4 PRs need a reply" — Open GitHub**.
27
+
28
+ One click takes the user to the space with all the work already laid out.
29
+
30
+ ## What's new in 0.3
31
+
32
+ - **An owned browser, not an attached one.** Zen MCP launches its own Zen,
33
+ proves through a per-launch nonce that the browser on the Marionette port is
34
+ the one it started, then closes every other connection and the listener. After
35
+ startup, no other local process can open a Marionette session. The browser is
36
+ quit when the server stops.
37
+ - **One-time approval and a global pause.** A card in Zen asks whether this
38
+ session may control the browser; declining closes it. The persistent banner
39
+ has a **Pause** button that blocks every read and change immediately, and
40
+ **Resume** turns access back on.
41
+ - **A dedicated agent profile is the default.** Opt into your normal profile
42
+ only when the agent should see signed-in pages.
43
+ - **Evidence Mode.** `zen_show_evidence` reuses or opens the source tab, finds
44
+ the cited passage, scrolls to it, and marks it with a temporary overlay,
45
+ without taking over the screen; the card gets a **Show source** action and
46
+ `focus: true` brings the tab forward on request. A card in browser chrome
47
+ names the claim, source, match method, and confidence.
48
+ `zen_show_evidence_batch` does the same for up to 20 citations and reports
49
+ each result. `zen_clear_evidence` removes the marks; the page's own text and
50
+ styles are never modified.
51
+ - Scoped reads now fail with `selector_not_found` instead of silently returning
52
+ the whole page when the selected element is absent.
53
+
54
+ ## What's new in 0.2
55
+
56
+ ![The Research space with a Reading folder, an essential tab, and the agent progress card](docs/screenshots/v0.2-space-overview.png)
57
+
58
+ - Batch reads up to 10 background tabs per call, with `text`, `markdown`,
59
+ `links`, `tables`, `metadata`, `outline`, or a CSS-selected element.
60
+ - A persistent progress card with a real **Stop** button, plus one event stream
61
+ for Stop presses, watch hits, and question answers.
62
+ - Watch mode for text changes and selectors that appear or disappear.
63
+ - Session snapshots and space templates for repeatable research layouts.
64
+ - Tab audit, domain grouping, recently closed tabs, clipboard handoff, Glance,
65
+ split view, pinned and essential tabs, and Firefox containers.
66
+ - A read-only mode, a domain allowlist, and a JSONL audit log.
67
+ - MCP resources for live state and prompts for common research and triage jobs.
68
+
69
+ More screenshots: [progress and Stop](docs/screenshots/v0.2-progress-stop.png),
70
+ [split view](docs/screenshots/v0.2-split-view.png),
71
+ [question card](docs/screenshots/v0.2-question-card.png),
72
+ [Glance](docs/screenshots/v0.2-glance.png).
73
+
74
+ ## Requirements
75
+
76
+ - Node.js 22 or newer (Node 22 and 24 are tested in CI).
77
+ - Zen Browser, with this support status:
78
+
79
+ | Platform | Status |
80
+ | --- | --- |
81
+ | Windows | Live-tested with Zen 1.24b |
82
+ | macOS | Code paths implemented and covered by CI; live launch not yet verified |
83
+ | Linux | Code paths implemented for distro, Flatpak, and Snap builds; live launch not yet verified |
84
+
85
+ The Firefox mechanisms (Marionette, profile locking, and remote chrome
86
+ access) are shared across platforms, but "not yet verified" means nobody has
87
+ run a real Zen launch there. Treat those platforms as untested until a live
88
+ launch, the consent card, and a clean shutdown have passed.
89
+ - Zen MCP must start Zen itself. Firefox only exposes chrome-level remote
90
+ control when the browser process is launched with `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`,
91
+ and the harness sets that only in the child process it spawns. A Zen that was
92
+ already open cannot be adopted, and a normal Zen launch never opens a debug
93
+ port.
94
+ - The default agent profile is separate from your normal browsing profile.
95
+ `zen-mcp setup --use-default-profile` opts into your normal profile, which
96
+ lets the agent see pages where you are signed in.
97
+
98
+ ## Install
99
+
100
+ With Node.js 22 or newer:
101
+
102
+ ```sh
103
+ npm install -g @spaxe-dev/zen-mcp
104
+ zen-mcp setup
105
+ ```
106
+
107
+ Or run the setup without a global install:
108
+
109
+ ```sh
110
+ npx @spaxe-dev/zen-mcp setup
111
+ ```
112
+
113
+ Each GitHub release also attaches a package tarball and a `SHA256SUMS` file:
114
+
115
+ ```sh
116
+ npm install -g ./zen-mcp-0.3.0.tgz
117
+ zen-mcp setup
118
+ ```
119
+
120
+ The installed command is `zen-mcp` in every case. `setup` detects Zen, writes a
121
+ config, and prints an MCP snippet.
122
+
123
+ ## Install from source
124
+
125
+ ```sh
126
+ git clone https://github.com/spaxe-dev/zen-mcp.git
127
+ cd zen-mcp
128
+ npm install
129
+ npm run build
130
+ npm link # optional: puts `zen-mcp` on PATH
131
+ ```
132
+
133
+ Then check the machine:
134
+
135
+ ```sh
136
+ zen-mcp setup # detects Zen, writes a config, prints an MCP snippet
137
+ zen-mcp doctor # config, executable, Marionette, bridge, policy
138
+ ```
139
+
140
+ `setup` writes `$APPDATA/zen-mcp/config.json` on Windows or
141
+ `~/.config/zen-mcp/config.json` elsewhere. Nothing is installed into Zen
142
+ itself: the bridge is injected at runtime.
143
+
144
+ ## Connect an MCP client
145
+
146
+ Claude Code:
147
+
148
+ ```sh
149
+ claude mcp add zen-mcp -- zen-mcp serve
150
+ ```
151
+
152
+ Any MCP client:
153
+
154
+ ```json
155
+ {
156
+ "mcpServers": {
157
+ "zen-mcp": {
158
+ "command": "zen-mcp",
159
+ "args": ["serve"]
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ If the package is not on `PATH`, use the absolute path to `dist/cli.js` as the
166
+ command. `serve` is also the default when the CLI is run without arguments.
167
+
168
+ The server owns the browser it uses. The first tool call launches Zen with a
169
+ dedicated agent profile if `autoLaunch` is enabled (the default), then waits for
170
+ the approval card in Zen before returning. That first call can take a few
171
+ seconds while Zen starts. If Zen is already running on the Marionette port, the
172
+ server refuses to attach and explains how to proceed; it never takes over a
173
+ browser someone else started.
174
+
175
+ A running browser is quit when the MCP server stops. Leave the server running
176
+ for the whole session, and expect the agent's Zen window to close when the
177
+ client disconnects.
178
+
179
+ ## Tools
180
+
181
+ ### Core
182
+
183
+ | Tool | What it does |
184
+ | --- | --- |
185
+ | `zen_status` | App version, active space and tab, every space with counts, bridge health |
186
+ | `zen_launch` | Start Zen with agent access or reconnect the bridge |
187
+ | `zen_spaces_list` | Spaces with tab, pinned, and folder counts |
188
+ | `zen_space_create` | Create a space; does not switch by default |
189
+ | `zen_space_switch` | Switch the visible space |
190
+ | `zen_space_delete` | Delete a space and its tabs (destructive) |
191
+
192
+ ### Tabs and layout
193
+
194
+ | Tool | What it does |
195
+ | --- | --- |
196
+ | `zen_tabs_list` | Tabs across every space, filterable by space, query, or pinning |
197
+ | `zen_tabs_open` | Open up to 30 URLs in a space, in the background by default |
198
+ | `zen_tabs_close` | Close tabs by id |
199
+ | `zen_tab_select` | Bring a tab into view (takes over the screen) |
200
+ | `zen_glance` | Preview a URL or tab in Zen's Glance overlay, without a new tab |
201
+ | `zen_split_view` | Show 2 to 4 tabs from the active space side by side |
202
+ | `zen_split_close` | Close a split view; the tabs stay open |
203
+ | `zen_pin_tabs` | Pin or unpin tabs in a space |
204
+ | `zen_essentials` | Add tabs to essentials or remove them |
205
+ | `zen_containers_list` | List Firefox containers for isolation |
206
+
207
+ ### Folders
208
+
209
+ | Tool | What it does |
210
+ | --- | --- |
211
+ | `zen_folders_list` | Folders with space, label, and tab ids |
212
+ | `zen_folder_create` | Group existing tabs into a folder |
213
+ | `zen_folder_add_tabs` | Move tabs into a folder |
214
+
215
+ ### Reading and research
216
+
217
+ | Tool | What it does |
218
+ | --- | --- |
219
+ | `zen_read_page` | Extract text or a structured view from any tab, without selecting it |
220
+ | `zen_read_pages` | Read up to 10 tabs in one call, three at a time |
221
+ | `zen_find_text` | Find literal text in one tab with raw offsets and excerpts |
222
+ | `zen_search_tabs` | Search up to 30 open tabs for the same text, two at a time |
223
+ | `zen_show_evidence` | Reuse a source in the background, find a cited quote, scroll to it, and mark it |
224
+ | `zen_show_evidence_batch` | Verify up to 20 citations in one call with per-citation results |
225
+ | `zen_clear_evidence` | Remove Evidence Mode overlays from one tab or every marked tab |
226
+ | `zen_tabs_audit` | Find duplicate, stale, and domain-clustered tabs |
227
+ | `zen_tabs_group` | Create one folder per domain for ungrouped tabs |
228
+ | `zen_history_search` | Search history by title or URL, optionally by domain |
229
+ | `zen_history_recently_closed` | Recently closed tabs |
230
+ | `zen_bookmarks_search` | Search bookmarks by title or URL |
231
+ | `zen_clipboard_write` | Copy text to the user's clipboard |
232
+
233
+ ### Coordination
234
+
235
+ | Tool | What it does |
236
+ | --- | --- |
237
+ | `zen_progress` | Show or update a persistent progress card with a Stop button |
238
+ | `zen_events` | Long-poll for Stop presses, watch hits, and question answers |
239
+ | `zen_ask` | Show a question card in Zen and wait for an answer |
240
+ | `zen_answers` | Pending and recently answered questions |
241
+ | `zen_notify` | Status card with an optional "open this space" action |
242
+ | `zen_watch_add` | Watch a tab for a text change or a selector appearing or disappearing |
243
+ | `zen_watch_list` | Active watches with interval, expiry, last check, and hit count |
244
+ | `zen_watch_remove` | Stop and remove a watch |
245
+
246
+ ### Sessions and templates
247
+
248
+ | Tool | What it does |
249
+ | --- | --- |
250
+ | `zen_session_save` | Snapshot every space, tab, folder, and essential in the window |
251
+ | `zen_session_list` | Saved sessions with counts |
252
+ | `zen_session_restore` | Restore a session, reusing spaces by name or creating new ones |
253
+ | `zen_session_delete` | Delete a saved session |
254
+ | `zen_space_templates` | Built-in and user templates |
255
+ | `zen_template_apply` | Create a space from a template |
256
+ | `zen_template_save` | Save a live space as a reusable template |
257
+ | `zen_template_delete` | Delete a user template |
258
+
259
+ ### Policy
260
+
261
+ | Tool | What it does |
262
+ | --- | --- |
263
+ | `zen_config` | Effective read-only mode, allowlist, audit settings, and data directory |
264
+ | `zen_audit_tail` | Recent tool calls, including blocked ones |
265
+
266
+ ### Resources and prompts
267
+
268
+ Five MCP resources expose live state as JSON: `zen://status`, `zen://spaces`,
269
+ `zen://tabs`, `zen://questions`, and `zen://watches`.
270
+
271
+ Three prompts set up common jobs: `zen_github_triage` for notifications and pull
272
+ requests, `zen_research_brief` for a source-backed brief, and `zen_clean_tabs`
273
+ for tab cleanup with a session saved first.
274
+
275
+ ### Client-visible behavior
276
+
277
+ Zen MCP uses the standard MCP request metadata rather than a custom side channel:
278
+
279
+ - **Structured results.** Every tool declares an `outputSchema`. A successful
280
+ call returns the typed object in `structuredContent` and the same JSON in a
281
+ text block, so older clients keep working. Errors are `isError: true` with no
282
+ `structuredContent`.
283
+ - **Progress.** When a client supplies a progress token, `zen_read_page`,
284
+ `zen_read_pages`, and `zen_show_evidence_batch` send
285
+ `notifications/progress` between phases or after each tab or citation. No
286
+ token means no notifications.
287
+ - **Cancellation.** A cancelled request stops waiting on the bridge and returns
288
+ a cancellation error. A browser command that is already in flight may still
289
+ finish in Zen, but the server never reports it as a success.
290
+ - **Resources.** All five resources carry a title. Successful tools that change
291
+ tabs or spaces emit `notifications/resources/list_changed` so clients can
292
+ refresh. Resource subscriptions are not offered in 0.3; clients re-read on
293
+ demand. Completion is not offered either, because the fixed resource URIs
294
+ have no template variables to complete.
295
+ - **Logging.** Server warnings and errors reach the client through
296
+ `notifications/message`. Messages contain the tool name, error code, and a
297
+ sanitized description with URLs replaced by `[redacted-url]`. They never
298
+ contain arguments, page text, tab URLs, or bridge keys. The file audit log
299
+ remains the durable record.
300
+
301
+ ## Reading pages in the background
302
+
303
+ `zen_read_page` and `zen_read_pages` never change what the user is looking at.
304
+ They go through the browser's own content actor, which can reach a loaded tab in
305
+ any space, including spaces that are not currently rendered.
306
+
307
+ Formats:
308
+
309
+ - `text`: readable page text, preferring `<article>`, `<main>`, or `role=main`.
310
+ - `markdown`: headings, lists, links, and tables as Markdown.
311
+ - `links`: unique http(s) links with their text.
312
+ - `tables`: table captions, headers, and rows.
313
+ - `metadata`: title, description, canonical URL, Open Graph tags, and language.
314
+ - `outline`: the heading tree.
315
+ - `selector`: limit any format to one CSS-selected element.
316
+
317
+ The result includes the title, URL, selected text, content type, length,
318
+ `offset`, and `nextOffset`. `maxChars` limits each chunk (24,000 by default,
319
+ 60,000 maximum).
320
+
321
+ Long `text` and `markdown` reads are paged. Pass `nextOffset` from one result as
322
+ `offset` on the next call; `nextOffset` is `null` when the stream is exhausted.
323
+ Offsets are clamped to the page length, so reading past the end returns empty
324
+ text instead of an error.
325
+
326
+ ```text
327
+ zen_read_page { tabId: "42", maxChars: 24000, offset: 0 }
328
+ → { text: "...", length: 85213, offset: 0, nextOffset: 24000, truncated: true }
329
+
330
+ zen_read_page { tabId: "42", maxChars: 24000, offset: 24000 }
331
+ → { text: "...", length: 85213, offset: 24000, nextOffset: 48000, truncated: true }
332
+ ```
333
+
334
+ `zen_read_pages` applies the same offset to every tab in the batch. `links`,
335
+ `tables`, `metadata`, and `outline` ignore `offset` and return their complete
336
+ structured data with a `limitation` note, because a character cursor does not
337
+ map cleanly to a list of items.
338
+
339
+ Offsets are positions in the extracted text, not the raw HTML. They stay stable
340
+ while the page is unchanged. If the page changes between calls, earlier offsets
341
+ can shift, so start again from offset 0 when the content has changed.
342
+
343
+ PDF text is extracted through Zen's PDF viewer. Firefox only initializes that
344
+ viewer for a visible PDF tab, so a PDF opened in a hidden space returns
345
+ `pdf_unreadable`; ask the user to open it, then read the active tab. HTML pages
346
+ have no such restriction.
347
+
348
+ Pages that cannot expose a document (privileged `about:` pages, tabs that have
349
+ not loaded) return a clear error instead of partial nonsense.
350
+
351
+ ## Evidence Mode
352
+
353
+ An answer is only as useful as the user's ability to check it.
354
+ `zen_show_evidence` turns a citation into something visible without interrupting
355
+ the user: it reuses or opens the source tab in the background, finds the cited
356
+ passage, scrolls to it, marks it, and shows a card in browser chrome with the
357
+ claim, source, excerpt, and match status. The card has a **Show source** action;
358
+ pass `focus: true` when the user asked to see the source immediately.
359
+
360
+ ```text
361
+ zen_show_evidence {
362
+ url: "https://example.com/report",
363
+ claim: "The pilot cut response time in half",
364
+ quote: "Median response time fell from 42 seconds to 21 seconds.",
365
+ context: "Results after the six-week pilot",
366
+ source_title: "2026 operations report"
367
+ }
368
+ ```
369
+
370
+ The flow:
371
+
372
+ 1. Reuse an open tab whose URL matches the source, or open the URL in the
373
+ background. A supplied `tab_id` is used only when that tab still shows the
374
+ same URL. `focus: true` switches to the tab and brings its window forward.
375
+ 2. Wait up to 12 seconds for the document to leave `about:blank` and finish
376
+ loading.
377
+ 3. Read the page's rendered text through the Marionette content actor.
378
+ 4. Locate the quote, then verify the page text has not changed before marking.
379
+ 5. Scroll the passage toward the center of the viewport.
380
+ 6. Paint an absolutely positioned overlay over the passage. The overlay fades
381
+ out after 20 seconds by default.
382
+ 7. Return structured JSON and show an activity card with a dismiss button.
383
+
384
+ ### Input
385
+
386
+ | Field | Required | Meaning |
387
+ | --- | --- | --- |
388
+ | `url` | yes | `http(s)` source URL. A missing scheme is assumed to be `https`. |
389
+ | `quote` | yes | The passage expected in the source, up to 20,000 characters. |
390
+ | `claim` | no | The claim the passage supports. It becomes the card title. |
391
+ | `context` | no | Nearby source text, used to choose between repeated passages. |
392
+ | `source_title` | no | Human-readable source name for the card. |
393
+ | `tab_id` | no | Reuse this tab only if it still shows `url`. |
394
+ | `min_confidence` | no | Fuzzy-match threshold from 0.5 to 1. Defaults to 0.85. |
395
+ | `highlight_ms` | no | How long the mark stays visible, 1,000 to 120,000 ms. Defaults to 20,000. |
396
+ | `focus` | no | Bring the source tab and window to the front. Defaults to `false`. |
397
+
398
+ `zen_clear_evidence` takes an optional `tab_id`. With no id it removes marks
399
+ from every tab marked during the server session.
400
+
401
+ ### Result
402
+
403
+ ```json
404
+ {
405
+ "ok": true,
406
+ "tabId": "42",
407
+ "tabReused": true,
408
+ "focused": false,
409
+ "sourceUrl": "https://example.com/report",
410
+ "url": "https://example.com/report",
411
+ "title": "2026 operations report",
412
+ "claim": "The pilot cut response time in half",
413
+ "matchedQuote": "Median response time fell from 42 seconds to 21 seconds.",
414
+ "matchMethod": "normalized",
415
+ "confidence": 0.99,
416
+ "occurrences": 1,
417
+ "scrolled": true,
418
+ "highlighted": true
419
+ }
420
+ ```
421
+
422
+ A failure sets `ok` to `false`, adds `error: { code, message }`, and never
423
+ highlights a different passage. Some successes carry a `limitation` string, for
424
+ example when the page was too large to search completely or the passage has no
425
+ visible box to paint.
426
+
427
+ | Code | Meaning |
428
+ | --- | --- |
429
+ | `PAGE_NOT_FOUND` | The tab closed, navigated away, or could not be reached. |
430
+ | `PAGE_STILL_LOADING` | The document did not finish loading within 12 seconds. |
431
+ | `QUOTE_NOT_FOUND` | The quote is absent from the page's readable text. |
432
+ | `AMBIGUOUS_MATCH` | The passage repeats and no context selected one occurrence. |
433
+ | `LOW_MATCH_CONFIDENCE` | The closest fuzzy passage is below the threshold. |
434
+ | `HIGHLIGHT_FAILED` | The page changed too often between matching and marking. |
435
+ | `PRIVILEGED_PAGE` | The tab is on a browser-internal page. |
436
+ | `ACTOR_UNAVAILABLE` | Marionette no longer exposes the content actor. |
437
+ | `UNSUPPORTED_PAGE` | PDF, non-HTML, or non-`http(s)` content. |
438
+
439
+ ### Matching behavior
440
+
441
+ Matching runs in fixed code inside the bridge, in this order:
442
+
443
+ 1. **Exact.** A raw substring match with exact offsets, including case.
444
+ 2. **Normalized.** HTML entities are decoded; typographic quotes, dashes, and
445
+ ellipses are folded; Unicode is NFKC-normalized, lowercased, and stripped of
446
+ diacritics; whitespace is collapsed. Offsets are mapped back to the raw page
447
+ text so the highlight covers the original characters.
448
+ 3. **Context.** When the quote appears more than once, the 800 characters around
449
+ each occurrence are scored against `context` using token containment and
450
+ bigram overlap. A clear winner is required; a tie stays ambiguous.
451
+ 4. **Fuzzy.** Token-anchored windows are compared with a bounded Levenshtein
452
+ distance. This only runs for quotes up to 300 characters and accepts a match
453
+ at or above `min_confidence`.
454
+
455
+ The matcher never picks one of several equally plausible passages. It reports
456
+ `AMBIGUOUS_MATCH` or `LOW_MATCH_CONFIDENCE` instead. Before painting, the
457
+ highlight script re-reads the page and checks that the raw text at the chosen
458
+ offsets still equals the matched passage; if not, it re-indexes and retries, up
459
+ to three times.
460
+
461
+ ### Supported pages
462
+
463
+ - `http(s)` HTML and XML documents with a loaded content document.
464
+ - Text that is rendered in the DOM and not hidden.
465
+ - Same-document content only. Text inside cross-origin iframes, shadow roots,
466
+ images, canvas, SVG, or form controls is not searched.
467
+ - PDFs, `about:`/`chrome:` pages, `file:` URLs, and other non-HTML responses
468
+ return `UNSUPPORTED_PAGE` or `PRIVILEGED_PAGE`.
469
+
470
+ ### Limitations
471
+
472
+ - The first 600,000 characters of page text are indexed. Truncation is reported
473
+ in `limitation`.
474
+ - Pages that continuously change can exhaust the three marking attempts and
475
+ return `HIGHLIGHT_FAILED`.
476
+ - The mark is an overlay, not a DOM edit. Layout changes while it is visible can
477
+ move the underlying text away from the boxes. It disappears after
478
+ `highlight_ms`, and `zen_clear_evidence` removes it sooner.
479
+ - Only the current DOM is searched. Infinite-scroll content and content behind
480
+ interaction are invisible until loaded.
481
+
482
+ ### Security
483
+
484
+ - Agents send only `url`, `quote`, `context`, and numeric options. Every DOM
485
+ operation is a fixed script built on the server; no agent-supplied JavaScript
486
+ is ever evaluated.
487
+ - URLs are normalized to `http(s)` and checked against the existing domain
488
+ allowlist. Read-only mode blocks `zen_show_evidence`,
489
+ `zen_show_evidence_batch`, and `zen_clear_evidence` because they open or
490
+ select a tab and add overlays.
491
+ - Overlay nodes are marked `aria-hidden`, ignore pointer events, and live in
492
+ their own layer. The page's text nodes and styles are never modified.
493
+ - The result card is rendered in a shadow root in browser chrome through the
494
+ existing activity-card system. Page scripts cannot reach it. Evidence Mode
495
+ does not create a second notification system.
496
+ - The Marionette endpoint and bridge token stay inside the local server; neither
497
+ is exposed to pages or to the agent.
498
+
499
+ ### Verifying several citations
500
+
501
+ `zen_show_evidence_batch` checks up to 20 citations in one call, two sources at
502
+ a time (three maximum). Citations that share a source URL reuse one tab, and
503
+ missing sources are opened once in the background. Every citation gets its own
504
+ result with the same fields as `zen_show_evidence`, and one summary card reports
505
+ how many were verified and lists up to three failures. `focus: true` brings the
506
+ first source forward once instead of switching for every citation.
507
+
508
+ Each source may have at most 5 quotes per batch. If any citation URL is not
509
+ `http(s)`, the whole batch is rejected before a tab opens, so a bad URL cannot
510
+ pull the batch halfway through. The call reports `total`, `matched`, `failed`,
511
+ `openedTabs`, and `reusedTabs`, and `ok` is true only when every citation
512
+ matched.
513
+
514
+ ## Finding text in tabs
515
+
516
+ Two read-only tools locate literal text without regex, selection, scrolling, or
517
+ highlights:
518
+
519
+ | Tool | Scope | Defaults |
520
+ | --- | --- | --- |
521
+ | `zen_find_text` | One tab | 20 matches, 120 characters of context |
522
+ | `zen_search_tabs` | Up to 30 tabs, two at a time | 5 matches per tab, 80 characters of context, 20 tabs |
523
+
524
+ Both accept a literal `query` and optional `case_sensitive`. By default matching
525
+ folds case, diacritics, typographic punctuation, and whitespace differences, so
526
+ `cafe` finds `Café` and `"hello"` finds `“hello”`. `case_sensitive` switches to
527
+ exact `indexOf`. Matches carry raw page offsets (`start`, `end`), the matched
528
+ text, and a short excerpt with ellipses.
529
+
530
+ `zen_search_tabs` searches every open tab, a `space`, or an explicit `tab_ids`
531
+ list. Each tab succeeds or fails independently, so privileged pages, PDFs, and
532
+ missing tabs appear as error entries in the results instead of failing the call.
533
+ Results are capped per tab and at 200 matches in total, and `truncated` reports
534
+ when anything was clipped. Use `zen_show_evidence` when the user should see the
535
+ passage. Like Evidence Mode, both tools search the rendered DOM text, so
536
+ infinite-scroll content and content behind interaction are invisible until
537
+ loaded.
538
+
539
+ ## Progress, events, and watches
540
+
541
+ Long jobs should keep the user informed without blocking on a modal dialog:
542
+
543
+ ```text
544
+ zen_progress { title: "Reading 12 sources", step: "3 of 12", progress: 0.25 }
545
+ zen_events { after: <cursor>, waitSeconds: 25 }
546
+ ```
547
+
548
+ A Stop press becomes a `kind: "stop"` event. The agent should finish the current
549
+ step, then call `zen_progress { done: true }` to clear the card. A stopped
550
+ event is not an error: it means the user asked for the job to wrap up.
551
+
552
+ The global Pause switch pushes `kind: "pause"` and `kind: "resume"` events, and
553
+ `zen_events` reports `paused: true` until Resume. While paused, every browser
554
+ tool returns the `paused` error; do not retry in a loop.
555
+
556
+ `zen_watch_add` watches a tab for:
557
+
558
+ - `change`: the page text changed, optionally only when it now contains a phrase.
559
+ - `appear`: a CSS selector appeared.
560
+ - `disappear`: a CSS selector disappeared.
561
+
562
+ Watches poll on the server, post a card in Zen when they fire, and report
563
+ `kind: "watch"` events through `zen_events`. They expire after `maxMinutes`
564
+ (120 by default), polling never goes below `watchMinIntervalSeconds`, and at
565
+ most 50 watches run at once. Adding or removing a watch changes server state,
566
+ so both tools are blocked in read-only mode.
567
+
568
+ ## Sessions and templates
569
+
570
+ `zen_session_save` snapshots every space, tab, folder, pin, and essential tab in
571
+ a window. `zen_session_restore` reuses a space with the same name unless
572
+ `newSpaces` is set, skips URLs that are already open, restores folders and pins,
573
+ and reports warnings instead of failing the whole restore. Restores are limited
574
+ to 300 tabs by default.
575
+
576
+ `zen_space_templates` ships four built-ins: `research`, `github-triage`, `news`,
577
+ and `docs`. `zen_template_save` turns a live space into a user template and
578
+ `zen_template_apply` creates a new space from one, including folders. Built-in
579
+ templates cannot be deleted.
580
+
581
+ ## Safety and policy
582
+
583
+ The server enforces policy outside the model:
584
+
585
+ - **Ownership.** Zen MCP launches Zen itself and only controls that browser.
586
+ It never attaches to an existing Marionette session, and the listener is shut
587
+ after startup.
588
+ - **One-time consent.** With `requireConsent` on (the default), the browser
589
+ shows an approval card before any tool can read or change anything. Declining
590
+ quits the browser. A timeout leaves the card open and the tool returns an
591
+ error, so a later call can wait again.
592
+ - **Global pause.** The banner in Zen has a **Pause** button. Pausing rejects
593
+ in-flight bridge requests, hides progress, defers questions, and blocks every
594
+ browser tool with error code `paused` until **Resume**. `zen_events`,
595
+ `zen_answers`, `zen_config`, and `zen_audit_tail` stay available so the agent
596
+ can see the pause and local policy.
597
+ - `readOnly` rejects every mutating tool with a specific error, including
598
+ `zen_watch_add` and `zen_watch_remove`. Reads, lists, status, questions,
599
+ events, watch listing, and the audit log keep working. A read-only server
600
+ also refuses to auto-launch Zen and blocks `zen_launch`, so read-only work
601
+ never starts a process or creates a profile.
602
+ - `allowedDomains` blocks URLs outside the list before `zen_tabs_open`,
603
+ `zen_glance`, `zen_show_evidence`, `zen_show_evidence_batch`, sessions, and
604
+ templates run. Entries match a host and its subdomains; an empty list allows
605
+ everything.
606
+ - `auditLog` appends one JSON line per call to `audit.jsonl` in the data
607
+ directory, including blocked calls. Long text and sensitive arguments are
608
+ stored as a length and SHA-256 digest, URLs keep only scheme, host, and path
609
+ (queries, fragments, and credentials are removed), and the log rotates at
610
+ 5 MB with one backup. `zen_audit_tail` reads the tail.
611
+ - Sessions and templates are sanitized and capped before use, and are written
612
+ atomically with owner-only permissions. A symlinked file is never written
613
+ through.
614
+ - There are no per-action approval cards. Approval is granted once per browser
615
+ session, and Pause is the stop switch. Use read-only mode and the domain
616
+ allowlist when an agent should not be able to change the browser at all.
617
+
618
+ ## CLI
619
+
620
+ ```text
621
+ zen-mcp [serve] Run the MCP server over stdio
622
+ zen-mcp launch Launch Zen once, verify ownership, then quit it
623
+ zen-mcp status Print config, profile mode, and port state
624
+ zen-mcp doctor Check config, executable, bridge, profile, port, policy
625
+ zen-mcp setup Detect Zen, write config, print an MCP snippet
626
+ zen-mcp setup --use-default-profile
627
+ zen-mcp setup --dedicated-profile
628
+ zen-mcp config show Print the config path and values
629
+ zen-mcp config set <key> <value>
630
+ ```
631
+
632
+ `launch` is a one-shot self-check: it starts an owned browser, proves the
633
+ nonce and lockdown work, then quits the browser before exiting. It does not keep
634
+ a browser open for later.
635
+
636
+ Config keys: `zenPath`, `profilePath`, `useDefaultProfile`, `requireConsent`,
637
+ `consentTimeoutSeconds`, `launchArgs`, `autoLaunch`, `launchTimeoutMs`,
638
+ `askTimeoutSeconds`, `marionettePort`, `readOnly`, `allowedDomains`,
639
+ `auditLog`, `dataDir`, `autoAttachWindows`, `watchMinIntervalSeconds`.
640
+
641
+ `config set` accepts `true` or `false` (also `1`/`0` and `yes`/`no`), numbers
642
+ within their allowed range, a comma-separated `allowedDomains` list, and
643
+ whitespace-separated `launchArgs`. Environment overrides are never written back
644
+ into the file. `doctor` also prints a **Policy** line that warns when consent,
645
+ read-only mode, the domain allowlist, or the audit log is weakened, when extra
646
+ launch arguments are set, or when `ZEN_MCP_BRIDGE_SCRIPT` replaces the bundled
647
+ bridge.
648
+
649
+ Environment variables override the file:
650
+
651
+ | Variable | Effect |
652
+ | --- | --- |
653
+ | `ZEN_MCP_CONFIG` | Config file path |
654
+ | `ZEN_MCP_DATA_DIR` | Sessions, templates, and audit log directory |
655
+ | `ZEN_MCP_ZEN_PATH` | Zen executable |
656
+ | `ZEN_MCP_PROFILE` | Custom agent profile directory |
657
+ | `ZEN_MCP_USE_DEFAULT_PROFILE` | `1` uses Zen's normal profile instead of the dedicated one |
658
+ | `ZEN_MCP_REQUIRE_CONSENT` | `0` skips the one-time approval card |
659
+ | `ZEN_MCP_CONSENT_TIMEOUT_SECONDS` | How long a tool waits for approval |
660
+ | `ZEN_MCP_LAUNCH_ARGS` | Extra Zen arguments, split on whitespace |
661
+ | `ZEN_MCP_MARIONETTE_PORT` | Marionette port (Zen currently always uses 2828) |
662
+ | `ZEN_MCP_READ_ONLY` | `1`, `true`, or `yes` enables read-only mode |
663
+ | `ZEN_MCP_ALLOWED_DOMAINS` | Comma-separated domain allowlist |
664
+ | `ZEN_MCP_AUDIT_LOG` | `1`, `true`, or `yes` enables the audit log |
665
+ | `ZEN_MCP_WATCH_MIN_INTERVAL_SECONDS` | Lower bound for watch polling |
666
+ | `ZEN_MCP_LOG` | `debug`, `info`, `warn`, or `error` |
667
+ | `ZEN_MCP_BRIDGE_SCRIPT` | Override the bundled `bridge.js` path |
668
+
669
+ Logs always go to **stderr**; stdout belongs to the MCP transport.
670
+
671
+ ## How it works
672
+
673
+ ```text
674
+ MCP client (Claude Code, Cursor, ...)
675
+ │ stdio, JSON-RPC
676
+ ▼
677
+ zen-mcp server ──── Marionette (127.0.0.1:2828) ──── Zen chrome scope
678
+ │ launch, inject,
679
+ │ WebSocket on 127.0.0.1, random token background reads
680
+ ▼
681
+ bridge inside each Zen window (system principal)
682
+ │
683
+ ▼
684
+ gZenWorkspaces · gZenFolders · gBrowser · Places · UI cards
685
+ ```
686
+
687
+ Three layers:
688
+
689
+ 1. **Launch and control plane.** The harness spawns Zen with agent access and a
690
+ random launch nonce, reads the nonce back through `Services.env` to prove the
691
+ browser on the port is the one it started, then closes every other Marionette
692
+ connection and the listening socket. Chrome-scope scripts are fixed server
693
+ code for setup, diagnostics, and the content-actor read path; agents cannot
694
+ submit arbitrary scripts.
695
+ 2. **Browser bridge.** A small bundle is injected into each browser window. It
696
+ owns the tab-id mapping, talks to Zen's internal space and folder APIs, and
697
+ renders the UI cards in a shadow root. It connects out to the server over
698
+ loopback with a token, so no listening port exists in the browser.
699
+ 3. **MCP surface.** Tools validate input, map to bridge operations, and wrap
700
+ errors with actionable messages. Server instructions carry the workflow
701
+ guidance, while sessions, templates, watches, and the audit log live in the
702
+ server process.
703
+
704
+ Space and folder operations use Zen's own JS APIs (`gZenWorkspaces`,
705
+ `gZenFolders`) rather than UI automation, so they behave like native actions.
706
+
707
+ ## Security model
708
+
709
+ The threat model is a local process on the same account, a page the agent reads,
710
+ or the model itself trying to drive the browser behind the user's back. Zen MCP
711
+ is built so each of those has a hard boundary, not just a policy check. The
712
+ full threat model is in [docs/security.md](docs/security.md). To report a
713
+ vulnerability, use the private channel in [SECURITY.md](SECURITY.md), not a
714
+ public issue.
715
+
716
+ - **Chrome access is opt-in per process.** Only a Zen spawned by Zen MCP gets
717
+ `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`, and only in that child's environment. No
718
+ preference is written, so a normal Zen launch never opens a debug port.
719
+ - **The server only controls a browser it started.** Before launching, it
720
+ refuses if the Marionette port is already open or, for the normal profile, if
721
+ Zen is already running. There is no attach path to a user's existing browser.
722
+ - **Identity is proven, not assumed.** Every launch carries a random nonce in
723
+ its environment. The server reads it back in chrome before touching anything,
724
+ and also records Gecko's real `moz:processID`. On a mismatch it attaches
725
+ nothing and kills nothing, so a racing browser is never harmed.
726
+ - **The listener is closed after startup.** The server closes every other
727
+ Marionette connection and calls `setAcceptConnections(false)`. From then on
728
+ the port refuses connections, so no other local tool can create a session.
729
+ `zen_config` and `zen_launch` report `lockedDown` and the owned browser pid.
730
+ - **One-time consent.** With `requireConsent` on (the default), a card in Zen
731
+ asks before the first read or change. Declining quits the owned browser. A
732
+ timeout leaves the card open and returns an error; nothing is read or changed
733
+ until the user approves.
734
+ - **Global pause.** The banner's Pause button rejects in-flight bridge
735
+ requests, hides progress, defers questions, pauses watches, and makes every
736
+ browser tool fail with `paused`. Resume restores access. Only local tools
737
+ (`zen_events`, `zen_answers`, `zen_config`, `zen_audit_tail`) stay usable.
738
+ - **The owned browser is quit on shutdown.** The server tries a graceful quit,
739
+ then a forced quit, then terminates the recorded browser process. A browser
740
+ whose identity was never verified is never killed.
741
+ - **The bridge authenticates both sides.** It listens on `127.0.0.1` only and
742
+ uses a fixed method map. A 256-bit key generated for the server session is
743
+ shared only with the injected bridge, and every connection, including a
744
+ reconnect, completes a mutual HMAC-SHA256 challenge with a fresh nonce before
745
+ any request is accepted. There is no eval-from-agent tool; Evidence Mode passes
746
+ only the quote, context, and offsets into scripts built by the server.
747
+ - **Input is constrained.** `zen_tabs_open` accepts only `http:`, `https:`, and
748
+ `about:` URLs. `zen_show_evidence` and `zen_show_evidence_batch` accept only
749
+ `http(s)` sources. Search queries are literal strings, never expressions. The
750
+ domain allowlist is checked before mutations, sessions, and templates.
751
+ - **UI stays out of pages.** Question, notification, consent, progress, and
752
+ evidence cards render in browser chrome inside a shadow root, not in page
753
+ content, so pages cannot reach or spoof them.
754
+ - **Evidence marks are inert and unspoofable.** Each call gets a random marker
755
+ attribute, highlights render in a closed shadow root that ignores pointer
756
+ events, and clearing removes only markers the server created. The page's own
757
+ text and styles are never changed.
758
+ - **The audit log records calls without retaining content.** One JSON line per
759
+ tool call, including blocked calls, with redacted URLs, outcome, and
760
+ duration. Long text and sensitive argument values become lengths and
761
+ SHA-256 digests; the file is owner-only and rotates at 5 MB.
762
+
763
+ ### Residual risks
764
+
765
+ No local browser harness can remove these. They are worth knowing before opting
766
+ into the normal profile:
767
+
768
+ - Between process start and lockdown there is a small window in which another
769
+ local process could race for a Marionette session, because Marionette itself
770
+ has no authentication. The server detects a competing session and fails
771
+ closed, but the race exists.
772
+ - Any process running as the same user can read process memory, inspect
773
+ arguments, or attach a debugger. Local tools cannot be defended against with
774
+ cryptography alone.
775
+ - Page text read by the agent is sent to whatever model provider the MCP client
776
+ uses. That is a data-sharing decision, not a browser-permission one.
777
+ - Using the normal profile means the agent can read pages where you are signed
778
+ in, including personal data. The dedicated agent profile is the default for a
779
+ reason.
780
+ - The lockdown relies on Zen's internal Marionette module layout. A future Zen
781
+ release can change it; the server then fails to start rather than silently
782
+ continuing without protection.
783
+
784
+ ## Troubleshooting
785
+
786
+ **"Zen is not running. Zen MCP launches its own browser with agent access..."**
787
+ Nothing owns the agent browser yet and `autoLaunch` is off. Call `zen_launch`,
788
+ start the server again, or set `autoLaunch` to true.
789
+
790
+ **"Marionette is already listening on port 2828"**
791
+ Another Zen or a WebDriver session owns the port. Zen MCP will not attach to it.
792
+ Quit that browser or stop the other tool, then call `zen_launch` again. Use
793
+ `ZEN_MCP_MARIONETTE_PORT` only if another tool permanently owns 2828.
794
+
795
+ **"Zen is already running with its normal profile"**
796
+ `useDefaultProfile` is on, a normal Zen is open, and a second launch would hand
797
+ the URL to that instance instead of creating an agent browser. Quit Zen
798
+ completely, or switch to the dedicated agent profile with
799
+ `zen-mcp setup --dedicated-profile`.
800
+
801
+ **"Zen did not open Marionette on port 2828 within Ns"**
802
+ The browser never accepted the agent port, usually because it handed off to a
803
+ running Zen. The launch attempt was stopped so it cannot keep the profile
804
+ locked. Quit Zen completely and try again.
805
+
806
+ **"The browser answering on the Marionette port was not the one Zen MCP just
807
+ started"**
808
+ A second browser won the port during the startup race. Nothing was attached and
809
+ nothing was killed. Quit the browser on 2828 and retry.
810
+
811
+ **"The Marionette port could not be locked down"**
812
+ Zen started, but the internal Marionette server did not close its listener.
813
+ The server shut the browser instead of continuing without the boundary. This is
814
+ usually a Zen version change; check `zen-mcp doctor`.
815
+
816
+ **"Zen MCP is waiting for approval in Zen"**
817
+ Click **Allow this session** on the card in the agent's Zen window, then call
818
+ the tool again. The timeout is `consentTimeoutSeconds`.
819
+
820
+ **"Browser access was declined in Zen"**
821
+ The browser Zen MCP started was closed. Call `zen_launch` to ask again, or set
822
+ `requireConsent` to false if the approval card is not wanted.
823
+
824
+ **A tool fails with `paused`**
825
+ Someone pressed **Pause** in the Zen banner. The browser is blocked until
826
+ **Resume** is pressed. This is not a retryable error; wait for the user.
827
+
828
+ **"The Zen profile at ... is already open in another browser"**
829
+ The configured profile is locked by a running Zen. Quit that instance, or use
830
+ the dedicated agent profile. This check happens before spawning, so it fails
831
+ immediately instead of waiting for a Marionette timeout.
832
+
833
+ **`zen_read_page` says the page is privileged or still loading**
834
+ `about:` pages and tabs without a content document cannot be scraped. Wait for
835
+ loading to finish, or open the HTTP version of the page.
836
+
837
+ **A PDF in another space reports `pdf_unreadable`**
838
+ Firefox does not initialize the PDF viewer for a hidden tab. Ask the user to open
839
+ the PDF, then read the active tab.
840
+
841
+ **`zen_show_evidence` returns `QUOTE_NOT_FOUND`, `AMBIGUOUS_MATCH`, or `LOW_MATCH_CONFIDENCE`**
842
+ No highlight was added and the quote should not be presented as support. Copy the
843
+ passage from the page, shorten it, or add surrounding `context`. PDFs and
844
+ privileged pages cannot be inspected at all.
845
+
846
+ **A tool reports `actor_unavailable`**
847
+ The owned browser disconnected. Because the Marionette listener stays shut,
848
+ this server cannot re-attach. Quit that Zen window, then call `zen_launch` to
849
+ start a new owned browser.
850
+
851
+ **The corner cards do not appear**
852
+ Only browser windows get the bridge. New windows are attached automatically when
853
+ `autoAttachWindows` is on; a tool call also injects into a window that does not
854
+ have it yet. If cards still do not show, run `zen-mcp doctor` and check the
855
+ bridge line.
856
+
857
+ **A tool is blocked with `read_only` or `domain_not_allowed`**
858
+ Run `zen_config` to see the effective policy, then `zen_audit_tail` to see the
859
+ blocked call. Change the config file or an environment variable and restart the
860
+ server.
861
+
862
+ ## Tests
863
+
864
+ ```sh
865
+ npm test # 185 unit tests, no browser
866
+ ZEN_MCP_E2E=1 npm run test:zen
867
+ ```
868
+
869
+ The integration suite has 34 tests in six groups: the MCP server against a
870
+ real headless Zen that the server launches itself, policy enforcement with
871
+ read-only and allowlist servers, the runtime against a real browser, and the
872
+ security boundary. It creates spaces, reads pages and formats, moves tabs into
873
+ folders, uses essentials, pins, containers, clipboard, progress, events,
874
+ watches, sessions, templates, recently closed tabs, and questions. The evidence
875
+ tests check exact, ambiguous, context-assisted, missing, and cleared matches,
876
+ background and focused verification, batch verification with opened and reused
877
+ tabs, literal search in one tab and across tabs, the real overlay and scroll
878
+ position in the page, and the card text in browser chrome. The security tests
879
+ click the real approval card, assert the Marionette listener is closed before
880
+ approval, reject a second client, verify Pause blocks requests and Resume
881
+ restores them, check denial quits the browser, and check shutdown quits it.
882
+
883
+ Profiles are created under `D:\tmp\zen-marionette-test` on Windows and
884
+ `$TMPDIR/zen-mcp-test` elsewhere, then removed; override with
885
+ `ZEN_MCP_TEST_PROFILE` to reuse a specific profile for debugging.
886
+
887
+ Manual probes with verbose output live in `scripts/probe-smoke.ts` (bridge, UI,
888
+ history, bookmarks) and `scripts/probe-mcp.ts` (stdio MCP round trip).
889
+
890
+ ## Known limitations
891
+
892
+ - Zen's internal workspace and folder APIs can change between releases. Pin a
893
+ Zen version if a newer build breaks spaces; the error will name the failing
894
+ call.
895
+ - PDF text extraction requires the PDF tab to be visible; hidden-space PDFs
896
+ return `pdf_unreadable`.
897
+ - Marionette is fixed at port 2828 in current Zen builds, so one agent browser
898
+ per machine. Two Zen MCP servers cannot share it.
899
+ - The startup race before lockdown cannot be eliminated while Marionette has no
900
+ authentication. The server detects it and fails closed.
901
+ - A browser whose Marionette session is lost cannot be re-attached, because the
902
+ listener stays shut. Quit it and start a new one.
903
+ - Reads capture the current DOM text. Infinite-scroll and client-rendered pages
904
+ only return what has loaded.
905
+ - Evidence Mode searches rendered DOM text, not pixels. PDFs, images, canvas,
906
+ cross-origin iframes, and shadow roots cannot be searched.
907
+ - Evidence marks are temporary overlays. They can drift if the page reflows
908
+ while visible, and pages that change constantly may return
909
+ `HIGHLIGHT_FAILED`.
910
+ - Watches run in the server process and stop when it exits. They do not survive
911
+ a restart.
912
+ - No screenshot or click automation inside pages. This harness is for Zen and
913
+ agent conversation, not a full WebDriver replacement.
914
+ - No per-action approval cards. Approval is per browser session, and Pause is
915
+ the global stop switch. Use read-only mode and the domain allowlist for
916
+ additional guardrails.
917
+
918
+ ## License
919
+
920
+ MIT. See [LICENSE](LICENSE).