Skip to content

Commit 5ba4942

Browse files
tinchox5claude
andcommitted
Prepare 0.1.1: registry metadata, tool annotations, npx install, SnapSurf identifiers
- package.json declares mcpName io.github.zumerlab/snapsurf and server.json is added for the official MCP Registry; test:pack checks both against the package version. - Every MCP tool carries a title and annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint); initialize returns server instructions with the browsing loop and the package version. - One-line install: `npx -y -p @zumer/snapsurf snapsurf-mcp` for the MCP server and `npx -y @zumer/snapsurf serve` for the CLI. Server and daemon install Playwright's Chromium on first start when it is missing, without Playwright's misleading npx banner. - Development-era identifiers renamed: SNAPSURF_* environment variables (SNAPDOM_AGENT_* still read as fallbacks), global install under ~/.snapsurf, Claude Code skill `snapsurf`, daemon identity `snapsurf` (legacy identity and token paths still recognised so older daemons stay discoverable). - Docs: README pitch and npx-first install, per-client integration snippets, environment variable table, AGENTS.md shipped in the package, release guide with the registry step, repository links to zumerlab/snapsurf, stale "when published" wording removed. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
1 parent 9abd4f5 commit 5ba4942

26 files changed

Lines changed: 616 additions & 332 deletions

‎AGENTS.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ SnapSurf MCP tools if your client has them (`browser_open`, `browser_find`,
99
`browser_parent`, `browser_act`, `browser_verify`, `browser_assert`, `browser_checkpoint`,
1010
`browser_diff`, `browser_text`, `browser_page`, `browser_screenshot`,
1111
`browser_session_*`), or the CLI: `node tools/browse.mjs <verb>` against a daemon
12-
started with `node tools/browse.mjs serve`.
12+
started with `node tools/browse.mjs serve` (`npx snapsurf <verb>` from an npm install).
1313

1414
The loop, and the rules previous agents paid to learn:
1515

@@ -39,18 +39,27 @@ The loop, and the rules previous agents paid to learn:
3939
result. The daemon browses anonymously in its own cookie jar: `authState` tells you
4040
the truth; it never sees the user's logged-in sessions.
4141

42+
The same method, as a Claude Code skill, is in `skill/SKILL.md`.
43+
4244
## Working on the code
4345

4446
- Node 22; `npm ci && npx playwright install chromium`.
4547
- `npm test` = real-browser core suite + daemon/MCP security and session regressions.
4648
Also: `npm run test:lint`, `npm run test:doc-contract` (every field a tool
47-
description promises must be demonstrably delivered), `npm run test:regression`.
49+
description promises must be demonstrably delivered), `npm run test:regression`,
50+
`npm run test:pack` (the npm archive, its `mcpName` and `server.json` parity).
4851
- The house rule is fail-loud honesty: no silent greens, counts never shrink silently,
4952
uncertainty is declared (`INDETERMINATE`, `unobservable`, `uncertainty.reasons`) —
5053
keep every change on that side of the line, and extend the tests when you extend a
5154
contract.
55+
- Configuration is read from `SNAPSURF_*` environment variables (`PORT`, `TOKEN`,
56+
`TOKEN_FILE`, `LOGDIR`, `MAX_BODY_BYTES`); the development-era `SNAPDOM_AGENT_*`
57+
names remain read fallbacks. Tests run against an isolated port through
58+
`tools/run-isolated.mjs`, never against a developer's live daemon.
5259
- `vendor/snapdom/` is the pinned engine build; `tools/sdk-bundle.mjs` defines the ONE
5360
in-page SDK bundle; `node tools/install-global.mjs` refreshes the machine-global copy
54-
under `~/.claude/snapdom-agent/` after source changes.
61+
under `~/.snapsurf/` (and the `snapsurf` skill under `~/.claude/skills/`) after source
62+
changes.
63+
- Releases: bump `package.json` and `server.json` together (see `docs/RELEASING.md`).
5564
- See `README.md` for the full map and `docs/INTEGRATIONS.md` for hooking the
5665
instrument into MCP clients.

‎CHANGELOG.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,25 @@
11
# Changelog
22

3+
## 0.1.1
4+
5+
- Declare `mcpName` (`io.github.zumerlab/snapsurf`) and ship `server.json` for the
6+
official MCP Registry; `npm run test:pack` checks that both stay in sync with the
7+
package version.
8+
- Run from npm without a separate install: `npx -y -p @zumer/snapsurf snapsurf-mcp`
9+
for the MCP server and `npx -y @zumer/snapsurf serve` for the CLI. Chromium for
10+
Playwright is installed automatically on first start when it is missing.
11+
- Add a `title` and MCP annotations (`readOnlyHint`, `destructiveHint`,
12+
`idempotentHint`, `openWorldHint`) to every tool, and server `instructions` with
13+
the browsing loop for clients that truncate tool descriptions. The server reports its
14+
package version.
15+
- Rename the remaining development-era identifiers: configuration uses `SNAPSURF_*`
16+
variables, the global install lives in `~/.snapsurf/`, the Claude Code skill is
17+
`snapsurf`, and the daemon identifies itself as `snapsurf`. The `SNAPDOM_AGENT_*`
18+
variables and the old token paths are still read as fallbacks. Re-run
19+
`node tools/install-global.mjs` and stop daemons started by 0.1.0.
20+
- Documentation: npx-first installation, per-client snippets, environment variables,
21+
`AGENTS.md` shipped in the package, repository links to `zumerlab/snapsurf`.
22+
323
## 0.1.0
424

525
First experimental release of SnapSurf, with a local CLI, MCP server and

‎README.md‎

Lines changed: 53 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,51 +2,69 @@
22

33
Web navigation and verification for AI agents.
44

5-
SnapSurf gives browser agents a compact page summary, a typed diff after each
6-
action, and assertions over that diff. It reports changes to content, state, layout
7-
and clickability, including when an action produces no observable change.
8-
9-
It runs locally through an MCP server or CLI, using its own Chromium session. The
10-
observation code also works as an in-page library built on
5+
Most browser tools tell an agent what a page looks like now. SnapSurf tells it **what
6+
its last action changed**: a compact semantic digest of the page, a typed diff after
7+
each action (content, state, layout and clickability, including when nothing observable
8+
changed), and assertions over that exact diff. Missing evidence and uncertainty are
9+
reported, not hidden.
10+
11+
It runs locally as an MCP server or CLI with its own Chromium session. The observation
12+
code also works as an in-page library built on
1113
[SnapDOM](https://github.com/zumerlab/snapdom).
1214

13-
Version 0.1.0 is experimental.
15+
Version 0.1.1 is experimental.
16+
17+
## Add it to your MCP client
1418

15-
## Install from npm
19+
Requires Node.js 22 or newer. Add a stdio server that runs this command; Chromium for
20+
Playwright is installed automatically the first time it starts:
21+
22+
```json
23+
{
24+
"command": "npx",
25+
"args": ["-y", "-p", "@zumer/snapsurf", "snapsurf-mcp"]
26+
}
27+
```
1628

17-
Requires Node.js 22 or newer. Create a separate installation directory:
29+
With Claude Code:
1830

1931
```bash
20-
mkdir SnapSurf
21-
cd SnapSurf
22-
npm install @zumer/snapsurf
23-
npx playwright install chromium
32+
claude mcp add --scope user snapsurf -- npx -y -p @zumer/snapsurf snapsurf-mcp
2433
```
2534

26-
`npm install` installs SnapSurf; the Playwright command downloads its Chromium browser.
27-
This installation becomes available when the first npm release is published.
28-
On Linux, use `npx playwright install --with-deps chromium` if system libraries
29-
are also needed.
35+
Codex CLI, Cursor, VS Code, Gemini CLI, Windsurf and the OpenAI Agents SDK take the same
36+
command; per-client snippets are in [Integrations](docs/INTEGRATIONS.md). Its name in the
37+
official MCP Registry is `io.github.zumerlab/snapsurf`.
3038

31-
## Connect your MCP client
39+
To pin a version or avoid `npx` at startup, install once and point the client at the
40+
server file:
3241

33-
Add a stdio MCP server to your client with these settings, replacing the path with
34-
the absolute path to the directory where you ran `npm install`:
42+
```bash
43+
mkdir snapsurf && cd snapsurf
44+
npm install @zumer/snapsurf
45+
```
3546

3647
```json
3748
{
3849
"command": "node",
39-
"args": ["/ABS/PATH/node_modules/@zumer/snapsurf/mcp/server.mjs"]
50+
"args": ["/ABS/PATH/snapsurf/node_modules/@zumer/snapsurf/mcp/server.mjs"]
4051
}
4152
```
4253

43-
The MCP server starts the browser daemon when needed. Client configuration examples
44-
are in [Integrations](docs/INTEGRATIONS.md).
54+
On Linux, if Chromium fails to start for lack of system libraries, run
55+
`npx playwright install --with-deps chromium` once.
4556

4657
Ask your agent to open a page with `browser_open`, locate controls with `browser_find`,
4758
act with `browser_act`, then call `browser_verify` after each action. Read
4859
`structuredContent` for the result.
4960

61+
## If you are an agent
62+
63+
Read [AGENTS.md](AGENTS.md): the loop, the rules earlier agents paid to learn, and how
64+
to read every field. [skill/SKILL.md](skill/SKILL.md) is the same method packaged as a
65+
Claude Code skill. The MCP tool descriptions carry the full contract, and the server's
66+
`instructions` summarize it for clients that truncate them.
67+
5068
## Assert what you just verified
5169

5270
`browser_verify` returns a `diffId` for the observed transition. Pass it to
@@ -99,27 +117,31 @@ limits, retries and unavailable evidence.
99117

100118
## Use the CLI
101119

102-
From the directory where you installed SnapSurf, start the daemon in one terminal:
120+
Start the daemon in one terminal:
103121

104122
```bash
105-
npx snapsurf serve
123+
npx -y @zumer/snapsurf serve
106124
```
107125

108126
Then run a local smoke check in another:
109127

110128
```bash
111-
npx snapsurf open 'data:text/html,<h1>Local%20check</h1>'
112-
npx snapsurf assert '{"exists":"Local check"}'
113-
npx snapsurf stop
129+
npx -y @zumer/snapsurf open 'data:text/html,<h1>Local%20check</h1>'
130+
npx -y @zumer/snapsurf assert '{"exists":"Local check"}'
131+
npx -y @zumer/snapsurf stop
114132
```
115133

134+
From a directory where you ran `npm install @zumer/snapsurf`, `npx snapsurf <verb>`
135+
does the same without downloading anything. The `SNAPSURF_*` environment variables
136+
(port, token file, log directory) are listed in the [usage reference](docs/USAGE.md).
137+
116138
## Development
117139

118140
To modify SnapSurf itself, clone the source and install the development dependencies:
119141

120142
```bash
121-
git clone https://github.com/zumerlab/SnapSurf.git
122-
cd SnapSurf
143+
git clone https://github.com/zumerlab/snapsurf.git
144+
cd snapsurf
123145
npm ci
124146
npx playwright install chromium
125147
```
@@ -137,7 +159,7 @@ npm run test:pack
137159

138160
[Usage and API reference](docs/USAGE.md) covers CLI commands, report fields,
139161
checkpoints, the library, sensor plugin and Chrome companion.
140-
[Release guide](docs/RELEASING.md) covers validation and manual publication.
162+
[Release guide](docs/RELEASING.md) covers validation, publication and the MCP Registry.
141163

142164
MIT licensed. Copyright © Juan Martin Muda / [zumerlab](https://github.com/zumerlab).
143165
See [LICENSE](LICENSE).

‎docs/INTEGRATIONS.md‎

Lines changed: 50 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -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

1930
After every action, verify once and pass its `diffId` to assert. For example, with an
2031
MCP client exposing `callTool`:
@@ -64,21 +75,26 @@ the daemon can return `ok: true` with `meta.assert.pass: false`. MCP exposes tha
6475
verdict as `structuredContent.pass: false` and sets `isError: true`, retaining the
6576
checks 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

84100
Codex 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
112128
from 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

149165
Any 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
153170
import subprocess
154171
out = 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

159176
Verbs, 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

163180
The daemon's loopback HTTP control plane (`/cmd`, HMAC-authenticated envelopes) is what
164181
the 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

Comments
 (0)