@spaxe-dev/zen-mcp 0.3.3 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,18 +13,19 @@
13
13
 
14
14
  Zen MCP is an MCP server that lets an AI agent work inside [Zen Browser](https://zen-browser.app) using Zen's own spaces, folders, and tabs. The agent can research in background tabs, read and search pages without switching what you are looking at, ask you a question in a small in-browser card, and show the evidence behind an answer.
15
15
 
16
- Status: **0.3.x, pre-1.0.** Windows is the only platform with a live-tested Zen launch. The public API, tools, and configuration keys can still change. See [Current maturity](#current-maturity-and-platform-support) and [Known limitations](https://github.com/spaxe-dev/zen-mcp/blob/main/docs/troubleshooting.md#known-limitations).
16
+ Status: **0.4.x, pre-1.0.** Windows is the only platform with a live-tested Zen launch. The public API, tools, and configuration keys can still change. See [Current maturity](#current-maturity-and-platform-support) and [Known limitations](https://github.com/spaxe-dev/zen-mcp/blob/main/docs/troubleshooting.md#known-limitations).
17
17
 
18
18
  ## What it does
19
19
 
20
20
  - Opens tabs in the background, reads them, and searches them without changing the active tab or taking over your screen.
21
+ - Clicks one control or types into one field when you explicitly ask the agent to operate a page, using named refs from an interactive read instead of agent-supplied JavaScript. Frame controls and frame reads are supported.
21
22
  - Creates and organizes native Zen spaces, folders, pinned tabs, essentials, split views, and Glance previews.
22
23
  - Shows progress cards with a real **Stop** button, asks questions in Zen chrome, and supports a global **Pause** switch.
23
24
  - Verifies citations with Evidence Mode: it reuses or opens the source, finds the quoted passage, marks it with a temporary overlay, and records the match method and confidence.
24
25
  - Saves window layouts as sessions and reusable space templates.
25
26
  - Enforces policy outside the model with read-only mode, a domain allowlist, an audit log, one-time consent, and an owned-browser boundary.
26
27
 
27
- There are 50 tools, 5 live resources, and 3 prompts. Tool arguments are structured, results are typed, and page content is treated as data, not instructions. The full surface is in [docs/tools.md](https://github.com/spaxe-dev/zen-mcp/blob/main/docs/tools.md).
28
+ There are 53 tools, 5 live resources, and 3 prompts. Tool arguments are structured, results are typed, and page content is treated as data, not instructions. The full surface is in [docs/tools.md](https://github.com/spaxe-dev/zen-mcp/blob/main/docs/tools.md).
28
29
 
29
30
  ## Who it is for
30
31
 
@@ -33,7 +34,7 @@ There are 50 tools, 5 live resources, and 3 prompts. Tool arguments are structur
33
34
  - **People using an MCP client** such as Claude Code, Cursor, or another client that can launch a stdio server.
34
35
  - **Users who want browser automation with explicit boundaries**: the agent controls only a browser Zen MCP started, and you can pause it or make it read-only.
35
36
 
36
- It is not a WebDriver replacement. It does not click inside pages, take page screenshots, fill forms, or drive unattended bots.
37
+ It is not a general WebDriver replacement. Clicking and typing exist so an agent can complete a specific step you asked for; there is no page screenshot, file upload, download handling, or unattended bot loop, and both tools are blocked in read-only mode.
37
38
 
38
39
  ## What makes it different
39
40
 
@@ -41,7 +42,7 @@ It is not a WebDriver replacement. It does not click inside pages, take page scr
41
42
 
42
43
  **Native Zen constructs.** Spaces, folders, pins, essentials, split view, and Glance use Zen's internal APIs, so the result behaves like something you did in the UI instead of a separate extension's bookkeeping.
43
44
 
44
- **Background first.** Reads and evidence checks work on loaded tabs in any space, including spaces that are not currently rendered. `zen_read_page`, `zen_read_pages`, `zen_find_text`, and `zen_search_tabs` do not select, scroll, or highlight anything unless you ask for it.
45
+ **Background first.** Reads, evidence checks, waits, and page actions work on loaded tabs in any space, including spaces that are not currently rendered. `zen_read_page`, `zen_read_pages`, `zen_find_text`, `zen_search_tabs`, and `zen_wait_for` do not select, scroll, or highlight anything unless you ask for it. `zen_click` and `zen_type` act on the tab you name, not on whatever tab is in front, and report whether the page visibly changed.
45
46
 
46
47
  **You stay in control.** One approval covers the server session. The persistent banner has a Pause button that blocks subsequent browser work. Read-only mode, the domain allowlist, and the audit log add policy the model cannot talk its way around. There are no per-action approval cards.
47
48
 
@@ -51,13 +52,13 @@ It is not a WebDriver replacement. It does not click inside pages, take page scr
51
52
 
52
53
  | Area | What you get |
53
54
  | --- | --- |
54
- | Research | Background page reads in text, Markdown, links, tables, metadata, outline, or a CSS-selected element; literal search across tabs; Evidence Mode for single or batched citations |
55
+ | Research | Background page reads in text, Markdown, links, tables, metadata, outline, an interactive element list, or a CSS-selected element; literal search across tabs; Evidence Mode for single or batched citations |
55
56
  | Organization | Spaces, folders, tabs, pins, essentials, split view, Glance, Firefox containers |
56
57
  | Awareness | History search, recently closed tabs, bookmarks, duplicate and stale tab audit, domain grouping |
57
58
  | Coordination | Progress card with Stop, in-browser questions, notifications, tab watches, one event stream |
58
59
  | Repeatability | Session snapshots and reusable space templates, including folders |
59
60
  | Policy | Owned browser, one-time consent, global Pause, read-only mode, domain allowlist, JSONL audit log |
60
- | Interface | 50 tools, 5 resources, 3 prompts, structured results, progress notifications, cancellation |
61
+ | Interface | 53 tools, 5 resources, 3 prompts, structured results, progress notifications, cancellation |
61
62
 
62
63
  ![The Research space with a Reading folder, an essential tab, and the agent progress card](https://raw.githubusercontent.com/spaxe-dev/zen-mcp/main/docs/screenshots/v0.2-space-overview.png)
63
64
 
@@ -87,6 +88,14 @@ npm install -g @spaxe-dev/zen-mcp
87
88
  zen-mcp setup
88
89
  ```
89
90
 
91
+ To upgrade later, run `zen-mcp update`. It checks npm, compares the latest
92
+ release with the installed version, and runs the matching global install
93
+ command (`npm`, `pnpm`, `yarn`, or `bun`). `zen-mcp update --check` only
94
+ reports the versions, and `zen-mcp doctor` includes the same update status.
95
+ The running server also checks once at startup and offers a newer release in
96
+ the browser banner: **Update** installs it, and dismissing leaves a small
97
+ icon that reopens the offer.
98
+
90
99
  Or run setup without a global install:
91
100
 
92
101
  ```sh
@@ -96,7 +105,7 @@ npx @spaxe-dev/zen-mcp setup
96
105
  Each GitHub release also attaches a package tarball and `SHA256SUMS`:
97
106
 
98
107
  ```sh
99
- npm install -g ./zen-mcp-0.3.3.tgz
108
+ npm install -g ./zen-mcp-0.5.0.tgz
100
109
  zen-mcp setup
101
110
  ```
102
111
 
@@ -119,6 +128,7 @@ zen-mcp setup # detects Zen, writes a config, prints an MCP snippet
119
128
  zen-mcp onboard # pick MCP clients and add Zen MCP to their config
120
129
  zen-mcp doctor # config, executable, Marionette, bridge, profile, policy
121
130
  zen-mcp status # config, profile mode, and port state
131
+ zen-mcp update # check npm and install the latest release
122
132
  ```
123
133
 
124
134
  `setup` writes `%APPDATA%\zen-mcp\config.json` on Windows. On macOS and Linux it writes `$XDG_CONFIG_HOME/zen-mcp/config.json` when `XDG_CONFIG_HOME` is set, otherwise `~/.config/zen-mcp/config.json`. Override the path with `ZEN_MCP_CONFIG`. The data directory defaults to `data` beside the config file.
@@ -131,7 +141,7 @@ Run the picker:
131
141
  zen-mcp onboard
132
142
  ```
133
143
 
134
- It lists Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI, Windsurf, Cline, and Zed. Clients found on this machine are preselected. Use the arrow keys to move, space to toggle, and enter to confirm. Zen MCP merges a `zen-mcp` entry into each selected client's own configuration file and leaves other servers alone. Choose **Other MCP client** to print a step-by-step runbook for any agent: known config paths, the right entry shape for JSON, VS Code, Zed and TOML clients, merge rules, a validation checklist, and a completion report.
144
+ It lists Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI, OpenCode, oh-my-pi, DeepSeek Harness, ZCode, Windsurf, Cline, Zed, Roo Code, Kilo Code, Continue, Amp, Crush, Qwen Code, Kiro, Warp, Copilot CLI, Factory Droid, Amazon Q, Goose, LM Studio, Junie, and Pi. The list scrolls inside the picker, and clients found on this machine are preselected. Use the arrow keys, Page Up, Page Down, Home and End to move, space to toggle, and enter to confirm. Zen MCP merges a `zen-mcp` entry into each selected client's own configuration file and leaves other servers alone. Choose **Other MCP client** to print a step-by-step runbook for any agent: known config paths, the right entry shape for JSON, nested JSON, VS Code, Zed, TOML, YAML and shell clients, merge rules, a validation checklist, and a completion report.
135
145
 
136
146
  For scripts or a shell without a TTY, name the clients:
137
147
 
@@ -205,8 +215,9 @@ Do not point `profilePath` at your normal profile unless that is the tradeoff yo
205
215
  | Browser ownership | Always on | Launches its own Zen, proves identity with a nonce and `moz:processID`, then closes the Marionette listener to every other client | A local process can race for the port before lockdown; the race is detected, not eliminated |
206
216
  | Consent | On | Shows one approval card per server process before the first read or change; decline closes the owned browser | After a decline, restart the server to ask again; a timeout leaves the card open |
207
217
  | Pause | Available in the banner | Blocks browser tools with `paused`, hides the progress card, defers questions, and skips watch polls until Resume | A command already running in Zen may finish; its result is discarded. Pause is not persisted, and existing evidence overlays are not removed |
208
- | Read-only mode | Off | Blocks all 30 tools in the mutating set, including `zen_launch`, a read-only server's auto-launch, and on-screen progress, question, and notification cards | Reads, lists, events, collected answers, and the audit log still work; session and template listings still show stored URLs |
218
+ | Read-only mode | Off | Blocks all 32 tools in the mutating set, including `zen_launch`, page clicks and typing, a read-only server's auto-launch, and on-screen progress, question, and notification cards | Reads, lists, events, collected answers, and the audit log still work; session and template listings still show stored URLs |
209
219
  | Domain allowlist | Empty | Matches an exact host or a subdomain on a label boundary before opening, previewing, verifying, watching, restoring a session, or applying a template | It is rechecked immediately after opening, but slow, script, or meta redirects can land elsewhere afterwards; reads recheck the tab URL |
220
+ | Page actions | Read-only blocks them | An interactive read tags controls with refs, including frame-prefixed refs; click and type resolve one ref or CSS selector through a fixed script and use Marionette's native input commands | A click is a real input that can submit a form, start a download, navigate, or purchase. The allowlist checks the tab URL, target frame URL, and link target, not what an in-page script does afterwards. Refs expire after another interactive read or a navigation. Typed text is capped at 10,000 characters; password values are never returned and file inputs are refused |
210
221
  | Private windows | Excluded | The bridge is not injected into private windows and an existing bridge is destroyed | This path is not covered by the automated live suite; treat it as a best-effort boundary |
211
222
  | Audit log | On | Appends one JSON line per tool call, including blocked calls, with URLs reduced to scheme, host, and path | Argument summaries are bounded; sensitive values are digested, but a preview of the summarized arguments can remain |
212
223
  | Data storage | Local only | Sessions, templates, audit log, and the default agent profile live in the data directory; files are owner-only where the platform supports POSIX modes | Any process running as your user can read them; contents are not encrypted at rest |
@@ -227,7 +238,9 @@ Zen MCP is usable but pre-1.0. The tool surface and configuration keys have chan
227
238
 
228
239
  - Marionette is fixed at 2828 in current Zen builds. Two Zen MCP servers cannot run at once.
229
240
  - A lost Marionette session cannot be re-attached, because the listener stays shut. Quit the browser and start a new one.
230
- - Reads and evidence search the current rendered DOM only. Iframes, shadow roots, canvas, images, SVG, and form controls are not read.
241
+ - Reads and evidence search one document at a time. Frame text is available with `framePath`, and interactive reads collect frame controls with refs such as `f0-e3`; canvas, images, SVG, and closed shadow roots are not read. Text reads skip open shadow roots and form controls; use an interactive read for form controls, which includes controls in open shadow roots.
242
+ - Page actions use fixed scripts. They reach frames through explicit refs or `framePath`, but not closed shadow roots or canvas content, and a ref from an older interactive read is rejected after another interactive read or a navigation.
243
+ - A click or typed key is a real browser input. It can submit a form, start a download, navigate, or make a purchase; the domain allowlist is checked before and after, but it cannot prevent an in-page script from acting on its own.
231
244
  - Hidden and unloaded tabs behave differently: a loaded tab in a background space can be read, but a tab that has not loaded returns `tab_not_loaded`.
232
245
  - PDF reads depend on Zen's PDF viewer and are unreliable for hidden tabs. Open the PDF and retry if you get `pdf_unreadable`.
233
246
  - Fuzzy evidence matches are reported with `verified: false`. A batch is `ok` only when every citation matched and every match was verified.