From d20fd3f055f25db1353b6381b4c47983b7f85623 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 27 Oct 2026 04:20:51 +0000 Subject: [PATCH 1/3] Add tab awareness without the debugger banner (AGE-584) listTabs, readTab, navigateTab, softClick, and softType use chrome.tabs and chrome.scripting. They do not attach the debugger or change focus. chromeTabId stays separate from the DevTools-connected tabId. Background navigation stays in the visible window and is gated like other input. Soft click and type report worked or needs a real gesture. Co-authored-by: werbel.ted --- CHANGELOG.md | 7 + README.md | 17 +- SECURITY.md | 7 +- browser-tools-mcp/src/connector/api-policy.ts | 13 + browser-tools-mcp/src/connector/connector.ts | 226 ++++++- browser-tools-mcp/src/gates/capability.ts | 15 + browser-tools-mcp/src/mcp/client.ts | 66 +++ browser-tools-mcp/src/mcp/server.ts | 45 +- browser-tools-mcp/src/mcp/tool-invoke.ts | 9 + browser-tools-mcp/src/runtime.ts | 15 + browser-tools-mcp/src/tabs/contract.ts | 204 +++++++ browser-tools-mcp/src/tabs/listing.ts | 202 +++++++ browser-tools-mcp/src/tabs/tools.ts | 311 ++++++++++ browser-tools-mcp/src/tools-cli.ts | 2 + .../test/e2e/tab-awareness.e2e.test.ts | 213 +++++++ browser-tools-mcp/test/fixtures/server.ts | 23 + .../test/helpers/fake-extension.ts | 69 ++- .../test/integration/mcp-server.test.ts | 10 + .../test/integration/tab-awareness.test.ts | 231 ++++++++ .../test/unit/capability-gates.test.ts | 26 + .../test/unit/extension-gates.test.ts | 42 +- .../test/unit/tab-contract.test.ts | 85 +++ .../test/unit/tab-extension.test.ts | 342 +++++++++++ .../test/unit/tab-listing.test.ts | 115 ++++ chrome-extension/gates.js | 3 + chrome-extension/manifest.json | 2 +- chrome-extension/popup.html | 8 + chrome-extension/popup.js | 16 + chrome-extension/tab-actions.js | 560 ++++++++++++++++++ chrome-extension/tab-page.js | 334 +++++++++++ chrome-extension/tab-safety.js | 92 +++ chrome-extension/worker.js | 232 +++----- 32 files changed, 3369 insertions(+), 173 deletions(-) create mode 100644 browser-tools-mcp/src/tabs/contract.ts create mode 100644 browser-tools-mcp/src/tabs/listing.ts create mode 100644 browser-tools-mcp/src/tabs/tools.ts create mode 100644 browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts create mode 100644 browser-tools-mcp/test/integration/tab-awareness.test.ts create mode 100644 browser-tools-mcp/test/unit/tab-contract.test.ts create mode 100644 browser-tools-mcp/test/unit/tab-extension.test.ts create mode 100644 browser-tools-mcp/test/unit/tab-listing.test.ts create mode 100644 chrome-extension/tab-actions.js create mode 100644 chrome-extension/tab-page.js create mode 100644 chrome-extension/tab-safety.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 76353c59..7b9be9e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,13 @@ info and the tab list carry the same fields. Screenshot, storage, console, network, and audits on those pages return that result instead of an empty success. +- **Tab awareness without the debugging banner.** `listTabs`, `readTab`, + `navigateTab`, `softClick`, and `softType` use `chrome.tabs` and + `chrome.scripting`. They do not attach the debugger and do not change focus. + `chromeTabId` from `listTabs` is separate from the DevTools-connected `tabId` + used by `listBrowserTabs`. The tab list does not claim to see every open tab. + Background navigation stays in the visible window. Soft click and type report + `worked` or `needs a real gesture`. ## 2.0.5 diff --git a/README.md b/README.md index 03755f74..6160e276 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,12 @@ setup and a silent one look the same. | `getSelectedElement` | The element selected in the Elements panel | | `getPageInfo` | Which page the browser is currently on | | `getConnectionStatus` | Whether the extension is connected, and capture counts | -| `listBrowserTabs` | Every tab with DevTools open, and the id to address it by | +| `listBrowserTabs` | Tabs with DevTools open, addressed by a DevTools-connected `tabId` | +| `listTabs` | Tabs `chrome.tabs` returns (not every open tab), addressed by `chromeTabId` | +| `readTab` | Headings, excerpt, and a snapshot of a `chromeTabId`, without the debugger | +| `navigateBrowser` | Load a URL in a DevTools-connected tab, without focusing it | +| `navigateTab` | Load a URL in the background from `listTabs`, visible window only | +| `softClick` / `softType` | Untrusted click or type. Result is `worked` or `needs a real gesture` | | `takeScreenshot` | Screenshot returned **as an image**, plus its file path | | `refreshBrowser` | Reloads the inspected tab | | `getBrowserStorage` | localStorage, sessionStorage and cookies (values gated) | @@ -116,6 +121,16 @@ All tools declare MCP output schemas, so clients receive structured data rather than prose they have to parse, and read-only tools are annotated as such so clients can auto-approve them safely. +### Tabs without DevTools + +`listTabs`, `readTab`, `navigateTab`, `softClick`, and `softType` use `chrome.tabs` and `chrome.scripting`. They do not attach the debugger, so they do not show the debugging banner, and they do not activate a tab or focus a window. + +`chromeTabId` comes from `listTabs`. `tabId` on the other tools comes from `listBrowserTabs`. They are different id spaces. Pass each id only to the tool that issued it. + +`listTabs` reports the tabs `chrome.tabs` returns in the windows it returns. Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. Incognito is skipped. This is not every open tab. Background navigation stays in the visible window until that is measured on Arc. + +The popup switch has to be on. Navigation and soft input also need `--allow-input` on `browser-tools-mcp`, or `--allow-actions` on the `browser-tools` CLI. The same origin rules as other input apply. An asleep tab is reported and not reloaded. A soft action says `worked` or `needs a real gesture` and does not claim a failed action worked. + ### Several tabs at once Every tab with DevTools open is tracked separately. Telemetry is attributed to diff --git a/SECURITY.md b/SECURITY.md index 64757b29..6c8ea2b0 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -127,8 +127,11 @@ be, both are worth reporting. - Chrome's "started debugging this browser" banner is a browser safety control. It is intentional, and this project never hides it, suppresses it, or documents a setup step that does. Features that can run without the - debugger do so. When a feature attaches the debugger, the banner stays - visible for that attachment, and dismissing it stops the attachment. + debugger do so. `listTabs`, `readTab`, `navigateTab`, `softClick`, and + `softType` use ordinary extension APIs and do not call `chrome.debugger`, + `tabs.update({active:true})`, or `windows.update({focused:true})`. When a + feature attaches the debugger, the banner stays visible for that attachment, + and dismissing it stops the attachment. - Credential-bearing headers and secret-shaped strings are redacted before storage, not before display. - Request bodies are size-limited; log retention is bounded and client-supplied diff --git a/browser-tools-mcp/src/connector/api-policy.ts b/browser-tools-mcp/src/connector/api-policy.ts index 83137184..2f44182e 100644 --- a/browser-tools-mcp/src/connector/api-policy.ts +++ b/browser-tools-mcp/src/connector/api-policy.ts @@ -34,6 +34,11 @@ const AUDIT_TOOL: Record = { * a unit test, so a new tool cannot skip the filter by accident. */ export const API_TOOL_NAMES: readonly string[] = [ + "listTabs", + "readTab", + "navigateTab", + "softClick", + "softType", "listBrowserTabs", "getConsoleLogs", "getConsoleErrors", @@ -97,6 +102,11 @@ function toolsForRequest(method: string, path: string, query: Record; + /** Tabs chrome.tabs returns. Not the DevTools-connected list from listTabs(). */ + listChromeTabs(): Promise; + readChromeTab(options: { chromeTabId: number }): Promise; + /** Background navigate by chrome.tabs id, or a new background tab when chromeTabId is omitted. */ + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise; + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise; + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise; close(): Promise; } @@ -267,6 +292,7 @@ export interface CapabilityCheck { action: string; reason: string; liveUrl: string | null; + excludeOrigins: string[]; } interface ExtensionConnection { @@ -575,6 +601,82 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { + try { + res.json(await listChromeTabs()); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/read", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + if (typeof chromeTabId !== "number") { + res.status(400).json({ error: "chromeTabId is required" }); + return; + } + res.json(await readChromeTab({ chromeTabId })); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/navigate", async (req: Request, res: Response) => { + try { + const url = typeof req.body?.url === "string" ? req.body.url.trim() : ""; + if (!url) { + res.status(400).json({ error: "url is required" }); + return; + } + const chromeTabId = req.body?.chromeTabId; + res.json( + await navigateChromeTab({ + url, + ...(typeof chromeTabId === "number" ? { chromeTabId } : {}), + }) + ); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/soft-click", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + const selector = req.body?.selector; + if (typeof chromeTabId !== "number" || typeof selector !== "string") { + res.status(400).json({ error: "chromeTabId and selector are required" }); + return; + } + res.json(await softClickChromeTab({ chromeTabId, selector })); + } catch (error) { + respondWithError(res, error); + } + }); + + api.post("/chrome-tabs/soft-type", async (req: Request, res: Response) => { + try { + const chromeTabId = req.body?.chromeTabId; + const selector = req.body?.selector; + const text = req.body?.text; + if (typeof chromeTabId !== "number" || typeof selector !== "string" || typeof text !== "string") { + res.status(400).json({ error: "chromeTabId, selector, and text are required" }); + return; + } + res.json( + await softTypeChromeTab({ + chromeTabId, + selector, + text, + submit: req.body?.submit === true, + }) + ); + } catch (error) { + respondWithError(res, error); + } + }); + api.post("/navigate", async (req: Request, res: Response) => { try { const url = typeof req.body?.url === "string" ? req.body.url.trim() : ""; @@ -1048,6 +1150,16 @@ export async function createConnector(config: ConnectorConfig = {}): Promise connection.role === "worker" && connection.fromExtension && connection.ws.readyState === WebSocket.OPEN ); + workers.sort((a, b) => b.lastSeen - a.lastSeen); + return workers[0]; } function denyCheck(action: string, reason: string): CapabilityCheck { - return { allowed: false, action, reason, liveUrl: null }; + return { + allowed: false, + action, + reason, + liveUrl: null, + excludeOrigins: capabilityPolicy.excludeOrigins, + }; } async function checkCapability( action: CapabilityAction, - options: { tabId?: TabId; destinationUrl?: string; hideBanner?: boolean } = {} + options: { tabId?: TabId; destinationUrl?: string; hideBanner?: boolean; creatingTab?: boolean } = {} ): Promise { if (options.hideBanner === true) return denyCheck(action, GateReason.banner); if (excludeListInvalid) return denyCheck(action, GateReason.excludeInvalid); @@ -1598,18 +1722,103 @@ export async function createConnector(config: ConnectorConfig = {}): Promise { + const gate = await checkCapability("listTabs"); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "list-chrome-tabs", {}); + assertTabActionSafe(response); + return normalizeChromeTabListing(response, { ...capabilityPolicy, excludeOrigins: gate.excludeOrigins }); + } + + async function readChromeTab(options: { chromeTabId: number }): Promise { + const gate = await checkCapability("readTab", { tabId: options.chromeTabId }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "read-chrome-tab", { + chromeTabId: options.chromeTabId, + approvedUrl: gate.liveUrl, }); + assertTabActionSafe(response); + return parseChromeTabRead(options.chromeTabId, response["read"]); + } - return { allowed: decision.allowed, action, reason: decision.reason, liveUrl }; + async function navigateChromeTab(options: { + url: string; + chromeTabId?: number; + }): Promise { + const requestedUrl = parseHttpUrl(options.url.trim()).href; + const creating = options.chromeTabId == null; + const gate = await checkCapability("navigate", { + destinationUrl: requestedUrl, + ...(creating ? { creatingTab: true } : { tabId: options.chromeTabId }), + }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "navigate-chrome-tab", { + url: requestedUrl, + ...(creating + ? { create: true } + : { chromeTabId: options.chromeTabId, approvedUrl: gate.liveUrl }), + }); + return parseChromeNavigate(requestedUrl, response); + } + + async function softClickChromeTab(options: { + chromeTabId: number; + selector: string; + }): Promise { + return softInput("softClick", options); + } + + async function softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return softInput("softType", options); + } + + async function softInput( + action: "softClick" | "softType", + options: { chromeTabId: number; selector: string; text?: string; submit?: boolean } + ): Promise { + const gate = await checkCapability(action, { tabId: options.chromeTabId }); + if (!gate.allowed) throw new ExtensionRequestError(gate.reason); + const response = await requestFromExtension(requireWorker(), "soft-input", { + op: action === "softType" ? "type" : "click", + chromeTabId: options.chromeTabId, + selector: options.selector, + approvedUrl: gate.liveUrl, + ...(action === "softType" ? { text: options.text ?? "", submit: options.submit === true } : {}), + }); + return parseSoftInput(options.chromeTabId, response); } async function close(): Promise { @@ -1661,6 +1870,11 @@ export async function createConnector(config: ConnectorConfig = {}): Promise; refresh(options?: { tabId?: TabId }): Promise; navigate(options: { url: string; tabId?: TabId }): Promise; + listChromeTabs(): Promise; + readChromeTab(options: { chromeTabId: number }): Promise; + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise; + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise; + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise; storage(kinds: string[], options?: { tabId?: TabId }): Promise>; audit( category: AuditCategory, @@ -172,6 +188,31 @@ export class InProcessConnectorClient implements ConnectorClient { return this.#connector.navigateTab(options); } + listChromeTabs(): Promise { + return this.#connector.listChromeTabs(); + } + + readChromeTab(options: { chromeTabId: number }): Promise { + return this.#connector.readChromeTab(options); + } + + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise { + return this.#connector.navigateChromeTab(options); + } + + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise { + return this.#connector.softClickChromeTab(options); + } + + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return this.#connector.softTypeChromeTab(options); + } + async storage( kinds: string[], options: { tabId?: TabId } = {} @@ -300,6 +341,31 @@ export class HttpConnectorClient implements ConnectorClient { return this.#request("/api/navigate", { method: "POST", body: options }); } + listChromeTabs(): Promise { + return this.#request("/api/chrome-tabs"); + } + + readChromeTab(options: { chromeTabId: number }): Promise { + return this.#request("/api/chrome-tabs/read", { method: "POST", body: options }); + } + + navigateChromeTab(options: { url: string; chromeTabId?: number }): Promise { + return this.#request("/api/chrome-tabs/navigate", { method: "POST", body: options }); + } + + softClickChromeTab(options: { chromeTabId: number; selector: string }): Promise { + return this.#request("/api/chrome-tabs/soft-click", { method: "POST", body: options }); + } + + softTypeChromeTab(options: { + chromeTabId: number; + selector: string; + text: string; + submit?: boolean; + }): Promise { + return this.#request("/api/chrome-tabs/soft-type", { method: "POST", body: options }); + } + async storage( kinds: string[], options: { tabId?: TabId } = {} diff --git a/browser-tools-mcp/src/mcp/server.ts b/browser-tools-mcp/src/mcp/server.ts index 35ac4ee2..16a9c4dd 100644 --- a/browser-tools-mcp/src/mcp/server.ts +++ b/browser-tools-mcp/src/mcp/server.ts @@ -20,6 +20,13 @@ import { RestrictedPageError, restrictedPageToolText, } from "../restricted-page.js"; +import { + DEVTOOLS_TAB_ID, + DEVTOOLS_TAB_INPUT, + LIST_BROWSER_TABS_DESCRIPTION, + NAVIGATE_BROWSER_DESCRIPTION, +} from "../tabs/contract.js"; +import { TAB_TOOLS } from "../tabs/tools.js"; const log = createLogger("mcp"); @@ -144,7 +151,9 @@ const queryOutputShape = { tabId: z .union([z.number(), z.string()]) .nullable() - .describe("The tab these entries came from, or null when reading every tab"), + .describe( + "DevTools-connected tab id these entries came from, or null when reading every connected tab. Not a chromeTabId from listTabs." + ), url: z.string().describe("The page that tab is on"), otherTabs: z .number() @@ -160,11 +169,7 @@ const queryOutputShape = { const tabIdInput = z .union([z.number().int(), z.string()]) .optional() - .describe( - "Which browser tab to use, from listBrowserTabs. Omit to use the current tab — the " + - "one DevTools was most recently opened on, which is right in almost every session. " + - "Only pass this when a result reported otherTabs above 0 and you need a specific tab." - ); + .describe(DEVTOOLS_TAB_INPUT); const allTabsInput = z .boolean() @@ -264,26 +269,22 @@ function auditTool( } const TOOLS: ToolDefinition[] = [ + ...TAB_TOOLS, { name: "listBrowserTabs", register(server, client) { server.registerTool( "listBrowserTabs", { - title: "List browser tabs", - description: - "Every browser tab that currently has DevTools open, with the tabId you can pass to any other tool. " + - "Call this when a result reported otherTabs above 0, or when the user mentions a page other than the one you have been reading. " + - "The tab marked isCurrent is the one every other tool uses when you do not pass tabId. " + - "A tab on chrome://, DevTools, view-source, the Chrome Web Store, an extension page, or the PDF viewer " + - `is metadata only (access "metadata-only", "${RESTRICTED_PAGE_MESSAGE}") and cannot be scripted.`, + title: "List DevTools-connected tabs", + description: LIST_BROWSER_TABS_DESCRIPTION, outputSchema: { tabs: z.array(z.record(z.string(), z.unknown())), - currentTabId: z.union([z.number(), z.string()]).nullable(), + currentTabId: z.union([z.number(), z.string()]).nullable().describe(DEVTOOLS_TAB_ID), connectedTabs: z.number().int(), }, annotations: { - title: "List browser tabs", + title: "List DevTools-connected tabs", readOnlyHint: true, destructiveHint: false, idempotentHint: true, @@ -627,26 +628,20 @@ const TOOLS: ToolDefinition[] = [ server.registerTool( "navigateBrowser", { - title: "Navigate to a URL", - description: - "Loads a URL in the chosen browser tab without focusing it or attaching the debugger. " + - "Uses the tabId from listBrowserTabs. Requires the extension service worker, the popup " + - "switch, and --allow-input on browser-tools-mcp (browser-tools CLI: --allow-actions). " + - "chrome://, DevTools, view-source, the Chrome Web Store, and extension pages are refused. " + - "An http(s) PDF may load, then the tool fails because the viewer cannot be scripted. " + - `The error text is JSON with access "metadata-only" and message "${RESTRICTED_PAGE_MESSAGE}".`, + title: "Navigate a DevTools-connected tab", + description: NAVIGATE_BROWSER_DESCRIPTION, inputSchema: { url: z.string().describe("http(s) URL to load in the tab"), tabId: tabIdInput, }, outputSchema: { - tabId: z.union([z.number(), z.string()]), + tabId: z.union([z.number(), z.string()]).describe(DEVTOOLS_TAB_ID), requestedUrl: z.string(), finalUrl: z.string(), wasDiscarded: z.boolean(), }, annotations: { - title: "Navigate to a URL", + title: "Navigate a DevTools-connected tab", readOnlyHint: false, destructiveHint: false, idempotentHint: false, diff --git a/browser-tools-mcp/src/mcp/tool-invoke.ts b/browser-tools-mcp/src/mcp/tool-invoke.ts index 8d46ffc0..e9eb3441 100644 --- a/browser-tools-mcp/src/mcp/tool-invoke.ts +++ b/browser-tools-mcp/src/mcp/tool-invoke.ts @@ -8,6 +8,7 @@ import { } from "./resources.js"; import type { AuditCategory } from "../lighthouse/types.js"; import { RestrictedPageError, restrictedPageToolText } from "../restricted-page.js"; +import { invokeTabTool } from "../tabs/tools.js"; export type ToolContent = | { type: "text"; text: string } @@ -124,6 +125,9 @@ export async function invokeTool( client: ConnectorClient, args: Record = {} ): Promise { + const tabTool = await invokeTabTool(name, client, args); + if (tabTool) return tabTool; + switch (name) { case "listBrowserTabs": try { @@ -317,6 +321,11 @@ async function runAudit( /** Every registered MCP tool name must have an invoke implementation. */ export const INVOKABLE_TOOL_NAMES: readonly string[] = [ + "listTabs", + "readTab", + "navigateTab", + "softClick", + "softType", "listBrowserTabs", "getConsoleLogs", "getConsoleErrors", diff --git a/browser-tools-mcp/src/runtime.ts b/browser-tools-mcp/src/runtime.ts index b2d458b1..3dc5d68f 100644 --- a/browser-tools-mcp/src/runtime.ts +++ b/browser-tools-mcp/src/runtime.ts @@ -72,6 +72,21 @@ class UnavailableConnectorClient implements ConnectorClient { navigate(): Promise { return this.#fail(); } + listChromeTabs(): Promise { + return this.#fail(); + } + readChromeTab(): Promise { + return this.#fail(); + } + navigateChromeTab(): Promise { + return this.#fail(); + } + softClickChromeTab(): Promise { + return this.#fail(); + } + softTypeChromeTab(): Promise { + return this.#fail(); + } storage(): Promise { return this.#fail(); } diff --git a/browser-tools-mcp/src/tabs/contract.ts b/browser-tools-mcp/src/tabs/contract.ts new file mode 100644 index 00000000..7b1353be --- /dev/null +++ b/browser-tools-mcp/src/tabs/contract.ts @@ -0,0 +1,204 @@ +import { RESTRICTED_PAGE_MESSAGE } from "../restricted-page.js"; + +/** + * Tab-awareness contracts (AGE-584). + * + * Two id spaces, kept apart in every description: + * + * - A DevTools-connected tab id comes from listBrowserTabs. It is + * chrome.devtools.inspectedWindow.tabId for a tab whose DevTools page is + * connected to the connector. Pass it as `tabId` to the existing tools. + * - A chrome.tabs id comes from listTabs. It is chrome.tabs.Tab.id for a tab + * the browser returned. Pass it as `chromeTabId` to listTabs, readTab, + * navigateTab, softClick, and softType. + * + * Chrome often uses the same integer for both when DevTools is open on that + * tab. The tools still do not accept each other's ids: a DevTools-connected + * id only addresses a connected DevTools page, and a chrome.tabs id is only + * valid when listTabs returned it. + */ + +/** What listTabs is willing to claim. AGE-618 left Arc unmeasured. */ +export const TAB_COVERAGE = + "Tabs the browser exposes through chrome.tabs in the windows it returns. " + + "Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. " + + "Incognito is skipped. This is not every open tab."; + +export const DEVTOOLS_TAB_ID = + "DevTools-connected tab id from listBrowserTabs (the inspected tab whose DevTools page is connected). " + + "Not a chromeTabId from listTabs. Do not pass a chrome.tabs id here."; + +export const CHROME_TAB_ID = + "chrome.tabs id from listTabs (chrome.tabs.Tab.id). Not a DevTools-connected tabId from listBrowserTabs. " + + "Pass only an id listTabs returned."; + +export const LIST_BROWSER_TABS_DESCRIPTION = + "Every browser tab that currently has DevTools open, with the DevTools-connected tabId you can pass to the telemetry tools. " + + "These ids are not chromeTabId values from listTabs. This list is only tabs with DevTools open, not every open tab. " + + "Call this when a result reported otherTabs above 0, or when the user mentions a page other than the one you have been reading. " + + "The tab marked isCurrent is the one the DevTools tools use when you do not pass tabId. " + + "A tab on chrome://, DevTools, view-source, the Chrome Web Store, an extension page, or the PDF viewer " + + `is metadata only (access "metadata-only", "${RESTRICTED_PAGE_MESSAGE}") and cannot be scripted.`; + +export const DEVTOOLS_TAB_INPUT = + "DevTools-connected tab id from listBrowserTabs. Not a chromeTabId from listTabs. " + + "Omit to use the current tab — the one DevTools was most recently opened on, which is right in almost every session. " + + "Only pass this when a result reported otherTabs above 0 and you need a specific DevTools-connected tab."; + +export const NAVIGATE_BROWSER_DESCRIPTION = + "Loads a URL in a DevTools-connected tab without focusing it or attaching the debugger. " + + "tabId is a DevTools-connected id from listBrowserTabs, not a chromeTabId from listTabs. " + + "Requires the extension service worker, the popup switch, and --allow-input on browser-tools-mcp " + + "(browser-tools CLI: --allow-actions). Does not call chrome.tabs.update({active:true}) or chrome.windows.update({focused:true}). " + + "chrome://, DevTools, view-source, the Chrome Web Store, and extension pages are refused. " + + "An http(s) PDF may load, then the tool fails because the viewer cannot be scripted. " + + `The error text is JSON with access "metadata-only" and message "${RESTRICTED_PAGE_MESSAGE}".`; + +export const LIST_TABS_DESCRIPTION = + TAB_COVERAGE + + " Each tab includes title, URL, site, window, last viewed, and whether it is asleep (discarded) or frozen. " + + "chromeTabId is a chrome.tabs id, not a DevTools-connected tabId from listBrowserTabs. " + + "Uses chrome.tabs and chrome.windows only. Does not attach the debugger and does not change focus. " + + "Needs the extension popup switch. The exclude list, empty by default, drops matching origins."; + +export const READ_TAB_DESCRIPTION = + "Reads headings, a short excerpt, and a compact snapshot of a tab from listTabs, without DevTools and without the debugger. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "Private details are stripped in the browser before the result leaves the page. " + + "An asleep (discarded) tab is reported as asleep and is not reloaded. A frozen tab is skipped. " + + "chrome:// pages, the Chrome Web Store, and the PDF viewer cannot be read. " + + "Needs the popup switch and host access for that site. Does not change focus."; + +export const NAVIGATE_TAB_DESCRIPTION = + "Loads a URL in the background with chrome.tabs, without DevTools and without the debugger. " + + "Pass chromeTabId from listTabs to update that tab, or omit it to open a new background tab. " + + "chromeTabId is not a DevTools-connected tabId from listBrowserTabs. " + + "Limited to the visible window until Arc Spaces are measured: a tab in another window is refused, and nothing switches window or Space. " + + "Never activates the tab or focuses the window. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules. " + + "Reports the final URL, whether an asleep tab was woken (wasDiscarded), and any tab or popup the page opened."; + +export const SOFT_CLICK_DESCRIPTION = + "Clicks an element in a tab from listTabs by dispatching untrusted pointer events. Does not attach the debugger and does not change focus. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "A submit control uses form.requestSubmit() rather than form.submit(). " + + "The result is outcome \"worked\" or \"needs a real gesture\" with a reason (file picker, clipboard, popup, fullscreen, " + + "the site checks isTrusted, anti-bot check, Google Docs or canvas app, or UI that needs the page drawn). " + + "A failed action is never reported as worked. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules."; + +export const SOFT_TYPE_DESCRIPTION = + "Types into an element in a tab from listTabs without the debugger and without changing focus. " + + "chromeTabId is a chrome.tabs id from listTabs, not a DevTools-connected tabId from listBrowserTabs. " + + "Ordinary inputs use the native value setter, then input and change events, so React and Vue fields update. " + + "Rich editors (contenteditable, ProseMirror, Lexical) are focused in the page and receive execCommand('insertText'). " + + "Pass submit true to submit the surrounding form with requestSubmit(). " + + "The result is outcome \"worked\" or \"needs a real gesture\" with a reason. A failed action is never reported as worked. " + + "Gated like input: popup switch, --allow-input (browser-tools CLI: --allow-actions), and the same origin rules."; + +export const SOFT_OUTCOMES = ["worked", "needs a real gesture"] as const; +export type SoftOutcome = (typeof SOFT_OUTCOMES)[number]; + +export const GESTURE_REASONS = [ + "file picker", + "clipboard", + "popup", + "fullscreen", + "the site checks isTrusted", + "anti-bot check", + "Google Docs or canvas app", + "UI that needs the page drawn", +] as const; +export type GestureReason = (typeof GESTURE_REASONS)[number]; + +export interface ChromeTabView { + chromeTabId: number; + windowId: number; + title: string; + url: string; + site: string; + active: boolean; + pinned: boolean; + /** chrome.tabs discarded. Asleep. Not reloaded by a read. */ + discarded: boolean; + frozen: boolean; + /** chrome.tabs lastAccessed, milliseconds, or null when the browser omitted it. */ + lastAccessed: number | null; + audible: boolean; + status: string; + index: number; +} + +export interface ChromeWindowView { + windowId: number; + focused: boolean; + type: string; + incognito: false; + tabs: ChromeTabView[]; +} + +export interface ChromeTabListing { + coverage: string; + visibleWindowId: number | null; + windows: ChromeWindowView[]; +} + +export interface ChromeTabHeading { + level: number; + text: string; +} + +export interface ChromeTabSnapshotNode { + depth: number; + role: string; + name: string; +} + +export interface ChromeTabRead { + chromeTabId: number; + url: string; + title: string; + site: string; + asleep: boolean; + frozen: boolean; + /** Set when the tab was not read. "frozen" or a short reason. */ + skipped: string | null; + headings: ChromeTabHeading[]; + excerpt: string; + snapshot: ChromeTabSnapshotNode[]; + hostAccess: boolean; +} + +export interface OpenedTab { + chromeTabId: number; + url: string; + windowId: number; + active: boolean; +} + +export interface SafetyCounts { + debuggerCalls: number; + focusChanges: number; +} + +export interface ChromeNavigateResult { + chromeTabId: number; + requestedUrl: string; + finalUrl: string; + wasDiscarded: boolean; + created: boolean; + visibleWindowId: number; + openedTabs: OpenedTab[]; + safety: SafetyCounts; +} + +export interface SoftInputResult { + chromeTabId: number; + outcome: SoftOutcome; + reason: GestureReason | null; + detail: string; + /** Synthetic events are never trusted. Always false. */ + trusted: false; +} + +export const TAB_TOOL_NAMES = ["listTabs", "readTab", "navigateTab", "softClick", "softType"] as const; diff --git a/browser-tools-mcp/src/tabs/listing.ts b/browser-tools-mcp/src/tabs/listing.ts new file mode 100644 index 00000000..773a9cd9 --- /dev/null +++ b/browser-tools-mcp/src/tabs/listing.ts @@ -0,0 +1,202 @@ +import { tabListed, type GatePolicy } from "../gates/capability.js"; +import { originOf } from "../lighthouse/destination.js"; +import { redactSecretsInString } from "../util/redact.js"; +import { + GESTURE_REASONS, + TAB_COVERAGE, + type ChromeNavigateResult, + type ChromeTabHeading, + type ChromeTabListing, + type ChromeTabRead, + type ChromeTabSnapshotNode, + type ChromeTabView, + type ChromeWindowView, + type GestureReason, + type OpenedTab, + type SafetyCounts, + type SoftInputResult, + type SoftOutcome, +} from "./contract.js"; + +function asRecord(value: unknown): Record | null { + return value !== null && typeof value === "object" ? (value as Record) : null; +} + +function finiteNumber(value: unknown): number | null { + return typeof value === "number" && Number.isFinite(value) ? value : null; +} + +export function siteOf(url: string): string { + return originOf(url) ?? ""; +} + +/** Drops incognito and excluded origins. Secrets in titles and URLs are redacted. */ +export function normalizeChromeTabListing(payload: unknown, policy: GatePolicy): ChromeTabListing { + const root = asRecord(payload) ?? {}; + const visibleWindowId = finiteNumber(root["visibleWindowId"]); + const rawWindows = Array.isArray(root["windows"]) ? root["windows"] : []; + const windows: ChromeWindowView[] = []; + + for (const rawWindow of rawWindows) { + const window = asRecord(rawWindow); + if (!window || window["incognito"] === true) continue; + const windowId = finiteNumber(window["windowId"]); + if (windowId === null) continue; + const rawTabs = Array.isArray(window["tabs"]) ? window["tabs"] : []; + const tabs: ChromeTabView[] = []; + for (const rawTab of rawTabs) { + const tab = asRecord(rawTab); + if (!tab || tab["incognito"] === true) continue; + const chromeTabId = finiteNumber(tab["chromeTabId"]); + if (chromeTabId === null) continue; + const url = redactSecretsInString(typeof tab["url"] === "string" ? tab["url"] : ""); + if (!tabListed(url, policy)) continue; + tabs.push({ + chromeTabId, + windowId: finiteNumber(tab["windowId"]) ?? windowId, + title: redactSecretsInString(typeof tab["title"] === "string" ? tab["title"] : "").slice(0, 300), + url, + site: siteOf(url), + active: tab["active"] === true, + pinned: tab["pinned"] === true, + discarded: tab["discarded"] === true, + frozen: tab["frozen"] === true, + lastAccessed: finiteNumber(tab["lastAccessed"]), + audible: tab["audible"] === true, + status: typeof tab["status"] === "string" ? tab["status"] : "", + index: finiteNumber(tab["index"]) ?? 0, + }); + } + windows.push({ + windowId, + focused: window["focused"] === true, + type: typeof window["type"] === "string" ? window["type"] : "normal", + incognito: false, + tabs, + }); + } + + return { coverage: TAB_COVERAGE, visibleWindowId, windows }; +} + +export function readSafety(payload: Record): SafetyCounts { + const safety = asRecord(payload["safety"]); + return { + debuggerCalls: finiteNumber(safety?.["debuggerCalls"]) ?? 0, + focusChanges: finiteNumber(safety?.["focusChanges"]) ?? 0, + }; +} + +export function assertTabActionSafe(payload: Record): SafetyCounts { + const safety = readSafety(payload); + if (safety.debuggerCalls > 0 || safety.focusChanges > 0) { + throw new Error("The tab action tried to attach the debugger or change focus, so it was refused."); + } + return safety; +} + +function text(value: unknown, max: number): string { + return redactSecretsInString(typeof value === "string" ? value : "").slice(0, max); +} + +export function parseChromeTabRead(chromeTabId: number, value: unknown): ChromeTabRead { + const read = asRecord(value) ?? {}; + const url = text(read["url"], 2000); + const headings: ChromeTabHeading[] = []; + if (Array.isArray(read["headings"])) { + for (const item of read["headings"].slice(0, 30)) { + const heading = asRecord(item); + if (!heading) continue; + const level = finiteNumber(heading["level"]); + headings.push({ + level: level !== null && level >= 1 && level <= 6 ? level : 1, + text: text(heading["text"], 200), + }); + } + } + const snapshot: ChromeTabSnapshotNode[] = []; + if (Array.isArray(read["snapshot"])) { + for (const item of read["snapshot"].slice(0, 60)) { + const node = asRecord(item); + if (!node) continue; + snapshot.push({ + depth: finiteNumber(node["depth"]) ?? 0, + role: text(node["role"], 40), + name: text(node["name"], 80), + }); + } + } + const skipped = typeof read["skipped"] === "string" && read["skipped"] ? read["skipped"].slice(0, 120) : null; + return { + chromeTabId, + url, + title: text(read["title"], 300), + site: siteOf(url), + asleep: read["asleep"] === true, + frozen: read["frozen"] === true, + skipped, + headings, + excerpt: text(read["excerpt"], 800), + snapshot, + hostAccess: read["hostAccess"] === true, + }; +} + +function parseOpenedTabs(value: unknown): OpenedTab[] { + if (!Array.isArray(value)) return []; + const opened: OpenedTab[] = []; + for (const item of value.slice(0, 20)) { + const tab = asRecord(item); + if (!tab) continue; + const chromeTabId = finiteNumber(tab["chromeTabId"]); + const windowId = finiteNumber(tab["windowId"]); + if (chromeTabId === null || windowId === null) continue; + opened.push({ + chromeTabId, + windowId, + url: text(tab["url"], 2000), + active: tab["active"] === true, + }); + } + return opened; +} + +export function parseChromeNavigate(requestedUrl: string, payload: Record): ChromeNavigateResult { + const safety = assertTabActionSafe(payload); + const chromeTabId = finiteNumber(payload["chromeTabId"]); + const visibleWindowId = finiteNumber(payload["visibleWindowId"]); + if (chromeTabId === null || visibleWindowId === null) { + throw new Error("The extension returned an incomplete navigation result."); + } + return { + chromeTabId, + requestedUrl, + finalUrl: text(payload["finalUrl"], 2000) || requestedUrl, + wasDiscarded: payload["wasDiscarded"] === true, + created: payload["created"] === true, + visibleWindowId, + openedTabs: parseOpenedTabs(payload["openedTabs"]), + safety, + }; +} + +export function parseSoftInput(chromeTabId: number, payload: Record): SoftInputResult { + assertTabActionSafe(payload); + const outcome = payload["outcome"]; + if (outcome !== "worked" && outcome !== "needs a real gesture") { + throw new Error("Soft input did not report worked or needs a real gesture."); + } + const reasonRaw = payload["reason"]; + const reason = GESTURE_REASONS.find((entry) => entry === reasonRaw) ?? null; + if (outcome === "needs a real gesture" && !reason) { + throw new Error("Soft input refused without a reason."); + } + const parsed: SoftInputResult = { + chromeTabId, + outcome: outcome as SoftOutcome, + reason: outcome === "worked" ? null : (reason as GestureReason), + detail: text(payload["detail"], 300), + trusted: false, + }; + return parsed; +} diff --git a/browser-tools-mcp/src/tabs/tools.ts b/browser-tools-mcp/src/tabs/tools.ts new file mode 100644 index 00000000..6b204f6d --- /dev/null +++ b/browser-tools-mcp/src/tabs/tools.ts @@ -0,0 +1,311 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; + +import type { ConnectorClient } from "../mcp/client.js"; +import { + CHROME_TAB_ID, + LIST_TABS_DESCRIPTION, + NAVIGATE_TAB_DESCRIPTION, + READ_TAB_DESCRIPTION, + SOFT_CLICK_DESCRIPTION, + SOFT_TYPE_DESCRIPTION, +} from "./contract.js"; + +type TextContent = { type: "text"; text: string }; + +export type TabToolResult = { + content: TextContent[]; + structuredContent?: Record; + isError?: boolean; +}; + +function ok(structured: Record): TabToolResult { + return { + content: [{ type: "text", text: JSON.stringify(structured, null, 2) }], + structuredContent: structured, + }; +} + +function fail(error: unknown): TabToolResult { + const message = error instanceof Error ? error.message : String(error); + return { content: [{ type: "text", text: message }], isError: true }; +} + +const chromeTabIdInput = z.number().int().positive().describe(CHROME_TAB_ID); + +const selectorInput = z + .string() + .min(1) + .max(500) + .describe("CSS selector for the element in that tab. Not a DevTools-connected tab id."); + +const safetyShape = { + debuggerCalls: z.number().int(), + focusChanges: z.number().int(), +}; + +const chromeTabShape = { + chromeTabId: z.number().int().describe(CHROME_TAB_ID), + windowId: z.number().int(), + title: z.string(), + url: z.string(), + site: z.string().describe("Origin of the tab, or empty when the URL is not http(s)."), + active: z.boolean(), + pinned: z.boolean(), + discarded: z.boolean().describe("Asleep. A read reports this and does not reload the tab."), + frozen: z.boolean(), + lastAccessed: z.number().nullable().describe("When the tab was last viewed, or null if the browser omitted it."), + audible: z.boolean(), + status: z.string(), + index: z.number().int(), +}; + +const windowShape = { + windowId: z.number().int(), + focused: z.boolean(), + type: z.string(), + incognito: z.literal(false), + tabs: z.array(z.object(chromeTabShape)), +}; + +export interface TabToolDefinition { + name: string; + register(server: McpServer, client: ConnectorClient): void; +} + +function chromeTabIdFrom(args: Record): number | undefined { + const value = args["chromeTabId"]; + return typeof value === "number" ? value : undefined; +} + +/** + * Runs one chrome.tabs tool. Returns null for every other tool name so the + * MCP server and the CLI share this path. + */ +export async function invokeTabTool( + name: string, + client: ConnectorClient, + args: Record = {} +): Promise { + try { + switch (name) { + case "listTabs": + return ok((await client.listChromeTabs()) as unknown as Record); + case "readTab": { + const chromeTabId = chromeTabIdFrom(args); + if (chromeTabId === undefined) return fail(new Error("chromeTabId is required")); + return ok((await client.readChromeTab({ chromeTabId })) as unknown as Record); + } + case "navigateTab": { + const url = args["url"]; + if (typeof url !== "string" || !url.trim()) return fail(new Error("url is required")); + const chromeTabId = chromeTabIdFrom(args); + return ok( + (await client.navigateChromeTab({ + url: url.trim(), + ...(chromeTabId !== undefined ? { chromeTabId } : {}), + })) as unknown as Record + ); + } + case "softClick": { + const chromeTabId = chromeTabIdFrom(args); + const selector = args["selector"]; + if (chromeTabId === undefined || typeof selector !== "string") { + return fail(new Error("chromeTabId and selector are required")); + } + return ok( + (await client.softClickChromeTab({ chromeTabId, selector })) as unknown as Record + ); + } + case "softType": { + const chromeTabId = chromeTabIdFrom(args); + const selector = args["selector"]; + const text = args["text"]; + if (chromeTabId === undefined || typeof selector !== "string" || typeof text !== "string") { + return fail(new Error("chromeTabId, selector, and text are required")); + } + return ok( + (await client.softTypeChromeTab({ + chromeTabId, + selector, + text, + submit: args["submit"] === true, + })) as unknown as Record + ); + } + default: + return null; + } + } catch (error) { + return fail(error); + } +} + +export const TAB_TOOLS: TabToolDefinition[] = [ + { + name: "listTabs", + register(server, client) { + server.registerTool( + "listTabs", + { + title: "List tabs chrome.tabs can see", + description: LIST_TABS_DESCRIPTION, + outputSchema: { + coverage: z.string(), + visibleWindowId: z.number().int().nullable(), + windows: z.array(z.object(windowShape)), + }, + annotations: { + title: "List tabs chrome.tabs can see", + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + }, + async () => invokeTabTool("listTabs", client, {}) as Promise + ); + }, + }, + { + name: "readTab", + register(server, client) { + server.registerTool( + "readTab", + { + title: "Read a background tab", + description: READ_TAB_DESCRIPTION, + inputSchema: { chromeTabId: chromeTabIdInput }, + outputSchema: { + chromeTabId: z.number().int(), + url: z.string(), + title: z.string(), + site: z.string(), + asleep: z.boolean(), + frozen: z.boolean(), + skipped: z.string().nullable(), + headings: z.array(z.object({ level: z.number().int(), text: z.string() })), + excerpt: z.string(), + snapshot: z.array(z.object({ depth: z.number().int(), role: z.string(), name: z.string() })), + hostAccess: z.boolean(), + }, + annotations: { + title: "Read a background tab", + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("readTab", client, args) as Promise + ); + }, + }, + { + name: "navigateTab", + register(server, client) { + server.registerTool( + "navigateTab", + { + title: "Navigate in the background", + description: NAVIGATE_TAB_DESCRIPTION, + inputSchema: { + url: z.string().describe("http(s) URL to load without focusing the tab or the window."), + chromeTabId: chromeTabIdInput + .optional() + .describe(CHROME_TAB_ID + " Omit to open a new background tab in the visible window."), + }, + outputSchema: { + chromeTabId: z.number().int(), + requestedUrl: z.string(), + finalUrl: z.string(), + wasDiscarded: z.boolean(), + created: z.boolean(), + visibleWindowId: z.number().int(), + openedTabs: z.array( + z.object({ + chromeTabId: z.number().int(), + url: z.string(), + windowId: z.number().int(), + active: z.boolean(), + }) + ), + safety: z.object(safetyShape), + }, + annotations: { + title: "Navigate in the background", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("navigateTab", client, args) as Promise + ); + }, + }, + { + name: "softClick", + register(server, client) { + server.registerTool( + "softClick", + { + title: "Soft click", + description: SOFT_CLICK_DESCRIPTION, + inputSchema: { chromeTabId: chromeTabIdInput, selector: selectorInput }, + outputSchema: { + chromeTabId: z.number().int(), + outcome: z.enum(["worked", "needs a real gesture"]), + reason: z.string().nullable(), + detail: z.string(), + trusted: z.literal(false), + }, + annotations: { + title: "Soft click", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("softClick", client, args) as Promise + ); + }, + }, + { + name: "softType", + register(server, client) { + server.registerTool( + "softType", + { + title: "Soft type", + description: SOFT_TYPE_DESCRIPTION, + inputSchema: { + chromeTabId: chromeTabIdInput, + selector: selectorInput, + text: z.string().max(20000).describe("Text to insert. Password fields are refused."), + submit: z + .boolean() + .optional() + .describe("After a successful type, submit the surrounding form with requestSubmit()."), + }, + outputSchema: { + chromeTabId: z.number().int(), + outcome: z.enum(["worked", "needs a real gesture"]), + reason: z.string().nullable(), + detail: z.string(), + trusted: z.literal(false), + }, + annotations: { + title: "Soft type", + readOnlyHint: false, + destructiveHint: false, + idempotentHint: false, + openWorldHint: true, + }, + }, + async (args) => invokeTabTool("softType", client, args) as Promise + ); + }, + }, +]; diff --git a/browser-tools-mcp/src/tools-cli.ts b/browser-tools-mcp/src/tools-cli.ts index 193dc550..03c5d347 100644 --- a/browser-tools-mcp/src/tools-cli.ts +++ b/browser-tools-mcp/src/tools-cli.ts @@ -96,7 +96,9 @@ Resource commands: Examples: browser-tools getConnectionStatus browser-tools getConsoleLogs '{"limit":20}' + browser-tools listTabs browser-tools --allow-actions navigateBrowser '{"url":"http://localhost:3000/","tabId":1}' + browser-tools --allow-actions navigateTab '{"url":"http://127.0.0.1:3000/","chromeTabId":4}' `; } diff --git a/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts new file mode 100644 index 00000000..ec3e50fa --- /dev/null +++ b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts @@ -0,0 +1,213 @@ +import { afterAll, beforeAll, describe, expect, it } from "vitest"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { chromium, type BrowserContext, type Page } from "playwright"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +import { createConnector, type Connector } from "../../src/connector/connector"; +import { InProcessConnectorClient } from "../../src/mcp/client"; +import { createMcpServer } from "../../src/mcp/server"; +import { browserAvailability } from "../helpers/browser-available"; +import { e2eChromiumOptions } from "../helpers/e2e-chromium"; +import { startFixtureServer, type FixtureServer } from "../fixtures/server"; +import { waitForPortFree } from "../helpers/port"; + +/** + * Tab awareness with DevTools closed. + * + * The other end-to-end file opens DevTools, which attaches chrome.debugger on + * purpose. This one must not: list and navigate go through chrome.tabs only, + * and the tab the user is looking at stays active. + */ +const browserSupport = await browserAvailability(); +if (!browserSupport.usable) console.warn(`\n SKIPPED: ${browserSupport.reason}\n`); + +const extensionPath = path.resolve(fileURLToPath(new URL("../../../chrome-extension", import.meta.url))); + +let connector: Connector; +let fixture: FixtureServer; +let context: BrowserContext | null = null; +let client: Client; +let closeServer: (() => Promise) | null = null; +let userDataDir: string; +let page: Page; + +beforeAll(async () => { + userDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "bt-e2e-tabs-")); + fixture = await startFixtureServer(); + await waitForPortFree(3026); + connector = await createConnector({ + port: 3026, + screenshotDir: fs.mkdtempSync(path.join(os.tmpdir(), "bt-e2e-tabs-shots-")), + allowInput: true, + heartbeatIntervalMs: 30_000, + }); + + const { server } = createMcpServer({ client: new InProcessConnectorClient(connector) }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + client = new Client({ name: "e2e-tabs", version: "1.0.0" }); + await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]); + closeServer = async () => { + await client.close(); + await server.close(); + }; + + if (!browserSupport.usable) return; + + context = await chromium.launchPersistentContext(userDataDir, { + ...browserSupport.launchOptions, + viewport: { width: 1100, height: 800 }, + ...e2eChromiumOptions([ + `--disable-extensions-except=${extensionPath}`, + `--load-extension=${extensionPath}`, + "--no-first-run", + "--no-default-browser-check", + ]), + }); + page = context.pages()[0] ?? (await context.newPage()); + await page.goto(fixture.url, { waitUntil: "domcontentloaded" }); +}, 240_000); + +afterAll(async () => { + await closeServer?.(); + await context?.close().catch(() => {}); + await connector?.close(); + await fixture?.close(); + fs.rmSync(userDataDir, { recursive: true, force: true }); +}); + +async function extensionWorker() { + const existing = context!.serviceWorkers().find((worker) => worker.url().includes("chrome-extension://")); + if (existing) return existing; + return context!.waitForEvent("serviceworker", { timeout: 30_000 }); +} + +async function callTool(name: string, args: Record = {}) { + const result = await client.callTool({ name, arguments: args }); + const text = result.content.find((block) => block.type === "text"); + const body = text && "text" in text ? text.text : ""; + if (result.isError) throw new Error(body); + return JSON.parse(body) as Record; +} + +async function browserState() { + const sw = await extensionWorker(); + return sw.evaluate(async () => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + const [active] = await chromeApi.tabs.query({ active: true, lastFocusedWindow: true }); + const safety = (globalThis as unknown as { __btmcpSafety?: { snapshot: () => { debuggerCalls: number; focusChanges: number } } }).__btmcpSafety?.snapshot() ?? { + debuggerCalls: -1, + focusChanges: -1, + }; + return { + activeId: active && active.id, + activeUrl: active && active.url, + windowId: active && active.windowId, + safety, + }; + }); +} + +/** True only if this extension has called chrome.debugger.attach on the tab. */ +async function extensionDebuggerAttached(tabId: number): Promise { + const sw = await extensionWorker(); + return sw.evaluate(async (id: number) => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + try { + await new Promise((resolve, reject) => { + chromeApi.debugger.sendCommand({ tabId: id }, "Runtime.evaluate", { expression: "1" }, () => { + const message = chromeApi.runtime.lastError?.message; + if (message) reject(new Error(message)); + else resolve(true); + }); + }); + return true; + } catch { + return false; + } + }, tabId); +} + +describe("tab awareness without DevTools", () => { + it.skipIf(!browserSupport.usable)( + "lists, navigates, reads, and soft-inputs without attaching the debugger or stealing focus", + async () => { + const sw = await extensionWorker(); + await sw.evaluate(async () => { + const chromeApi = (globalThis as unknown as { chrome: any }).chrome; + await chromeApi.storage.session.set({ btmcpPopupSwitch: true }); + }); + + let listing: Record | undefined; + const deadline = Date.now() + 45_000; + let lastError = ""; + while (Date.now() < deadline) { + try { + listing = await callTool("listTabs"); + const blob = JSON.stringify(listing); + if (blob.includes(String(fixture.port))) break; + } catch (error) { + lastError = error instanceof Error ? error.message : String(error); + } + await new Promise((resolve) => setTimeout(resolve, 300)); + } + if (!listing || !JSON.stringify(listing).includes(String(fixture.port))) { + throw new Error(`listTabs did not see the fixture. Last error: ${lastError}`); + } + + expect(listing["coverage"]).toMatch(/This is not every open tab/); + expect(String(listing["coverage"])).not.toMatch(/every tab you have|all open tabs/); + + const before = await browserState(); + expect(before.safety.debuggerCalls).toBe(0); + expect(before.safety.focusChanges).toBe(0); + + const opened = await callTool("navigateTab", { url: `${fixture.url}form` }); + expect(opened["created"]).toBe(true); + expect(opened["safety"]).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + const chromeTabId = opened["chromeTabId"] as number; + + const afterNavigate = await browserState(); + expect(afterNavigate.activeId).toBe(before.activeId); + expect(afterNavigate.activeUrl).toBe(before.activeUrl); + expect(afterNavigate.windowId).toBe(before.windowId); + expect(afterNavigate.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + expect(page.url()).toBe(fixture.url); + + const read = await callTool("readTab", { chromeTabId }); + expect(read["asleep"]).toBe(false); + expect(JSON.stringify(read["headings"])).toContain("Soft form"); + expect(JSON.stringify(read)).not.toContain("user@example.com"); + + const file = await callTool("softClick", { chromeTabId, selector: "#file" }); + expect(file).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + + const typed = await callTool("softType", { + chromeTabId, + selector: "#name", + text: "Ada", + submit: true, + }); + expect(typed).toMatchObject({ outcome: "worked", trusted: false }); + + const settled = await browserState(); + expect(settled.activeId).toBe(before.activeId); + expect(settled.activeUrl).toBe(before.activeUrl); + expect(settled.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + + const again = await callTool("listTabs"); + const tabs = JSON.stringify(again); + expect(tabs).toContain("Form result"); + expect(tabs).toContain(String(before.activeId)); + + // After the product path. sendCommand counts as a debugger call, so this + // stays last. A miss means the extension never attached. + expect(await extensionDebuggerAttached(chromeTabId)).toBe(false); + expect(await extensionDebuggerAttached(before.activeId as number)).toBe(false); + }, + 180_000 + ); +}); diff --git a/browser-tools-mcp/test/fixtures/server.ts b/browser-tools-mcp/test/fixtures/server.ts index f6bc406e..b7fa75d7 100644 --- a/browser-tools-mcp/test/fixtures/server.ts +++ b/browser-tools-mcp/test/fixtures/server.ts @@ -118,6 +118,29 @@ export async function startFixtureServer(): Promise { return; } + if (url === "/form" || url.startsWith("/form?")) { + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }); + res.end(` + Soft form + +

Soft form

+
+ + +
+ +
+

user@example.com

+ `); + return; + } + + if (url.startsWith("/form-result")) { + res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }); + res.end("Form result

Form result

"); + return; + } + if (url === "/image.png") { res.writeHead(200, { "Content-Type": "image/png" }); res.end( diff --git a/browser-tools-mcp/test/helpers/fake-extension.ts b/browser-tools-mcp/test/helpers/fake-extension.ts index d2931ad2..372b0ff7 100644 --- a/browser-tools-mcp/test/helpers/fake-extension.ts +++ b/browser-tools-mcp/test/helpers/fake-extension.ts @@ -15,6 +15,10 @@ export interface FakeExtensionOptions { onScreenshot?: (msg: any) => Promise | unknown; onRefresh?: (msg: any) => Promise | unknown; onNavigate?: (msg: any) => Promise | unknown; + onListChromeTabs?: (msg: any) => Promise | unknown; + onReadChromeTab?: (msg: any) => Promise | unknown; + onNavigateChromeTab?: (msg: any) => Promise | unknown; + onSoftInput?: (msg: any) => Promise | unknown; onStorage?: (msg: any) => Promise | unknown; /** `worker` answers capability probes and is not a DevTools tab. */ role?: "devtools" | "worker"; @@ -110,10 +114,73 @@ export class FakeExtension { const custom = this.#options.onNavigate; const payload = custom ? await custom(msg) - : { ok: true, finalUrl: msg.url, wasDiscarded: false }; + : { ok: true, finalUrl: msg.url, wasDiscarded: false, safety: { debuggerCalls: 0, focusChanges: 0 } }; this.send({ type: "navigate-result", requestId: msg.requestId, ...(payload as object) }); break; } + case "list-chrome-tabs": { + const custom = this.#options.onListChromeTabs; + const payload = custom + ? await custom(msg) + : { ok: true, visibleWindowId: 1, windows: [], safety: { debuggerCalls: 0, focusChanges: 0 } }; + this.send({ type: "chrome-tabs-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "read-chrome-tab": { + const custom = this.#options.onReadChromeTab; + const payload = custom + ? await custom(msg) + : { + ok: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + read: { + url: "http://127.0.0.1/", + title: "", + asleep: false, + frozen: false, + skipped: null, + headings: [], + excerpt: "", + snapshot: [], + hostAccess: true, + }, + }; + this.send({ type: "chrome-tab-read-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "navigate-chrome-tab": { + const custom = this.#options.onNavigateChromeTab; + const payload = custom + ? await custom(msg) + : { + ok: true, + chromeTabId: msg.chromeTabId ?? 1, + finalUrl: msg.url, + wasDiscarded: false, + created: msg.create === true, + visibleWindowId: 1, + openedTabs: [], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }; + this.send({ type: "navigate-chrome-result", requestId: msg.requestId, ...(payload as object) }); + break; + } + case "soft-input": { + const custom = this.#options.onSoftInput; + const payload = custom + ? await custom(msg) + : { + ok: true, + chromeTabId: msg.chromeTabId, + outcome: "worked", + reason: null, + detail: "ok", + trusted: false, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }; + this.send({ type: "soft-input-result", requestId: msg.requestId, ...(payload as object) }); + break; + } case "get-storage": { const custom = this.#options.onStorage; const payload = custom diff --git a/browser-tools-mcp/test/integration/mcp-server.test.ts b/browser-tools-mcp/test/integration/mcp-server.test.ts index 2efdc3c3..de18dc93 100644 --- a/browser-tools-mcp/test/integration/mcp-server.test.ts +++ b/browser-tools-mcp/test/integration/mcp-server.test.ts @@ -71,7 +71,12 @@ describe("tool registration", () => { "getPageInfo", "getSelectedElement", "listBrowserTabs", + "listTabs", "navigateBrowser", + "navigateTab", + "readTab", + "softClick", + "softType", "refreshBrowser", "runAccessibilityAudit", "runBestPracticesAudit", @@ -103,6 +108,8 @@ describe("tool registration", () => { "getSelectedElement", "getPageInfo", "getConnectionStatus", + "listTabs", + "readTab", ]) { expect(byName.get(name)?.annotations?.readOnlyHint, name).toBe(true); } @@ -112,6 +119,9 @@ describe("tool registration", () => { const { tools } = await client.listTools(); const byName = new Map(tools.map((t) => [t.name, t])); + expect(byName.get("navigateTab")?.annotations?.readOnlyHint).toBe(false); + expect(byName.get("softClick")?.annotations?.readOnlyHint).toBe(false); + expect(byName.get("softType")?.annotations?.readOnlyHint).toBe(false); expect(byName.get("wipeLogs")?.annotations?.readOnlyHint).toBe(false); expect(byName.get("wipeLogs")?.annotations?.destructiveHint).toBe(true); expect(byName.get("refreshBrowser")?.annotations?.readOnlyHint).toBe(false); diff --git a/browser-tools-mcp/test/integration/tab-awareness.test.ts b/browser-tools-mcp/test/integration/tab-awareness.test.ts new file mode 100644 index 00000000..747e3cf4 --- /dev/null +++ b/browser-tools-mcp/test/integration/tab-awareness.test.ts @@ -0,0 +1,231 @@ +import { afterEach, describe, expect, it } from "vitest"; +import os from "node:os"; +import path from "node:path"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; + +import { createConnector } from "../../src/connector/connector"; +import { InProcessConnectorClient } from "../../src/mcp/client"; +import { createMcpServer } from "../../src/mcp/server"; +import { invokeTool } from "../../src/mcp/tool-invoke"; +import { TAB_COVERAGE } from "../../src/tabs/contract"; +import { GateReason } from "../../src/gates/capability"; +import { FakeExtension } from "../helpers/fake-extension"; + +describe("chrome.tabs tools", () => { + let connector: Awaited> | undefined; + let worker: FakeExtension | undefined; + let devtools: FakeExtension | undefined; + let probePopup = false; + + afterEach(async () => { + await devtools?.close(); + await worker?.close(); + await connector?.close(); + probePopup = false; + }); + + async function start(allowInput: boolean) { + const screenshotDir = path.join(os.tmpdir(), `bt-tabs-${Date.now()}-${Math.random()}`); + connector = await createConnector({ port: 0, screenshotDir, allowInput }); + worker = new FakeExtension({ + port: connector.port, + role: "worker", + onCapabilityProbe: () => ({ + popupEnabled: probePopup, + panelEnabled: false, + liveUrl: "http://127.0.0.1:3000/app", + excludeOrigins: [], + }), + onListChromeTabs: () => ({ + ok: true, + visibleWindowId: 1, + windows: [ + { + windowId: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [ + { + chromeTabId: 4, + windowId: 1, + title: "Fixture", + url: "http://127.0.0.1:3000/app", + active: true, + discarded: false, + frozen: false, + lastAccessed: 10, + index: 0, + }, + ], + }, + { + windowId: 9, + focused: false, + type: "normal", + incognito: true, + tabs: [{ chromeTabId: 99, windowId: 9, title: "Hidden", url: "https://secret.example/", active: true }], + }, + ], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + onNavigateChromeTab: (msg) => ({ + ok: true, + chromeTabId: msg.chromeTabId ?? 15, + finalUrl: msg.url, + wasDiscarded: msg.chromeTabId === 4, + created: msg.create === true, + visibleWindowId: 1, + openedTabs: [{ chromeTabId: 16, url: "http://127.0.0.1:3000/popup", windowId: 1, active: false }], + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + onReadChromeTab: () => ({ + ok: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + read: { + url: "http://127.0.0.1:3000/app", + title: "Fixture", + asleep: true, + frozen: false, + skipped: "asleep", + headings: [], + excerpt: "", + snapshot: [], + hostAccess: true, + }, + }), + onSoftInput: (msg) => ({ + ok: true, + outcome: msg.selector === "#file" ? "needs a real gesture" : "worked", + reason: msg.selector === "#file" ? "file picker" : null, + detail: msg.selector === "#file" ? "A file picker needs a real gesture." : "Value set", + trusted: false, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }), + }); + await worker.connect(); + worker.send({ type: "capability-state", popupEnabled: true }); + probePopup = true; + await expect.poll(async () => (await connector!.checkCapability("listTabs")).allowed).toBe(true); + } + + it("lists chrome.tabs metadata and drops incognito", async () => { + await start(false); + const listing = await connector!.listChromeTabs(); + expect(listing.coverage).toBe(TAB_COVERAGE); + expect(listing.windows).toHaveLength(1); + expect(listing.windows[0]?.tabs[0]).toMatchObject({ chromeTabId: 4, site: "http://127.0.0.1:3000", lastAccessed: 10 }); + expect(JSON.stringify(listing)).not.toContain("secret.example"); + const sent = worker!.received.filter((message) => message.type === "list-chrome-tabs"); + expect(sent).toHaveLength(1); + expect(JSON.stringify(sent)).not.toMatch(/active"\s*:\s*true|focused"\s*:\s*true|debugger/); + }); + + it("navigates in the background only when input is allowed, and reports popups", async () => { + await start(true); + const created = await connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next" }); + expect(created.created).toBe(true); + expect(created.chromeTabId).toBe(15); + expect(created.openedTabs[0]?.url).toContain("/popup"); + expect(created.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); + const message = worker!.received.find((entry) => entry.type === "navigate-chrome-tab"); + expect(message.create).toBe(true); + expect(message.active).toBeUndefined(); + expect(message.focused).toBeUndefined(); + + const updated = await connector!.navigateChromeTab({ + url: "http://127.0.0.1:3000/woken", + chromeTabId: 4, + }); + expect(updated.wasDiscarded).toBe(true); + expect(updated.created).toBe(false); + }); + + it("refuses navigation when input is off and when the action would change focus", async () => { + await start(false); + await expect + .poll(async () => + (await connector!.checkCapability("navigate", { + creatingTab: true, + destinationUrl: "http://127.0.0.1:3000/next", + })).reason + ) + .toBe(GateReason.inputOff); + await expect(connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next" })).rejects.toThrow(GateReason.inputOff); + + await connector!.close(); + await worker!.close(); + await start(true); + worker!.received.length = 0; + const previous = worker!; + // Replace the navigate handler by closing and using a worker that reports a focus change. + await previous.close(); + worker = new FakeExtension({ + port: connector!.port, + role: "worker", + onCapabilityProbe: () => ({ + popupEnabled: true, + panelEnabled: false, + liveUrl: "http://127.0.0.1:3000/app", + excludeOrigins: [], + }), + onNavigateChromeTab: () => ({ + ok: true, + chromeTabId: 4, + finalUrl: "http://127.0.0.1:3000/next", + wasDiscarded: false, + created: false, + visibleWindowId: 1, + openedTabs: [], + safety: { debuggerCalls: 0, focusChanges: 1 }, + }), + }); + await worker.connect(); + worker.send({ type: "capability-state", popupEnabled: true }); + await expect + .poll(async () => + (await connector!.checkCapability("navigate", { + tabId: 4, + destinationUrl: "http://127.0.0.1:3000/next", + })).allowed + ) + .toBe(true); + await expect( + connector!.navigateChromeTab({ url: "http://127.0.0.1:3000/next", chromeTabId: 4 }) + ).rejects.toThrow(/change focus/); + }); + + it("reads an asleep tab and reports soft click outcomes through MCP and the CLI path", async () => { + await start(true); + const read = await connector!.readChromeTab({ chromeTabId: 4 }); + expect(read).toMatchObject({ asleep: true, skipped: "asleep", chromeTabId: 4 }); + + const click = await connector!.softClickChromeTab({ chromeTabId: 4, selector: "#file" }); + expect(click).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + const typed = await connector!.softTypeChromeTab({ chromeTabId: 4, selector: "#name", text: "Ada" }); + expect(typed).toMatchObject({ outcome: "worked", trusted: false }); + + const client = new InProcessConnectorClient(connector!); + const invoked = await invokeTool("listTabs", client, {}); + expect(invoked.isError).toBeUndefined(); + expect(invoked.structuredContent?.["coverage"]).toBe(TAB_COVERAGE); + + const { server } = createMcpServer({ client }); + const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair(); + const mcp = new Client({ name: "tab-test", version: "1.0.0" }); + await Promise.all([server.connect(serverTransport), mcp.connect(clientTransport)]); + const listed = await mcp.listTools(); + const listTabs = listed.tools.find((tool) => tool.name === "listTabs"); + const navigate = listed.tools.find((tool) => tool.name === "navigateTab"); + expect(listTabs?.description).toContain("This is not every open tab"); + expect(listTabs?.description).not.toMatch(/every tab you have|all open tabs/); + expect(navigate?.description).toContain("chromeTabId"); + expect(navigate?.description).toContain("not a DevTools-connected tabId"); + expect(navigate?.description).toContain("visible window"); + const called = await mcp.callTool({ name: "softType", arguments: { chromeTabId: 4, selector: "#name", text: "Ada" } }); + expect(called.isError).toBeUndefined(); + await mcp.close(); + await server.close(); + }); +}); diff --git a/browser-tools-mcp/test/unit/capability-gates.test.ts b/browser-tools-mcp/test/unit/capability-gates.test.ts index 1a501b33..928cf0ee 100644 --- a/browser-tools-mcp/test/unit/capability-gates.test.ts +++ b/browser-tools-mcp/test/unit/capability-gates.test.ts @@ -180,6 +180,32 @@ describe("origin allowlist", () => { policy: policy({ allowInput: true, allowEval: true }), }); + it("checks only the destination when opening a new background tab", () => { + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: "http://127.0.0.1:3000/next", + }) + ).toEqual({ allowed: true, reason: GateReason.allowed }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "https://example.com/", + }) + ).toEqual({ allowed: false, reason: GateReason.destinationNotAllowed }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: null, + }) + ).toEqual({ allowed: false, reason: GateReason.destinationMissing }); + }); + it("allows local addresses by default and refuses a public origin until it is listed", () => { expect( decideCapability("softClick", { ...open, liveUrl: "http://localhost:3000/app" }).allowed diff --git a/browser-tools-mcp/test/unit/extension-gates.test.ts b/browser-tools-mcp/test/unit/extension-gates.test.ts index a518bbd3..5df781c4 100644 --- a/browser-tools-mcp/test/unit/extension-gates.test.ts +++ b/browser-tools-mcp/test/unit/extension-gates.test.ts @@ -85,6 +85,25 @@ describe("extension confirmBeforeAct", () => { ).toEqual({ allowed: false, reason: "tab URL is missing" }); }); + it("allows a new background tab without a live URL while the popup switch is on", () => { + expect( + gates.confirmBeforeAct({ + action: "navigate", + popupEnabled: true, + panelEnabled: false, + creatingTab: true, + }) + ).toEqual({ allowed: true, reason: "allowed" }); + expect( + gates.confirmBeforeAct({ + action: "navigate", + popupEnabled: false, + panelEnabled: false, + creatingTab: true, + }) + ).toEqual({ allowed: false, reason: "popup switch is off" }); + }); + it("allows a list and a matching live origin only while the switch is on", () => { expect( gates.confirmBeforeAct({ @@ -108,14 +127,35 @@ describe("extension confirmBeforeAct", () => { describe("worker probe", () => { const worker = fs.readFileSync(path.join(extensionDir, "worker.js"), "utf8"); + const actions = fs.readFileSync(path.join(extensionDir, "tab-actions.js"), "utf8"); + const page = fs.readFileSync(path.join(extensionDir, "tab-page.js"), "utf8"); + const safety = fs.readFileSync(path.join(extensionDir, "tab-safety.js"), "utf8"); it("reads tabs for probes and navigate without the debugger or focus changes", () => { expect(worker).toContain("tabs.get"); expect(worker).toContain("navigate-tab"); - expect(worker).toMatch(/tabs\.update\([^)]*active:\s*false/); + expect(worker).toContain("list-chrome-tabs"); expect(worker).not.toMatch(/chrome\.debugger|api\.debugger|\.attach\(/); expect(worker).not.toContain("windows.update"); expect(worker).not.toContain("executeScript"); expect(worker).not.toContain("silent-debugger"); + expect(worker).not.toMatch(/active\s*:\s*true/); + expect(worker).not.toMatch(/focused\s*:\s*true/); + }); + + it("keeps chrome.tabs actions off the debugger and off focus changes", () => { + const behavior = actions + page; + expect(behavior).not.toMatch(/chrome\.debugger|api\.debugger/); + expect(behavior).not.toMatch(/active\s*:\s*true/); + expect(behavior).not.toMatch(/focused\s*:\s*true/); + expect(behavior).not.toContain("silent-debugger"); + expect(behavior).not.toContain("--disable-features"); + expect(actions).toContain("active: false"); + expect(actions).toContain("visible window"); + expect(page).toContain("requestSubmit"); + expect(page).toContain("insertText"); + expect(page).toContain("needs a real gesture"); + expect(safety).toContain("Refusing to change focus."); + expect(safety).not.toContain("silent-debugger"); }); }); diff --git a/browser-tools-mcp/test/unit/tab-contract.test.ts b/browser-tools-mcp/test/unit/tab-contract.test.ts new file mode 100644 index 00000000..8021a740 --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-contract.test.ts @@ -0,0 +1,85 @@ +import { describe, expect, it } from "vitest"; + +import { + CHROME_TAB_ID, + DEVTOOLS_TAB_ID, + GESTURE_REASONS, + LIST_TABS_DESCRIPTION, + NAVIGATE_TAB_DESCRIPTION, + READ_TAB_DESCRIPTION, + SOFT_CLICK_DESCRIPTION, + SOFT_TYPE_DESCRIPTION, + TAB_COVERAGE, + TAB_TOOL_NAMES, +} from "../../src/tabs/contract"; +import { + DEVTOOLS_TAB_INPUT, + LIST_BROWSER_TABS_DESCRIPTION, + NAVIGATE_BROWSER_DESCRIPTION, +} from "../../src/tabs/contract"; + +describe("tab id contract", () => { + it("keeps DevTools-connected ids and chrome.tabs ids in separate sentences", () => { + expect(DEVTOOLS_TAB_ID).toMatch(/listBrowserTabs/); + expect(DEVTOOLS_TAB_ID).toMatch(/Not a chromeTabId/); + expect(CHROME_TAB_ID).toMatch(/listTabs/); + expect(CHROME_TAB_ID).toMatch(/Not a DevTools-connected tabId/); + expect(DEVTOOLS_TAB_INPUT).toMatch(/Not a chromeTabId/); + }); + + it("does not claim listBrowserTabs is every open tab", () => { + expect(LIST_BROWSER_TABS_DESCRIPTION).toMatch(/not every open tab/); + expect(LIST_BROWSER_TABS_DESCRIPTION).toMatch(/not chromeTabId/); + }); + + it("describes navigateBrowser as the DevTools-connected path", () => { + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/listBrowserTabs/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/not a chromeTabId/); + expect(NAVIGATE_BROWSER_DESCRIPTION).not.toMatch(/silent-debugger/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/active:true/); + expect(NAVIGATE_BROWSER_DESCRIPTION).toMatch(/focused:true/); + }); +}); + +describe("chrome.tabs tool descriptions", () => { + it("uses the measured coverage sentence and does not say every open tab", () => { + expect(TAB_COVERAGE).toBe( + "Tabs the browser exposes through chrome.tabs in the windows it returns. " + + "Other Arc Spaces, Little Arc, pinned favorites, split-view partners, and slept tabs may be missing. " + + "Incognito is skipped. This is not every open tab." + ); + expect(LIST_TABS_DESCRIPTION.startsWith(TAB_COVERAGE)).toBe(true); + expect(LIST_TABS_DESCRIPTION).toMatch(/This is not every open tab/); + expect(LIST_TABS_DESCRIPTION).not.toMatch(/every tab you have|all open tabs|see every/i); + for (const text of [READ_TAB_DESCRIPTION, NAVIGATE_TAB_DESCRIPTION, SOFT_CLICK_DESCRIPTION, SOFT_TYPE_DESCRIPTION]) { + expect(text).toMatch(/chromeTabId/); + expect(text).toMatch(/not a DevTools-connected tabId/); + expect(text).not.toMatch(/every open tab/i); + expect(text).not.toMatch(/silent-debugger/); + } + }); + + it("keeps background navigate inside the visible window and gated like input", () => { + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/visible window/); + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/--allow-input/); + expect(NAVIGATE_TAB_DESCRIPTION).toMatch(/wasDiscarded/); + expect(NAVIGATE_TAB_DESCRIPTION).not.toMatch(/active:\s*true/); + }); + + it("names both soft-input outcomes and the gesture reasons", () => { + expect(SOFT_CLICK_DESCRIPTION).toMatch(/"worked"/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/"needs a real gesture"/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/native value setter/); + expect(SOFT_TYPE_DESCRIPTION).toMatch(/insertText/); + expect(SOFT_CLICK_DESCRIPTION).toMatch(/requestSubmit/); + for (const reason of GESTURE_REASONS) { + expect(SOFT_CLICK_DESCRIPTION).toContain(reason); + } + }); + + it("lists the chrome.tabs tools separately from listBrowserTabs", () => { + expect([...TAB_TOOL_NAMES]).toEqual(["listTabs", "readTab", "navigateTab", "softClick", "softType"]); + expect(TAB_TOOL_NAMES).not.toContain("listBrowserTabs"); + expect(TAB_TOOL_NAMES).not.toContain("navigateBrowser"); + }); +}); diff --git a/browser-tools-mcp/test/unit/tab-extension.test.ts b/browser-tools-mcp/test/unit/tab-extension.test.ts new file mode 100644 index 00000000..0d5b47c1 --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-extension.test.ts @@ -0,0 +1,342 @@ +import { describe, expect, it } from "vitest"; +import fs from "node:fs"; +import path from "node:path"; +import vm from "node:vm"; +import { fileURLToPath } from "node:url"; + +const extensionDir = path.resolve(fileURLToPath(new URL("../../../chrome-extension", import.meta.url))); + +function loadExtension(chromeApi: Record, documentMock?: Record) { + const context: Record = { + URL, + Promise, + setTimeout, + clearTimeout, + globalThis: {}, + api: chromeApi, + document: documentMock, + location: { hostname: "127.0.0.1" }, + HTMLInputElement: class HTMLInputElement {}, + HTMLTextAreaElement: class HTMLTextAreaElement {}, + Event: class Event { + type: string; + bubbles: boolean; + constructor(type: string, init: { bubbles?: boolean } = {}) { + this.type = type; + this.bubbles = init.bubbles === true; + } + }, + MouseEvent: class MouseEvent { + type: string; + constructor(type: string) { + this.type = type; + } + }, + PointerEvent: class PointerEvent { + type: string; + constructor(type: string) { + this.type = type; + } + }, + NodeFilter: { SHOW_TEXT: 4, FILTER_REJECT: 2, FILTER_ACCEPT: 1 }, + }; + context["globalThis"] = context; + vm.createContext(context); + for (const file of ["gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js"]) { + vm.runInContext(fs.readFileSync(path.join(extensionDir, file), "utf8"), context); + } + return context as { + BTMCP_SAFETY: { + install: (api: unknown) => void; + snapshot: () => { debuggerCalls: number; focusChanges: number }; + tabsUpdate: (api: unknown, tabId: number, props: { url: string; active: boolean }) => Promise; + }; + BTMCP_TABS: { + list: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + navigateChrome: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + read: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + soft: (api: unknown, message: unknown, respond: (id: string, payload: Record) => void) => Promise; + }; + btmcpScrubText: (value: string) => string; + btmcpSoftAct: (command: Record) => { outcome: string; reason: string | null; trusted: boolean }; + btmcpReadPage: () => { headings: unknown[]; excerpt: string }; + }; +} + +function storageArea(initial: Record = {}) { + const data = { ...initial }; + return { + get(key: string | string[], callback: (stored: Record) => void) { + const keys = Array.isArray(key) ? key : [key]; + const stored: Record = {}; + for (const name of keys) stored[name] = data[name]; + callback(stored); + }, + set(value: Record, callback?: () => void) { + Object.assign(data, value); + callback?.(); + }, + }; +} + +describe("tab safety wrapper", () => { + it("counts debugger calls and refuses to activate a tab or focus a window", async () => { + const calls: string[] = []; + const api = { + debugger: { + attach: () => { + calls.push("attach"); + }, + }, + tabs: { + update: (id: number, props: unknown) => { + calls.push(`update:${id}:${JSON.stringify(props)}`); + return Promise.resolve(props); + }, + create: () => Promise.resolve({ id: 1 }), + }, + windows: { + update: () => { + calls.push("windows.update"); + return Promise.resolve(); + }, + }, + }; + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + api.debugger.attach(); + expect(loaded.BTMCP_SAFETY.snapshot().debuggerCalls).toBe(1); + expect(calls).toContain("attach"); + expect(() => api.tabs.update(3, { url: "http://127.0.0.1/", active: true })).toThrow(/focus/); + expect(() => api.windows.update(1, { focused: true })).toThrow(/focus/); + expect(calls.some((call) => call.startsWith("update:"))).toBe(false); + expect(calls).not.toContain("windows.update"); + await loaded.BTMCP_SAFETY.tabsUpdate(api, 3, { url: "http://127.0.0.1/next", active: false }); + expect(calls).toContain('update:3:{"url":"http://127.0.0.1/next","active":false}'); + expect(loaded.BTMCP_SAFETY.snapshot().focusChanges).toBe(2); + }); +}); + +describe("chrome.tabs actions", () => { + function apiFor(tabs: Record>, windows: Record[]) { + const calls: { method: string; props?: unknown }[] = []; + const api = { + storage: { + session: storageArea({ btmcpPopupSwitch: true }), + local: storageArea({ btmcpExcludeOrigins: [] }), + }, + tabs: { + get: async (id: number) => tabs[id], + update: async (id: number, props: Record) => { + calls.push({ method: "tabs.update", props }); + return { ...tabs[id], ...props }; + }, + create: async (props: Record) => { + calls.push({ method: "tabs.create", props }); + return { id: 20, windowId: props["windowId"], url: props["url"], active: props["active"] }; + }, + onCreated: { addListener() {}, removeListener() {} }, + onUpdated: { + addListener(listener: (id: number, change: { status: string }, tab: { url?: string }) => void) { + listener(20, { status: "complete" }, { url: "http://127.0.0.1:4000/" }); + }, + removeListener() {}, + }, + }, + windows: { + getAll: async () => windows, + getLastFocused: async () => windows.find((win) => win["focused"]) ?? windows[0], + update: async () => { + calls.push({ method: "windows.update" }); + }, + }, + permissions: { contains: async () => true }, + scripting: { + executeScript: async () => [{ result: { title: "Hi", headings: [{ level: 1, text: "Hi" }], excerpt: "Hello", snapshot: [] } }], + }, + debugger: { attach() { calls.push({ method: "debugger.attach" }); } }, + }; + return { api, calls }; + } + + it("lists normal windows and skips incognito without touching the debugger or focus", async () => { + const { api, calls } = apiFor({}, [ + { + id: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [{ id: 4, windowId: 1, url: "http://127.0.0.1:3000/", title: "Local", active: true, discarded: false, lastAccessed: 5 }], + }, + { id: 2, focused: false, type: "normal", incognito: true, tabs: [{ id: 9, windowId: 2, url: "https://secret.example/", title: "Secret" }] }, + ]); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.list(api, { requestId: "1" }, (_id, payload) => { + result = payload; + }); + expect(result["ok"]).toBe(true); + const windows = result["windows"] as { tabs: { chromeTabId: number }[] }[]; + expect(windows).toHaveLength(1); + expect(windows[0]?.tabs[0]?.chromeTabId).toBe(4); + expect(JSON.stringify(result)).not.toContain("secret.example"); + expect(calls).toEqual([]); + expect((result["safety"] as { debuggerCalls: number; focusChanges: number }).debuggerCalls).toBe(0); + }); + + it("refuses background navigate outside the visible window and does not activate a tab", async () => { + const { api, calls } = apiFor( + { 8: { id: 8, windowId: 2, url: "http://127.0.0.1:3000/", discarded: false, incognito: false } }, + [ + { id: 1, focused: true, type: "normal", incognito: false, tabs: [] }, + { id: 2, focused: false, type: "normal", incognito: false, tabs: [] }, + ] + ); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.navigateChrome( + api, + { requestId: "2", chromeTabId: 8, url: "http://127.0.0.1:3000/next", approvedUrl: "http://127.0.0.1:3000/" }, + (_id, payload) => { + result = payload; + } + ); + expect(result["ok"]).toBe(false); + expect(String(result["error"])).toMatch(/visible window/); + expect(calls).toEqual([]); + }); + + it("opens a background tab in the visible window with active false", async () => { + const { api, calls } = apiFor({}, [{ id: 1, focused: true, type: "normal", incognito: false, tabs: [] }]); + const loaded = loadExtension(api); + loaded.BTMCP_SAFETY.install(api); + let result: Record = {}; + await loaded.BTMCP_TABS.navigateChrome( + api, + { requestId: "3", create: true, url: "http://127.0.0.1:4000/" }, + (_id, payload) => { + result = payload; + } + ); + expect(result["ok"]).toBe(true); + expect(result["created"]).toBe(true); + expect(calls).toEqual([{ method: "tabs.create", props: { url: "http://127.0.0.1:4000/", active: false, windowId: 1 } }]); + expect(calls.some((call) => call.method === "debugger.attach" || call.method === "windows.update")).toBe(false); + }); + + it("reports an asleep tab without reading or reloading it", async () => { + const { api, calls } = apiFor( + { 6: { id: 6, url: "http://127.0.0.1:3000/", title: "Sleeping", discarded: true, frozen: false } }, + [] + ); + const loaded = loadExtension(api); + let result: Record = {}; + await loaded.BTMCP_TABS.read( + api, + { requestId: "4", chromeTabId: 6, approvedUrl: "http://127.0.0.1:3000/" }, + (_id, payload) => { + result = payload; + } + ); + const read = result["read"] as { asleep: boolean; skipped: string }; + expect(read.asleep).toBe(true); + expect(read.skipped).toBe("asleep"); + expect(calls.some((call) => call.method === "tabs.update")).toBe(false); + }); + + it("reads loopback pages when permissions.contains is false, and skips other origins", async () => { + const scripts: { world?: string; files?: string[] }[] = []; + const { api } = apiFor( + { + 7: { id: 7, url: "http://127.0.0.1:3000/form", title: "Form", discarded: false, frozen: false }, + 8: { id: 8, url: "https://example.com/", title: "Example", discarded: false, frozen: false }, + }, + [] + ); + (api.permissions as { contains: () => Promise }).contains = async () => false; + api.scripting.executeScript = async (details: { world?: string; files?: string[] }) => { + scripts.push(details); + return [{ result: { title: "Form", headings: [{ level: 1, text: "Soft form" }], excerpt: "Soft form", snapshot: [] } }]; + }; + const loaded = loadExtension(api); + let local: Record = {}; + await loaded.BTMCP_TABS.read(api, { requestId: "5", chromeTabId: 7, approvedUrl: "http://127.0.0.1:3000/form" }, (_id, payload) => { + local = payload; + }); + const read = local["read"] as { headings: { text: string }[]; hostAccess: boolean }; + expect(read.hostAccess).toBe(true); + expect(read.headings[0]?.text).toBe("Soft form"); + expect(scripts[0]).toMatchObject({ world: "ISOLATED", files: ["tab-page.js"] }); + + scripts.length = 0; + let remote: Record = {}; + await loaded.BTMCP_TABS.read(api, { requestId: "6", chromeTabId: 8, approvedUrl: "https://example.com/" }, (_id, payload) => { + remote = payload; + }); + const skipped = remote["read"] as { skipped: string; headings: unknown[] }; + expect(skipped.skipped).toMatch(/host access/); + expect(skipped.headings).toEqual([]); + expect(scripts).toEqual([]); + }); +}); + +describe("soft input in the page", () => { + it("scrubs private details and reports a file picker as needing a real gesture", () => { + const input = { + tagName: "INPUT", + type: "file", + getAttribute: (name: string) => (name === "type" ? "file" : null), + getBoundingClientRect: () => ({ width: 10, height: 10, left: 0, top: 0 }), + closest: () => null, + contains: () => false, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() {}, + }; + const loaded = loadExtension( + {}, + { + querySelector: () => input, + elementFromPoint: () => input, + } + ); + expect(loaded.btmcpScrubText("user@example.com ghp_abcdefghijklmnopqrstuvwxyz0123456789")).not.toMatch(/user@|ghp_/); + const result = loaded.btmcpSoftAct({ op: "click", selector: "#file" }); + expect(result).toMatchObject({ outcome: "needs a real gesture", reason: "file picker", trusted: false }); + }); + + it("sets an input with the native setter and reports worked", () => { + let stored = ""; + class HTMLInputElement {} + const descriptor = { set: (value: string) => { stored = value; }, configurable: true }; + Object.defineProperty(HTMLInputElement.prototype, "value", descriptor); + const input = { + tagName: "INPUT", + type: "text", + disabled: false, + readOnly: false, + get value() { return stored; }, + set value(next: string) { stored = next; }, + getAttribute: (name: string) => (name === "type" ? "text" : null), + getBoundingClientRect: () => ({ width: 20, height: 10, left: 0, top: 0 }), + closest: () => null, + contains: () => true, + addEventListener() {}, + removeEventListener() {}, + dispatchEvent() {}, + }; + const context = loadExtension( + {}, + { + querySelector: () => input, + elementFromPoint: () => input, + } + ); + (context as unknown as { HTMLInputElement: typeof HTMLInputElement }).HTMLInputElement = HTMLInputElement; + const result = context.btmcpSoftAct({ op: "type", selector: "#name", text: "Ada" }); + expect(result).toMatchObject({ outcome: "worked", reason: null, trusted: false }); + expect(stored).toBe("Ada"); + }); +}); diff --git a/browser-tools-mcp/test/unit/tab-listing.test.ts b/browser-tools-mcp/test/unit/tab-listing.test.ts new file mode 100644 index 00000000..f284dcff --- /dev/null +++ b/browser-tools-mcp/test/unit/tab-listing.test.ts @@ -0,0 +1,115 @@ +import { describe, expect, it } from "vitest"; + +import { defaultGatePolicy } from "../../src/gates/capability"; +import { TAB_COVERAGE } from "../../src/tabs/contract"; +import { + normalizeChromeTabListing, + parseChromeNavigate, + parseSoftInput, +} from "../../src/tabs/listing"; + +describe("normalizeChromeTabListing", () => { + it("drops incognito, excluded origins, and keeps chrome.tabs metadata", () => { + const listing = normalizeChromeTabListing( + { + visibleWindowId: 1, + windows: [ + { + windowId: 1, + focused: true, + type: "normal", + incognito: false, + tabs: [ + { + chromeTabId: 7, + windowId: 1, + title: "Local", + url: "http://127.0.0.1:3000/app", + active: true, + pinned: false, + discarded: true, + frozen: false, + lastAccessed: 100, + audible: false, + status: "complete", + index: 0, + }, + { + chromeTabId: 8, + windowId: 1, + title: "Mail sess_abcdefghijklmnopqrstuvwxyz", + url: "https://excluded.example/inbox?token=ghp_abcdefghijklmnopqrstuvwxyz0123456789", + active: false, + discarded: false, + frozen: true, + lastAccessed: 50, + }, + ], + }, + { + windowId: 2, + focused: false, + type: "normal", + incognito: true, + tabs: [{ chromeTabId: 9, windowId: 2, title: "Private", url: "https://example.com/", active: true }], + }, + ], + }, + { ...defaultGatePolicy(), excludeOrigins: ["https://excluded.example"] } + ); + + expect(listing.coverage).toBe(TAB_COVERAGE); + expect(listing.visibleWindowId).toBe(1); + expect(listing.windows).toHaveLength(1); + expect(listing.windows[0]?.tabs).toHaveLength(1); + expect(listing.windows[0]?.tabs[0]).toMatchObject({ + chromeTabId: 7, + site: "http://127.0.0.1:3000", + discarded: true, + lastAccessed: 100, + active: true, + }); + expect(JSON.stringify(listing)).not.toContain("ghp_"); + expect(JSON.stringify(listing)).not.toContain("Private"); + }); +}); + +describe("tab action results", () => { + it("refuses a navigation that attached the debugger or changed focus", () => { + expect(() => + parseChromeNavigate("http://127.0.0.1/", { + chromeTabId: 3, + visibleWindowId: 1, + finalUrl: "http://127.0.0.1/", + safety: { debuggerCalls: 1, focusChanges: 0 }, + }) + ).toThrow(/debugger or change focus/); + }); + + it("never reports a soft action as trusted", () => { + expect( + parseSoftInput(4, { + outcome: "worked", + reason: null, + detail: "Value set", + trusted: true, + safety: { debuggerCalls: 0, focusChanges: 0 }, + }) + ).toEqual({ + chromeTabId: 4, + outcome: "worked", + reason: null, + detail: "Value set", + trusted: false, + }); + + expect(() => + parseSoftInput(4, { + outcome: "needs a real gesture", + reason: "made up", + detail: "", + safety: { debuggerCalls: 0, focusChanges: 0 }, + }) + ).toThrow(/without a reason/); + }); +}); diff --git a/chrome-extension/gates.js b/chrome-extension/gates.js index bba82090..0ffd379d 100644 --- a/chrome-extension/gates.js +++ b/chrome-extension/gates.js @@ -52,6 +52,9 @@ var BTMCP_GATES = (function () { if (input.action === "listTabs") { return { allowed: true, reason: "allowed" }; } + if (input.action === "navigate" && input.creatingTab === true) { + return { allowed: true, reason: "allowed" }; + } var liveOrigin = originOf(input.liveUrl); var approvedOrigin = originOf(input.approvedUrl); if (!liveOrigin || !approvedOrigin) { diff --git a/chrome-extension/manifest.json b/chrome-extension/manifest.json index e3500977..4026242b 100644 --- a/chrome-extension/manifest.json +++ b/chrome-extension/manifest.json @@ -11,7 +11,7 @@ "service_worker": "worker.js" }, "devtools_page": "devtools.html", - "permissions": ["debugger", "storage", "tabs", "alarms"], + "permissions": ["debugger", "storage", "tabs", "alarms", "scripting"], "optional_permissions": ["cookies"], "host_permissions": ["http://127.0.0.1/*", "http://localhost/*"], "optional_host_permissions": [""], diff --git a/chrome-extension/popup.html b/chrome-extension/popup.html index a2ff9fa4..cbf782a6 100644 --- a/chrome-extension/popup.html +++ b/chrome-extension/popup.html @@ -99,6 +99,14 @@

BrowserTools MCP

One http(s) origin per line. Listed origins are never acted on.

+

+ +

+

+ Reading a tab and soft input need host access for that site. Local pages are already allowed. + This asks Chrome for access. It does not hide the debugging banner, and the debugging banner + stays off unless a DevTools capture attaches the debugger. +

diff --git a/chrome-extension/popup.js b/chrome-extension/popup.js index c6191ecf..86b8e7ee 100644 --- a/chrome-extension/popup.js +++ b/chrome-extension/popup.js @@ -12,6 +12,7 @@ var api = typeof globalThis.browser !== "undefined" ? globalThis.browser : globalThis.chrome; var allow = document.getElementById("allowPageActions"); var exclude = document.getElementById("excludeOrigins"); + var grant = document.getElementById("grantHostAccess"); var saved = document.getElementById("saved"); function storageGet(area, key) { @@ -86,6 +87,21 @@ await notifyWorker(); }); + if (grant) { + grant.addEventListener("click", function () { + var request = api.permissions.request({ origins: [""] }); + Promise.resolve(request) + .then(function (granted) { + saved.textContent = granted + ? "Host access granted for open pages." + : "Host access was not granted."; + }) + .catch(function () { + saved.textContent = "Host access was not granted."; + }); + }); + } + document.documentElement.dataset.ready = "true"; } diff --git a/chrome-extension/tab-actions.js b/chrome-extension/tab-actions.js new file mode 100644 index 00000000..13d9ee4c --- /dev/null +++ b/chrome-extension/tab-actions.js @@ -0,0 +1,560 @@ +/** + * chrome.tabs actions for the service worker. + * + * List, read, background navigate, and soft click/type. No debugger API. + * Navigation always passes active: false and never focuses a window. + * Background navigate stays in the visible window. + */ +var BTMCP_TABS = (function () { + function storageGet(area, keys) { + return new Promise(function (resolve) { + try { + area.get(keys, function (stored) { + resolve(stored || {}); + }); + } catch (error) { + resolve({}); + } + }); + } + + async function readHumanState(chromeApi) { + var session = await storageGet(chromeApi.storage.session, [BTMCP_GATES.POPUP_SWITCH_KEY]); + var local = await storageGet(chromeApi.storage.local, [BTMCP_GATES.EXCLUDE_KEY]); + var exclude = local[BTMCP_GATES.EXCLUDE_KEY]; + return { + popupEnabled: session[BTMCP_GATES.POPUP_SWITCH_KEY] === true, + excludeOrigins: Array.isArray(exclude) + ? exclude.filter(function (entry) { + return typeof entry === "string"; + }) + : [], + }; + } + + function excluded(url, list) { + var origin = BTMCP_GATES.originOf(url); + if (!origin) return false; + for (var i = 0; i < list.length; i++) { + if (BTMCP_GATES.originOf(list[i]) === origin) return true; + } + return false; + } + + function fail(respond, requestId, type, error) { + respond(requestId, { type: type, ok: false, error: error instanceof Error ? error.message : String(error) }); + } + + function delta(before) { + var after = BTMCP_SAFETY.snapshot(); + return { + debuggerCalls: after.debuggerCalls - before.debuggerCalls, + focusChanges: after.focusChanges - before.focusChanges, + }; + } + + function serializeTab(tab, windowId) { + return { + chromeTabId: tab.id, + windowId: typeof tab.windowId === "number" ? tab.windowId : windowId, + title: typeof tab.title === "string" ? tab.title : "", + url: typeof tab.url === "string" ? tab.url : "", + active: tab.active === true, + pinned: tab.pinned === true, + discarded: tab.discarded === true, + frozen: tab.frozen === true, + lastAccessed: typeof tab.lastAccessed === "number" ? tab.lastAccessed : null, + audible: tab.audible === true, + status: typeof tab.status === "string" ? tab.status : "", + index: typeof tab.index === "number" ? tab.index : 0, + incognito: tab.incognito === true, + }; + } + + async function visibleWindowId(chromeApi, already) { + var windows = already || (await chromeApi.windows.getAll({ populate: false })); + var i; + for (i = 0; i < windows.length; i++) { + var win = windows[i]; + if (win && win.focused === true && win.incognito !== true && (win.type === "normal" || !win.type)) { + return win.id; + } + } + try { + var last = await chromeApi.windows.getLastFocused({ windowTypes: ["normal"] }); + if (last && last.incognito !== true && typeof last.id === "number") return last.id; + } catch (error) { + /* fall through to the first normal window */ + } + for (i = 0; i < windows.length; i++) { + if (windows[i] && windows[i].incognito !== true && windows[i].type === "normal") return windows[i].id; + } + return null; + } + + function unsupportedPage(url) { + if (!url) return "missing url"; + var lower = url.toLowerCase(); + if ( + lower.indexOf("chrome://") === 0 || + lower.indexOf("chrome-extension://") === 0 || + lower.indexOf("edge://") === 0 || + lower.indexOf("about:") === 0 || + lower.indexOf("devtools://") === 0 + ) { + return "unsupported page"; + } + if (lower.indexOf("https://chrome.google.com/webstore") === 0 || lower.indexOf("https://chromewebstore.google.com") === 0) { + return "web store"; + } + if (/\.pdf($|\?)/i.test(lower)) return "pdf viewer"; + if (!/^https?:\/\//i.test(url)) return "unsupported page"; + return null; + } + + /** + * chrome.permissions.contains only reports optional grants. The manifest + * already allows http loopback, and that must count as granted. + */ + function manifestCovers(url) { + try { + var parsed = new URL(url); + return parsed.protocol === "http:" && (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost"); + } catch (error) { + return false; + } + } + + async function hostGranted(chromeApi, url) { + if (manifestCovers(url)) return true; + try { + var parsed = new URL(url); + var candidates = ["", parsed.origin + "/*"]; + if (parsed.port) candidates.push(parsed.protocol + "//" + parsed.hostname + "/*"); + for (var i = 0; i < candidates.length; i++) { + var granted = await chromeApi.permissions.contains({ origins: [candidates[i]] }); + if (granted) return true; + } + return false; + } catch (error) { + return false; + } + } + + /** + * executeScript serializes `func` alone. Helpers live in tab-page.js, so + * that file is injected into the same world before the call. + */ + async function runInTab(chromeApi, tabId, world, entry, args) { + await chromeApi.scripting.executeScript({ + target: { tabId: tabId }, + world: world, + files: ["tab-page.js"], + }); + var details = { + target: { tabId: tabId }, + world: world, + func: entry, + }; + if (args) details.args = args; + return chromeApi.scripting.executeScript(details); + } + + function readPageEntry() { + return btmcpReadPage(); + } + + function softActEntry(command) { + return btmcpSoftAct(command); + } + + function watchOpened(chromeApi) { + var opened = []; + function onCreated(tab) { + if (!tab || typeof tab.id !== "number") return; + opened.push({ + chromeTabId: tab.id, + url: tab.pendingUrl || tab.url || "", + windowId: typeof tab.windowId === "number" ? tab.windowId : 0, + active: tab.active === true, + }); + } + if (chromeApi.tabs.onCreated && chromeApi.tabs.onCreated.addListener) { + chromeApi.tabs.onCreated.addListener(onCreated); + } + return { + stop: function () { + if (chromeApi.tabs.onCreated && chromeApi.tabs.onCreated.removeListener) { + chromeApi.tabs.onCreated.removeListener(onCreated); + } + }, + list: function (selfId) { + return opened.filter(function (tab) { + return tab.chromeTabId !== selfId; + }); + }, + }; + } + + function waitForTabUrl(chromeApi, tabId, timeoutMs) { + return new Promise(function (resolve) { + var done = false; + function finish(url) { + if (done) return; + done = true; + clearTimeout(timer); + if (chromeApi.tabs.onUpdated) chromeApi.tabs.onUpdated.removeListener(onUpdated); + resolve(url || ""); + } + var timer = setTimeout(function () { + chromeApi.tabs + .get(tabId) + .then(function (tab) { + finish(tab && tab.url ? tab.url : ""); + }) + .catch(function () { + finish(""); + }); + }, timeoutMs); + function onUpdated(updatedId, changeInfo, tab) { + if (String(updatedId) !== String(tabId)) return; + if (changeInfo.status === "complete" && tab && tab.url) finish(tab.url); + } + if (chromeApi.tabs.onUpdated) chromeApi.tabs.onUpdated.addListener(onUpdated); + }); + } + + async function list(chromeApi, message, respond) { + var state = await readHumanState(chromeApi); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: "listTabs", + popupEnabled: state.popupEnabled, + panelEnabled: false, + hideBanner: message && message.hideBanner === true, + }); + if (!gate.allowed) { + fail(respond, message.requestId, "chrome-tabs-result", gate.reason); + return; + } + var before = BTMCP_SAFETY.snapshot(); + try { + var all = await chromeApi.windows.getAll({ populate: true }); + var visible = await visibleWindowId(chromeApi, all); + var windows = []; + for (var i = 0; i < all.length; i++) { + var win = all[i]; + if (!win || win.incognito === true) continue; + if (win.type && win.type !== "normal" && win.type !== "popup") continue; + var tabs = []; + var raw = win.tabs || []; + for (var t = 0; t < raw.length; t++) { + var tab = raw[t]; + if (!tab || tab.incognito === true || typeof tab.id !== "number") continue; + if (excluded(tab.url || "", state.excludeOrigins)) continue; + tabs.push(serializeTab(tab, win.id)); + } + windows.push({ + windowId: win.id, + focused: win.focused === true, + type: win.type || "normal", + incognito: false, + tabs: tabs, + }); + } + respond(message.requestId, { + type: "chrome-tabs-result", + ok: true, + visibleWindowId: visible, + windows: windows, + safety: delta(before), + }); + } catch (error) { + fail(respond, message.requestId, "chrome-tabs-result", error); + } + } + + async function navigateConnected(chromeApi, message, respond) { + var tabId = message.tabId; + var url = message.url; + if ((typeof tabId !== "number" && typeof tabId !== "string") || typeof url !== "string" || !url) { + fail(respond, message.requestId, "navigate-result", "tabId and url are required"); + return; + } + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var before = await chromeApi.tabs.get(tabId); + var wasDiscarded = Boolean(before && before.discarded); + await BTMCP_SAFETY.tabsUpdate(chromeApi, tabId, { url: url, active: false }); + var finalUrl = await waitForTabUrl(chromeApi, tabId, 30000); + if (!finalUrl) { + var after = await chromeApi.tabs.get(tabId); + finalUrl = after && after.url ? after.url : url; + } + respond(message.requestId, { + type: "navigate-result", + ok: true, + finalUrl: finalUrl, + wasDiscarded: wasDiscarded, + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "navigate-result", error); + } + } + + async function navigateChrome(chromeApi, message, respond) { + var url = message.url; + if (typeof url !== "string" || !url) { + fail(respond, message.requestId, "navigate-chrome-result", "url is required"); + return; + } + var state = await readHumanState(chromeApi); + var creating = message.create === true || message.chromeTabId == null; + var beforeSafety = BTMCP_SAFETY.snapshot(); + var watcher = watchOpened(chromeApi); + try { + var visible = await visibleWindowId(chromeApi); + if (typeof visible !== "number") { + throw new Error("No visible window to navigate in."); + } + if (creating) { + var createdGate = BTMCP_GATES.confirmBeforeAct({ + action: "navigate", + popupEnabled: state.popupEnabled, + panelEnabled: false, + creatingTab: true, + hideBanner: message.hideBanner === true, + }); + if (!createdGate.allowed) throw new Error(createdGate.reason); + var created = await BTMCP_SAFETY.tabsCreate(chromeApi, { + windowId: visible, + url: url, + active: false, + }); + var createdId = created && created.id; + if (typeof createdId !== "number") throw new Error("The browser did not return a tab id."); + var createdUrl = await waitForTabUrl(chromeApi, createdId, 30000); + respond(message.requestId, { + type: "navigate-chrome-result", + ok: true, + chromeTabId: createdId, + finalUrl: createdUrl || url, + wasDiscarded: false, + created: true, + visibleWindowId: visible, + openedTabs: watcher.list(createdId), + safety: delta(beforeSafety), + }); + return; + } + + var chromeTabId = message.chromeTabId; + if (typeof chromeTabId !== "number") throw new Error("chromeTabId must be a chrome.tabs id from listTabs."); + var before = await chromeApi.tabs.get(chromeTabId); + if (!before) throw new Error("Tab not found."); + if (before.incognito === true) throw new Error("Incognito is skipped."); + if (before.windowId !== visible) { + throw new Error( + "Background navigate stays limited to the visible window. This tab is in another window." + ); + } + var liveGate = BTMCP_GATES.confirmBeforeAct({ + action: "navigate", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: before.url || "", + hideBanner: message.hideBanner === true, + }); + if (!liveGate.allowed) throw new Error(liveGate.reason); + var wasDiscarded = before.discarded === true; + await BTMCP_SAFETY.tabsUpdate(chromeApi, chromeTabId, { url: url, active: false }); + var finalUrl = await waitForTabUrl(chromeApi, chromeTabId, 30000); + respond(message.requestId, { + type: "navigate-chrome-result", + ok: true, + chromeTabId: chromeTabId, + finalUrl: finalUrl || url, + wasDiscarded: wasDiscarded, + created: false, + visibleWindowId: visible, + openedTabs: watcher.list(chromeTabId), + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "navigate-chrome-result", error); + } finally { + watcher.stop(); + } + } + + function emptyRead(tab, extra) { + return Object.assign( + { + chromeTabId: tab.id, + url: typeof tab.url === "string" ? tab.url : "", + title: typeof tab.title === "string" ? tab.title : "", + asleep: tab.discarded === true, + frozen: tab.frozen === true, + skipped: null, + headings: [], + excerpt: "", + snapshot: [], + hostAccess: false, + }, + extra || {} + ); + } + + async function read(chromeApi, message, respond) { + var chromeTabId = message.chromeTabId; + if (typeof chromeTabId !== "number") { + fail(respond, message.requestId, "chrome-tab-read-result", "chromeTabId must be a chrome.tabs id from listTabs."); + return; + } + var state = await readHumanState(chromeApi); + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var tab = await chromeApi.tabs.get(chromeTabId); + if (!tab) throw new Error("Tab not found."); + if (tab.incognito === true) throw new Error("Incognito is skipped."); + if (excluded(tab.url || "", state.excludeOrigins)) throw new Error("origin is excluded"); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: "readTab", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: tab.url || "", + hideBanner: message.hideBanner === true, + }); + if (!gate.allowed) throw new Error(gate.reason); + if (tab.discarded === true) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { asleep: true, skipped: "asleep", hostAccess: true }), + }); + return; + } + if (tab.frozen === true) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { frozen: true, skipped: "frozen", hostAccess: true }), + }); + return; + } + var blocked = unsupportedPage(tab.url || ""); + if (blocked) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { skipped: blocked, hostAccess: false }), + }); + return; + } + var granted = await hostGranted(chromeApi, tab.url); + if (!granted) { + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { skipped: "host access is not granted", hostAccess: false }), + }); + return; + } + var injected = await runInTab(chromeApi, chromeTabId, "ISOLATED", readPageEntry); + var page = injected && injected[0] && injected[0].result ? injected[0].result : {}; + respond(message.requestId, { + type: "chrome-tab-read-result", + ok: true, + safety: delta(beforeSafety), + read: emptyRead(tab, { + asleep: false, + frozen: false, + skipped: null, + hostAccess: true, + title: page.title || tab.title || "", + headings: Array.isArray(page.headings) ? page.headings : [], + excerpt: typeof page.excerpt === "string" ? page.excerpt : "", + snapshot: Array.isArray(page.snapshot) ? page.snapshot : [], + }), + }); + } catch (error) { + fail(respond, message.requestId, "chrome-tab-read-result", error); + } + } + + async function soft(chromeApi, message, respond) { + var chromeTabId = message.chromeTabId; + var selector = message.selector; + var op = message.op === "type" ? "type" : "click"; + if (typeof chromeTabId !== "number") { + fail(respond, message.requestId, "soft-input-result", "chromeTabId must be a chrome.tabs id from listTabs."); + return; + } + if (typeof selector !== "string" || !selector || selector.length > 500) { + fail(respond, message.requestId, "soft-input-result", "selector is required"); + return; + } + if (op === "type" && (typeof message.text !== "string" || message.text.length > 20000)) { + fail(respond, message.requestId, "soft-input-result", "text is required"); + return; + } + var state = await readHumanState(chromeApi); + var beforeSafety = BTMCP_SAFETY.snapshot(); + try { + var tab = await chromeApi.tabs.get(chromeTabId); + if (!tab) throw new Error("Tab not found."); + if (tab.incognito === true) throw new Error("Incognito is skipped."); + if (tab.discarded === true) throw new Error("Tab is asleep. It was not reloaded."); + if (tab.frozen === true) throw new Error("Tab is frozen and was skipped."); + var blocked = unsupportedPage(tab.url || ""); + if (blocked) throw new Error(blocked); + var gate = BTMCP_GATES.confirmBeforeAct({ + action: op === "type" ? "softType" : "softClick", + popupEnabled: state.popupEnabled, + panelEnabled: false, + approvedUrl: message.approvedUrl, + liveUrl: tab.url || "", + hideBanner: message.hideBanner === true, + }); + if (!gate.allowed) throw new Error(gate.reason); + var granted = await hostGranted(chromeApi, tab.url); + if (!granted) throw new Error("host access is not granted"); + var injected = await runInTab(chromeApi, chromeTabId, "MAIN", softActEntry, [ + { op: op, selector: selector, text: message.text || "", submit: message.submit === true }, + ]); + var result = injected && injected[0] ? injected[0].result : null; + if (!result || (result.outcome !== "worked" && result.outcome !== "needs a real gesture")) { + throw new Error("Soft input did not report an outcome."); + } + if (result.outcome === "needs a real gesture" && typeof result.reason !== "string") { + throw new Error("Soft input refused without a reason."); + } + respond(message.requestId, { + type: "soft-input-result", + ok: true, + chromeTabId: chromeTabId, + outcome: result.outcome, + reason: result.outcome === "worked" ? null : result.reason, + detail: typeof result.detail === "string" ? result.detail : "", + trusted: false, + safety: delta(beforeSafety), + }); + } catch (error) { + fail(respond, message.requestId, "soft-input-result", error); + } + } + + return { + list: list, + read: read, + soft: soft, + navigateChrome: navigateChrome, + navigateConnected: navigateConnected, + }; +})(); diff --git a/chrome-extension/tab-page.js b/chrome-extension/tab-page.js new file mode 100644 index 00000000..c81e5cb6 --- /dev/null +++ b/chrome-extension/tab-page.js @@ -0,0 +1,334 @@ +/** + * Runs inside a tab via chrome.scripting.executeScript. + * + * btmcpReadPage stays in the isolated world. btmcpSoftAct runs in the page's + * main world so the native value setter and execCommand reach React, Vue, and + * rich editors. Neither function calls the debugger API or changes window focus. + */ + +function btmcpScrubText(value) { + var text = String(value == null ? "" : value); + text = text.replace(/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, "[redacted]"); + text = text.replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g, "[redacted]"); + text = text.replace(/\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, "[redacted]"); + text = text.replace(/\bgh[pousr]_[A-Za-z0-9]{16,}\b/g, "[redacted]"); + text = text.replace(/\bgithub_pat_[A-Za-z0-9_]{16,}\b/g, "[redacted]"); + text = text.replace(/\b(?:bearer\s+)\S+/gi, "bearer [redacted]"); + text = text.replace(/\b\d{13,19}\b/g, "[redacted]"); + return text; +} + +function btmcpSkipText(element) { + var tag = element && element.tagName; + return tag === "SCRIPT" || tag === "STYLE" || tag === "NOSCRIPT" || tag === "TEXTAREA" || tag === "INPUT" || tag === "SELECT"; +} + +function btmcpReadPage() { + var headings = []; + var nodes = document.querySelectorAll("h1, h2, h3, h4, h5, h6"); + var limit = Math.min(nodes.length, 30); + for (var i = 0; i < limit; i++) { + var heading = nodes[i]; + var level = Number(heading.tagName.slice(1)); + var text = btmcpScrubText((heading.innerText || heading.textContent || "").replace(/\s+/g, " ").trim()).slice(0, 200); + if (text) headings.push({ level: level, text: text }); + } + + var excerpt = ""; + var walker = document.createTreeWalker(document.body || document.documentElement, NodeFilter.SHOW_TEXT, { + acceptNode: function (node) { + var parent = node.parentElement; + if (!parent || btmcpSkipText(parent) || parent.closest("script, style, textarea, input, select")) { + return NodeFilter.FILTER_REJECT; + } + return NodeFilter.FILTER_ACCEPT; + }, + }); + var chunk; + while ((chunk = walker.nextNode())) { + var piece = (chunk.textContent || "").replace(/\s+/g, " ").trim(); + if (!piece) continue; + excerpt = excerpt ? excerpt + " " + piece : piece; + if (excerpt.length >= 800) break; + } + excerpt = btmcpScrubText(excerpt).slice(0, 800); + + var roleByTag = { + A: "link", + BUTTON: "button", + H1: "heading", + H2: "heading", + H3: "heading", + H4: "heading", + H5: "heading", + H6: "heading", + INPUT: "textbox", + TEXTAREA: "textbox", + SELECT: "combobox", + NAV: "navigation", + MAIN: "main", + FORM: "form", + IMG: "img", + }; + var snapshot = []; + + function nodeName(element) { + var aria = element.getAttribute && element.getAttribute("aria-label"); + if (aria) return btmcpScrubText(aria).slice(0, 80); + var tag = element.tagName; + if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT") { + if ((element.getAttribute("type") || "").toLowerCase() === "password") return "password"; + var placeholder = element.getAttribute("placeholder"); + if (placeholder) return btmcpScrubText(placeholder).slice(0, 80); + return element.getAttribute("name") || element.id || ""; + } + var raw = (element.innerText || element.textContent || "").replace(/\s+/g, " ").trim(); + return btmcpScrubText(raw).slice(0, 80); + } + + function walk(element, depth) { + if (!element || snapshot.length >= 60 || depth > 4) return; + var tag = element.tagName; + var role = (element.getAttribute && element.getAttribute("role")) || roleByTag[tag]; + if (role && tag !== "SCRIPT" && tag !== "STYLE") { + snapshot.push({ depth: depth, role: role, name: nodeName(element) }); + } + var children = element.children || []; + for (var c = 0; c < children.length; c++) walk(children[c], depth + 1); + } + + walk(document.body || document.documentElement, 0); + + return { + title: btmcpScrubText(document.title || "").slice(0, 200), + headings: headings, + excerpt: excerpt, + snapshot: snapshot, + }; +} + +function btmcpGesture(reason, detail) { + return { outcome: "needs a real gesture", reason: reason, detail: detail, trusted: false }; +} + +function btmcpWorked(detail) { + return { outcome: "worked", reason: null, detail: detail, trusted: false }; +} + +function btmcpLabel(element) { + var aria = (element.getAttribute && element.getAttribute("aria-label")) || ""; + var text = (element.innerText || element.textContent || "").replace(/\s+/g, " ").trim(); + return (aria + " " + text).trim(); +} + +function btmcpSoftAct(command) { + var op = command && command.op; + var selector = command && command.selector; + if (typeof selector !== "string" || !selector) { + return btmcpGesture("UI that needs the page drawn", "A selector is required."); + } + var element; + try { + element = document.querySelector(selector); + } catch (error) { + return btmcpGesture("UI that needs the page drawn", "The selector is not valid."); + } + if (!element) { + return btmcpGesture("UI that needs the page drawn", "No element matches that selector."); + } + + var host = (location.hostname || "").toLowerCase(); + if (host === "docs.google.com" || host === "sheets.google.com" || host === "slides.google.com") { + return btmcpGesture("Google Docs or canvas app", "Google Docs does not accept untrusted input."); + } + if (element.tagName === "CANVAS" || (element.closest && element.closest("canvas"))) { + return btmcpGesture("Google Docs or canvas app", "Canvas content needs the page drawn and a real gesture."); + } + + var type = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + if (type === "file" || (element.closest && element.closest("input[type='file']"))) { + return btmcpGesture("file picker", "A file picker needs a real gesture."); + } + + var label = btmcpLabel(element); + if (/\b(copy|paste|cut)\b/i.test(label) || /clipboard/i.test(String((element.getAttribute && element.getAttribute("onclick")) || ""))) { + return btmcpGesture("clipboard", "Clipboard access needs a real gesture."); + } + if (/\bfull\s*screen\b/i.test(label) || /requestFullscreen/.test(String((element.getAttribute && element.getAttribute("onclick")) || ""))) { + return btmcpGesture("fullscreen", "Fullscreen needs a real gesture."); + } + if (element.tagName === "A" && String(element.getAttribute("target") || "").toLowerCase() === "_blank") { + return btmcpGesture("popup", "Opening another tab or window needs a real gesture."); + } + + var bot = element.closest + ? element.closest(".g-recaptcha, .cf-turnstile, #px-captcha, iframe") + : null; + if (bot) { + var src = (bot.getAttribute && bot.getAttribute("src")) || ""; + var botClass = String(bot.className || ""); + if ( + bot.id === "px-captcha" || + botClass.indexOf("g-recaptcha") !== -1 || + botClass.indexOf("cf-turnstile") !== -1 || + /recaptcha|hcaptcha|challenges\.cloudflare|turnstile/i.test(src) + ) { + return btmcpGesture("anti-bot check", "An anti-bot check covers this control."); + } + } + + var rect = element.getBoundingClientRect ? element.getBoundingClientRect() : { width: 0, height: 0, left: 0, top: 0 }; + if (!rect || rect.width <= 0 || rect.height <= 0) { + return btmcpGesture("UI that needs the page drawn", "The element has no box."); + } + var x = rect.left + rect.width / 2; + var y = rect.top + rect.height / 2; + var top = document.elementFromPoint ? document.elementFromPoint(x, y) : element; + if (!top || (top !== element && !element.contains(top) && !(top.contains && top.contains(element)))) { + return btmcpGesture("UI that needs the page drawn", "Another element covers the target."); + } + + if (op === "type") return btmcpTypeInto(element, command.text == null ? "" : String(command.text), command.submit === true); + if (op === "click") return btmcpClick(element); + return btmcpGesture("UI that needs the page drawn", "Unknown soft action."); +} + +function btmcpFire(element, type, x, y) { + var pointer = type.indexOf("pointer") === 0; + var Ctor = pointer && typeof PointerEvent === "function" ? PointerEvent : MouseEvent; + element.dispatchEvent( + new Ctor(type, { + bubbles: true, + cancelable: true, + clientX: x, + clientY: y, + button: 0, + view: window, + }) + ); +} + +function btmcpClick(element) { + var rect = element.getBoundingClientRect(); + var x = rect.left + rect.width / 2; + var y = rect.top + rect.height / 2; + var form = element.closest ? element.closest("form") : null; + var inputType = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + var isSubmit = + Boolean(form) && + (inputType === "submit" || + (element.tagName === "BUTTON" && inputType !== "button" && inputType !== "reset")); + + if (element.tagName === "A" && element.href) { + return btmcpGesture("the site checks isTrusted", "An untrusted click does not follow a link."); + } + if (inputType === "checkbox" || inputType === "radio") { + return btmcpGesture("the site checks isTrusted", "An untrusted click does not toggle this control."); + } + + var saw = false; + function mark() { + saw = true; + } + element.addEventListener("click", mark); + btmcpFire(element, "pointerdown", x, y); + btmcpFire(element, "mousedown", x, y); + btmcpFire(element, "pointerup", x, y); + btmcpFire(element, "mouseup", x, y); + btmcpFire(element, "click", x, y); + element.removeEventListener("click", mark); + + if (isSubmit) { + var submitted = false; + function onSubmit() { + submitted = true; + } + form.addEventListener("submit", onSubmit); + try { + form.requestSubmit(element); + } catch (error) { + form.removeEventListener("submit", onSubmit); + return btmcpGesture("the site checks isTrusted", "requestSubmit did not run."); + } + form.removeEventListener("submit", onSubmit); + if (submitted) return btmcpWorked("Form submitted with requestSubmit."); + return btmcpGesture("the site checks isTrusted", "requestSubmit did not fire submit."); + } + + if (saw) return btmcpWorked("Untrusted click was delivered to the element."); + return btmcpGesture("the site checks isTrusted", "The element did not receive the click."); +} + +function btmcpSetNativeValue(element, text) { + var proto = element.tagName === "TEXTAREA" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype; + var descriptor = Object.getOwnPropertyDescriptor(proto, "value"); + if (descriptor && descriptor.set) descriptor.set.call(element, text); + else element.value = text; + element.dispatchEvent(new Event("input", { bubbles: true })); + element.dispatchEvent(new Event("change", { bubbles: true })); +} + +function btmcpFindEditor(element) { + if (element.isContentEditable) return element; + if (element.closest) { + return element.closest("[contenteditable='true'], .ProseMirror, .lexical-editor, [data-lexical-editor]"); + } + return null; +} + +function btmcpMaybeSubmit(element, submit) { + if (!submit) return null; + var form = element.closest ? element.closest("form") : null; + if (!form || typeof form.requestSubmit !== "function") { + return btmcpGesture("the site checks isTrusted", "The text was entered but there is no form to submit."); + } + var submitted = false; + function onSubmit() { + submitted = true; + } + form.addEventListener("submit", onSubmit); + try { + form.requestSubmit(); + } catch (error) { + form.removeEventListener("submit", onSubmit); + return btmcpGesture("the site checks isTrusted", "The text was entered but requestSubmit did not run."); + } + form.removeEventListener("submit", onSubmit); + if (!submitted) { + return btmcpGesture("the site checks isTrusted", "The text was entered but the form did not submit."); + } + return null; +} + +function btmcpTypeInto(element, text, submit) { + var inputType = ((element.getAttribute && element.getAttribute("type")) || element.type || "").toLowerCase(); + if (element.tagName === "INPUT" || element.tagName === "TEXTAREA") { + if (inputType === "password") { + return btmcpGesture("the site checks isTrusted", "Password fields are not filled by soft input."); + } + if (element.disabled || element.readOnly) { + return btmcpGesture("the site checks isTrusted", "The field is disabled or read-only."); + } + btmcpSetNativeValue(element, text); + if (element.value !== text) { + return btmcpGesture("the site checks isTrusted", "The value did not stick."); + } + var submitResult = btmcpMaybeSubmit(element, submit); + if (submitResult) return submitResult; + return btmcpWorked(submit ? "Value set and the form submitted." : "Value set with the native setter."); + } + + var editor = btmcpFindEditor(element); + if (!editor) { + return btmcpGesture("UI that needs the page drawn", "This element does not accept text."); + } + if (typeof editor.focus === "function") editor.focus(); + var inserted = typeof document.execCommand === "function" && document.execCommand("insertText", false, text); + var after = editor.textContent || ""; + if (!inserted || after.indexOf(text) === -1) { + return btmcpGesture("the site checks isTrusted", "execCommand did not insert the text."); + } + var editorSubmit = btmcpMaybeSubmit(editor, submit); + if (editorSubmit) return editorSubmit; + return btmcpWorked(submit ? "Text inserted and the form submitted." : "Inserted text with execCommand."); +} diff --git a/chrome-extension/tab-safety.js b/chrome-extension/tab-safety.js new file mode 100644 index 00000000..57134824 --- /dev/null +++ b/chrome-extension/tab-safety.js @@ -0,0 +1,92 @@ +/** + * Counts debugger calls and refuses focus changes. + * + * Wrapping chrome.debugger still calls through, so a real attach would show + * the banner. Tab actions never call it. tabs.update({active:true}) and + * windows.update({focused:true}) throw before the browser sees them. + */ +var BTMCP_SAFETY = (function () { + var debuggerCalls = 0; + var focusChanges = 0; + var installed = false; + + function snapshot() { + return { debuggerCalls: debuggerCalls, focusChanges: focusChanges }; + } + + function noteFocus() { + focusChanges += 1; + } + + function assertNoFocus(props) { + if (!props || typeof props !== "object") return; + if (props.active === true || props.focused === true) { + noteFocus(); + throw new Error("Refusing to change focus."); + } + } + + function install(chromeApi) { + if (installed || !chromeApi) return; + installed = true; + + if (chromeApi.debugger) { + ["attach", "sendCommand", "detach"].forEach(function (name) { + var original = chromeApi.debugger[name]; + if (typeof original !== "function") return; + chromeApi.debugger[name] = function () { + debuggerCalls += 1; + return original.apply(chromeApi.debugger, arguments); + }; + }); + } + + if (chromeApi.tabs && typeof chromeApi.tabs.update === "function") { + var update = chromeApi.tabs.update.bind(chromeApi.tabs); + chromeApi.tabs.update = function (tabId, props) { + assertNoFocus(props); + return update(tabId, props); + }; + } + + if (chromeApi.windows && typeof chromeApi.windows.update === "function") { + var winUpdate = chromeApi.windows.update.bind(chromeApi.windows); + chromeApi.windows.update = function (windowId, props) { + assertNoFocus(props); + return winUpdate(windowId, props); + }; + } + + var root = typeof globalThis !== "undefined" ? globalThis : self; + root.__btmcpSafety = { snapshot: snapshot }; + } + + /** + * Navigation and new tabs must say active: false. Anything else is refused + * and is not forwarded. + */ + function tabsUpdate(chromeApi, tabId, props) { + if (!props || props.active !== false || props.focused === true) { + noteFocus(); + throw new Error("Navigation must pass active: false."); + } + return chromeApi.tabs.update(tabId, { url: props.url, active: false }); + } + + function tabsCreate(chromeApi, props) { + if (!props || props.active !== false || props.focused === true) { + noteFocus(); + throw new Error("A new tab must pass active: false."); + } + var create = { url: props.url, active: false }; + if (typeof props.windowId === "number") create.windowId = props.windowId; + return chromeApi.tabs.create(create); + } + + return { + install: install, + snapshot: snapshot, + tabsUpdate: tabsUpdate, + tabsCreate: tabsCreate, + }; +})(); diff --git a/chrome-extension/worker.js b/chrome-extension/worker.js index cd7420ed..854c1aa1 100644 --- a/chrome-extension/worker.js +++ b/chrome-extension/worker.js @@ -3,11 +3,13 @@ * * Owns the toolbar-popup switch (session storage, so it resets when the * browser quits) and answers capability probes with a tab URL read at that - * moment via chrome.tabs.get. It does not click, type, navigate, or attach - * the debugger; those actions are separate work and must call - * BTMCP_GATES.confirmBeforeAct with a fresh tab read before they run. + * moment via chrome.tabs.get. Tab list, read, background navigate, and soft + * input go through BTMCP_TABS. Those paths do not call the debugger API and do + * not activate a tab or focus a window. DevTools capture stays in devtools.js. */ -importScripts("shared.js", "gates.js"); +importScripts("shared.js", "gates.js", "tab-safety.js", "tab-page.js", "tab-actions.js"); + +BTMCP_SAFETY.install(api); var socket = null; var reconnectTimer = null; @@ -40,16 +42,20 @@ async function readHumanState() { }; } -function send(message) { - if (!socket || socket.readyState !== WebSocket.OPEN) return false; +function sendOn(ws, message) { + if (!ws || ws.readyState !== WebSocket.OPEN) return false; try { - socket.send(JSON.stringify(message)); + ws.send(JSON.stringify(message)); return true; } catch (error) { return false; } } +function send(message) { + return sendOn(socket, message); +} + async function reportState() { var state = await readHumanState(); send({ @@ -68,159 +74,115 @@ function scheduleReconnect() { reconnectDelayMs = Math.min(reconnectDelayMs * 2, 15000); } +var connecting = false; + async function ensureConnected() { - if (closing) return; + if (closing || connecting) return; if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) { return; } + connecting = true; - var settings = await loadSettings(); - var found = await discoverServer(settings); - if (!found) { - scheduleReconnect(); - return; - } - - var token = ""; try { - var paired = await fetch("http://" + found.host + ":" + found.port + "/.pair", { method: "POST" }); - if (paired.ok) { - var body = await paired.json(); - if (body && typeof body.token === "string") token = body.token; + var settings = await loadSettings(); + var found = await discoverServer(settings); + if (!found) { + scheduleReconnect(); + return; } - } catch (error) { - token = ""; - } - if (!token) { - scheduleReconnect(); - return; - } - var ws; - try { - ws = new WebSocket("ws://" + found.host + ":" + found.port + "/extension-ws", ["browser-tools", token]); - } catch (error) { - scheduleReconnect(); - return; - } - socket = ws; - - ws.onopen = function () { - reconnectDelayMs = 1000; - send({ type: "hello", extensionVersion: "2.0.4", role: "worker" }); - void reportState(); - }; - - ws.onmessage = function (event) { - var message; + var token = ""; try { - message = JSON.parse(event.data); + var paired = await fetch("http://" + found.host + ":" + found.port + "/.pair", { method: "POST" }); + if (paired.ok) { + var body = await paired.json(); + if (body && typeof body.token === "string") token = body.token; + } } catch (error) { + token = ""; + } + if (!token) { + scheduleReconnect(); return; } - if (message && message.type === "capability-probe") { - void answerProbe(message); - } else if (message && message.type === "navigate-tab") { - void navigateTab(message); - } else if (message && message.type === "ping") { - send({ type: "pong", id: message.id }); + + var ws; + try { + ws = new WebSocket("ws://" + found.host + ":" + found.port + "/extension-ws", ["browser-tools", token]); + } catch (error) { + scheduleReconnect(); + return; } - }; + socket = ws; - ws.onclose = function () { - if (socket === ws) socket = null; - scheduleReconnect(); - }; + function reply(requestId, payload) { + sendOn(ws, Object.assign({ requestId: requestId }, payload)); + } - ws.onerror = function () { - /* onclose follows */ - }; + ws.onopen = function () { + reconnectDelayMs = 1000; + sendOn(ws, { type: "hello", extensionVersion: "2.0.4", role: "worker" }); + // State belongs on this socket. reportState() uses the current global + // socket, which a restart may already have replaced. + void readHumanState().then(function (state) { + sendOn(ws, { + type: "capability-state", + popupEnabled: state.popupEnabled, + excludeOrigins: state.excludeOrigins, + }); + }); + }; + + ws.onmessage = function (event) { + var message; + try { + message = JSON.parse(event.data); + } catch (error) { + return; + } + if (message && message.type === "capability-probe") { + void answerProbe(message, reply); + } else if (message && message.type === "navigate-tab") { + void BTMCP_TABS.navigateConnected(api, message, reply); + } else if (message && message.type === "list-chrome-tabs") { + void BTMCP_TABS.list(api, message, reply); + } else if (message && message.type === "navigate-chrome-tab") { + void BTMCP_TABS.navigateChrome(api, message, reply); + } else if (message && message.type === "read-chrome-tab") { + void BTMCP_TABS.read(api, message, reply); + } else if (message && message.type === "soft-input") { + void BTMCP_TABS.soft(api, message, reply); + } else if (message && message.type === "ping") { + sendOn(ws, { type: "pong", id: message.id }); + } + }; + + ws.onclose = function () { + if (socket === ws) socket = null; + scheduleReconnect(); + }; + + ws.onerror = function () { + /* onclose follows */ + }; + } finally { + connecting = false; + } } /** * Reads the switch and the tab again. The URL on the probe message is ignored; * chrome.tabs.get is the only source. */ -function respond(requestId, payload) { - send(Object.assign({ requestId: requestId }, payload)); -} - -function waitForTabUrl(tabId, timeoutMs) { - return new Promise(function (resolve) { - var done = false; - var timer = setTimeout(function () { - if (done) return; - done = true; - api.tabs - .get(tabId) - .then(function (tab) { - resolve(tab && tab.url ? tab.url : ""); - }) - .catch(function () { - resolve(""); - }); - }, timeoutMs); - - function onUpdated(updatedId, changeInfo, tab) { - if (done) return; - if (String(updatedId) !== String(tabId)) return; - if (changeInfo.status === "complete" && tab && tab.url) { - done = true; - clearTimeout(timer); - api.tabs.onUpdated.removeListener(onUpdated); - resolve(tab.url); - } - } - api.tabs.onUpdated.addListener(onUpdated); - }); -} - -async function navigateTab(message) { - var tabId = message.tabId; - var url = message.url; - if ((typeof tabId !== "number" && typeof tabId !== "string") || typeof url !== "string" || !url) { - respond(message.requestId, { - type: "navigate-result", - ok: false, - error: "tabId and url are required", - }); - return; - } - - try { - var before = await api.tabs.get(tabId); - var wasDiscarded = Boolean(before && before.discarded); - await api.tabs.update(tabId, { url: url, active: false }); - var finalUrl = await waitForTabUrl(tabId, 30000); - if (!finalUrl) { - var after = await api.tabs.get(tabId); - finalUrl = after && after.url ? after.url : url; - } - respond(message.requestId, { - type: "navigate-result", - ok: true, - finalUrl: finalUrl, - wasDiscarded: wasDiscarded, - }); - } catch (error) { - respond(message.requestId, { - type: "navigate-result", - ok: false, - error: error instanceof Error ? error.message : String(error), - }); - } -} - -async function answerProbe(message) { +async function answerProbe(message, reply) { var state = await readHumanState(); var liveUrl = null; if (message.tabId != null && (state.popupEnabled || state.panelEnabled)) { var tabId = typeof message.tabId === "number" ? message.tabId : Number(message.tabId); if (!Number.isInteger(tabId)) { - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: false, error: "Could not read the tab", popupEnabled: state.popupEnabled, @@ -233,9 +195,8 @@ async function answerProbe(message) { var tab = await api.tabs.get(tabId); liveUrl = tab && typeof tab.url === "string" ? tab.url : null; } catch (error) { - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: false, error: "Could not read the tab", popupEnabled: state.popupEnabled, @@ -246,9 +207,8 @@ async function answerProbe(message) { } } - send({ + reply(message.requestId, { type: "capability-probe-result", - requestId: message.requestId, ok: true, liveUrl: liveUrl, popupEnabled: state.popupEnabled, From a4fd3408c4fb78d31783b1d1e37fc14b43176cca Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 27 Oct 2026 04:32:16 +0000 Subject: [PATCH 2/3] Refuse restricted destinations when opening a new background tab. Opening a tab had no live page, so the restricted-page check on navigate did not run. chrome:// and the Web Store are refused there too. An http(s) PDF can still load. Co-authored-by: werbel.ted --- .../test/unit/capability-gates.test.ts | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/browser-tools-mcp/test/unit/capability-gates.test.ts b/browser-tools-mcp/test/unit/capability-gates.test.ts index 928cf0ee..4e6b1616 100644 --- a/browser-tools-mcp/test/unit/capability-gates.test.ts +++ b/browser-tools-mcp/test/unit/capability-gates.test.ts @@ -206,6 +206,31 @@ describe("origin allowlist", () => { ).toEqual({ allowed: false, reason: GateReason.destinationMissing }); }); + it("refuses a restricted destination when opening a new background tab", () => { + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + liveUrl: null, + destinationUrl: "chrome://settings", + }) + ).toEqual({ allowed: false, reason: GateReason.restricted }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "https://chromewebstore.google.com/detail/ext", + }) + ).toEqual({ allowed: false, reason: GateReason.restricted }); + expect( + decideCapability("navigate", { + ...open, + creatingTab: true, + destinationUrl: "http://localhost:3000/manual.pdf", + }).allowed + ).toBe(true); + }); + it("allows local addresses by default and refuses a public origin until it is listed", () => { expect( decideCapability("softClick", { ...open, liveUrl: "http://localhost:3000/app" }).allowed From cfe0346b040e788073e94316222a5c8c5aa8184f Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 27 Oct 2026 04:34:41 +0000 Subject: [PATCH 3/3] Wait for the form result title before asserting listTabs. The submitted page can still be loading when listTabs runs, so the title is the URL. Poll until the title is present. Co-authored-by: werbel.ted --- browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts index ec3e50fa..0890631b 100644 --- a/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts +++ b/browser-tools-mcp/test/e2e/tab-awareness.e2e.test.ts @@ -198,7 +198,15 @@ describe("tab awareness without DevTools", () => { expect(settled.activeUrl).toBe(before.activeUrl); expect(settled.safety).toEqual({ debuggerCalls: 0, focusChanges: 0 }); - const again = await callTool("listTabs"); + // The result page's title replaces the URL only after load. listTabs can + // observe the tab while it is still loading. + let again: Record | undefined; + const titleDeadline = Date.now() + 5_000; + while (Date.now() < titleDeadline) { + again = await callTool("listTabs"); + if (JSON.stringify(again).includes("Form result")) break; + await new Promise((resolve) => setTimeout(resolve, 100)); + } const tabs = JSON.stringify(again); expect(tabs).toContain("Form result"); expect(tabs).toContain(String(before.activeId));