@@ -5,16 +5,27 @@ in order of preference:
55
66## 1. MCP — works with any MCP-capable client (the normal path)
77
8- Install with ` npm install @zumer/ snapsurf` and ` npx playwright install chromium `
9- as shown in the [ README ] ( ../README.md ) . In the examples below, ` /ABS/PATH ` is the
10- absolute directory where you ran ` npm install ` .
8+ SnapSurf needs Node.js 22 or newer. ` snapsurf-mcp ` is a standard MCP ** stdio ** server:
9+ any client that can run a local command speaks to it. The command that every client
10+ below uses is:
1111
12- ` mcp/server.mjs ` is a standard MCP ** stdio** server: any client that can run a local
13- command speaks to it. The tool descriptions ARE the instructions — they teach the loop
14- (digest → find → act → verify → assert), the fail-loud contract, and how to read every
15- field, so the consuming model needs no extra prompt to use the tools correctly.
16- Structured clients read ` structuredContent ` ; clients that only read text get the same
17- facts as prose.
12+ ``` text
13+ npx -y -p @zumer/snapsurf snapsurf-mcp
14+ ```
15+
16+ The server starts and owns the browser daemon on demand, and installs Chromium for
17+ Playwright the first time it is missing (on Linux, run
18+ ` npx playwright install --with-deps chromium ` once if system libraries are absent).
19+ To pin a version or skip ` npx ` at startup, run ` npm install @zumer/snapsurf ` in a
20+ directory and use ` node /ABS/PATH/node_modules/@zumer/snapsurf/mcp/server.mjs ` instead.
21+
22+ The tool descriptions ARE the instructions — they teach the loop (digest → find → act →
23+ verify → assert), the fail-loud contract, and how to read every field, so the consuming
24+ model needs no extra prompt to use the tools correctly. The server also returns a short
25+ ` instructions ` text in ` initialize ` for clients that truncate tool descriptions, and
26+ every tool carries a ` title ` and MCP annotations (` readOnlyHint ` , ` destructiveHint ` ,
27+ ` idempotentHint ` , ` openWorldHint ` ). Structured clients read ` structuredContent ` ; clients
28+ that only read text get the same facts as prose.
1829
1930After every action, verify once and pass its ` diffId ` to assert. For example, with an
2031MCP client exposing ` callTool ` :
@@ -64,21 +75,26 @@ the daemon can return `ok: true` with `meta.assert.pass: false`. MCP exposes tha
6475verdict as ` structuredContent.pass: false ` and sets ` isError: true ` , retaining the
6576checks and evidence for diagnosis.
6677
67- The invariant for every client: ** command ` node ` , args ` ["/ABS/PATH/node_modules/@zumer/snapsurf/mcp/server.mjs"] ` ** .
68- The server starts and owns the daemon on demand. Exact config file names drift between
69- clients — check yours if a snippet below has moved.
78+ Exact config file names drift between clients — check yours if a snippet below has moved.
7079
7180** Claude Code**
7281
7382``` bash
74- claude mcp add --scope user snapsurf -- node /ABS/PATH/node_modules/@zumer/snapsurf/mcp/server.mjs
83+ claude mcp add --scope user snapsurf -- npx -y -p @zumer/snapsurf snapsurf-mcp
84+ ```
85+
86+ ** Claude Desktop** — ` claude_desktop_config.json ` :
87+
88+ ``` json
89+ { "mcpServers" : { "snapsurf" : {
90+ "command" : " npx" , "args" : [" -y" , " -p" , " @zumer/snapsurf" , " snapsurf-mcp" ] } } }
7591```
7692
7793** Codex CLI** (registers globally in ` ~/.codex/config.toml ` under
7894` [mcp_servers.snapsurf] ` ; verify with ` codex mcp list ` ):
7995
8096``` bash
81- codex mcp add snapsurf -- node /ABS/PATH/node_modules/ @zumer/snapsurf/ mcp/server.mjs
97+ codex mcp add snapsurf -- npx -y -p @zumer/snapsurf snapsurf- mcp
8298```
8399
84100Codex also reads ` AGENTS.md ` — this repo ships one with the browsing playbook, and a
@@ -89,31 +105,31 @@ truncate long tool descriptions.
89105
90106``` json
91107{ "mcpServers" : { "snapsurf" : {
92- "command" : " node " , "args" : [" /ABS/PATH/node_modules/ @zumer/snapsurf/ mcp/server.mjs " ] } } }
108+ "command" : " npx " , "args" : [" -y " , " -p " , " @zumer/snapsurf" , " snapsurf- mcp" ] } } }
93109```
94110
95111** VS Code (Copilot agent mode)** — ` .vscode/mcp.json ` :
96112
97113``` json
98114{ "servers" : { "snapsurf" : {
99- "type" : " stdio" , "command" : " node " , "args" : [" /ABS/PATH/node_modules/ @zumer/snapsurf/ mcp/server.mjs " ] } } }
115+ "type" : " stdio" , "command" : " npx " , "args" : [" -y " , " -p " , " @zumer/snapsurf" , " snapsurf- mcp" ] } } }
100116```
101117
102118** Gemini CLI** — ` ~/.gemini/settings.json ` :
103119
104120``` json
105121{ "mcpServers" : { "snapsurf" : {
106- "command" : " node " , "args" : [" /ABS/PATH/node_modules/ @zumer/snapsurf/ mcp/server.mjs " ] } } }
122+ "command" : " npx " , "args" : [" -y " , " -p " , " @zumer/snapsurf" , " snapsurf- mcp" ] } } }
107123```
108124
109125** OpenAI Agents SDK** (Python):
110126
111127``` python
112128from agents.mcp import MCPServerStdio
113129
114- snapdom = MCPServerStdio(params = {
115- " command" : " node " ,
116- " args" : [" /ABS/PATH/node_modules/ @zumer/snapsurf/ mcp/server.mjs " ],
130+ snapsurf = MCPServerStdio(params = {
131+ " command" : " npx " ,
132+ " args" : [" -y " , " -p " , " @zumer/snapsurf" , " snapsurf- mcp" ],
117133})
118134```
119135
@@ -124,7 +140,7 @@ Notes for non-Claude models:
124140
125141- Some clients truncate long tool descriptions. The descriptions here are deliberately
126142 complete (they carry the usage contract); if your client truncates, pair the tools
127- with the playbook below.
143+ with the server ` instructions ` and the playbook below.
128144- ** Schemas are deliberately flat** — no ` oneOf ` /` anyOf ` unions in any ` inputSchema ` .
129145 A real client (Codex CLI, first field test) projected union branches as complete
130146 signatures and lost the conditional fields, so calls died client-side. Per-action
@@ -137,32 +153,34 @@ Notes for non-Claude models:
137153
138154## 2. The playbook prompt — for agents that need the method, not just the tools
139155
140- ` skill/SKILL.md ` (installed as the ` agent-browse ` skill for Claude Code) is a
141- model-agnostic method: when to ` find ` instead of scroll, ` look ` after every action
142- instead of screenshots, checkpoint before risky actions, ids expire per epoch, covered
143- is literal, how to escalate to pixels. For any other framework, paste or adapt it into
144- the agent's system prompt next to the MCP tools. It is the distilled version of every
145- mistake previous agents paid for .
156+ ` skill/SKILL.md ` (installed as the ` snapsurf ` skill for Claude Code by
157+ ` tools/install-global.mjs ` ) is a model-agnostic method: when to ` find ` instead of
158+ scroll, ` look ` after every action instead of screenshots, checkpoint before risky
159+ actions, ids expire per epoch, covered is literal, how to escalate to pixels. For any
160+ other framework, paste or adapt it into the agent's system prompt next to the MCP tools.
161+ ` AGENTS.md ` at the repository root is the same method in the form coding agents read .
146162
147163## 3. No MCP at all — subprocess or HTTP
148164
149165Any framework that can spawn a process can drive the CLI (auth against the local daemon
150- is automatic; both sides must run as the same OS user):
166+ is automatic; both sides must run as the same OS user). Start the daemon once with
167+ ` npx -y @zumer/snapsurf serve ` , then:
151168
152169``` python
153170import subprocess
154171out = subprocess.run(
155- [" node " , " /ABS/PATH/node_modules/ @zumer/snapsurf/tools/browse.mjs " , " open" , " example.com" ],
172+ [" npx " , " -y " , " @zumer/snapsurf" , " open" , " example.com" ],
156173 capture_output = True , text = True ).stdout
157174```
158175
159176Verbs, output shapes and policies are in the [ usage reference] ( USAGE.md ) . For batch flows use
160- ` browse.mjs run "open …" "find …"` (one process, N verbs). Structured metadata for
161- every command also lands in the session JSONL under ` logs/ ` .
177+ ` snapsurf run "open …" "find …"` (one process, N verbs). Structured metadata for
178+ every command also lands in the session JSONL under ` logs/ ` (or ` SNAPSURF_LOGDIR ` ) .
162179
163180The daemon's loopback HTTP control plane (` /cmd ` , HMAC-authenticated envelopes) is what
164181the CLI and MCP server themselves use; ` tools/daemon-client.mjs ` is the reference
165- client if you want to integrate at that layer directly.
182+ client if you want to integrate at that layer directly. Port, token file and log
183+ directory come from ` SNAPSURF_PORT ` , ` SNAPSURF_TOKEN_FILE ` and ` SNAPSURF_LOGDIR ` .
166184
167185## What travels to the model (cost notes)
168186
0 commit comments