Skip to main content
Glama

RawTrace MCP

让 AI 看见网页变化的过程:持续采集,按需回溯。

Passive browser tracing for coding agents — document baselines, incremental changes, and queryable history.

English · 快速开始 · 工具与查询 · Trace v2 · 安全说明

这是做什么的?

RawTrace 是一个本地 MCP 记录器。你的 Playwright 脚本或其他工具负责操作浏览器,RawTrace 通过 CDP 旁路连接选定标签页,持续记录 DOM、表单状态、网络、WebSocket、Cookie、Console 和 iframe 生命周期。

适合排查:一闪而过的提示、偶发自动化失败、异步 DOM 更新、请求与界面状态不一致、登录跳转和 WebSocket 消息时序。采集结束后,可以搜索事件,也可以查询某个时间或事件序号时的页面状态。

Playwright / 其他浏览器工具 ──操作──> 已开启 CDP 的 Chromium
                                        │
                                     RawTrace
                                        │
                          初始基线 → 增量事件 → 检查点
                                        │
                        本地文件 ← MCP 查询 / 历史状态重建
  • 增量记录:初始文档保存一份节点树,后续记录节点增删、移动、属性、文本和表单状态变化。

  • 可回溯:刷新或导航建立新基线;检查点缩短历史状态重建所需的增量链。

  • 可查询:按页面、来源、时间、序号、节点或文本检索;支持明确开启的网络 body 文本搜索。

  • 持久保存:NDJSON 分段写入,大内容按 SHA-256 去重;服务重启后仍可查询。

  • 范围明确:只录制显式选择的标签页及其 iframe,不自动跟随弹窗或其他标签页。

网络请求、WebSocket 消息和 Console 日志本身按事件保存,不对它们强行做 DOM diff。重复的消息事件仍保留,只有附件内容去重。

Related MCP server: FlowLens MCP

版本与安装渠道

渠道

当前内容

使用方式

本仓库 main / 源码 0.4.0

新版持续采集,9 个工具,trace v2

按下方步骤从源码构建

npm 0.3.0 / v0.3.0 标签

旧版浏览器控制与监控接口,trace v1

仅用于旧工作流

插件市场当前固定版本

仍指向已发布的 npm 0.3.0

尚不提供本文的新版接口

0.4.0 尚未发布到 npm。 直接执行 npx rawtrace-mcp 或从当前插件市场安装,可能得到旧版;要使用本页描述的功能,请先使用源码构建和绝对路径配置。发布新版后再更新市场固定版本。

新版移除了全部 browser_*、monitor_*、--tool-profile 以及 ZIP 导出。旧 trace 不会被修改,但 v2 查询器不重建 v1;旧文件请用 0.3.x 或对应历史版本读取。

快速开始

1. 获取并构建

需要 Node.js 22+。

git clone https://github.com/ss26367098/rawtrace-mcp.git
cd rawtrace-mcp
npm ci
npm run build

2. 准备一个可连接的浏览器

如果你的自动化工具已经提供 Chromium CDP 地址,直接使用它,并跳到第 3 步。RawTrace 自身不会启动、导航或关闭浏览器。

没有现成 CDP 浏览器时,可以使用仓库中的独立示例控制器:

npx playwright install chromium
node examples/browser.mjs http://localhost:3000

把 URL 换成你的测试站点,或省略 URL 打开空白页。示例启动一个独立测试 profile,CDP 地址默认为 http://127.0.0.1:9222,可通过 --port 9333 修改;终端需保持运行。它是外部控制器示例,不是 MCP 工具。

你可以在这个浏览器中手动复现,也可以让现有 Playwright 控制器连接同一个 CDP 地址进行操作。两个不同的浏览器实例不会自动共享录制范围。没有暴露 CDP 的内置浏览器不能直接接入。

3. 在 MCP 客户端配置本地入口

Codex:编辑 ~/.codex/config.toml,按实际路径填写:

[mcp_servers.rawtrace]
command = "node"
args = [
  "/absolute/path/rawtrace-mcp/dist/cli.js",
  "--output-root",
  "/absolute/path/rawtrace-data"
]
startup_timeout_sec = 30

Windows 路径可用正斜杠,例如 C:/Projects/rawtrace-mcp/dist/cli.js 和 C:/Data/rawtrace-traces。使用绝对输出路径,避免重启后因工作目录变化而找不到历史。配置格式参考 Codex 官方 MCP 文档。

也可以通过 CLI 注册:

codex mcp add rawtrace -- node /absolute/path/rawtrace-mcp/dist/cli.js --output-root /absolute/path/rawtrace-data

支持 mcpServers JSON 的客户端:

{
  "mcpServers": {
    "rawtrace": {
      "command": "node",
      "args": ["/absolute/path/rawtrace-mcp/dist/cli.js", "--output-root", "/absolute/path/rawtrace-data"]
    }
  }
}

重启客户端或新建会话,确认出现下表中的 9 个工具。不要同时保留一个提供旧接口的同名插件。stdio 模式由客户端启动,不需要额外在终端启动 MCP 服务。

4. 让 Agent 开始采集

可以直接给 Agent 这段提示:

我的授权测试浏览器 CDP 地址是 http://127.0.0.1:9222。先列出标签页,只选 URL 为 http://localhost:3000 的页面开启 RawTrace 持续采集。浏览器操作交给原有工具。复现结束后停止采集,检索相关 DOM 和网络事件,并给出关键事件序号及前后页面状态。不要在回复里展示原始凭据。

工具调用顺序:

  1. capture_targets:传入 cdpUrl 和 acknowledgeRawCapture: true,取得真实 targetId。

  2. capture_start:传入同一 cdpUrl、选定的 targetIds 和 acknowledgment。保存返回的 sessionId。

  3. 用外部工具或手动操作复现问题。期间可调用 capture_status。

  4. capture_stop({}):刷新记录并断开;浏览器保持运行。

  5. 用返回的 sessionId 查询历史;trace_state.pageId 使用之前选定的 targetId。

工具与查询

工具

用途

capture_targets

发现现有 CDP 浏览器中的页面

capture_start

对明确目标开启一个持续采集会话

capture_status

查看计数、队列、容量及异常状态

capture_stop

停止并落盘,释放连接

trace_list

从输出根目录发现历史记录,包括标注为 legacy 的 v1

trace_info

读取 manifest、检查点和恢复诊断

trace_events

分页检索事件,按需搜索网络 body

trace_state

重建指定时刻的节点树或文本及可用 Cookie 状态

trace_artifact

按引用分块读取经完整性校验的附件

除 capture_stop 外,发现及数据读取工具均要求 acknowledgeRawCapture: true。同一服务进程允许一个活动采集会话,该会话可显式选择多个页面。

以下 JSON 是 MCP 工具参数,不是终端命令。把占位 ID 换成实际返回值。

搜索 DOM 变化 — trace_events:

{
  "sessionId": "trace_REPLACE_WITH_SESSION_ID",
  "source": "dom",
  "text": "加载中",
  "afterSeq": 0,
  "limit": 100,
  "acknowledgeRawCapture": true
}

搜索接口响应内容 — trace_events:

{
  "sessionId": "trace_REPLACE_WITH_SESSION_ID",
  "source": "network",
  "urlContains": "/api/profile",
  "text": "unauthorized",
  "searchBodies": true,
  "acknowledgeRawCapture": true
}

重建某一事件之后的页面文本 — trace_state:

{
  "sessionId": "trace_REPLACE_WITH_SESSION_ID",
  "pageId": "REPLACE_WITH_TARGET_ID",
  "atSeq": 120,
  "format": "text",
  "acknowledgeRawCapture": true
}

省略 atSeq 查询最新已录状态;也可以改用 atTime(Unix epoch 毫秒),两者不能同时指定。format: "tree" 返回带节点 ID 的结构和表单状态。请同时检查 complete 和 gaps。

事件每页默认 100 条、最多 1,000 条。若 hasMore: true,使用返回的 nextAfterSeq 作为下一次的 afterSeq。大型查询结果会返回 JSON 附件引用,用 trace_artifact 的 ref、offset 和 maxBytes 分块读取;精确拼接二进制内容时使用 encoding: "base64"。完整参数和格式见 Trace v2。

可选配置、数据范围与限制

  • 各采集种类默认开启,可在 capture_start 单独设置 captureDom、captureNetwork、captureWebSockets、captureCookies、captureConsole、captureFrames。

  • Cookie 按所选页面所在的整个共享浏览器上下文采样:初始基线、每秒差异、停止前最后比较;采样间的快速变化可能漏过。

  • 单个网络 body 默认上限为 20 MB,maxBodyBytes 可调整;没有会话总容量限制或自动历史清理。磁盘空间需要自行管理。

  • DOM 默认在有变化的 60 秒后,或累计 5,000 个增量事件后建立检查点。事件日志按 64 MiB 分段,附件按内容去重。

  • 队列、断连和写入失败会报告;并不保证捕获浏览器中所有内部事件。

  • 跨域 iframe 的检查点异步补齐;中间时刻查询可能明确返回文档缺失。closed shadow DOM、Canvas/WebGL、CSSOM 动画和视觉回放不在范围内。

  • 重建文本是记录的文本节点拼接,不等于浏览器布局后的 innerText。时间对齐是估算,事件先后不能直接证明因果关系。

增量存储不是脱敏。 基线及变化仍可能包含输入值、密码、Cookie、token、请求体和个人信息。只在授权系统使用,CDP 地址保持私有,不要提交或分享真实 trace。

可选 HTTP 接入

node dist/cli.js --transport http --host 127.0.0.1 --port 3757 --output-root /absolute/path/rawtrace-data

客户端连接 http://127.0.0.1:3757/mcp。非 loopback 绑定需要 --unsafe-remote 和 --auth-token。stdio 和 HTTP 是二选一的服务启动方式;它们都需要另外提供浏览器的 CDP 地址。

常见问题

现象

检查方法

仍出现 35/59 个旧工具

检查是否仍在使用 npm 0.3.0 或旧插件;改为本地 dist/cli.js 后重启

CDP 连接失败

检查浏览器是否运行、端口是否开启;9222 是浏览器端口,3757 是可选 MCP HTTP 端口

找不到 targetId

重新调用 capture_targets,标签页关闭重开后 ID 会变化

找不到历史会话

保持同一个绝对 --output-root;trace_list 只发现其下的会话

不能读取旧 trace

v1 仅列出,不自动转换;使用旧版本读取

基线缺失或 complete=false

查看 trace_info / gaps;查询时间可能早于首份基线,或存在导航、iframe、缓冲或断连缺口

开发与验证

npm run typecheck
npm run lint
npm test
npm run test:real-run

集成测试通过独立 Playwright 浏览器验证记录与重建;real-run 实际调用全部 9 个工具。实现分为 CDP 连接、采集、会话存储、状态重建和 MCP 接口;浏览器脚本本地打包,不加载 CDN。

贡献指南 · 安全策略 · MIT License

Available Tools

59 tools
browser_attach_cdpAttach to ChromiumA

Use when an already-running Chromium instance contains the page that must be diagnosed and a tab needs to be selected by page ID, URL, title, or index. Preconditions: the CDP endpoint and target browser must be explicitly authorized and reachable. Next: confirm the selected page with browser_get_state, then observe one action or start a multi-step trace. Sensitivity: attaching exposes the live browser context and any data visible in the selected tab.

Inputs: cdpUrl (required), pageId, activate, targetIndex, +2 more. Returns: ok, error, result

browser_checkCheck Form ControlA
Destructive

Use when a checkbox or radio control must be checked or unchecked during a reproduction. Preconditions: an active page and precise selector are required. Next: continue the flow or inspect validation, DOM, and request changes. Sensitivity: changing a control can submit data, mutate remote state, or expose values in traces.

Inputs: selector (required), checked, timeoutMs. Returns: ok, error, result

browser_clear_cookiesClear Browser CookiesA
Destructive

Use when a full-profile test needs a deliberate logged-out or clean-cookie state. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required; filters should be as narrow as possible. Next: reproduce the intended authentication or redirect behavior after clearing. Sensitivity: clearing cookies can sign out accounts and irreversibly remove session state from the active context.

Inputs: name, path, domain, acknowledgeRawCapture, +1 more. Returns: ok, error, result

browser_clickClick ElementA
Destructive

Use when a known element must be clicked during a traced multi-step reproduction and before/after aggregation is not needed. Preconditions: an active page and a precise selector are required; prefer browser_observe_action_result when the outcome is uncertain. Next: continue the reproduction or inspect the resulting state and network events. Sensitivity: clicking can submit forms, mutate remote data, navigate, download files, or trigger other external effects.

Inputs: selector (required), timeoutMs. Returns: ok, error, result

browser_closeClose BrowserA
Destructive

Use when the RawTrace browser context is no longer needed or must be reset before a clean reproduction. Preconditions: stop an active monitor first when its trace must be flushed and retained. Next: launch or attach again only if more browser work is required. Sensitivity: closing destroys the in-memory browser context and can discard unsaved page state.

Inputs: no named parameters. Returns: ok, error, result

browser_close_tabClose Browser TabA
Destructive

Use when a full-profile workflow must remove an unneeded page or recover from a page-specific failure. Preconditions: identify the intended page and stop any trace that must retain its final events. Next: list tabs or inspect state to confirm which page remains active. Sensitivity: closing a tab discards its unsaved in-memory state.

Inputs: pageId. Returns: ok, error, result

browser_evalEvaluate Page JavaScriptA
Destructive

Use when a full-profile diagnosis cannot be completed with safe DOM, action, wait, or trace tools and exact page-side JavaScript is essential. Preconditions: an active authorized page plus acknowledgeRawCapture: true and acknowledgeDangerousEval: true are required. Next: prefer a targeted inspection tool afterward and document why arbitrary evaluation was necessary. Sensitivity: arbitrary JavaScript can read or modify DOM, storage, page-visible credentials, and remote application state.

Inputs: expression (required), arg, maxBytes, frameName, +4 more. Returns: ok, error, result

browser_export_storage_stateExport Storage StateA

Use when a full-profile authorized workflow explicitly needs a Playwright storageState file for reproduction or transfer. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required and the output path must be protected. Next: use the file only for the intended test and remove it when no longer needed. Sensitivity: the exported file may contain reusable cookies, tokens, origins, and IndexedDB data.

Inputs: maxBytes, indexedDB, outputPath, acknowledgeRawCapture, +1 more. Returns: ok, error, result

browser_fill_formFill FormA
Destructive

Use when multiple form controls must be populated consistently and optionally submitted during a reproduction. Preconditions: an active page and unambiguous field selectors, names, labels, or placeholders are required; provide only intended test data. Next: observe validation, submission requests, redirects, and final state. Sensitivity: filled values may be captured in the DOM, requests, screenshots, traces, or remote application state.

Inputs: fields (required), timeoutMs, submitSelector. Returns: ok, error, result

browser_get_accessibilityInspect AccessibilityA
Read-onlyIdempotent

Use when a full-profile diagnosis specifically needs DOM-derived roles, names, states, or accessibility-oriented element summaries. Preconditions: an active page and acknowledgeRawCapture: true are required. Next: use the returned selector and role context in a targeted action or source fix. Sensitivity: accessible names and values are derived from raw DOM and may contain sensitive content.

Inputs: limit, selector, textContains, acknowledgeRawCapture. Returns: ok, error, result

browser_get_cookiesRead Browser CookiesA
Read-onlyIdempotent

Use when a full-profile authentication or cookie-specific diagnosis explicitly requires raw cookie values. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required on an authorized account. Next: inspect only the relevant cookie fields and avoid copying values into reports or code. Sensitivity: cookies are credentials and must be treated as secrets.

Inputs: urls, acknowledgeRawCapture, acknowledgeCredentialAccess. Returns: ok, error, result

browser_get_domInspect DOMA
Read-onlyIdempotent

Use when current HTML or text for a page region is needed to understand transient DOM state, hidden content, or selector behavior. Preconditions: an active page and acknowledgeRawCapture: true are required; narrow with a selector when possible. Next: use browser_get_elements for actionable targets or compare DOM mutations in a trace. Sensitivity: raw DOM and text may contain secrets, personal data, hidden form values, or externalized artifacts.

Inputs: mode, maxBytes, selector, acknowledgeRawCapture. Returns: ok, error, result

browser_get_downloadsList DownloadsA
Read-onlyIdempotent

Use when saved downloads from the current runtime must be located or verified after a download flow. Preconditions: at least one download should have completed in this runtime. Next: use the relevant local file with an appropriate parser or test assertion. Sensitivity: download paths, filenames, URLs, and files can contain sensitive information.

Inputs: limit. Returns: ok, error, result

browser_get_elementsList Interactive ElementsA
Read-onlyIdempotent

Use when stable selectors and concise metadata for clickable, editable, or otherwise interactive elements are needed before an action. Preconditions: an active page and acknowledgeRawCapture: true are required; filter by selector or text on large pages. Next: call browser_observe_action_result with the chosen selector for a single uncertain interaction. Sensitivity: element summaries can include visible text, attributes, values, and other raw page metadata.

Inputs: limit, selector, textContains, acknowledgeRawCapture. Returns: ok, error, result

browser_get_formsInspect FormsA
Read-onlyIdempotent

Use when form structure, labels, controls, values, validation state, or submit targets are needed before reproducing a form issue. Preconditions: an active page and acknowledgeRawCapture: true are required; filter to the relevant form when possible. Next: use browser_fill_form for a multi-field reproduction or browser_observe_action_result for one uncertain control action. Sensitivity: form metadata can contain visible or hidden values, personal data, and credential fields.

Inputs: limit, maxBytes, selector, textContains, +1 more. Returns: ok, error, result

browser_get_networkGet Recent Network EventsA
Read-onlyIdempotent

Use when recent request and response summaries are needed to explain a click with no request, wrong endpoint, status failure, redirect, or timing issue. Preconditions: a trace session must exist; filter by URL, method, status, or sequence when possible. Next: use monitor_search_events for cross-stream correlation or monitor_search_bodies only when body content is relevant. Sensitivity: network summaries can expose URLs, headers, status details, and references to sensitive bodies.

Inputs: limit, method, status, sinceSeq, +2 more. Returns: ok, error, result

browser_get_stateGet Page StateA
Read-onlyIdempotent

Use when the current URL, title, frames, viewport, or focused element is needed to orient a browser diagnosis. Preconditions: an active page and acknowledgeRawCapture: true are required in an authorized environment. Next: use browser_snapshot for richer page context or choose the next targeted action. Sensitivity: state can expose URLs, frame metadata, and focused values from the live page.

Inputs: acknowledgeRawCapture. Returns: ok, error, result

browser_get_storageRead Web StorageA
Read-onlyIdempotent

Use when a full-profile authentication or application-state diagnosis explicitly requires localStorage or sessionStorage. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required for an authorized origin. Next: inspect only relevant keys and avoid returning raw secrets in summaries. Sensitivity: web storage frequently contains tokens, identifiers, preferences, and personal data.

Inputs: origin, maxBytes, acknowledgeRawCapture, includeSessionStorage, +1 more. Returns: ok, error, result

browser_go_backGo BackA
Destructive

Use when history navigation is specifically needed to reproduce a redirect, back-button state bug, or single-page application history issue. Preconditions: an active page with a previous history entry is required. Next: inspect state and relevant network events after navigation. Sensitivity: history navigation can reissue requests and expose credential-bearing page state.

Inputs: timeoutMs, waitUntil. Returns: ok, error, result

browser_go_forwardGo ForwardA
Destructive

Use when forward history navigation is specifically required to reproduce a cached state, redirect, or single-page application history issue. Preconditions: an active page with a forward history entry is required. Next: inspect state and relevant network events after navigation. Sensitivity: history navigation can reissue requests and expose credential-bearing page state.

Inputs: timeoutMs, waitUntil. Returns: ok, error, result

browser_grant_permissionsGrant Browser PermissionsA
Destructive

Use when a full-profile authorized test explicitly requires browser permissions such as geolocation, notifications, camera, or microphone. Preconditions: acknowledgePermissionChange: true and the minimal intended permission list are required. Next: run the permission-dependent flow and avoid granting unrelated capabilities. Sensitivity: permissions expose device-like capabilities and can change what the target page may access.

Inputs: permissions (required), origin, acknowledgePermissionChange. Returns: ok, error, result

browser_handle_dialogHandle JavaScript DialogA
Destructive

Use when an alert, confirm, prompt, or beforeunload dialog blocks or changes the browser reproduction. Preconditions: configure the intended accept or dismiss behavior before the dialog appears. Next: trigger the dialog and inspect the resulting action, navigation, or state. Sensitivity: accepting prompts or confirmations can submit text, authorize actions, or mutate application state.

Inputs: action (required), once, promptText. Returns: ok, error, result

browser_hoverHover ElementA

Use when hover-driven menus, tooltips, lazy content, or transient UI state must be reproduced. Preconditions: an active page and precise selector are required. Next: inspect the transient DOM promptly or continue the monitored sequence. Sensitivity: hover handlers can trigger network requests, analytics, or application state changes.

Inputs: selector (required), timeoutMs. Returns: ok, error, result

browser_import_storage_stateImport Storage StateA
Destructive

Use when a full-profile authorized reproduction explicitly needs to replace active browser credential and origin state from a Playwright storageState file. Preconditions: raw-capture and credential acknowledgements are required; CDP or userDataDir contexts also require acknowledgeStorageStateOverwrite: true. Next: navigate or reload to verify the intended authenticated state. Sensitivity: import clears and replaces cookies, localStorage, and IndexedDB and can overwrite a real logged-in profile.

Inputs: path (required), acknowledgeRawCapture, acknowledgeCredentialAccess, acknowledgeStorageStateOverwrite. Returns: ok, error, result

browser_launchLaunch BrowserA

Use when a RawTrace-controlled Chromium session is not running yet, or a known CDP endpoint or storage state must be opened before reproducing a browser issue. Preconditions: provide only profiles and systems you are authorized to inspect; storageState use also requires the raw-capture and credential acknowledgements. Next: navigate or inspect the selected page, then use browser_observe_action_result for one action or monitor_start for a multi-step reproduction. Sensitivity: launch options can expose an existing browser profile, CDP session, or credential-bearing storage state.

Inputs: cdpUrl, headless, userDataDir, storageStatePath, +3 more. Returns: ok, error, result

browser_list_tabsList Browser TabsA
Read-onlyIdempotent

Use when a full-profile workflow must discover the open pages before switching, closing, or selecting a CDP target. Preconditions: an active browser context is required. Next: use browser_switch_tab with the chosen page ID. Sensitivity: tab URLs and titles may reveal private application or account information.

Inputs: no named parameters. Returns: ok, error, result

browser_navigateNavigate PageA
Destructive

Use when the active page must open an exact URL as part of a reproduction, redirect investigation, authentication flow, or network-timing diagnosis. Preconditions: a browser must be active and the destination must be within the authorized development or test scope. Next: inspect state or begin the action sequence; use monitor_get_summary after stopping any active trace. Sensitivity: navigation contacts an external origin and may send cookies or other browser credentials.

Inputs: url (required), waitUntil. Returns: ok, error, result

browser_new_tabOpen New TabA

Use when a full-profile reproduction genuinely requires a separate page rather than the existing active tab. Preconditions: an active browser context is required and any supplied URL must be authorized. Next: inspect or trace the new active tab, then close it when finished. Sensitivity: opening a URL contacts an external origin and may send context credentials.

Inputs: url, waitUntil. Returns: ok, error, result

browser_observe_action_resultObserve Action ResultA
Destructive

Use when one click, type, press, check, select, hover, scroll, reload, navigate, or authorized eval has an unclear outcome and a compact before/after diff is needed. Preconditions: an active page and acknowledgeRawCapture: true are required; eval actions also require acknowledgeDangerousEval: true. Next: use the returned DOM, state, network, and optional screenshot diff to decide whether a longer monitor_start reproduction is necessary. Sensitivity: before/after snapshots, values, screenshots, URLs, and network changes can contain sensitive raw page data.

Inputs: action (required), waitAfterMs, afterSnapshot, beforeSnapshot, +3 more. Returns: ok, error, result

browser_optimize_selectorOptimize SelectorA
Read-onlyIdempotent

Use when a full-profile workflow needs a shorter unique selector for a target that is already known. Preconditions: an active page, acknowledgeRawCapture: true, and a selector matching the intended element are required. Next: verify the returned selector with browser_get_elements before relying on it in automation. Sensitivity: candidate analysis reads DOM attributes and text that may be sensitive.

Inputs: selector (required), name, role, targetIndex, +4 more. Returns: ok, error, result

browser_poll_untilPoll Until Page Conditions MatchA
Read-onlyIdempotent

Use when asynchronous DOM, URL, element value, or authentication signals must be sampled until one or all conditions match. Preconditions: an active page and acknowledgeRawCapture: true are required; use bounded timeout and interval values. Next: use the matched snapshot to continue the flow or explain the timing boundary. Sensitivity: poll snapshots can repeatedly capture raw text, values, URLs, authentication signals, and element metadata.

Inputs: conditions (required), match, snapshot, timeoutMs, +2 more. Returns: ok, error, result

browser_pressPress Keyboard KeyA
Destructive

Use when a keyboard action such as Enter, Escape, Tab, or a shortcut is part of the browser reproduction. Preconditions: an active page is required and the optional selector must identify the intended focus target. Next: continue the sequence or inspect any resulting navigation, dialog, DOM, or network activity. Sensitivity: key presses can submit data, trigger shortcuts, navigate, or mutate remote state.

Inputs: key (required), delayMs, selector, timeoutMs. Returns: ok, error, result

browser_reloadReload PageA
Destructive

Use when a reload is necessary to reproduce initialization races, cached-versus-fresh behavior, redirects, or intermittent requests. Preconditions: an active page is required; start monitor_start first when the whole reload sequence matters. Next: inspect the resulting state or stop the trace and read its summary. Sensitivity: reload can repeat writes or requests performed by the page and may transmit active credentials.

Inputs: timeoutMs, waitUntil. Returns: ok, error, result

browser_screenshotCapture ScreenshotA

Use when visual evidence is necessary to understand layout, overlays, rendering, or the result of a browser interaction. Preconditions: an active page and acknowledgeRawCapture: true are required; select a region when the full page is unnecessary. Next: use the saved PNG as supporting evidence and continue with targeted DOM or trace inspection. Sensitivity: screenshots may capture personal data, secrets, account state, or other sensitive pixels and are written locally.

Inputs: fullPage, selector, outputPath, acknowledgeRawCapture. Returns: ok, error, result

browser_screenshot_annotatedCapture Annotated ScreenshotA

Use when a full-profile visual diagnosis needs temporary selector or coordinate annotations over the page. Preconditions: an active page and acknowledgeRawCapture: true are required; annotations must identify authorized content. Next: inspect the saved PNG and use normal DOM tools for machine-readable details. Sensitivity: the image and labels may expose sensitive page content and are written locally.

Inputs: boxes, fullPage, selector, selectors, +2 more. Returns: ok, error, result

browser_scrollScroll Page or ElementA

Use when lazy loading, infinite scroll, sticky layout, viewport-dependent behavior, or an off-screen target must be reproduced. Preconditions: an active page is required; provide a selector only when a specific scroll region matters. Next: wait for resulting activity or inspect DOM and network changes. Sensitivity: scroll listeners can trigger external requests, analytics, and dynamic content loading.

Inputs: deltaX, deltaY, selector, timeoutMs. Returns: ok, error, result

browser_select_optionSelect OptionA
Destructive

Use when one or more values must be selected in a native select control during a reproduction. Preconditions: an active page, precise selector, and intended value, label, or index are required. Next: continue the flow or inspect dependent DOM and network activity. Sensitivity: selection can submit forms, alter application state, or expose chosen values in traces.

Inputs: values (required), selector (required), timeoutMs. Returns: ok, error, result

browser_set_cookiesSet Browser CookiesA
Destructive

Use when a full-profile authorized test explicitly requires establishing or changing cookie state. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required; use only intended test credentials. Next: verify the resulting flow without exposing cookie values and clear temporary state when appropriate. Sensitivity: this modifies credential state and raw cookie values are secrets.

Inputs: cookies (required), acknowledgeRawCapture, acknowledgeCredentialAccess. Returns: ok, error, result

browser_set_geolocationSet Browser GeolocationA
Destructive

Use when a full-profile authorized test explicitly depends on a controlled latitude, longitude, and accuracy. Preconditions: acknowledgeLocationAccess: true is required and only intended coordinates may be supplied. Next: reload or exercise the location-dependent behavior. Sensitivity: the coordinates are exposed to authorized pages that have geolocation permission.

Inputs: latitude (required), longitude (required), accuracy, acknowledgeLocationAccess. Returns: ok, error, result

browser_set_storageSet Web StorageA
Destructive

Use when a full-profile authorized test explicitly needs controlled localStorage or sessionStorage values. Preconditions: acknowledgeRawCapture: true and acknowledgeCredentialAccess: true are required; target the intended origin and keys. Next: reload or navigate as needed to observe the application's reaction. Sensitivity: this changes potentially credential-bearing application state.

Inputs: origin, localStorage, sessionStorage, acknowledgeRawCapture, +1 more. Returns: ok, error, result

browser_set_viewportSet Browser ViewportA

Use when a full-profile reproduction explicitly depends on responsive breakpoints or viewport dimensions. Preconditions: an active page and intended positive width and height are required. Next: reload or inspect the affected layout and events. Sensitivity: viewport changes can trigger application reflow, lazy loading, analytics, and network requests.

Inputs: width (required), height (required). Returns: ok, error, result

browser_snapshotSnapshot PageA
Read-onlyIdempotent

Use when a compact combined view of page state, text, inputs, links, and interactive elements is more useful than separate inspection calls. Preconditions: an active page and acknowledgeRawCapture: true are required. Next: select a target for browser_observe_action_result or compare with a later snapshot. Sensitivity: snapshots may include DOM text, visible input values, links, and externalized raw artifacts.

Inputs: selector, includeLinks, maxTextBytes, elementsLimit, +2 more. Returns: ok, error, result

browser_switch_tabSwitch Browser TabA

Use when a full-profile workflow must make a previously discovered page the active target. Preconditions: obtain a valid page ID from browser_list_tabs or browser_attach_cdp. Next: confirm selection with browser_get_state before acting. Sensitivity: the selected tab may contain private content or an authenticated session.

Inputs: pageId (required). Returns: ok, error, result

browser_typeType Into ElementB
Destructive

Use when text must be entered into a known input during a reproduction. Preconditions: an active page and precise selector are required; use only data intended for the authorized target. Next: continue with the next action or observe the resulting request and DOM changes. Sensitivity: typed values may be captured in DOM, console, network, screenshots, or trace artifacts.

Inputs: text (required), selector (required), delayMs, timeoutMs. Returns: ok, error, result

browser_upload_fileUpload Local FileA
Destructive

Use when a full-profile authorized test explicitly requires providing local files to a page file input. Preconditions: acknowledgeFileAccess: true, an exact selector, and intended local paths are required. Next: continue the upload flow and verify the resulting request or UI state. Sensitivity: this sends local file contents to the target site and can expose private data.

Inputs: paths (required), selector (required), timeoutMs, acknowledgeFileAccess. Returns: ok, error, result

browser_waitWait for Browser ConditionA
Read-onlyIdempotent

Use when the reproduction needs an explicit selector, URL, quiet-period, or bounded timeout wait instead of an arbitrary sleep. Preconditions: an active page is required and mode-specific selector or pattern inputs should be narrow. Next: perform the next action immediately after the expected condition is reached. Sensitivity: waiting observes live page and network state but does not itself redact any subsequently captured data.

Inputs: mode (required), delayMs, pattern, quietMs, +2 more. Returns: ok, error, result

browser_wait_for_downloadWait for DownloadA
Destructive

Use when a browser action should create a download and the saved file, filename, or timing must be verified. Preconditions: an active page is required; when triggerSelector is used it must identify the authorized download action, and raw capture requires acknowledgement. Next: inspect browser_get_downloads or the saved file through an appropriate local-file workflow. Sensitivity: downloaded files may contain sensitive application data and the optional trigger can cause external effects.

Inputs: outputDir, timeoutMs, triggerSelector, suggestedFilename, +1 more. Returns: ok, error, result

browser_wait_for_responseWait for Network ResponseA
Read-onlyIdempotent

Use when an action is expected to produce a response and timing or endpoint matching is the central question. Preconditions: start this wait before triggering the relevant action and provide narrow URL, method, or status filters. Next: correlate the matched response with the action or use the body variant only when content matters. Sensitivity: response metadata can expose private URLs, headers, status details, and timing information.

Inputs: method, status, urlRegex, timeoutMs, +1 more. Returns: ok, error, result

browser_wait_for_response_bodyWait for Response BodyA
Read-onlyIdempotent

Use when an action is expected to produce one response whose raw or parsed body is directly required for an API, authentication, redirect, or payload diagnosis. Preconditions: start the wait before the action, use narrow filters, and pass acknowledgeRawCapture: true on an authorized system. Next: extract only the needed fields and prefer trace search for multi-request investigations. Sensitivity: response bodies may contain credentials, personal data, application secrets, or large binary content.

Inputs: method, status, maxBytes, urlRegex, +4 more. Returns: ok, error, result

monitor_exportExport Trace BundleA

Use when an authorized handoff or offline analysis explicitly requires a portable ZIP of a completed trace. Preconditions: a trace session must exist and the destination must be a protected local path. Next: share the bundle only through an approved sensitive-data channel and remove it when no longer needed. Sensitivity: the ZIP can contain every captured secret, body, cookie, DOM value, screenshot, and WebSocket frame.

Inputs: format, sessionId, outputPath. Returns: ok, error, result

monitor_get_manifestGet Trace ManifestA
Read-onlyIdempotent

Use when a full-profile workflow needs exact capture configuration, file inventory, schema, timing, or session metadata. Preconditions: a completed or active trace session must exist. Next: prefer monitor_get_summary for diagnosis and use manifest paths only to target later reads. Sensitivity: the manifest can expose local paths, target URLs, capture options, and trace metadata.

Inputs: sessionId. Returns: ok, error, result

monitor_get_summarySummarize TraceA
Read-onlyIdempotent

Use when a stopped multi-step trace needs the first compact AI-readable explanation of actions, DOM changes, requests, responses, WebSockets, console, and frames. Preconditions: complete the reproduction and call monitor_stop first whenever possible. Next: use monitor_search_events or monitor_search_bodies only for questions the summary does not answer. Sensitivity: summaries minimize volume but may still include sensitive URLs, text, values, and event details.

Inputs: sessionId. Returns: ok, error, result

monitor_list_sessionsList Trace SessionsA
Read-onlyIdempotent

Use when a full-profile workflow must enumerate trace sessions created by the current MCP process. Preconditions: at least one trace session should exist. Next: select a session ID for manifest, summary, search, read, or export operations. Sensitivity: session paths and metadata may reveal local directories and sensitive investigation context.

Inputs: no named parameters. Returns: ok, error, result

monitor_read_artifactRead Trace ArtifactA
Read-onlyIdempotent

Use when summary and targeted search have identified one exact body, DOM, screenshot, eval, storage-state, or snapshot artifact needed to finish the diagnosis. Preconditions: acknowledgeRawCapture: true and a trace-contained path or reference are required; keep maxBytes bounded. Next: extract only the necessary finding and do not dump the artifact into source control or broad logs. Sensitivity: artifacts are raw and can contain reusable credentials, personal data, secrets, screenshots, or full application content.

Inputs: ref, path, asText, maxBytes, +3 more. Returns: ok, error, result

monitor_read_eventsRead Raw Trace EventsA
Read-onlyIdempotent

Use when a full-profile investigation needs paginated raw events after summary and search have identified the exact stream and range. Preconditions: a trace session and explicit stream are required; keep offset and limit narrow. Next: correlate the returned sequence with a targeted artifact only if necessary. Sensitivity: raw events may contain DOM text, headers, form values, cookie metadata, console output, and WebSocket payloads.

Inputs: stream (required), limit, offset, sessionId. Returns: ok, error, result

monitor_search_bodiesSearch Request and Response BodiesA
Read-onlyIdempotent

Use when authentication, API, GraphQL, request, or response content is directly relevant and body capture was enabled for the trace. Preconditions: acknowledgeRawCapture: true and a precise text query are required on an authorized session. Next: use monitor_read_artifact only for the specific matching body reference that answers the question. Sensitivity: request and response bodies can contain credentials, personal data, application secrets, and large raw payloads.

Inputs: text (required), limit, method, status, +4 more. Returns: ok, error, result

monitor_search_eventsSearch Trace EventsA
Read-onlyIdempotent

Use when a trace summary leaves a targeted question about an endpoint, DOM text, event type, sequence boundary, redirect, or WebSocket message. Preconditions: a trace session must exist; provide the narrowest useful stream and filters. Next: read only the matching artifact or small event range if more detail is needed. Sensitivity: matches may expose raw event fields, inline DOM content, URLs, headers, values, or payloads.

Inputs: text, type, limit, stream, +3 more. Returns: ok, error, result

monitor_startStart Raw TraceA

Use when a multi-step browser failure, transient DOM change, network race, WebSocket sequence, redirect, download, or authentication flow must be reproduced end to end. Preconditions: an authorized browser must be active and acknowledgeRawCapture: true is required; normally set captureCookies: false and captureBodies: false unless directly relevant. Next: perform the complete reproduction with RawTrace browser actions, then call monitor_stop before reading monitor_get_summary. Sensitivity: trace streams can capture raw DOM, headers, values, frames, console data, cookies, bodies, and WebSocket messages depending on options.

Inputs: outputDir, captureDom, maxBodyBytes, captureBodies, +6 more. Returns: ok, error, result

monitor_stopStop Raw TraceA

Use when the complete reproduction has finished and buffered trace events must be flushed before analysis. Preconditions: a monitor should be active; avoid extra unrelated browser actions before stopping. Next: call monitor_get_summary first, then targeted search tools, and read a raw artifact only when necessary. Sensitivity: the resulting trace directory is sensitive and must not be committed or broadly shared.

Inputs: no named parameters. Returns: ok, error, result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 59 tools

    Disambiguation5/5

    Each of the 59 tools has a distinct, well-defined purpose with clear descriptions that prevent overlap. For example, browser_get_state, browser_snapshot, browser_get_dom, and browser_get_elements each target different aspects of page information, and actions like browser_observe_action_result serve a unique before/after diff role.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with underscores, using logical prefixes ('browser_' for browser actions, 'monitor_' for trace management). This predictability makes it easy for an agent to infer tool purpose from the name.

    Tool Count4/5

    At 59 tools, the count is high but appropriate for the comprehensive browser automation and tracing coverage. Each tool addresses a specific need, and the complexity of the domain justifies the number, though it exceeds the typical 3-15 range.

    Completeness5/5

    The tool set covers the full lifecycle of browser interactions: launching, navigating, inspecting, acting, waiting, and tracing. It includes advanced features like storage state management, permissions, geolocation, and detailed trace analysis, leaving no obvious gaps for its stated purpose.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers