@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/LICENSE +21 -0
- package/README.md +919 -2
- package/dist/bridge.js +5636 -0
- package/dist/cli.js +8888 -0
- package/dist/cli.js.map +7 -0
- package/package.json +58 -4
package/README.md
CHANGED
|
@@ -1,3 +1,920 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Zen MCP
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/spaxe-dev/zen-mcp/actions/workflows/ci.yml)
|
|
4
|
+
[](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
|
+

|
|
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).
|