e2e 0.15.1 → 0.16.0

package/docs/reference/mcp.mdx

@@ -0,0 +1,205 @@
+---
+title: MCP server (e2e mcp)
+description: Let a coding agent inspect and interact with your app over MCP.
+---
+
+<CodeGroup>
+```bash npm
+npx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+```
+
+```bash pnpm
+pnpm exec e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+```
+
+```bash bun
+bunx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+```
+</CodeGroup>
+
+`e2e mcp` lets coding agents such as Claude Code and Cursor inspect your app,
+try locators, and take masked screenshots before writing tests. It runs over
+stdio and uses the project's configured engine.
+
+Four MCP tools manage the session and call its available app tools. The app
+tool catalog reloads from the config whenever a session opens.
+
+## Setup
+
+The server ships with `e2e`. `e2e init` offers to register it in
+`.mcp.json` (Claude Code) and `.cursor/mcp.json` (Cursor). By hand:
+
+<CodeGroup>
+```bash npm
+claude mcp add e2e -- npx e2e mcp
+```
+
+```bash pnpm
+claude mcp add e2e -- pnpm exec e2e mcp
+```
+
+```bash bun
+claude mcp add e2e -- bunx e2e mcp
+```
+</CodeGroup>
+
+For clients that use a `mcpServers` config, add:
+
+```json
+{
+  "mcpServers": {
+    "e2e": { "command": "npx", "args": ["e2e", "mcp"] }
+  }
+}
+```
+
+The server needs no model: a project without the optional `ai` package
+opens sessions and drives the app with the deterministic tools.
+
+Start the server in the project directory. Config discovery works like
+`e2e run`. Set `--config` for another location, or pass `config` to
+`open_session` for one session.
+
+| Flag | Behavior |
+| --- | --- |
+| `--config <path>` | The config every session loads unless `open_session` names one. Configs are reloaded on every `open_session`, with every file they import by path. |
+| `--target <name>` | The target every session opens on. Otherwise `open_session` names one, or the only target is used; several targets and no name is `TARGET_REQUIRED`. |
+| `--headless` | Hide the browser or simulator. Sessions are headed by default outside CI. |
+| `--max-sessions <n>` | How many sessions may be open at once, 1 through 16; default 4. Each session is its own browser or device. |
+
+Operator output goes to stderr, prefixed `e2e mcp:`. Stdout carries only the
+protocol; anything a config module writes to stdout is redirected.
+
+## Tools
+
+| Tool | Arguments | Result |
+| --- | --- | --- |
+| `open_session` | `target` (optional), `config` (optional path) | Loads the config, starts the target's app command, boots the engine, starts one attempt, opens the app URL when the engine can navigate. Returns the session id, the catalog, and the first observation. |
+| `tools` | `tool` (optional), `session` (required while several are open) | The catalog, one line per tool. With `tool`, its full description and argument schema. |
+| `call` | `tool`, `args` (optional), `session` (required while several are open) | Runs one catalog tool. Arguments are validated against the tool's closed schema first: a wrong type or an argument the tool does not declare is `INVALID_ARGUMENT`, and nothing runs. An action that fails is an error result that still carries the screen it re-observed, and leads with the tool, its target, and the code: `navigate file:///etc/passwd failed: POLICY_DENIED: forbidden URL scheme: file:`. |
+| `close_session` | `session` (required while several are open) | Saves a recording still running, ends the attempt, disposes the engine, stops the app processes the session started once no other session uses them. |
+
+## Several sessions
+
+Several sessions can be open at once, up to `--max-sessions`, each on its
+own attempt and its own browser or device. Parallel agents, such as a
+coding agent's subagents, share one server this way: each opens a session
+and passes its id to every `tools`, `call`, and `close_session`.
+
+- `session` may be left out only while exactly one session is open. With
+  several open, a call without it fails with `SESSION_REQUIRED` and the
+  list of open sessions.
+- A `session` id that is not open fails with `NO_SESSION`; for a session
+  that is closing or ended, the message says why.
+- An `open_session` past the limit fails with `SESSION_OPEN`. A session
+  holds its slot from `open_session` until its attempt has closed, so
+  sessions still booting or still closing count toward it.
+- Sessions open at once share one config: credentials and secrets resolve
+  through one registry per process. An `open_session` on another config
+  fails with `CONFIG_IN_USE` until the others close.
+- While the server shuts down it cancels sessions still opening and waits
+  for them, closes every session, and refuses new ones with `SESSION_OPEN`.
+  A client that cancels an `open_session`, or disconnects, cancels it too.
+  A cancelled open fails with `CANCELLED` once what it started (an app command
+  still waiting on its `readyUrl`, say) has stopped.
+- Each session loads the config afresh, down to the files it imports by
+  path, such as a base config it spreads, so each gets engine instances of
+  its own. An engine created inside a package is one instance every session
+  shares, and a second session on it fails with `ENGINE_IN_USE`.
+- Sessions on one app command share its process: the first session starts
+  it, and it stops when the last of them closes. A URL declared with port
+  `0` gets its own port in each session, and so its own process. A shared
+  start that every waiting session gave up on is cancelled, and the next
+  session starts it afresh.
+- On mobile, each session needs its own simulator or emulator: declare one
+  target per device, each naming its `device`, and open each session on its
+  own target.
+
+[Bug bashes](/bug-bash) use this: every verifying subagent drives its own
+session.
+
+### The catalog
+
+What `call` can run depends on the session's target:
+
+| Catalog tool | Arguments | Result |
+| --- | --- | --- |
+| `observe` | none | A fresh observation, one node per line as `#id role "name" ...`, with the current path and revision. A link's `href` is its path when it is on the app URL's origin, else origin and path; `mailto:`, `tel:`, and `blob:` targets keep their scheme. `…` marks what is left out: `?…` a query, `#…` a fragment, `data:…` or `javascript:…` an inline payload, a trailing `…` a target cut at 256 characters. |
+| `tap`, `double_tap`, `long_press`, `right_click`, `hover`, `type`, `press`, `select`, `check`, `scroll`, `scroll_to`, `drag`, `upload`, `navigate`, `back`, `type_secret` | A node id from the newest observation, plus the value, key, `checked` state, direction, drop target, project-relative `files`, URL, or secret name | The action's summary and what changed on screen. A verb the engine does not declare is not in the catalog. `upload` refuses a path outside the project, a hidden file, or a file under a hidden directory with `POLICY_DENIED`. `type_secret` is listed when the config declares `credentials` or `secrets`; the plaintext never reaches the agent. |
+| `dismiss_keyboard` | none | Hides the on-screen keyboard. Listed when the engine's keyboard declares `dismiss`, as the device engines do. |
+| `locate` | Exactly one of `role` (with optional `name`), `text`, `label`, `placeholder`, `testId`; `exact` | How many nodes match, which, and the `screen.*` call to write. Zero or several matches name the error a test would get. What it shows of a node passes the secret ledger, as `observe` does: a filled secret reads `<secret:name>`. |
+| `screenshot` | none | The masked viewport as an image. From then on every action result carries a fresh screenshot. Once a secret has been filled it answers `PIXEL_TAINTED` instead, for the rest of the session. |
+| `tap_at` | `x`, `y` in the latest screenshot's pixels | Taps that point: a listed control under it by id, otherwise the bare point through the engine's `performAt`; without `performAt` the point must land on a listed control. Listed when the engine declares `tap` or `performAt`. |
+| `hover_at` | `x`, `y` in the latest screenshot's pixels | Hovers that point the same way: a listed control under it by id, otherwise the bare point through `performAt`'s `hover` kind. Listed when the engine declares the `hover` action or pointer kind. |
+| `type_at` | `x`, `y`, `value`; `replace` on an engine with a keyboard | Fills a listed input under the point by id. With a keyboard, anything else is tapped to focus it and typed into, at the caret unless `replace` is set; without one, a point on nothing listed fails. Listed when the engine declares `type` or a keyboard. |
+| `press_at` | `x`, `y`, `key` | Sends the key to a listed control under the point by id; with a keyboard, anything else is tapped to focus it and the key goes through the keyboard. Listed when the engine declares `press` or a keyboard. |
+| `select_at` | `x`, `y`, `value`, the option's visible label | Picks the option in the listed select-like control under the point; nothing listed there fails. Listed when the engine declares `select`. |
+| `start_recording` | `name` (optional; up to 64 letters, digits, `-`, and `_`, starting with a letter or digit) | Starts a video of the app. One recording at a time; a second start reports the one running. Listed when the engine records video. |
+| `stop_recording` | none | Stops the recording and returns the absolute path of each video file. Listed when the engine records video. |
+
+The five point tools answer `PIXEL_TAINTED` once a secret has been filled.
+Before the session's first `screenshot` each answers with the line that says
+to take one, at no cost.
+
+Project tools in `agents.default.tools` follow in the catalog under
+their own names, scoped to the target's platform. A mobile project that
+passes `mobileTools(...)` also gets `open_app`, `swipe`,
+and `alert`. A project tool named like a built-in fails the config load with `INVALID_CONFIG`. An unknown
+name fails with `UNKNOWN_TOOL` and the list of names.
+
+### Recording
+
+A session records video only between `start_recording` and
+`stop_recording`, as many times as needed; the configured
+[`video`](/reference/config#video) mode applies to runs, not sessions. The
+configured [`trace`](/reference/config#trace) mode does apply: a session is
+one attempt that closes as passed, so it keeps a trace under `on` (the local
+default) and records none under a retry mode (the CI default) or
+`retain-on-failure`. A `trace` the config sets on an engine that cannot
+trace is skipped with a notice in the server log, as a run skips it. Each recording is saved to
+`<output>/videos/<session>/<n>[-<name>].webm` (`.mp4` on mobile, and
+[`output`](/reference/config#output) is `.e2e` by default), where `n`
+counts the session's recordings. A web recording that spans a restart or a
+state reset has one file per page, `-part2`, `-part3`, and so on, in play
+order. A browser or device provider that records the lease itself records
+the session instead: [Kernel](/integrations/kernel) downloads its replay,
+saved here as `<n>[-<name>].mp4` like any other file, and a provider that
+keeps its recordings is listed by URL instead of a file. `close_session`, the idle timeout, and the session
+TTL save a recording still running, and the close result lists its files.
+
+Recordings are not masked and are not withheld after a secret was filled:
+they are files for a person to watch, and no tool returns their pixels. A
+secret typed into a plain input while recording is readable in the video,
+and a recording stopped after a secret was filled says so.
+
+A session is one attempt on one target. A `call` before any session is
+open fails with `NO_SESSION`. A session closes on `close_session`, after 30
+idle minutes, after 4 hours, when the client disconnects, and on SIGINT or
+SIGTERM. The client disconnects when it closes the server's stdin or dies,
+so the pipes break under the server: every session closes, the app commands
+the sessions started stop, and the server exits.
+
+Sessions enforce what tests enforce. Node ids are valid only against the
+newest observation. A secret fills only through `type_secret`; once one has
+been filled, `screenshot` and the point tools (`tap_at`, `hover_at`,
+`type_at`, `press_at`, `select_at`) stay in the catalog but answer
+`PIXEL_TAINTED` for the rest of the session. Every text a `call` returns, a node `locate` found,
+an action's result, or an error, passes the attempt's secret ledger. Nothing a
+session does is recorded as a test result or into the replay cache; its
+artifacts land under `<output>/artifacts/<target>/sessions/`, its videos under
+`<output>/videos/`. A later `e2e run` clears `<output>/artifacts`; the
+videos stay.
+
+## Resources
+
+| URI | Content |
+| --- | --- |
+| `e2e://guide` | The agent skill's overview, the text `e2e guide` prints. |
+| `e2e://guide/{topic}` | One topic: `setup`, `writing-tests`, `agent`, `running`, `explore`, `debugging`, `mcp`, `bug-bash`. |
+
+## Exit codes
+
+`e2e mcp` exits 0 when the client disconnects, with or without a session
+open, or a signal ends it, and 2
+when the command line is invalid. Config and engine failures come back as
+tool errors with the same codes the CLI prints.