io.github.YawLabs/vew-mcp

Go back one entry in the browser history, then return a fresh snapshot of the page you land on. No-op error if there is no previous entry.

Click the interactive element addressed by `ref` (from the most recent snapshot), then return a fresh snapshot of the resulting page. Use this for buttons, links, checkboxes, tabs, menu items.

Evaluate a JavaScript EXPRESSION in the current page's context and return the JSON-serializable result. This is the escape hatch for reading computed state or extracting structured data the snapshot does not surface -- e.g. 'document.title', 'location.href', or '({ count: document.querySelectorAll("a").length })'. Runs in the page sandbox (not the server process). The result must be JSON-serializable; DOM nodes and functions come back empty. Arbitrary JS can also mutate the page, so this is not a read-only call. The call is bounded by timeout_ms and returns an error if the expression has not resolved by then (note: a synchronous infinite loop pins the page's JS thread, so control returns to you but the page may need a re-navigate to fully recover -- prefer terminating expressions).

Set one or more local files on the file input addressed by `ref` (from the most recent snapshot). Paths resolve on the machine running the browser. The ref must point at an <input type=file> (it appears in the snapshot as a textbox). Returns a fresh snapshot.

Go forward one entry in the browser history, then return a fresh snapshot of the page you land on. No-op error if there is no forward entry.

Return the readable text (innerText) of the current page, normalized and clamped to a character budget. Use this when you want the page content WITHOUT the interactive-element list that browser_snapshot includes.

Configure how the browser answers the next native JS dialog (alert / confirm / prompt / beforeunload), and report the most recent dialog seen. By default vew auto-ACCEPTS dialogs when driving its own launched browser (so a confirm()-gated action proceeds and alert() text is captured) and auto-DISMISSES them when attached to an existing browser (VEW_CDP_URL) so it does not hijack the human's dialogs. Pass `accept` to override that for the next dialog (and `prompt_text` to answer a prompt()); the override stays armed until a dialog actually fires (then it reverts to the mode default) or you call this again -- so if the action you expected to raise a dialog does not, re-issue or clear the override before the next one. Calling with NO arguments does NOT change the disposition -- it just reports the last dialog, leaving the mode default in place (important in attach mode, where a stray accept would auto-confirm the human's dialogs). This call never opens a dialog or changes the page.

Hover the pointer over the element addressed by `ref` (from the most recent snapshot), then return a fresh snapshot. Use this to reveal hover-only menus, tooltips, or action icons that are not in the page until hovered.

Navigate the persistent browser page to a URL and return a fresh snapshot of the resulting page. This is usually the first call: it loads the page and immediately gives you the ref-addressable element list + readable text so you can act without a second round-trip. Waits for the load event by default. The page renders at Playwright's default 1280x720 viewport. The snapshot lists every rendered element with a recognized interactive role (button, link, textbox, checkbox, ...), including ones below the fold; scroll only to load content injected lazily as you scroll.

Press a single keyboard key, optionally on the element addressed by `ref`. Use Playwright key names: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp/PageDown, or a single character; combos use '+', e.g. 'Control+A'. With a `ref` the element is focused first (e.g. to submit a field or drive a focused widget); without one the key goes to whatever currently has focus (e.g. Escape to close a modal). Returns a fresh snapshot.

Capture a PNG screenshot of the current page and return it as an image. Defaults to the viewport; set full_page to capture the entire scrollable page. Prefer browser_snapshot for acting on the page -- a screenshot is for when you need to SEE pixels (layout, charts, visual verification).

Scroll the page one viewport in the given direction, then return a fresh snapshot. Useful to bring lazily-loaded content (infinite scroll, IntersectionObserver widgets) into the DOM so it appears in the snapshot.

Select an option in a native <select> dropdown addressed by `ref` (from the most recent snapshot). The `value` is matched against each option's visible label OR its value attribute. browser_type cannot fill a <select> -- use this instead. On a <select multiple>, this selects only the matching option and clears any others. Returns a fresh snapshot.

Return a compact, token-efficient view of the CURRENT page: a ref-tagged list of interactive elements (each line is `[ref] role "name"`, optionally with value/checked/disabled) followed by the readable page text. This is the core capability -- prefer it over a raw DOM dump. Refs (e1, e2, ...) are stable within this snapshot and RENUMBER on the next one; always act off the most recent snapshot. Pass a ref to browser_click / browser_type. Lists every rendered element with a recognized interactive role, including below-the-fold ones; scroll only to surface content that loads lazily on scroll.

Type `text` into the textbox/searchbox/combobox addressed by `ref` (from the most recent snapshot). The field is cleared first. Set `submit: true` to press Enter afterward (e.g. to run a search). Returns a fresh snapshot.

Wait for a condition on the current page, then return a fresh snapshot. Provide at least one of: `text` (wait until that text becomes visible), `text_gone` (wait until that text is no longer visible), or `time_ms` (wait a fixed time); when several are given they apply in that order. Use this after an action that triggers async / SPA rendering so the next snapshot reflects the settled page instead of racing a half-rendered DOM.