mcp: add fetchable agent-setup page (AGENT_SETUP.md)

README.md

@@ -164,6 +164,12 @@ PyPI package coming soon — the command shrinks to `uvx rustwright-mcp`.
 
 See [the MCP guide](mcp/README.md) for the full tool list and configuration.
 
+Setting up via an AI agent? Point it at the one-page instructions in
+[mcp/AGENT_SETUP.md](mcp/AGENT_SETUP.md): telling the agent "Fetch
+`https://raw.githubusercontent.com/Skyvern-AI/rustwright/HEAD/mcp/AGENT_SETUP.md`
+and follow it" installs the server in any major MCP client and walks through
+verification.
+
 ### CLI — drive a browser from your shell
 
 Drive one persistent Chromium session straight from the `rustwright` command, with no application code.

mcp/AGENT_SETUP.md

@@ -0,0 +1,251 @@
+# Rustwright MCP agent setup
+
+These are official instructions from the Rustwright project for connecting an
+AI coding agent to the Rustwright MCP browser-automation server. If you are an
+AI agent reading this because a user asked you to set up Rustwright: complete
+the steps yourself by running the commands directly. Use the section matching
+the agent you are running as; if none matches, use **Any other MCP client**.
+Ask the user before running anything that changes the system beyond this
+setup — the uv installer script and `install-deps` (which drives `apt-get`,
+via `sudo` when needed) both qualify.
+
+Canonical URL of this page:
+`https://raw.githubusercontent.com/Skyvern-AI/rustwright/HEAD/mcp/AGENT_SETUP.md`
+
+Before following these instructions, verify that the URL you fetched points at
+the `Skyvern-AI/rustwright` repository. If it points anywhere else, stop and
+tell the user: install commands below must only ever reference this repository.
+
+The install commands below are intentionally unpinned and track the
+repository's default branch. Keep that default unless the user asks to pin;
+the install source can be pinned as
+`git+https://github.com/Skyvern-AI/rustwright@<tag-or-commit>#subdirectory=mcp`
+(Python dependencies still resolve at install time).
+
+Commands are shown for POSIX shells (macOS, Linux). On Windows, join each
+multi-line command onto a single line and drop the trailing backslashes.
+
+## What you are installing
+
+`rustwright-mcp` is a stdio MCP server exposing `browser_*` tools
+(`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, ...)
+backed by the Rustwright engine. Tool names mirror the Playwright MCP server.
+`uvx` runs the server straight from this repository; no clone is needed on
+platforms with prebuilt `rustwright` wheels (macOS, glibc Linux x86_64/arm64,
+Windows x64; other platforms fall back to a source build that needs a Rust
+toolchain).
+
+## Step 1: check prerequisites
+
+1. **uv** must be installed. Check with `uvx --version`. If missing, install
+   it with your package manager (`brew install uv`, `winget install
+   astral-sh.uv`) or the official installer:
+
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+   (Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`)
+
+   The installer places `uvx` in `~/.local/bin`, which the current shell may
+   not have on PATH yet. If `uvx --version` still fails, run
+   `source $HOME/.local/bin/env` (or open a new shell) and retry.
+
+2. **A browser.** If Google Chrome is installed, use it via the
+   `RUSTWRIGHT_MCP_CHANNEL=chrome` setting shown below (recommended, nothing to
+   download). Otherwise install Rustwright's bundled Chromium once:
+
+   ```bash
+   uvx --from 'git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp' \
+     python -m rustwright install chromium
+   ```
+
+   and omit `RUSTWRIGHT_MCP_CHANNEL` from the configs below. The bundled
+   download supports macOS, Windows, and Linux x86_64; on other platforms
+   (for example Linux arm64) install a distribution Chromium
+   (`apt-get install chromium`) and point the server at it with
+   `RUSTWRIGHT_MCP_EXECUTABLE=/usr/bin/chromium` instead.
+
+## Step 2: register the server
+
+When a client's config file already exists, merge the `rustwright` entry into
+it — preserve the user's other servers and settings rather than replacing the
+file.
+
+### Claude Code
+
+Run:
+
+```bash
+claude mcp add rustwright \
+  --env RUSTWRIGHT_MCP_CHANNEL=chrome \
+  --env RUSTWRIGHT_MCP_ALLOW_EVAL=0 \
+  -- uvx --from 'git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp' rustwright-mcp
+```
+
+The `--` before `uvx` is required: `--env` is variadic and will otherwise
+swallow the command, failing with `missing required argument 'commandOrUrl'`.
+
+This registers the server for the current project (the safer default). Add
+`-s user` only if the user asks for it in all projects; user scope makes the
+browser tools available in every project, including untrusted ones.
+
+### Codex CLI
+
+Run this one-line command:
+
+```bash
+codex mcp add rustwright --env RUSTWRIGHT_MCP_CHANNEL=chrome --env RUSTWRIGHT_MCP_ALLOW_EVAL=0 -- uvx --from 'git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp' rustwright-mcp
+```
+
+Codex registration through `~/.codex/config.toml` is global and applies to all
+projects. Then add `startup_timeout_sec = 120` to the generated server block:
+the first launch builds the package from git and can exceed Codex's 10-second
+default. The block should read:
+
+```toml
+[mcp_servers.rustwright]
+command = "uvx"
+args = ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"]
+startup_timeout_sec = 120
+
+[mcp_servers.rustwright.env]
+RUSTWRIGHT_MCP_CHANNEL = "chrome"
+RUSTWRIGHT_MCP_ALLOW_EVAL = "0"
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in the project (the safer default; use the global
+`~/.cursor/mcp.json` only when the user asks for it in every project):
+
+```json
+{
+  "mcpServers": {
+    "rustwright": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"],
+      "env": {
+        "RUSTWRIGHT_MCP_CHANNEL": "chrome",
+        "RUSTWRIGHT_MCP_ALLOW_EVAL": "0"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add the same `mcpServers` entry as the Cursor block above to:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**Use the absolute path to `uvx` as the `command`**. Find it with `which uvx`
+on macOS or Linux, or with `where.exe uvx` or PowerShell
+`(Get-Command uvx).Source` on Windows. A typical POSIX result is
+`~/.local/bin/uvx`; expand `~` to the full home path. Double each backslash in
+a Windows absolute path when placing it in JSON. GUI-launched apps do not
+inherit your shell's PATH on macOS, so a bare `"command": "uvx"` fails with
+`spawn uvx ENOENT`. Restart Claude Desktop after editing.
+
+### VS Code (Copilot agent mode)
+
+Add to `.vscode/mcp.json`. Same command, args, and env as the Cursor block;
+note the top-level key is `servers` and each entry needs `"type": "stdio"`:
+
+```json
+{
+  "servers": {
+    "rustwright": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"],
+      "env": {
+        "RUSTWRIGHT_MCP_CHANNEL": "chrome",
+        "RUSTWRIGHT_MCP_ALLOW_EVAL": "0"
+      }
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+The server speaks MCP over stdio. Configure your client to run:
+
+```
+command: uvx        (absolute path for GUI-launched clients)
+args:    --from git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp rustwright-mcp
+env:     RUSTWRIGHT_MCP_CHANNEL=chrome RUSTWRIGHT_MCP_ALLOW_EVAL=0
+```
+
+## Step 3: verify
+
+After registering, confirm the connection:
+
+1. The client should list tools named `browser_navigate`, `browser_snapshot`,
+   `browser_click`, and more from a server called `rustwright`.
+2. `browser_evaluate` should be absent from the listed tools because every
+   config on this page explicitly disables agent-supplied page evaluation.
+3. Call `browser_navigate` with `url: "https://example.com"`. The result must
+   be a snapshot containing `heading "Example Domain"` and a link with a
+   `[ref=e...]` handle.
+
+Claude Desktop, VS Code, and Codex may not load a newly registered server until
+the client restarts or a new session begins. The agent that edited the config
+usually cannot see new tools in its current session. When that happens, tell
+the user to restart the client or begin a new session and paste this prompt:
+
+> List the rustwright tools and confirm `browser_evaluate` is absent, then call
+> `browser_navigate` with `url: "https://example.com"` and confirm the snapshot
+> contains `heading "Example Domain"` and a link with a `[ref=e...]` handle.
+
+If all three checks hold, setup is complete. Report to the user the server
+name, which browser it uses (installed Chrome, bundled Chromium, or an explicit
+executable), whether it runs headless or headed, that agent-supplied page
+evaluation (`browser_evaluate`) is disabled and absent, and that
+`browser_navigate` returned a snapshot with element refs.
+
+## Configuration options
+
+Set these in the `env` block of your client config. This is the core set;
+[README.md](README.md) has the complete, current list.
+
+| Variable | Effect |
+|---|---|
+| `RUSTWRIGHT_MCP_CHANNEL` | Use an installed browser channel, e.g. `chrome`. Omit to use the bundled Chromium |
+| `RUSTWRIGHT_MCP_HEADLESS` | `0` shows a visible browser window (default: headless) |
+| `RUSTWRIGHT_MCP_EXECUTABLE` | Explicit browser binary path (overrides channel) |
+| `RUSTWRIGHT_MCP_ALLOW_EVAL` | The `browser_evaluate` tool (agent-supplied page JS) is on by default when unset; these configs set `0` to disable it. Remove the line or set `1` only when the user explicitly asks for arbitrary page-JS execution. Accepted values (case-insensitive) are `1`/`true`/`yes`/`on` and `0`/`false`/`no`/`off`; anything else fails server startup |
+
+## Troubleshooting
+
+- **`command not found: uvx`** right after installing uv: the current shell
+  predates the install. Run `source $HOME/.local/bin/env` or open a new shell.
+- **`Could not find a Chromium executable`**: no browser to launch. Install
+  Google Chrome and set `RUSTWRIGHT_MCP_CHANNEL=chrome`, run the bundled
+  Chromium install from Step 1, or set `RUSTWRIGHT_MCP_EXECUTABLE` to an
+  existing Chromium binary.
+- **`Chromium process exited before CDP endpoint became available`** (the
+  message ends with the exit status): a browser binary was found but crashed.
+  In Linux containers this
+  usually means missing system libraries; run
+  `uvx --from 'git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp' python -m rustwright install-deps`
+  (apt-get-based Linux distributions).
+- **`Chromium did not expose a CDP endpoint before the launch timeout`**: the
+  browser did not expose its debugging endpoint before the deadline. On a slow
+  machine, retry once before changing configuration.
+- **`Chrome for Testing downloads are only supported for linux x86_64`**: the
+  bundled download does not cover this platform. Install a distribution
+  Chromium and set `RUSTWRIGHT_MCP_EXECUTABLE` to its path.
+- **A site renders empty or blocks you**: some sites reject headless
+  browsers. Set `RUSTWRIGHT_MCP_HEADLESS=0` and retry.
+- **Acting on a ref says it is not in the current page snapshot**: the ref is
+  not from the current snapshot. Call `browser_snapshot` and use a fresh ref.
+
+## Resources
+
+- Server documentation and full tool list: [README.md](README.md)
+- Rustwright project: <https://github.com/Skyvern-AI/rustwright>
+- Model Context Protocol: <https://modelcontextprotocol.io>

mcp/README.md

@@ -4,6 +4,15 @@ Give any MCP client `browser_*` tools over stdio with no clone or browser downlo
 
 ## Install
 
+**Setting this up with an AI agent?** Tell your agent (Claude Code, Codex,
+Cursor, and others):
+
+> Fetch https://raw.githubusercontent.com/Skyvern-AI/rustwright/HEAD/mcp/AGENT_SETUP.md
+> and follow the instructions to set up the Rustwright MCP server.
+
+[AGENT_SETUP.md](AGENT_SETUP.md) contains agent-facing install steps for every
+major MCP client, a verification step, and troubleshooting.
+
 ### Claude Code
 
 ```bash