Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

## Unreleased

- **Opt-in 8-hour tab timeline.** Recording stays off until the user enables a
tab or an origin in the extension popup. `listTracked` lists what is on.
`getTimeline` returns redacted console and network for one tab or origin
between `from` and `to`, or for `lastMinutes`. The log is local, kept for a
rolling 8 hours, then dropped. Cookie and Authorization values are removed
before storage. A tab that was never enabled, or a time outside the window,
comes back empty. The capture wraps console and fetch/XHR. It does not
attach the debugger and does not hide the debugging banner.
- **Non-scriptable pages are reported the same way everywhere.** `chrome://`,
DevTools, `view-source:`, the Chrome Web Store, extension pages, and the
built-in PDF viewer come back as metadata only (`access: "metadata-only"`,
Expand Down
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,8 @@ setup and a silent one look the same.
| `takeScreenshot` | Screenshot returned **as an image**, plus its file path |
| `refreshBrowser` | Reloads the inspected tab |
| `getBrowserStorage` | localStorage, sessionStorage and cookies (values gated) |
| `listTracked` | Tabs and origins the user enabled for the 8-hour log |
| `getTimeline` | Redacted console and network for one tab or origin, by time |
| `wipeLogs` | Clears captured telemetry before a clean reproduction |
| `runAccessibilityAudit` | Lighthouse accessibility audit |
| `runPerformanceAudit` | Lighthouse performance audit with Core Web Vitals |
Expand All @@ -131,6 +133,14 @@ clients can auto-approve them safely.

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.

### 8-hour log

Recording is off until the user turns it on for a tab or a site in the extension popup. `listTracked` shows what is on. `getTimeline` reads redacted console and network for one `chromeTabId` or origin, using `from` and `to` or `lastMinutes`.

The log stays on this machine for a rolling 8 hours, then it is dropped. Cookie and Authorization values are removed before they are stored. If that tab or origin was never enabled, or the time is outside the window, the result is empty. It does not guess from the DevTools buffer.

This path wraps the page's console and fetch/XHR. It does not attach the debugger, so it does not show or hide the debugging banner, and it does not click or drive the page. `wipeLogs` clears the DevTools buffer only.

### Several tabs at once

Every tab with DevTools open is tracked separately. Telemetry is attributed to
Expand Down
7 changes: 7 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,13 @@ be, both are worth reporting.
`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.
- The 8-hour tab log is off until the user enables a tab or an origin in the
extension popup. It is stored only in the local state directory
(`timeline.json`, mode `0600`), kept for a rolling 8 hours, then deleted.
Cookie, Set-Cookie, and Authorization values are removed before storage.
Capture uses page hooks, not `chrome.debugger`, so it does not hide the
debugging banner. A query for a target that was never enabled, or a time
outside that window, returns an empty result.
- 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
Expand Down
3 changes: 2 additions & 1 deletion browser-tools-mcp/src/connector-bin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
*/
import { parseCli, readPackageVersion } from "./cli.js";
import { createConnector } from "./connector/connector.js";
import { clearSessionFile, writeSessionFile } from "./util/session.js";
import { clearSessionFile, sessionDir, writeSessionFile } from "./util/session.js";
import { createLogger } from "./util/logger.js";
import { getDefaultScreenshotDir } from "./util/paths.js";

Expand Down Expand Up @@ -70,6 +70,7 @@ async function main(): Promise<void> {
...(options.enabledTools ? { enabledTools: options.enabledTools } : {}),
...(options.disabledTools ? { disabledTools: options.disabledTools } : {}),
...(options.extensionId ? { extensionId: options.extensionId } : {}),
timelineDir: sessionDir(),
});

writeSessionFile({
Expand Down
4 changes: 4 additions & 0 deletions browser-tools-mcp/src/connector/api-policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ export const API_TOOL_NAMES: readonly string[] = [
"navigateBrowser",
"getBrowserStorage",
"wipeLogs",
"listTracked",
"getTimeline",
...AUDIT_CATEGORIES.map((category) => AUDIT_TOOL[category]),
];

Expand Down Expand Up @@ -112,6 +114,8 @@ function toolsForRequest(method: string, path: string, query: Record<string, unk
if (method === "POST" && path === "/navigate") return ["navigateBrowser"];
if (method === "POST" && path === "/storage") return ["getBrowserStorage"];
if (method === "POST" && path === "/wipe") return ["wipeLogs"];
if (method === "GET" && path === "/timeline") return ["listTracked"];
if (method === "GET" && path === "/timeline/logs") return ["getTimeline"];
if (method === "GET" && path === "/export/console") return ["getConsoleLogs", "getConsoleErrors"];
if (method === "GET" && path === "/export/network") return ["getNetworkLogs", "getNetworkErrors"];

Expand Down
56 changes: 56 additions & 0 deletions browser-tools-mcp/src/connector/connector.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,13 @@ import {
type QueryResult,
type TabId,
} from "./store.js";
import {
TimelineQueryError,
TimelineStore,
type TimelineListing,
type TimelineQuery,
type TimelineResult,
} from "../timeline/store.js";
import {
bearerToken,
extensionOriginAllowed,
Expand Down Expand Up @@ -178,6 +185,11 @@ export interface ConnectorConfig {
disabledTools?: string[];
/** When set, only this extension (bare id or full origin) may pair. */
extensionId?: string;
/**
* Directory for the opt-in 8-hour log. Omit in tests to keep it in memory.
* The running connector passes the local state directory.
*/
timelineDir?: string;
}

export interface TabView {
Expand Down Expand Up @@ -284,6 +296,10 @@ export interface Connector {
text: string;
submit?: boolean;
}): Promise<SoftInputResult>;
/** Tabs and origins the user has enabled for the 8-hour log. */
listTracked(): TimelineListing;
/** Redacted console and network for one tab or origin. Empty when untracked or outside the window. */
queryTimeline(query: TimelineQuery): TimelineResult;
close(): Promise<void>;
}

Expand Down Expand Up @@ -349,6 +365,7 @@ export async function createConnector(config: ConnectorConfig = {}): Promise<Con
const requestTimeoutMs = config.requestTimeoutMs ?? 10_000;

const store = new TelemetryStore({ redact: config.redact !== false });
const timeline = new TimelineStore(config.timelineDir ? { dir: config.timelineDir } : {});
const verbose = config.verbose === true;

const inputOriginList = normalizeOriginList(config.allowInputOrigins);
Expand Down Expand Up @@ -557,6 +574,30 @@ export async function createConnector(config: ConnectorConfig = {}): Promise<Con
});
});

api.get("/timeline", (_req, res) => {
res.json(timeline.list());
});

api.get("/timeline/logs", (req: Request, res: Response) => {
try {
const chromeTabId = parseCount(req.query["chromeTabId"]);
const lastMinutes = parseCount(req.query["lastMinutes"]);
const limit = parseCount(req.query["limit"]);
res.json(
timeline.query({
...(chromeTabId !== undefined ? { chromeTabId } : {}),
...(typeof req.query["origin"] === "string" ? { origin: req.query["origin"] } : {}),
...(typeof req.query["from"] === "string" ? { from: req.query["from"] } : {}),
...(typeof req.query["to"] === "string" ? { to: req.query["to"] } : {}),
...(lastMinutes !== undefined ? { lastMinutes } : {}),
...(limit !== undefined ? { limit } : {}),
})
);
} catch (error) {
respondWithError(res, error);
}
});

api.get("/status", (_req, res) => {
res.json({
version: SERVER_VERSION,
Expand Down Expand Up @@ -1219,6 +1260,14 @@ export async function createConnector(config: ConnectorConfig = {}): Promise<Con
case "settings":
store.updateSettings(message["settings"]);
break;
case "timeline-targets":
if (connection.role !== "worker" || !connection.fromExtension) break;
timeline.replaceTargets(message["targets"]);
break;
case "timeline-event":
if (connection.role !== "worker" || !connection.fromExtension) break;
timeline.ingest(message["event"]);
break;
case "screenshot-result":
case "refresh-result":
case "navigate-result":
Expand Down Expand Up @@ -1823,6 +1872,7 @@ export async function createConnector(config: ConnectorConfig = {}): Promise<Con

async function close(): Promise<void> {
clearInterval(heartbeat);
timeline.flush();
for (const { timer, reject } of pending.values()) {
clearTimeout(timer);
reject(new Error("Connector shutting down"));
Expand Down Expand Up @@ -1877,6 +1927,8 @@ export async function createConnector(config: ConnectorConfig = {}): Promise<Con
softTypeChromeTab,
readStorage,
runAudit,
listTracked: () => timeline.list(),
queryTimeline: (query) => timeline.query(query),
close,
};
}
Expand Down Expand Up @@ -1912,6 +1964,10 @@ function respondWithError(res: Response, error: unknown): void {
res.status(502).json({ error: error.message, code: "EXTENSION_ERROR" });
return;
}
if (error instanceof TimelineQueryError) {
res.status(400).json({ error: error.message, code: "BAD_TIMELINE_QUERY" });
return;
}
log.error("Unexpected error:", error);
res.status(500).json({ error: (error as Error)?.message ?? "Internal error" });
}
Expand Down
19 changes: 19 additions & 0 deletions browser-tools-mcp/src/mcp/client.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ import type {
ChromeTabRead,
SoftInputResult,
} from "../tabs/contract.js";
import type { TimelineListing, TimelineQuery, TimelineResult } from "../timeline/store.js";

export interface PageInfo {
url: string;
Expand Down Expand Up @@ -111,6 +112,8 @@ export interface ConnectorClient {
exportConsole(options?: { tabId?: TabId; allTabs?: boolean }): Promise<ExportResult<ConsoleEntry>>;
exportNetwork(options?: { tabId?: TabId; allTabs?: boolean }): Promise<ExportResult<NetworkEntry>>;
readArtifact(kind: "screenshot" | "audit", name: string): Promise<Artifact>;
listTracked(): Promise<TimelineListing>;
getTimeline(query: TimelineQuery): Promise<TimelineResult>;
}

/** Talks straight to an embedded connector — no network hop, no discovery. */
Expand Down Expand Up @@ -242,6 +245,14 @@ export class InProcessConnectorClient implements ConnectorClient {
async readArtifact(kind: "screenshot" | "audit", name: string): Promise<Artifact> {
return this.#connector.readArtifact(kind, name);
}

async listTracked(): Promise<TimelineListing> {
return this.#connector.listTracked();
}

async getTimeline(query: TimelineQuery): Promise<TimelineResult> {
return this.#connector.queryTimeline(query);
}
}

export interface HttpConnectorClientOptions {
Expand Down Expand Up @@ -399,4 +410,12 @@ export class HttpConnectorClient implements ConnectorClient {
readArtifact(kind: "screenshot" | "audit", name: string): Promise<Artifact> {
return this.#request(`/api/artifact/${kind}/${encodeURIComponent(name)}`);
}

listTracked(): Promise<TimelineListing> {
return this.#request("/api/timeline");
}

getTimeline(query: TimelineQuery): Promise<TimelineResult> {
return this.#request("/api/timeline/logs", { query: query as Record<string, unknown> });
}
}
9 changes: 8 additions & 1 deletion browser-tools-mcp/src/mcp/prompts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,14 @@ evidence before changing code.
Never assume a log line is current — check timestamps against the reproduction.
Captured values are redacted where they looked like credentials; if a value
reads as [REDACTED] that is this tool protecting the user, not the application
misbehaving.`;
misbehaving.

The 8-hour log is separate from the DevTools buffer and stays off until the
user enables a tab or a site in the extension popup. Call listTracked to see
what they enabled. Call getTimeline with chromeTabId or origin, and from/to
or lastMinutes. If reason is not-enabled or outside-window, the arrays are
empty on purpose. Do not fill that gap from getConsoleLogs, and do not guess
a different tab.`;

const AUDIT_MODE = `You are running a quality audit of a live page using BrowserTools MCP.

Expand Down
2 changes: 2 additions & 0 deletions browser-tools-mcp/src/mcp/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ import {
NAVIGATE_BROWSER_DESCRIPTION,
} from "../tabs/contract.js";
import { TAB_TOOLS } from "../tabs/tools.js";
import { TIMELINE_TOOLS } from "../timeline/tools.js";

const log = createLogger("mcp");

Expand Down Expand Up @@ -270,6 +271,7 @@ function auditTool(

const TOOLS: ToolDefinition[] = [
...TAB_TOOLS,
...TIMELINE_TOOLS,
{
name: "listBrowserTabs",
register(server, client) {
Expand Down
5 changes: 5 additions & 0 deletions browser-tools-mcp/src/mcp/tool-invoke.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import {
import type { AuditCategory } from "../lighthouse/types.js";
import { RestrictedPageError, restrictedPageToolText } from "../restricted-page.js";
import { invokeTabTool } from "../tabs/tools.js";
import { invokeTimelineTool } from "../timeline/tools.js";

export type ToolContent =
| { type: "text"; text: string }
Expand Down Expand Up @@ -127,6 +128,8 @@ export async function invokeTool(
): Promise<ToolResult> {
const tabTool = await invokeTabTool(name, client, args);
if (tabTool) return tabTool;
const timelineTool = await invokeTimelineTool(name, client, args);
if (timelineTool) return timelineTool;

switch (name) {
case "listBrowserTabs":
Expand Down Expand Up @@ -339,6 +342,8 @@ export const INVOKABLE_TOOL_NAMES: readonly string[] = [
"navigateBrowser",
"getBrowserStorage",
"wipeLogs",
"listTracked",
"getTimeline",
"runAccessibilityAudit",
"runPerformanceAudit",
"runSEOAudit",
Expand Down
9 changes: 8 additions & 1 deletion browser-tools-mcp/src/runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ import {
InProcessConnectorClient,
type ConnectorClient,
} from "./mcp/client.js";
import { readSessionFile, writeSessionFile, clearSessionFile } from "./util/session.js";
import { readSessionFile, sessionDir, writeSessionFile, clearSessionFile } from "./util/session.js";
import { createLogger } from "./util/logger.js";
import { readPackageVersion, type CliOptions } from "./cli.js";

Expand Down Expand Up @@ -102,6 +102,12 @@ class UnavailableConnectorClient implements ConnectorClient {
readArtifact(): Promise<never> {
return this.#fail();
}
listTracked(): Promise<never> {
return this.#fail();
}
getTimeline(): Promise<never> {
return this.#fail();
}
}

/**
Expand Down Expand Up @@ -203,6 +209,7 @@ export async function createRuntime(options: CliOptions): Promise<Runtime> {
...(options.enabledTools ? { enabledTools: options.enabledTools } : {}),
...(options.disabledTools ? { disabledTools: options.disabledTools } : {}),
...(options.extensionId ? { extensionId: options.extensionId } : {}),
timelineDir: sessionDir(),
});

writeSessionFile({
Expand Down
Loading
Loading