websense
WebSense is a non-vision, AI-native browser automation MCP server that drives a real logged-in Chrome profile via a Chrome extension, letting an agent map pages, act by reference, and verify changes with grouped diffs.
browse— open/bind a tab and map it in one call: navigate, seed a diff baseline, collect a lossless element inventory, and return an INDEX, page vocabulary, and region outline.find— search the stored inventory by query, tag, role, region, attr, index, viewport, focusable/interactive/field flags; each hit reports WHERE (region + ancestor branch chain) and WHAT (role/name/attrs/state), returning all matches with no cap.act— perform actions:click · hover · rightclick · drag · type · key · form · upload · scroll · dialog, targeting aref,selector, or rawx/y; supportshow:"auto" | "trusted" | "os"(trusted = browser's own input pipeline, background tab, no focus steal),modifiers,fromRef/toRef,filePath, andframeId.page_slice— pull full-fidelity records for one slice of the snapshot (indices, tag, role, region, vp, interactive, focusable, field, attr, query) or any cached part of a diff (structure | content | visual | viewport | all) via a FULL DIFF handle.tabs— tab/window management:list · switch · close · bind · frames · windows · focus · move · transfer · switchread, including moving a selector/value between tabs and binding page ops to a tab without activation.debug— introspect WebSense and read raw page data:status · session · logs · cookies · clipboard · screenshot · ax · evaluate · main_world · explore_page · reload · respawn · guide, with optionaltabId/frameId.websense_guide— returns the full in-tool guide (the runtime source of truth); call it first before acting.Verification built in — every mutating action returns a grouped DIFF (structure/content/viewport), an
effectverdict (upgraded toconfirmedon real DOM movement), and navigation confirmation; viewport churn never fakes a landing.Cross-cutting support — same-origin iframes walked and clickable, trusted input on canvas/WebGL, JS/DOM/OS dialog handling, Windows-only OS-level input via
real_*/how:"os", and stdio or streamable-HTTP transport (30 further unlisted-but-callable tools).
Enables browser automation of GitHub, allowing AI agents to navigate repositories, click, fill forms, and read state changes through the Semantic Action Graph.
Enables automation of the Gmail web interface for reading, composing, and managing mail via the browser extension.
Supports automation of Google web properties, including search and other Google pages, with structured actions and before/after diffs.
Supports automation of Telegram Web through the accessibility-tree ax tool, covering canvas/WebGL-heavy interfaces.
Supports automation of TradingView charts and the web app via the accessibility-tree ax tool, especially for canvas/WebGL content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@websense Open Hacker News and show me the top 3 stories"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
WebSense MCP
Non-vision, AI-native web automation via a Chrome extension. No screenshots, no debug port, no bot detection — the model reads structured JSON and acts through the browser's own input pipeline.
WebSense gives an AI agent hands on a real, logged-in Chrome profile. The agent gets a lossless, addressable map of the page, acts on it by reference, and is told — with a grouped diff — whether the page actually changed. No vision model, no headless browser, no remote-debugging port.
Requirements
Node.js ≥ 18
Google Chrome / Chromium (Manifest V3, offscreen WebSocket bridge). Chrome-only: there is no Firefox code in this repo.
OS-level input is Windows-only. Everything else (browse / find / act, trusted input, frames, diffs) is cross-platform.
act{how:"os"},real_click,real_paste,real_activate_tabanddialog{keystroke}use WindowsSendInput/ PowerShell.main_world(the CSP-proof MAIN-world read path) needs Chrome 138+ with the per-extension "Allow User Scripts" toggle enabled.
Related MCP server: live-mcp
Install
git clone https://github.com/spliffspliff70-wq/websense-mcp
cd websense-mcp
npm install1. Load the extension. Open chrome://extensions, turn on Developer mode, click Load unpacked, and select the extension/ folder. It connects to the WebSocket hub on ws://127.0.0.1:38401 automatically — there is no launcher page. (For main_world, open the extension's Details and enable Allow User Scripts.)
2. Register the MCP server with your client.
stdio — one client per server process:
{ "mcpServers": { "websense": { "command": "node", "args": ["src/server.js"] } } }streamable HTTP — one server, many clients:
node src/server.js --http --http-port 9222
# then point each client at http://localhost:9222/mcp3. Call websense_guide (or just browse). The guide is the runtime source of truth and documents every tool.
Bridge port. Default 38401, plain ws:// on 127.0.0.1 (loopback is exempt from mixed-content blocking, so it works from HTTPS pages). Override with --port <n> on the server and the matching PORT constant in extension/offscreen.js. If the port is already taken the hub logs a warning and the server keeps running — MCP still works, the bridge just isn't claimed. Run isolated servers with different --port values.
The model's surface: 8 listed tools
A model sees exactly eight tools. The rest stay callable by name but are not listed, so a model never has to choose between a wall of one-verb tools.
tool | what it does |
| TOOL 1 — open (or bind) a tab and map it in one call: navigate, seed the diff baseline, collect a lossless inventory, and return only the INDEX + the page's vocabulary + a region outline. |
| TOOL 2 — search the stored inventory. Every hit answers WHERE (region + branch chain, resolved from parent pointers) and WHAT (role / name / attrs / state). |
| Do something: |
| Full-fidelity records for one slice of the inventory ( |
| Tab/window ops: |
| WebSense itself + raw reads: |
| Call this first when anything is refused. Walks launch → server → extension → binding → page-ready, stops at the first broken link, and returns the command that fixes it. Read-only by default. |
| Start here — returns the full in-tool guide. |
38 tools are registered; 30 of them are unlisted but callable by name. The listable extras are summarised under Other registered tools.
Quick start — the loop
browse {url}— one call that navigates (or binds), seeds the diff baseline, stores a lossless inventory of every element (nothing filtered, capped or truncated) and returns the small INDEX + a region outline. The full records stay server-side, addressable by index.find {query}— locate the control. Each hit tells you WHERE it is and WHAT it is, so five controls called "New" are distinguishable.act {action, ref, ...}— do it. Reach forhow:"trusted"when the page checksisTrusted, reads coordinates, or a default action must run. Works in a background tab — no focus steal.Read the diff the reply carries.
The diff (did it land?)
Every mutating action returns a second block: a grouped DIFF against your browse baseline.
structure — the page's shape changed (elements added/removed; tag/role/name/attrs changed). Page truth.
content — the same element's value/text changed and its shape did not. The page answered you.
viewport — only
vp/x/ydiffer. That is scroll/layout churn and is not a mutation.
mutated is true only when structure or content moved — viewport churn can never make an action look landed. The reply ends with a FULL DIFF: <handle> line; fetch any part with page_slice{diff:"<handle>", part:"structure|content|visual|viewport"}. The full delta is cached because it can be hundreds of KB for one action — the summary is what changed, the handle is the rest. Pass verify:false to skip the diff on a call you don't need checked.
A navigation is the strongest confirmation and is not in the groups: when a click or press_key (Enter/Space) replaces the document, the result carries effect:"confirmed" plus a navigation {from,to}, and the diff line says so explicitly — a diff across a navigation compares two different documents, so its groups are meaningless.
Verdicts, and when they are wrong
effect is derived from page_state — url, title, readyState, scroll. That is a deliberately weak signal, and an action that only changes the DOM does not move any of them. Two rules make that honest:
The diff can upgrade the verdict. When the page-side differ measures a real structure/content move (
mutated:true), anunverifiableorsuspected_noopverdict is upgraded toconfirmedand carrieseffectSource:"page_diff", and its stale escalation advice is removed with it. Measured on x.com: every trustedtypeinto the thread composer used to answerunverifiablewhile the same reply saidmutated:true— a verdict contradicting its own evidence, which reads as "no proof" and makes a caller re-run an action that already worked. It only ever upgrades: afailedverdict (the action layer refused — disabled, read-only) staysfailed. The measurement happened;classifyEffectsimply could not see it.An ambiguous selector is refused, not guessed.
querySelectorreturns the first match with no word, so a selector matching two elements silently drove the wrong one. Measured on x.com's/compose/post:[data-testid="tweetTextarea_0"]matches twice — the dialog's real composer and the empty page-level inline composer. You now get a refusal naming the count and the tag (ambiguous selector … matches 2 elements — refusing to pick one silently). Scope it and retry:[role="dialog"] [data-testid="tweetTextarea_0"], or any selector that is unique on that page. This is also whyfindreturns all matches with no cap — a cap would hide the second element and make the ambiguity invisible.
effect remains weak evidence for everything else: confirmed means "the page measurably moved", never "the app accepted and persisted it". Re-read the field or the page when the outcome matters.
Trusted input — act{how:"trusted"}
how:"trusted" drives chrome.debugger + Input.dispatchMouseEvent / Input.dispatchKeyEvent, so the page receives isTrusted events and the browser itself runs the default action (a link navigates, an Enter submits, a checkbox toggles, an arrow key moves a slider) instead of the tool guessing. It works in a background tab — no focus steal, no window activation. Chrome shows its "debugging this browser" infobar while attached.
Off-screen targets are scrolled into view first. Measured: a trusted click aimed at y=1727 below the fold hit nothing; after the fix it re-aimed at y=938 and the page recorded the click.
how:"os" is the OS-level rung (Windows SendInput) — reach for it only when a page rejects programmatic input outright, or for a raw-input / canvas surface. It lands on the frontmost window and so steals focus.
Dialog handling
JS dialogs, by type — this is measured behavior, not a blanket rule. The MAIN-world hook shadows
alertonly (its return is undefined, so nothing can branch on it) — it is captured intopendingDialogsand auto-dismisses after 30s, matching what Chrome itself does in a background tab.confirm/promptstay NATIVE: a hooked confirm returns a Promise (always truthy), so everyif(confirm(...))would take the TRUE branch regardless of the answer — the auto-answer-after-30s behavior was a bug, not a safety net, and it is gone. A nativeconfirm/promptblocks the page; answer it on request withdialog{native:true, action:"accept"|"dismiss", value:promptText}— that goes throughPage.handleJavaScriptDialog(chrome.debugger), so the page's own branch follows the agent's real choice, on a background tab, with no focus steal. Nothing ever auto-answers a decision the agent did not make.DOM modals (
[role=dialog], most in-app modals) are closed by ref;status.hasModal/dialogCountcome from a visibility-blind scan (a hidden modal still counts).OS-level dialogs (HTTP basic-auth, proxy-auth, print) cannot be intercepted by JS.
dialog{keystroke:true, key:"enter"|"escape"}injects a global keystroke through Windows control (PowerShellSendKeys) — Windows-only.File picker: handled by
form{action:"upload"}(DataTransfer API) — no OS dialog.
Iframes / frames
Same-origin iframes are walked and clickable — verified: the frame echoes the click. List them with tabs{action:"frames"} (pass tabId; omit it for your bound tab) and pass frameId to any element tool — this unlocks Gmail compose, Notion, Figma and any site that renders key UI inside child frames. Cross-origin frames are skipped: nothing in the page can read them and no click can be aimed inside them.
Other registered tools
These are registered and callable by name — the standalone forms that act / debug absorbed are noted inline:
explore_page— quick look at a page's actions (SAG).compact:true,intent:"submit",goal:"log in",preload:true,incremental:true. For a full page map usebrowse+findinstead.read— page text:text · content · markdown · diff · scrollextract · preload.click— click a ref (default)· mode:"hover" · "rightclick" · "drag" (fromRef/toRef) · x,yfor canvas.trusted_click·trusted_key— the standalone trusted mouse / keyboard paths.press_key— synthetic key events only; runs no default action. Usetrusted_key/act{how:"trusted"}when the default matters.type_text— fill one input (React-safe native setter) orfields:[{ref,text},…]for a verified batch.form—state · select · toggle · special · upload.reveal— pre-extract hidden content:dropdown · tabs · accordion.scroll—direction+amount(ticks) ·yabsolute ·intoView.status—page · bridge · doctor · downloads.wait— poll conditions (ANDed) until met, or wait for an event.evaluate— run JS and return its value (auto-reroutes through the MAIN world on a CSP block) or a no-evalqueryDOM read.main_world— run a compiled function in the page's MAIN world (CSP-proof; needs "Allow User Scripts").ax— native accessibility tree viachrome.debugger(for canvas SPAs andchrome://pages).screenshot—captureVisibleTab→ PNG/JPEG dataUrl, for a vision model.dialog—accept | dismiss(+value); captures the page's own JSalert/confirm/prompt.session—reset · map · mermaid.network_log·console_log— captured page fetch/XHR · console + JS errors.cookies—list · get · clear(values are masked on other surfaces).clipboard—copy · read.inspect—element · geometry · relation.navigate— navigate a tab (reuses your bound tab; no tab spam).page_snapshot— collect / return the lossless inventory index directly.respawn_offscreen·extension_reload— extension maintenance (MV3 traps).real_activate_tab·real_click·real_paste— Windows OS-level input; the last rung.
Architecture
MCP Client (Claude / Cline / Cursor / Hermes)
↔ stdio or streamable HTTP
WebSense MCP Server (src/server.js)
↔ WebSocket ws://127.0.0.1:38401
Chrome Extension (extension/)
├── background.js service worker, tab management, binding
├── offscreen.js WebSocket client, auto-reconnect
└── websense-cs.js SAG extraction + native DOM interaction (CSP-safe)
↔ chrome.runtime.sendMessage / chrome.debugger (trusted input)
Live DOMWhat's new in 2.0
A 7-tool listed surface —
browse · find · act · page_slice · tabs · debug · websense_guide.actanddebugare facades that dispatch to the real handlers, so the 30 unlisted tools remain callable by name with identical behaviour.browse→find→act→ read the diff replacesexplore_page → click/typeas the primary loop.browsereturns an INDEX over a lossless inventory;findreturns WHERE + WHAT per hit;page_sliceloads one branch at full fidelity.A grouped auto-diff after every mutating action, with
mutatedderived from structure + content only (viewport churn cannot fake a landing), a summary in the reply, and the full delta cached behindFULL DIFF: <handle>.Trusted input:
act{how:"trusted"}runs throughchrome.debugger+Input.dispatchMouseEvent/Input.dispatchKeyEvent, so the page seesisTrustedevents and the browser performs the default action — in a background tab. Off-screen targets are scrolled into view first.Same-origin iframes are walked and clickable.
Known limitations (honest)
Trusted drag works end-to-end (verified on the fixture):
act{action:"drag", how:"trusted"}produces trusteddragstart/dragenter/dragoverand a realdrop, from a background tab, with both ends scrolled into view automatically. The drop only fires if the target accepts drops (preventDefault()ondragover) — a non-zone target correctly getsdragleave, exactly as a real mouse would, so check the target before blaming the driver. The plaindragmode still fires the whole sequence but its events are not trusted — usehow:"trusted"when the page checksisTrusted.OS-click equivalence is unproven.
act{how:"trusted"}is the browser's own input pipeline; it is not proven byte-identical to a real OS click.real_click(WindowsSendInput) is the only genuinely OS-level path.Canvas / WebGL: coordinate clicks are TRUSTED (fixed 2026-10-02 — this line said "not trusted" and was stale).
act{action:"click", how:"trusted", x, y}drivesInput.dispatchMouseEventat the raw viewport point, so a canvas that inspectsisTrustednow sees a real one. The untrusted form still exists ashow:"auto"and lands within 1px; preferhow:"trusted"on canvas/WebGL, which is exactly the surface class that checks the flag.Chrome-only. MV3 + offscreen WebSocket bridge; no Firefox code.
OS-level input is Windows-only (
real_*,dialog{keystroke}).OS-level input additionally needs Python 3 with
pyautogui+pywinauto(Windows only). Everything else — the wholebrowse/find/actloop, trusted input, frames, diffs — needs neither Python nor Windows. The server discovers an interpreter (py→python→python3); override withWEBSENSE_PYTHON=/path/to/python. If none is found the error says so instead of failing as a mysterious page problem (fixed 2026-10-02 — the interpreter path was previously hard-coded to the maintainer's machine, so OS input could not work for anyone else).main_worldrequires the "Allow User Scripts" toggle (Chrome 138+). Without it the CSP-proof MAIN-world path is unavailable.evaluate{script}runs your JS and returns its value; the isolated-worldnew Functionpath is blocked by the extension's own MV3 CSP, so it transparently re-routes through the MAIN world (chrome.userScripts, no eval) and reportsvia:"main_world".evaluate{query:{…}}remains the lighter path for plain DOM reads.A JS dialog raised while the tab is hidden can be auto-dismissed by Chrome before anyone sees it — act fast:
dialog{native:true, action, value}answers a still-pending native confirm/prompt viaPage.handleJavaScriptDialogon the background tab (no activation needed). A hookedalertis still recorded (status.recentDialogs); nativeconfirm/promptare NOT in the hook's queue (they are never shadowed), so checkstatusand answer immediately if the branch matters.axattacheschrome.debuggerand shows Chrome's warning banner while attached; it requires an explicittabId.One profile, per-tab isolation. Concurrent jobs share one Chrome profile — there is no cookie/storage isolation between them. Scope work with
tabs{action:"bind", tabId}+ an explicittabId. Session state (map/history) is per-session:session{action:"reset"}clears only your own history.Logged-in sites (LinkedIn, etc.) must already be authenticated in that Chrome profile;
navigateopens a fresh tab that needs an existing session cookie.Refs are stable —
E#refs are assigned in viewport order on the first scan, then held by element identity (a per-element cache + adata-websense-refattribute), so they survive re-explores, scrolls and framework re-renders. A ref dies only when its element leaves the DOM with nothing to heal from. CSS-selector refs (#id) remain the safest choice for anything long-lived or across navigations.
Testing
# Regression suite — no Chrome needed (hub, diff, snapshot, trusted-input,
# guide-truth and doc-drift guards). Currently 170 tests.
npm test
# Print the LISTED surface from a running server (tools/list is filtered to it)
node tools/tools-list.mjs # names-only preflight
node tools/tools-list.mjs --full # name + one-line description
# End-to-end MCP client test (needs Chrome + the extension loaded)
node test/mcp-client-test.js
# Keep MODEL_PROMPT.md in sync with the in-tool guide (also enforced inside npm test)
node tools/export-guide.mjs --checkFile structure
websense-mcp/
├── src/
│ ├── server.js # MCP server: tool registration, the 7-tool listed surface, facades
│ ├── hub.js # WebSocket hub on ws://127.0.0.1:38401
│ ├── session.js # exploration map + per-session state
│ ├── snapshot.js # lossless page inventory (collector + slicer)
│ ├── diff-cache.js # cached grouped diffs behind FULL DIFF handles
│ ├── diff-collector.js # in-page diff collection
│ └── climb.js, incr.js, upload.js, summarize.js, mermaid.js
├── extension/
│ ├── manifest.json # Chrome MV3
│ ├── background.js # service worker (tab mgmt, offscreen lifecycle)
│ ├── offscreen.js # WebSocket client (auto-reconnect)
│ ├── websense-cs.js # built content script (generated — do not hand-edit)
│ └── cs-src/ # content-script sources (edit here; build with tools/build-cs.mjs)
├── test/
│ └── mcp-client-test.js # end-to-end MCP client test
└── tools/ # build + measurement scripts (build-cs, export-guide, tools-list…)License
MIT — see LICENSE.
Available Tools
7 toolsactC
DO something: click, hover, rightclick, drag, type, key, form, upload, scroll, dialog.…
Inputs: action (required), x, y, how, +13 more.
browseB
TOOL 1. Go to a page and map it in ONE call: navigate (or bind an existing tab), seed the auto-diff BASELINE f…
Inputs: url, fresh, tabId, newTab, +1 more.
debugD
WebSense itself, and raw reads: op=status, session, logs, cookies, clipboard, screenshot, ax, evaluate, main_w…
Inputs: op (required), url, func, kind, +4 more.
findC
TOOL 2. Search the stored page inventory and get WHERE and WHAT the hit is: its own role/name/attributes/state…
Inputs: vp, tag, attr, role, +10 more.
page_sliceC
Full-fidelity records from the stored page snapshot, filtered to ONE slice: indices / tag / role / region / vp…
Inputs: vp, tag, attr, diff, +11 more.
tabsC
Tab/window ops. bind routes page ops to a tab WITHOUT focus — page ops NEVER need activation.…
Inputs: action (required), tabId, toTab, fromTab, +6 more.
websense_guideB
START HERE. The listed tools: browse, find, act, page_slice, tabs, debug, guide. Call once before you act.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct primary purpose (browse for navigation/mapping, find for search, act for interactions, page_slice for snapshot extraction, debug for raw reads, tabs for management, websense_guide for orientation). However, debug and page_slice both read page data, and find and page_slice both retrieve page inventory entries, so minor confusion is possible.
Tool names mix verbs (browse, find, act) with nouns (tabs, page_slice) and a prefixed noun phrase (websense_guide). There is no consistent verb_noun or other predictable pattern, making the naming style inconsistent.
Seven tools is well within the 3–15 range for a browser automation server. Each tool covers a broad area (e.g., act handles many actions, debug handles many raw reads), so the count feels well-scoped without redundancy.
The set covers navigation, search, interaction, tab management, raw reads, and page data extraction, which are core browser automation needs. Minor gaps include no explicit wait/synchronization tool and no download handling, though these can likely be worked around via debug.evaluate or act.
Maintenance
Related MCP Connectors
AI-powered browser automation — navigate, click, fill forms, and extract data from any website.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
AI-powered web automation. Navigate websites using AI agents for one page or a thousand
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to directly control your real Chrome browser with full context including login sessions, cookies, and open tabs. It provides tools for page scanning, JavaScript execution, CDP control, screenshots, and physical mouse/keyboard input for authentic browser automation.20243MIT
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to declaratively control web pages using real mouse and keyboard events via Chrome DevTools Protocol, without executing page JavaScript.1-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to autonomously control browsers with zero-hardcoding semantic DOM interaction, real-time network telemetry, Cloudflare/bot self-healing, and human-in-the-loop reasoning for web QA and automation.-
- AlicenseBqualityBmaintenanceEnables AI agents and developers to automate real Chrome/Chromium browsers through the Chrome DevTools Protocol, with token-efficient snapshots, multi-action batching, shadow DOM traversal, system-page control, extension management, and network/WebSocket inspection.951MIT