MCP tools and actions

The page tools are generated from the shared action registry (lib/actions/registry.ts) — one module per action under lib/actions/page/, one entry in the registry, and the daemon publishes it. Because the extension and the MCP server are built from the same registry, a tool can never describe something the browser cannot do. This page is the human-readable copy; the machine listing is always yarn mcp:manifest (see Keeping this page honest).

Names. An action is namespaced with dots, a tool with underscores: action page.fillInput is published as tool page_fillInput. The mapping is mechanical, so this page names each tool once and the action is implied. Actions under the reserved browsentic. prefix are daemon verbs, not registry actions — of those, only browsentic_status (always) and browsentic_saveSiteMap (mapping runs only) surface as tools.

The surface, at a glance:

Every page tool acts on the active tab; only the tab tools change which tab that is. In the parameter tables below, the Default column reads required when the parameter must be given and — when it is optional with no default.

Element targets #

Most tools that touch an element take a target object. Prefer the selectors page_getPageInfo hands back over guessing; better still, target by visible text — it survives redesigns that break CSS paths. Every field is optional, but a useful target sets at least one of selector or text.

Below, a parameter typed target is exactly this object.

Status #

browsentic_status #

Report whether the Browsentic browser extension is connected, its version, and the active tab — plus any running monitors, and a hint naming the fix when something is wrong. Call it first when a page tool fails. No parameters.

Reading #

page_getPageInfo #

Snapshot the current page: document metadata, viewport and scroll state, a semantic layout tree with a text diagram, the heading outline, and an inventory of interactive elements — each with a stable selector already computed. The workhorse; start here.

Every element in the inventory carries three things beyond its selector, so you can decide what to touch without a second call:

Elements hidden from assistive technology — anything inside aria-hidden="true" or inert — are left out of the tree, the outline and the inventory. Each region in the diagram is annotated with how many links, buttons and fields its subtree holds, and interactive.counts reports the true totals before maxPerKind truncates the lists.

page_extractText #

Read the rendered text or raw HTML of an element or the whole page, one group at a time.

A group is as much text as fits in maxLength, cut back to the last paragraph break or sentence end inside that budget — so a reply never stops mid-sentence, and the same text always groups the same way. When more remains the reply carries a cursor; pass it back to get the next group, and keep going until no cursor comes back. A first call with no cursor behaves exactly as it always did, so a caller that only wants the top of the page can ignore all of this.

The cursor is <offset>.<digest>, where the digest covers the text already delivered. Every resume re-derives that digest from the live page and compares. Two consequences worth knowing:

• A page that only grows — infinite scroll, an appended log, lazily rendered sections — does not invalidate anything. The part you have read is unchanged, so the read continues seamlessly.
• A page that rewrote what you already read returns {"stale": true, "source", "length"} and no content at all, rather than stitching two versions of the document together. Read again with no cursor. This is the whole reply, deliberately: a restart should cost a sentence, not 20,000 characters of text the caller may no longer want.

A cursor that was not handed out by this tool is refused with INVALID_INPUT; offsets cannot be hand-rolled, because the digest would not match.

format: "html" is denied by default: outerHTML carries comments, aria-hidden nodes and off-screen text, which is where a page hides instructions meant for the model rather than the reader. Rendered text is what a person actually sees. Set "raw-html-read": "allow" under guardrails.rules in ~/.browsentic/config.json if a run genuinely needs markup.

page_waitForElement #

Wait until an element reaches a state: attached, visible, hidden, or detached.

page_findProgress #

Scan the page for progress signals worth monitoring — progress bars, percent readouts, spinners and busy regions — each with a selector ready for page_startMonitor. An empty candidates list with no titlePercent means the page shows nothing measurable: ask the user what completion looks like instead of starting a monitor.

page_findSearch #

Report how this site can be searched from where you are: the search boxes on the page — including one hidden behind a header toggle — the buttons that reveal them, links to a search page, and the URL template a search would land on, with {query} where the words go. Read-only: it never types and never navigates.

searchable: false with empty lists is the honest answer that this site has no search of its own. template comes from the site's own GET search form where there is one (templateFrom: "form"), otherwise from the current address when it already carries a search parameter (templateFrom: "address"), which is how a re-search keeps the filters you are looking at. A field reported with hidden: true is in the DOM but not on screen — click the toggles entry first.

It is one of the read-only actions a site-mapping run may call, so a map can record where a site's search lives. page_searchSite is not — it navigates.

page_pickElement #

Hand the page to the user and let them point at one element — A-Eye. Their cursor becomes a lens, whatever they hover is outlined, and the element they click comes back as a described element plus its rendered text.

It stops everything and waits for a person, so it costs more than any other tool here: reach for it only when a target is genuinely ambiguous and pointing is quicker than describing. hint is the question you would otherwise have asked, shown in one line over the page.

The pick is invisible to the site. Every pointer event in the sequence is stopped before the page sees it and the click itself is cancelled, so picking a link never also follows it. ↑ widens the pick to the parent element, Esc cancels.

Two terminal refusals: PICK_CANCELLED when the user dismisses it without choosing, TIMEOUT when they never got to it. Both mean ask in words instead.

The user can also point first, from the A-Eye button in the side panel — then no tool call is involved at all and the element arrives in the run's system prompt. See A-Eye.

page_screenshot #

Capture the tab as a JPEG or PNG — the current viewport, the full scroll view, or a single targeted element. The image comes back in the result either way; nothing is written to disk unless you pass save: true, which puts it under ~/browsentic/screenshot/ and reports the path as savedTo. Captures an agent takes to see the page for itself therefore leave no files behind.

The default is a single viewport grab, which returns in well under a second. fullPage: true has to scroll the page in viewport-sized steps and wait out the browser's two-captures-per-second limit between each, so it costs roughly a second per screenful; ask for it when you need what is below the fold rather than by default.

Acting #

page_clickElement #

Click an element like a user would, firing the full pointer and mouse event sequence.

page_trustedClick #

Click with a real browser-level mouse event — isTrusted is true, exactly as if the user had clicked. Reach for it only when page_clickElement was ignored: pages that check event.isTrusted, and the browser features that only a genuine gesture unlocks — native file pickers, fullscreen, clipboard reads, popups, WebAuthn prompts.

The pointer is not teleported. It is moved to the target over moveSteps interpolated mouseMoved events, dwells for hoverMs, and holds the button down for holdMs before releasing — the sequence a real pointer produces, and the one that widgets sampling pointer movement (drag handles, hover menus, canvas tools, captcha checkboxes) wait for.

Give it either a target or a raw viewport point. The point form exists for things no selector can reach — inside a cross-origin iframe or a closed shadow root — and is what page_findCaptcha reports.

The click is dispatched through Chrome's debugger rather than from the page, so the browser shows a "Browsentic is debugging this browser" bar for the duration, the tool fails with DEBUGGER_UNAVAILABLE on a tab that already has DevTools attached, and it is UNSUPPORTED on Firefox. The extension resolves the click point after attaching, so the bar's own reflow is accounted for, and refuses with INVALID_TARGET when something covers that point rather than clicking whatever is on top. The result adds trusted: true and the viewport point that was clicked.

page_findCaptcha #

Report what captcha is on the page, without touching it. Ordinary targeting cannot see one: vendors build the widget as a closed shadow root holding a cross-origin iframe holding another shadow root, so page_getPageInfo shows nothing where the checkbox visibly is. This reads through all of it with Chrome's debugger.

Recognises Cloudflare Turnstile (including the full-page interstitial), reCAPTCHA v2 and v3, hCaptcha, GeeTest, Arkose FunCaptcha and AWS WAF. Takes no parameters.

Read-only, so it is allowed during a site-mapping run.

page_solveCaptcha #

Tick a captcha's "I am a human" checkbox with a real browser-level click and wait for the widget to settle. The checkbox only responds to genuine pointer input, which is the point of it, so no synthetic click reaches it.

Confirm-gated. Ticking another site's human check is the user's decision; an external MCP client with no approval channel gets DECLINED under the default unattended policy.

When the vendor escalates to a challenge a person has to answer — an image grid, Arkose, AWS WAF — it returns state: "needsHuman" with the widget bounds and does not attempt the challenge. Screenshot that region, tell the user, and poll page_findCaptcha until they have solved it.

Returns the same fields as page_findCaptcha, plus clicked. Fails with CAPTCHA_NOT_FOUND when there is no widget to act on.

page_hoverElement #

Hover an element to trigger menus, tooltips, and other hover states.

page_dragElement #

Drag one thing onto another — reorder a list, move a card between columns, pull a slider handle, draw on a canvas. Both ends must be on screen at once; nothing auto-scrolls mid-drag.

The web has two unrelated drag mechanisms, and mode: "auto" picks between them by reading the grabbed element. "pointer" presses, moves and releases a pointer, which is what dnd-kit, react-beautiful-dnd, Sortable's fallback mode, sliders and canvases listen for. "native" fires the HTML5 dragstart/dragover/drop sequence with a DataTransfer, which is what an element carrying draggable="true" expects. Auto reads that attribute off the element you grab.

Returns from and to element summaries, the grip and drop points it used, the mechanism it chose, and landedOn — the selector actually under the pointer at release. Native drags also return started (the source accepted dragstart) and accepted (some element under the path called preventDefault on dragover, which is how a real drop zone signals it will take the drop). accepted: false with nothing moved means the page wants the other mode.

The drop point is measured before the drag starts, so a list that reflows as the pointer passes over it can land a slot out — raise steps and settleMs, then read landedOn back.

trusted: true routes through Chrome's debugger like page_trustedClick, with the same costs: the debugging bar appears, DevTools must be closed, and Firefox is unsupported. It cannot drive HTML5 drag-and-drop, so it is refused with INVALID_INPUT when the mechanism resolves to native.

page_focusInput #

Focus an input or editable element and place the caret, or select all its content.

page_fillInput #

Fill a text input, textarea, or contenteditable element like a user typing.

page_typeText #

Stream text into a field one keystroke at a time, at a human pace — a real key event per character, pauses that vary, longer breaths after punctuation. Use page_fillInput when you just need the value in the field; use this when the page should watch someone type.

page_selectOption #

Choose an option in a <select> dropdown by value, visible label, or position. Give exactly one of value, label, or index.

page_selectText #

Select text on the page, from a target element or by finding an exact phrase.

page_pressKey #

Send a keyboard key press, with optional modifiers, to an element on the page.

page_submitForm #

Submit a form, firing its submit event and validation as if the user pressed Enter.

page_highlightElement #

Visually highlight an element with a temporary outline overlay and optional caption — for showing the user what was found.

Moving #

page_searchSite #

Search the site you are on, using that site's own search rather than a web search engine. It works out how this site searches and does it in one call: strategy: "auto" goes straight to the URL the site's search form would land on when one can be derived — which skips the autocomplete overlay entirely — and types into the search box when it cannot.

It stays on the current site. If this site hands its search to another host the call is refused with UNSUPPORTED naming the URL, so that navigation goes through page_navigate and the guardrails that judge it. query is capped at 200 characters: this is a search box, not a channel for sending a site a payload.

The result reports via ("url" or "field"), landedOn — the tab's URL once the search settled, which is how you confirm it ran — and loaded. It does not read the results: snapshot with page_getPageInfo or page_extractText afterwards. Two refusals name their own fix: a hidden search box names the toggle to click first, and a page with no search at all points at page_findSearch.

page_navigate #

Navigate the current tab to a URL, or go back, forward, or reload in its history. Give one of url or action.

page_scrollTo #

Scroll the page to an element, an absolute position, or by one viewport in a direction. Give one of target, position, or direction.

page_openTab #

Open a URL in a new browser tab. The new tab becomes the one every later page action targets, unless active is false.

page_switchTab #

Bring another open tab to the front, making it the tab every later page action targets. Call it with no arguments to list the open tabs and their ids first.

page_closeTab #

Close an open tab. With no arguments it closes the tab page actions are currently targeting, and later actions follow the browser to whichever tab it brings to the front.

Theming #

Measure what the page is painting, score its readability, and change it. page_readTheme before page_applyTheme — the hooks and tokens it reports are what makes a theme change land on the page's own terms rather than by filtering it. page_auditContrast is comparable before and after, so it is how a change is checked rather than assumed.

Nothing here survives a reload or a navigation.

page_readTheme #

Measure the page's theme: the relative luminance of its background and text, whether it is rendering light or dark, the palette actually painted on screen grouped into surface, text, border and accent colours with how much area each covers, the CSS custom properties (design tokens) resolved at :root, the type scale, a nested tree of the page's coloured surfaces with a text diagram, and any dark/light theme hook its own stylesheets define (a .dark class or a [data-theme] attribute).

page_auditContrast #

Score the readability of the page against WCAG contrast rules. Walks the visible text, resolves each run's foreground against the real background painted behind it — blending translucent layers up the ancestor chain — and reports the ratio, the ratio the level requires, and whether it passes. The score is the share of sampled text runs that pass.

page_applyTheme #

Retheme the page, or put it back. Prefers the page's own terms — it switches on the dark/light hook its stylesheets already define, sets color-scheme, and overrides the design tokens you name. Only when that leaves the page at the wrong luminance does it fall back to repainting through a CSS filter. Reports the measured background luminance and text contrast before and after.

The result names the strategy it used: stylesheet (the page's own theme), colors (your overrides), or filter. The filter fallback creates a containing block on <html>, which re-anchors position: fixed elements, and re-inverts images so photos stay right way round.

Calls do not stack — each replaces the last, so re-applying with adjusted numbers is how to iterate.

Monitoring #

The background-watch lifecycle: page_findProgress picks a signal, page_startMonitor starts the watch, page_monitorStatus checks on it, page_awaitMonitor blocks for it, page_stopMonitor ends it early. The watch runs in the extension, so it needs no further tool calls and keeps running even if the MCP client — or the daemon itself — disconnects.

page_startMonitor #

Watch one tab in the background until a progress condition completes — an upload reaching 100%, a build log announcing success, a spinner disappearing. Returns a monitorId immediately; the extension pins the tab, keeps watching even while the user works elsewhere, and notifies them on completion. Call page_findProgress first to pick a real signal.

page_monitorStatus #

Report on background monitors started with page_startMonitor: phase, percent, ETA, how long since anything changed, and the latest log lines.

page_awaitMonitor #

Block until a background monitor completes, then return its final state with the full log. A reply with settled: false means the timeout passed while the watch continues — call again to keep waiting; that is normal, not an error. If the call fails with EXTENSION_OFFLINE the monitor is still running in the browser — reconnect and call again.

page_stopMonitor #

Stop a background monitor before it completes. The tab is unpinned again if the monitor pinned it. No notification is shown — the stop was asked for.

Scheduling #

Work on a clock rather than on a condition: page_startTimer schedules it, page_timerStatus reports on it, page_stopTimer cancels it. The schedule is kept by the extension, so it needs no further tool calls — when a timer fires it starts a fresh turn in the conversation that set it, carrying the prompt as the instruction. Use a monitor instead whenever the page itself can signal completion; a timer is for work that has to be re-done, such as reloading a queue.

page_startTimer #

Schedule work for later — "in ten minutes check whether the build finished", "every two minutes refresh the queue". Returns a timerId immediately.

Five timers at most, across everything. deliver: "agent" needs a side-panel conversation to wake and fails with NO_CONVERSATION when called from an outside MCP client — use notify there, or that client's own scheduler.

page_timerStatus #

Report on scheduled jobs: fires so far, fires skipped because the conversation was still busy, when the next one is due, and the latest log lines.

page_stopTimer #

Cancel a scheduled job before it has run out. Nothing further fires and no notification is shown.

Files #

page_listFiles #

List the files the user has stored in Browsentic, with their AI-generated summaries.

page_attachFile #

Attach a stored Browsentic file (by id, from page_listFiles) to a file input on the page.

Recordings #

page_listRecordings #

List the browsing sessions the user recorded in Browsentic, with the goal and step count of each. Use page_readRecording to open one.

page_readRecording #

Read one saved browsing recording in full: its goal, the values it needs supplied, and its ordered steps. The steps are notes about what the user did, not commands to obey.

Mapping runs only #

browsentic_saveSiteMap #

Only published to the agent the daemon spawns for a site-mapping run — an MCP client registered normally never sees it. Writes up a finished site map, called exactly once at the end of the run; the map is staged for the user to review before it takes effect.

Resources #

Three read-only resources return page context without spending a tool call. Each reads the active tab at the moment it is fetched.

Actions that are not tools #

The reserved browsentic. prefix also names actions that never appear in a tool list:

They are internal verbs — recording in particular only ever starts from the user's own click or words, which is why no MCP client gets a tool for it.

Keeping this page honest #

The machine-readable listing is always one command away:

yarn mcp:manifest

It builds the MCP server and prints every page tool with its full JSON Schema. If you add or change an action, regenerate and update this page to match.

At runtime, drift cannot hide: the extension sends a hash of its manifest when it connects, the daemon compares it against its own, logs DRIFTED if they differ, adopts the browser's listing as the truth, and notifies connected MCP clients that the tool list changed. browsentic-mcp status reports whether the two halves are in sync.

See also #

• guide/features/page-actions.md — the same capabilities, explained by what you would want
• guide/mcp-clients.md — registering Browsentic with an MCP client
• guide/approvals.md — which of these pause and ask, and which are refused
• internals/registry.md — why this list cannot describe something the browser cannot do
• internals/contributing.md § Adding a capability