diff --git a/README.md b/README.md index 0fbe3d7..3e8d060 100644 --- a/README.md +++ b/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. diff --git a/mcp/AGENT_SETUP.md b/mcp/AGENT_SETUP.md new file mode 100644 index 0000000..ecd3085 --- /dev/null +++ b/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@#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: +- Model Context Protocol: diff --git a/mcp/README.md b/mcp/README.md index 3c21d46..c8ce91e 100644 --- a/mcp/README.md +++ b/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