From 7f1bedc7ff2efef9b078b2bf827cb33b7e501dd4 Mon Sep 17 00:00:00 2001 From: Sujith PS Date: Sat, 18 Jul 2026 23:53:48 +0530 Subject: [PATCH 1/4] mcp: add fetchable agent-setup page (AGENT_SETUP.md) One-page, agent-facing install instructions in the style of developers.cloudflare.com/agent-setup/prompt.md: a user tells their agent to fetch the raw URL and follow it. Covers prerequisites, per-client registration (Claude Code, Codex, Cursor, Claude Desktop, VS Code, generic stdio), a verification step with expected output, env configuration, and troubleshooting for the known failure modes. Linked from mcp/README.md and the root README agent section. --- README.md | 5 ++ mcp/AGENT_SETUP.md | 173 +++++++++++++++++++++++++++++++++++++++++++++ mcp/README.md | 9 +++ 3 files changed, 187 insertions(+) create mode 100644 mcp/AGENT_SETUP.md diff --git a/README.md b/README.md index 5a5a044..4dbfd55 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,11 @@ Key environment variables: `RUSTWRIGHT_MCP_HEADLESS` (`0` runs headed), `RUSTWRIGHT_MCP_ALLOW_EVAL` (`1` exposes the `browser_evaluate` tool, off by default). Full setup, tool list, and configuration: [mcp/README.md](mcp/README.md). +Setting up via an AI agent? Point it at the one-page instructions: +[mcp/AGENT_SETUP.md](mcp/AGENT_SETUP.md) — "Fetch +`https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/mcp/AGENT_SETUP.md` +and follow it" installs and verifies the server in any major MCP client. + ## Remote browsers (Skyvern) Rustwright drives browsers — but you still need somewhere to run them. Skyvern (the team behind Rustwright) offers hosted **[Browser Sessions](https://www.skyvern.com/docs/developers/features/browser-sessions)** as a paid service that funds this project. diff --git a/mcp/AGENT_SETUP.md b/mcp/AGENT_SETUP.md new file mode 100644 index 0000000..0ca1ea1 --- /dev/null +++ b/mcp/AGENT_SETUP.md @@ -0,0 +1,173 @@ +# 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**. + +Canonical URL of this page: +`https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/mcp/AGENT_SETUP.md` + +## 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, a Rust CDP reimplementation of Playwright. +Tool names mirror the Playwright MCP server. Snapshots are accessibility-style +outlines where interactive elements carry `[ref=eN]` handles; pass a ref (or a +CSS selector) to the action tools. No clone or build is needed: `uvx` runs the +server straight from this repository. + +## Step 1: check prerequisites + +1. **uv** must be installed. Check with `uvx --version`. If missing, install it: + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + + (Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`) + +2. **A Chromium-based 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. + +## Step 2: register the server + +### Claude Code + +Run: + +```bash +claude mcp add rustwright \ + --env RUSTWRIGHT_MCP_CHANNEL=chrome \ + -- 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'`. +Add `-s user` to register for all projects instead of the current one. + +### Codex CLI + +Add to `~/.codex/config.toml`: + +```toml +[mcp_servers.rustwright] +command = "uvx" +args = ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"] + +[mcp_servers.rustwright.env] +RUSTWRIGHT_MCP_CHANNEL = "chrome" +``` + +### Cursor + +Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): + +```json +{ + "mcpServers": { + "rustwright": { + "command": "uvx", + "args": ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"], + "env": { "RUSTWRIGHT_MCP_CHANNEL": "chrome" } + } + } +} +``` + +### 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` + +Then restart Claude Desktop. + +### VS Code (Copilot agent mode) + +Add to `.vscode/mcp.json`: + +```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" } + } + } +} +``` + +### Any other MCP client + +The server speaks MCP over stdio. Configure your client to run: + +``` +command: uvx +args: --from git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp rustwright-mcp +env: RUSTWRIGHT_MCP_CHANNEL=chrome +``` + +## Step 3: verify + +After registering (restart the client if it does not hot-reload MCP config), +confirm the connection: + +1. The client should list tools named `browser_navigate`, `browser_snapshot`, + `browser_click`, and more from a server called `rustwright`. +2. 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. + +If both hold, setup is complete. Report to the user: + +``` +Rustwright MCP setup complete +- server: rustwright (stdio via uvx) +- browser: , headless +- verified: browser_navigate returned a snapshot with element refs +``` + +## Configuration options + +Set these in the `env` block of your client config: + +| 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` | `1` exposes `browser_evaluate` (arbitrary page JS; off by default) | + +## Troubleshooting + +- **`missing required argument 'commandOrUrl'`** (Claude Code): you omitted + the `--` separator before `uvx`. Re-run the exact command from Step 2. +- **`Failed to launch chromium: Chromium did not expose a CDP endpoint`**: + no usable browser. Either install Google Chrome and keep + `RUSTWRIGHT_MCP_CHANNEL=chrome`, or run the bundled-Chromium install from + Step 1 and remove the channel variable. On very slow machines the 30-second + launch timeout itself can be the cause; retry once before changing config. +- **A site renders empty or blocks you**: some sites reject headless browsers. + Set `RUSTWRIGHT_MCP_HEADLESS=0` and retry. +- **Acting on a ref fails with a stale-snapshot error**: the page changed + since the last snapshot. Call `browser_snapshot` and use a fresh ref. + +## Resources + +- Server documentation and full tool list: [mcp/README.md](README.md) +- Rustwright project: +- Model Context Protocol: diff --git a/mcp/README.md b/mcp/README.md index ad903cc..cdf56d3 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -10,6 +10,15 @@ re-learning the surface. `browser_snapshot` returns an accessibility-style outline where interactive elements carry `[ref=eN]` handles; pass a ref (or a raw CSS selector) to the action tools. +**Setting this up with an AI agent?** Tell your agent (Claude Code, Codex, +Cursor, and others): + +> Fetch https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/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. + ## Quick start (no clone needed) With [uv](https://docs.astral.sh/uv/) installed, register the server with From a3f61263835581693b5509fec931bb8f78435959 Mon Sep 17 00:00:00 2001 From: Sujith PS Date: Sun, 19 Jul 2026 11:42:36 +0530 Subject: [PATCH 2/4] =?UTF-8?q?mcp:=20agent-setup=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20platform=20coverage,=20error=20mapping,=20URL=20har?= =?UTF-8?q?dening?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Claude Desktop: require absolute uvx path (GUI apps miss the shell PATH, bare 'uvx' fails with spawn ENOENT) - Troubleshooting: map errors to their real causes; 'Could not find a Chromium executable' vs 'did not expose a CDP endpoint' (missing system libs in containers; document install-deps), and add the Linux arm64 bundled-download limit with the RUSTWRIGHT_MCP_EXECUTABLE escape hatch - Windows: -ExecutionPolicy ByPass on the uv installer, note that multi-line commands are POSIX-shell, add winget/brew alternatives - uv PATH: tell agents to source ~/.local/bin/env when uvx is not found right after install - Codex: startup_timeout_sec=120 (cold uvx git build exceeds the 10s default) - ALLOW_EVAL: correct accepted values (1/true/yes) and add leave-unset guidance for autonomous readers - Preamble: verify the fetched URL points at Skyvern-AI/rustwright before running anything - Raw URLs use /HEAD/ instead of /main/ (survives default-branch rename) - Local-browser prerequisite and config table no longer claim completeness (stays correct when remote CDP attach lands) - Completion report is descriptive, not a hardcoded 'headless' template --- README.md | 6 +-- mcp/AGENT_SETUP.md | 101 +++++++++++++++++++++++++++++---------------- mcp/README.md | 2 +- 3 files changed, 70 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 4dbfd55..7bbe6ae 100644 --- a/README.md +++ b/README.md @@ -153,9 +153,9 @@ Key environment variables: `RUSTWRIGHT_MCP_HEADLESS` (`0` runs headed), `RUSTWRIGHT_MCP_ALLOW_EVAL` (`1` exposes the `browser_evaluate` tool, off by default). Full setup, tool list, and configuration: [mcp/README.md](mcp/README.md). -Setting up via an AI agent? Point it at the one-page instructions: -[mcp/AGENT_SETUP.md](mcp/AGENT_SETUP.md) — "Fetch -`https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/mcp/AGENT_SETUP.md` +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 and verifies the server in any major MCP client. ## Remote browsers (Skyvern) diff --git a/mcp/AGENT_SETUP.md b/mcp/AGENT_SETUP.md index 0ca1ea1..0bebef6 100644 --- a/mcp/AGENT_SETUP.md +++ b/mcp/AGENT_SETUP.md @@ -7,29 +7,42 @@ 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**. Canonical URL of this page: -`https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/mcp/AGENT_SETUP.md` +`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. + +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, a Rust CDP reimplementation of Playwright. -Tool names mirror the Playwright MCP server. Snapshots are accessibility-style -outlines where interactive elements carry `[ref=eN]` handles; pass a ref (or a -CSS selector) to the action tools. No clone or build is needed: `uvx` runs the -server straight from this repository. +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: +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 -c "irm https://astral.sh/uv/install.ps1 | iex"`) + (Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`) -2. **A Chromium-based browser.** If Google Chrome is installed, use it via the + 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: @@ -38,7 +51,11 @@ server straight from this repository. python -m rustwright install chromium ``` - and omit `RUSTWRIGHT_MCP_CHANNEL` from the configs below. + 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 @@ -54,16 +71,21 @@ claude mcp add rustwright \ The `--` before `uvx` is required: `--env` is variadic and will otherwise swallow the command, failing with `missing required argument 'commandOrUrl'`. -Add `-s user` to register for all projects instead of the current one. + +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 -Add to `~/.codex/config.toml`: +Add to `~/.codex/config.toml`. The `startup_timeout_sec` matters: the first +launch builds the package from git and can exceed Codex's 10-second default. ```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" @@ -92,11 +114,15 @@ 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` -Then restart Claude Desktop. +**Use the absolute path to `uvx` as the `command`** (find it with `which uvx`; +typically `~/.local/bin/uvx` expanded to the full home path). 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`: +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 { @@ -116,7 +142,7 @@ Add to `.vscode/mcp.json`: The server speaks MCP over stdio. Configure your client to run: ``` -command: uvx +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 ``` @@ -132,42 +158,47 @@ confirm the connection: be a snapshot containing `heading "Example Domain"` and a link with a `[ref=e...]` handle. -If both hold, setup is complete. Report to the user: - -``` -Rustwright MCP setup complete -- server: rustwright (stdio via uvx) -- browser: , headless -- verified: browser_navigate returned a snapshot with element refs -``` +If both 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, and that `browser_navigate` +returned a snapshot with element refs. ## Configuration options -Set these in the `env` block of your client config: +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` | `1` exposes `browser_evaluate` (arbitrary page JS; off by default) | +| `RUSTWRIGHT_MCP_ALLOW_EVAL` | `1`, `true`, or `yes` exposes `browser_evaluate` (arbitrary page JS). Leave unset unless the user explicitly asks for it | ## Troubleshooting -- **`missing required argument 'commandOrUrl'`** (Claude Code): you omitted - the `--` separator before `uvx`. Re-run the exact command from Step 2. -- **`Failed to launch chromium: Chromium did not expose a CDP endpoint`**: - no usable browser. Either install Google Chrome and keep - `RUSTWRIGHT_MCP_CHANNEL=chrome`, or run the bundled-Chromium install from - Step 1 and remove the channel variable. On very slow machines the 30-second - launch timeout itself can be the cause; retry once before changing config. -- **A site renders empty or blocks you**: some sites reject headless browsers. - Set `RUSTWRIGHT_MCP_HEADLESS=0` and retry. +- **`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 did not expose a CDP endpoint before the launch timeout`**: a + browser binary was found but failed to start. 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-based distributions). On a slow machine the launch can simply time + out; 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 fails with a stale-snapshot error**: the page changed since the last snapshot. Call `browser_snapshot` and use a fresh ref. ## Resources -- Server documentation and full tool list: [mcp/README.md](README.md) +- Server documentation and full tool list: [README.md](README.md) - Rustwright project: - Model Context Protocol: diff --git a/mcp/README.md b/mcp/README.md index cdf56d3..32b3530 100644 --- a/mcp/README.md +++ b/mcp/README.md @@ -13,7 +13,7 @@ raw CSS selector) to the action tools. **Setting this up with an AI agent?** Tell your agent (Claude Code, Codex, Cursor, and others): -> Fetch https://raw.githubusercontent.com/Skyvern-AI/rustwright/main/mcp/AGENT_SETUP.md +> 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 From 3a14768908b0d579887b1d1ef62be11062ef0bc6 Mon Sep 17 00:00:00 2001 From: suchintan <3853670+suchintan@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:30:22 -0400 Subject: [PATCH 3/4] =?UTF-8?q?mcp:=20agent-setup=20review=20fixes=20?= =?UTF-8?q?=E2=80=94=20eval-off=20configs,=20restart=20handoff,=20Windows?= =?UTF-8?q?=20paths?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Ship RUSTWRIGHT_MCP_ALLOW_EVAL=0 in every registration config and correct the configuration table: page-world evaluation is on by default when unset (the previous wording implied the opposite); verify browser_evaluate is absent in Step 3 and report eval status to the user - Codex CLI: register via 'codex mcp add' (verified flags), note config.toml is global scope, keep startup_timeout_sec block - Troubleshooting: split Chromium launch failures into process-exited (missing libraries -> install-deps) and launch-timeout (slow machine) cases to match the actual error strings; align stale-ref wording with the server message - Step 3: restart handoff with a paste-ready verification prompt for clients that load MCP servers only on restart - Claude Desktop: Windows equivalents for locating uvx and JSON backslash escaping; note that install sources are unpinned with a pin syntax for reproducible installs - README: move the agent-setup pointer from the CLI section into the MCP server section (merge artifact) Co-Authored-By: Claude Fable 5 --- README.md | 10 +++--- mcp/AGENT_SETUP.md | 83 +++++++++++++++++++++++++++++++++------------- 2 files changed, 65 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 43d970e..14f695f 100644 --- a/README.md +++ b/README.md @@ -164,6 +164,11 @@ 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 and verifies the server in any major MCP client. + ### CLI — drive a browser from your shell Drive one persistent Chromium session straight from the `rustwright` command, with no application code. @@ -186,11 +191,6 @@ rustwright close See [the agent interface guide](docs/agent-interfaces.md) for every verb, flag, and security detail. -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 and verifies the server in any major MCP client. - ## Remote browsers (Skyvern) Rustwright drives browsers — but you still need somewhere to run them. Skyvern (the team behind Rustwright) offers hosted **[Browser Sessions](https://www.skyvern.com/docs/developers/features/browser-sessions)** as a paid service that funds this project. diff --git a/mcp/AGENT_SETUP.md b/mcp/AGENT_SETUP.md index 0bebef6..771148b 100644 --- a/mcp/AGENT_SETUP.md +++ b/mcp/AGENT_SETUP.md @@ -13,6 +13,11 @@ 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 wants a +reproducible install; they can pin the source as +`git+https://github.com/Skyvern-AI/rustwright@#subdirectory=mcp`. + Commands are shown for POSIX shells (macOS, Linux). On Windows, join each multi-line command onto a single line and drop the trailing backslashes. @@ -66,6 +71,7 @@ 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 ``` @@ -78,8 +84,16 @@ browser tools available in every project, including untrusted ones. ### Codex CLI -Add to `~/.codex/config.toml`. The `startup_timeout_sec` matters: the first -launch builds the package from git and can exceed Codex's 10-second default. +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] @@ -89,6 +103,7 @@ startup_timeout_sec = 120 [mcp_servers.rustwright.env] RUSTWRIGHT_MCP_CHANNEL = "chrome" +RUSTWRIGHT_MCP_ALLOW_EVAL = "0" ``` ### Cursor @@ -101,7 +116,10 @@ Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): "rustwright": { "command": "uvx", "args": ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"], - "env": { "RUSTWRIGHT_MCP_CHANNEL": "chrome" } + "env": { + "RUSTWRIGHT_MCP_CHANNEL": "chrome", + "RUSTWRIGHT_MCP_ALLOW_EVAL": "0" + } } } } @@ -114,10 +132,13 @@ 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`; -typically `~/.local/bin/uvx` expanded to the full home path). 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. +**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) @@ -131,7 +152,10 @@ note the top-level key is `servers` and each entry needs `"type": "stdio"`: "type": "stdio", "command": "uvx", "args": ["--from", "git+https://github.com/Skyvern-AI/rustwright#subdirectory=mcp", "rustwright-mcp"], - "env": { "RUSTWRIGHT_MCP_CHANNEL": "chrome" } + "env": { + "RUSTWRIGHT_MCP_CHANNEL": "chrome", + "RUSTWRIGHT_MCP_ALLOW_EVAL": "0" + } } } } @@ -144,24 +168,35 @@ 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 +env: RUSTWRIGHT_MCP_CHANNEL=chrome RUSTWRIGHT_MCP_ALLOW_EVAL=0 ``` ## Step 3: verify -After registering (restart the client if it does not hot-reload MCP config), -confirm the connection: +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. Call `browser_navigate` with `url: "https://example.com"`. The result must +2. `browser_evaluate` should be absent from the listed tools because every + config on this page explicitly disables page-world 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. -If both 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, and that `browser_navigate` -returned a snapshot with element refs. +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 page-world evaluation is +disabled and `browser_evaluate` is absent, and that `browser_navigate` returned +a snapshot with element refs. ## Configuration options @@ -173,7 +208,7 @@ Set these in the `env` block of your client config. This is the core set; | `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` | `1`, `true`, or `yes` exposes `browser_evaluate` (arbitrary page JS). Leave unset unless the user explicitly asks for it | +| `RUSTWRIGHT_MCP_ALLOW_EVAL` | Page-world evaluation 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 are `1`/`true`/`yes`/`on` and `0`/`false`/`no`/`off`; any other value fails server startup | ## Troubleshooting @@ -183,19 +218,21 @@ Set these in the `env` block of your client config. This is the core set; 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 did not expose a CDP endpoint before the launch timeout`**: a - browser binary was found but failed to start. In Linux containers this +- **`Chromium process exited before CDP endpoint became available (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-based distributions). On a slow machine the launch can simply time - out; retry once before changing configuration. + (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 fails with a stale-snapshot error**: the page changed - since the last snapshot. Call `browser_snapshot` and use a fresh ref. +- **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 From 664b4e8ff87f043269feeb371f4b67bdc351ea17 Mon Sep 17 00:00:00 2001 From: suchintan <3853670+suchintan@users.noreply.github.com> Date: Tue, 21 Jul 2026 12:45:02 -0400 Subject: [PATCH 4/4] =?UTF-8?q?mcp:=20agent-setup=20round-2=20fixes=20?= =?UTF-8?q?=E2=80=94=20precise=20eval=20wording,=20config-merge=20and=20sy?= =?UTF-8?q?stem-change=20guardrails?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopted from a second review round (security + factual lenses): - Quote only the invariant part of the process-exited launch error so agents can match it verbatim (the emitted string embeds a real exit status) - ALLOW_EVAL row: name the browser_evaluate tool rather than page-world evaluation broadly (the server still runs its own internal page scripts), note values are case-insensitive - Ask the user before the uv installer script or install-deps (apt-get/sudo) - Merge the rustwright entry into existing client configs instead of replacing files; Cursor gets the same project-scope-first guidance as the other clients - Pin note no longer claims full reproducibility (deps still resolve at install time); README claim softened to installs + walks through verification Co-Authored-By: Claude Fable 5 --- README.md | 3 ++- mcp/AGENT_SETUP.md | 32 +++++++++++++++++++++----------- 2 files changed, 23 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 14f695f..3e8d060 100644 --- a/README.md +++ b/README.md @@ -167,7 +167,8 @@ 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 and verifies the server in any major MCP client. +and follow it" installs the server in any major MCP client and walks through +verification. ### CLI — drive a browser from your shell diff --git a/mcp/AGENT_SETUP.md b/mcp/AGENT_SETUP.md index 771148b..ecd3085 100644 --- a/mcp/AGENT_SETUP.md +++ b/mcp/AGENT_SETUP.md @@ -5,6 +5,9 @@ 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` @@ -14,9 +17,10 @@ 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 wants a -reproducible install; they can pin the source as -`git+https://github.com/Skyvern-AI/rustwright@#subdirectory=mcp`. +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@#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. @@ -64,6 +68,10 @@ toolchain). ## 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: @@ -108,7 +116,8 @@ RUSTWRIGHT_MCP_ALLOW_EVAL = "0" ### Cursor -Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): +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 { @@ -178,7 +187,7 @@ 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 page-world evaluation. + 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. @@ -194,9 +203,9 @@ the user to restart the client or begin a new session and paste this prompt: 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 page-world evaluation is -disabled and `browser_evaluate` is absent, and that `browser_navigate` returned -a snapshot with element refs. +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 @@ -208,7 +217,7 @@ Set these in the `env` block of your client config. This is the core set; | `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` | Page-world evaluation 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 are `1`/`true`/`yes`/`on` and `0`/`false`/`no`/`off`; any other value fails server startup | +| `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 @@ -218,8 +227,9 @@ Set these in the `env` block of your client config. This is the core set; 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 (status: - ...)`**: a browser binary was found but crashed. In Linux containers this +- **`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).