io.github.t3ratech/mcp-session-bridge

Click an element, by CSS selector or by an @eN ref from session_snapshot. Scrolls the element into view and dispatches a real mouse press and release at its centre, so handlers that ignore synthetic events still fire. Returns {clicked} naming what was targeted. Fails with 'Element not found' rather than clicking something else when nothing matches.

Close a tab, named explicitly by its id from session_list_tabs. Returns {closed, tabId}. Unlike every other tool here, tabId is required and there is no active-tab default: closing a tab is not undoable, and the active tab is the one the user is looking at. Requires the T3rnel Browser extension; the standalone browser refuses it by name.

Run JavaScript in the page's own context and return its completion value. Use it for what the other tools do not cover — reading computed styles, walking a data structure the page holds, or checking a condition too specific for session_wait. Objects come back as formatted JSON, strings as themselves, and an expression with no value as "undefined". End the code with the expression you want back; a trailing statement returns nothing useful.

Set a form field's value in one step — input, textarea, or a rich-text editor such as ProseMirror, Lexical or Slate. Writes through the native value setter and then fires input and change, which is what React and Vue listen for. Returns {filled} naming the field. Use session_type instead when a field only reacts to real keystrokes, and session_select for a dropdown.

Report which transport is live and what it can do. Call this first when another tool fails unexpectedly: it separates 'the extension is not running' from 'this browser does not implement that API', which produce very different fixes. Returns {ok, mode, browser, profileDir} in standalone mode, and the connection state plus the available browser APIs when the extension is attached.

Return setup instructions for the T3rnel Browser extension and for the free standalone automation browser. Needs no browser and no licence, so it is the one tool that always answers — call it when another tool reports the extension is missing. Returns installation steps as text.

List every open tab. Returns an array of {id, title, url}. The ids are what every other tool's optional tabId argument accepts; omit tabId and a tool acts on the active tab, which is rarely what you want once you have opened tabs of your own.

Decrypt stored credentials for a domain and fill them into the page's sign-in form. Requires the T3rnel Browser extension with Pro, because the encrypted vault lives in the extension; the refusal comes from the extension rather than from this bridge, so there is one gate rather than two that can disagree. The standalone browser has no vault — sign in once by hand in its profile instead, and the session persists.

Navigate a tab to a URL inside the user's authenticated session, so pages behind a login load as themselves rather than as a signed-out visitor. Reuses the active tab unless newTab is true. Returns {navigated} with the requested URL, and newTab when a tab was created. It returns once navigation is dispatched, not once the page has settled — follow it with session_wait before reading.

Press a single keyboard key on the focused element, or on a named element after focusing it. Use it to submit a form with Enter, dismiss a dialog with Escape, or walk a suggestion list with ArrowDown. Returns {pressed} naming the key. Supported keys are Enter, Tab, Escape, Backspace, Delete, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Home, End, PageUp, PageDown and Space; anything else fails with the supported list rather than doing nothing.

Read a page's visible text, as rendered in the user's authenticated session. Returns {url, title, text, truncated}; text is the body's rendered innerText capped at 50,000 characters, and truncated is true when the page was longer. Prefer this over session_snapshot when the goal is to read or summarise; prefer session_snapshot when the goal is to interact.

Fetch the captured events of a recording, in the order they happened. Returns {events, count}, where count is the total held for the session and events is one page of {type, timestamp, tabId, data}; type is one of click, scroll, keypress, input, navigation, focus, select or resize. Page through long recordings with limit and offset rather than reading them whole, since a session can hold tens of thousands of events. Requires the T3rnel Browser extension.

List every recording, running or finished, so a caller can find the id that session_record_events and session_record_replay need. Returns {sessions}, each entry being {id, tabId, active, startedAt, stoppedAt, stoppedReason, eventCount, durationMs}. Requires the T3rnel Browser extension.

Replay a stopped recording in its original tab, reproducing the recorded interactions in order. Returns {sessionId, totalEvents, replayedEvents, failedEvents, errors}, so a partial replay reports which steps failed instead of appearing to succeed. The tab must still be open. This acts on the live page and its effects are real — it will re-send messages, re-submit forms and re-spend money — so the extension classifies it high risk and gates it behind an approval prompt. Requires the T3rnel Browser extension.

Begin recording what happens in a tab: clicks, scrolls, keystrokes, form fills, selections and navigations, each with a timestamp. Returns {recording, sessionId, tabId} — keep the sessionId, since every other recording tool needs it. Requires the T3rnel Browser extension. Recording stops on its own if the tab closes or after four hours.

Stop a recording and return {recording, sessionId, eventCount, durationMs}. The events themselves are read separately with session_record_events, so this is cheap to call on a long recording. Requires the T3rnel Browser extension. With several recordings active, sessionId is required and the error names how many are running.

Capture what is currently on screen in a tab. Returns a data: URL holding a base64 PNG or JPEG. This is the visible viewport only — it does not scroll or stitch, so a long page needs the extension's full-page capture instead.

Choose an option in a <select> dropdown, by value, by visible text, or by index. Filling a select as though it were a text field does nothing — the native value setter belongs to HTMLInputElement and has no effect here — which is the silent failure this tool exists to prevent. Matches value first, then exact visible text, then a substring, then index. Returns {selected, value, text} for the chosen option, and on no match fails with the available options listed.

Capture a semantic map of a page for deciding what to act on. Returns {url, title, elements}, where each element is {ref, tag, text} — ref being an @eN handle that session_click, session_fill, session_type, session_select and session_press all accept in place of a CSS selector. Prefer this over session_read_page when the goal is to interact rather than to read: it lists only elements a user could actually operate. Skips zero-size and hidden elements, caps each label at 120 characters, and stops at 200 elements.

Encrypt credentials for a domain and store them in the extension's vault, for session_login to use later. Requires the T3rnel Browser extension with Pro. The password is never returned by this or any other tool, and never appears in a listing or an error.

Type text one character at a time, firing the key events a real keyboard would. Use this instead of session_fill when a field only reacts to keystrokes — search boxes with live suggestions, autocompletes, and inputs with per-character validation. Returns {typed} with the number of characters sent. Slower than session_fill, so reach for it only when session_fill leaves the page unchanged.

Block until a page reaches a known state, so the next tool acts on a settled page rather than a half-loaded one. Waits for the load event, for the URL to contain a string, or for a selector to appear. Returns as soon as the condition holds — {condition, waited} for load, {condition, url} for url, {condition, found} for selector — and fails at the timeout with a named error rather than hanging the client. Polls every 200ms; the default timeout is 10000ms.