web-bridge-mcp is a relay MCP server that lets an AI editor browse, inspect, script, and interact with any static web page that embeds client.js, using either HTTP or stdio transport.
list_pages — List all connected browser pages (pageId, title, URL, connected time).
eval_js — Execute arbitrary JavaScript in a page, with await support and helpers like $/$$, $deep/$$deep, $import, $wait, $frame, $rect, and $css.
get_console — Read recent console logs and uncaught errors, with optional incremental fetching via since.
click / type / hover / focus / scroll_to — Interact with page elements using deep CSS selectors (piercing shadow DOM).
wait_for — Poll until a selector appears/disappears or a JS predicate holds, essential for SPAs.
get_text — Read innerText from the page or a specific element.
get_dom_snapshot — Get a text-based “virtual screenshot” of an element subtree, including geometry and computed styles, without needing permissions.
get_screenshot — Capture a real rendered JPEG screenshot (requires one-time browser display-capture authorization).
Supports local stdio mode and remote HTTP mode, plus optional admin console/group isolation for multi-project or shared deployments.
Pages auto-reconnect and show a status bubble with an operation log, so humans can see what the AI did.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@web-bridge List the connected pages, then click the #btn button and read the console output."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
web-bridge is an MCP Server (a single Node process with dual interfaces) that lets AI editors execute JavaScript, read the console, and simulate clicks / input on static web pages that include client.js. It is suitable for local cross-browser, multi-tab debugging, and can also be deployed to a public server (--transport http, see “Remote Deployment” below).
AI 编辑器 ┌───────────────────┐ 浏览器页面
┌──────────────┐ │ MCP Server │ ┌──────────────────┐
│ MCP Client │ │ （Node 单进程） │ │ <script src= │
│ │ stdio 或 │ · 接口B: MCP │ WebSocket │ :3210/client.js">│
│ AI 只到这里 │◄─────────►│ (stdio / http) │◄──────────►│ client.js │
└──────────────┘ Streamable│ · 接口A: WebSocket │ 接口A │ （eval 执行/ │
HTTP(远程) │ · HTTP /client.js │ │ console 捕获） │
└───────────────────┘ └──────────────────┘The AI editor and the browser are not directly connected: both connections terminate at the MCP Server (server.js), and the AI indirectly controls the page through tool calls.
cd web-bridge
npm install # 首次Include the script in a static web page (any page, any port, cross-origin allowed):
<script src="http://127.0.0.1:3210/client.js"></script>Configure the MCP service in your AI editor: replace <REPO>/server.js in mcp.json with the absolute path to this repository, and paste it as described for your editor below. As soon as the editor starts server.js, the WebSocket service (default 127.0.0.1:3210) is ready.
Tell the AI: “Use web-bridge's list_pages to see which pages are connected, then use eval_js to click #btn and read the console.”
Load order note: it doesn't matter if the page loads it first; client.js will automatically reconnect (1s→2s→5s→10s backoff), and the page will reattach automatically after the editor starts. Hub status page: http://127.0.0.1:3210/
Related MCP server: browser-mcp
Tool | Parameters | Description |
| — | List connected pages (pageId, title, URL, connection time) |
|
| Execute arbitrary JS on the page and return a serialized result; supports |
| optional | Read the page's recent console output and uncaught exceptions |
|
| Find the element and trigger click() (scrollIntoView first) |
|
| Focus, write text, dispatch input / change events (compatible with contenteditable) |
| optional | Read the element's innerText |
pageId rule: can be omitted when only one page is connected; when multiple pages are connected and none is specified, the tool returns an error and a list of pages, and the AI will retry with pageId added.
The examples below assume the repository's absolute path is /path/to/web-bridge; replace it as needed.
ZCode / Claude Code (project root .mcp.json, or claude mcp add):
{
"mcpServers": {
"web-bridge": {
"command": "node",
"args": ["/path/to/web-bridge/server.js"],
"env": { "PORT": "3210" }
}
}
}Cursor (.cursor/mcp.json): same format as above.
Claude Desktop (claude_desktop_config.json): same format as above.
Command-line arguments: node server.js --port 3210 --host 127.0.0.1 --token <secret> (environment variables PORT / HOST / TOKEN can also be used).
The default stdio mode requires the editor to start the process locally; to deploy web-bridge to a public server, switch to HTTP transport mode, and the editor only needs to fill in a url in the MCP configuration:
1. Start it on the server (systemd / pm2 recommended; a token is required on the public internet):
node server.js --transport http --host 0.0.0.0 --port 3210 --token <secret>2. Editor configuration (Claude Code / Cursor / ZCode, etc., paste it in the original config location):
{
"mcpServers": {
"web-bridge": {
"type": "http",
"url": "https://your-domain.com/mcp",
"headers": { "Authorization": "Bearer <secret>" }
}
}
}For a direct connection (no reverse proxy / TLS), set url to http://<服务器IP>:3210/mcp. Note: Claude Desktop only supports local stdio mode, not a remote url.
3. Change the page-side script to point to the server:
<script src="https://your-domain.com/client.js?token=<secret>"></script>Notes:
HTTPS pages can only connect to https/wss (mixed content restriction). It is recommended to use a reverse proxy such as nginx / caddy to terminate TLS and forward to this service; when client.js is served, it automatically detects X-Forwarded-Proto / X-Forwarded-Host and generates the correct wss:// connection address, no extra configuration needed. caddy example (automatic certificate signing):
your-domain.com {
reverse_proxy 127.0.0.1:3210
}After a token is enabled, the /mcp endpoint supports three authentication formats: Authorization: Bearer <secret> (recommended; set headers in the editor configuration), X-Web-Bridge-Token: <secret>, and the url parameter ?token=.
The HTTP transport uses the official Streamable HTTP protocol (stateless mode); each request is handled independently and shares the same hub, so multiple editors can connect simultaneously.
For public deployment, be sure to: set --token, use TLS, and allow only the needed ports in the firewall.
By default it listens only on 127.0.0.1. Any web page open on this machine (including third-party sites you browse) can try to connect to the local port — in the default no-token mode, they can receive code sent by the AI and also forge results.
In untrusted network environments, or when you want devices on the LAN such as phones to connect (--host 0.0.0.0), be sure to enable --token: in this case, fetching client.js requires ?token=<secret>, and the first WebSocket packet also validates the token.
The WS messages between the browser and the MCP Server are all JSON text frames; refer to this when maintaining lib/hub.mjs / client.js:
Direction | Message | Fields | Description |
Page→Server |
|
| First packet after connecting; disconnected if not received within 5 seconds; when pageId is duplicated (duplicate tab), the new connection replaces the old one |
Page→Server |
|
| Reported after connection, on DOMContentLoaded/load/popstate/hashchange, and via a 5s polling fallback (for SPAs) |
Page→Server |
|
| Console wrapper and uncaught exception capture, batched with 500ms throttling; hub keeps a ring buffer of 500 messages per page (retained after disconnection) |
Page→Server |
|
| Late responses (already timed out) are ignored |
Server→Page |
|
| hello validation passed |
Server→Page |
|
| Code to be executed |
Server→Page |
|
| e.g. token error |
eval execution conventions (client.js): first wrap as an expression async () => ( code ); on SyntaxError, fall back to a statement block (return allowed); $ / $$ are predefined; timeout is tracked on the hub side (default 30s, max 120s); results are safely serialized as a string preview (Error→stack, DOM→outerHTML summary, circular reference markers, depth ≤ 6, ≤ 50k characters).
Testing: npm test (Node e2e: start process + simulated page + call tools over both stdio/HTTP transports); npm run test:browser (Playwright real-browser flow: Chromium loads test/test-page.html, verifies the 6 tools over a real WebSocket; run npx playwright install chromium before the first time). The real-browser flow can also be verified manually by opening the test page.
Dependencies: ws (WebSocket), @modelcontextprotocol/sdk (MCP), zod (parameter validation); dev dependency @playwright/test. Node ≥ 18.
通过 CSS 选择器找到元素并触发 click()（会先 scrollIntoView）。找不到元素时返回错误。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | Yes | CSS 选择器 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and adds useful details: it calls scrollIntoView first and returns an error if the element is not found. It does not mention success return values or multiple-match behavior, but the disclosed behaviors add real value beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence that conveys the core action, key pre-behavior, and failure mode with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple click tool, the description covers the essential behavior, preprocessing, and error case. It could be more complete by noting what happens with multiple matching elements or what a successful call returns, but it is sufficiently clear for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description only restates the selector concept and adds no parameter-specific guidance beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: find an element via CSS selector and trigger click(). It also distinguishes itself from sibling tools like hover, focus, and type by describing the click action explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not state when to use this tool versus alternatives like eval_js, hover, or type. It only implies usage through the word 'click', but provides no explicit context, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在指定页面（pageId 省略且只连了一页时自动选中）执行任意 JavaScript 并返回序列化结果。支持 await 与多语句；最后一句表达式会被自动 return，也可显式 return。预置 $ / $$（普通查询）、$deep / $$deep（穿 shadow DOM 深度查询）、$import（页面路径动态 import）、$wait（轮询等条件，函数或选择器字符串，第二参为超时 ms）、$frame（同源 iframe 查询辅助，返回 {$,$$,$deep,$$deep,document,window}）、$rect（元素几何+可见性）、$css（批量写样式）。
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | 要执行的 JS 代码 | |
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（可从 list_pages 获取；单页时可省略） | |
| timeoutMs | No | 超时毫秒数，默认 30000，上限 120000 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
无 annotations，描述承担全部行为披露责任。它详细说明了自动选中页面、返回序列化结果、支持 await 与多语句、末句自动 return 或显式 return 等执行语义，并逐个定义了 9 个辅助函数的行为。但未说明 JS 抛错时的处理、超时后的表现，也未提示执行任意 JS 可能带来的页面副作用。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
长句但信息密度极高，从目的说明、执行语义到辅助函数清单，几乎无冗余，且核心目的前置。不过辅助函数以逗号连排成长句，缺少分项层级，可读性略受影响；在如此高复杂度的工具下篇幅总体合理。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
工具复杂度高（任意 JS 执行、9 个辅助函数、4 个参数），且无 annotations 也无 output schema。描述覆盖了执行语义和辅助函数 API，但未说明返回值封装结构（仅提"序列化结果"）、JS 异常与超时行为，也没有副作用警告——对高风险 eval 工具而言这些都是明显缺口。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
schema 覆盖率为 100%，基线为 3；但描述为 code 参数补充了大量超出 schema（仅"要执行的 JS 代码"）的语义：await/多语句规则、自动 return 行为、全部辅助函数的签名与返回值（如 $frame 返回 {$,$$,$deep,$$deep,document,window}），并对 pageId 省略时的自动选中行为做了补充，明显高于基线。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
描述以明确的动词+资源开篇："在指定页面执行任意 JavaScript 并返回序列化结果"，准确说明工具做什么。与兄弟工具（click、type、get_text 等）形成清晰区分——这是唯一执行任意脚本的工具，并补充了页面自动选中规则，无歧义、非同义反复。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
通过预置辅助函数（$wait、$deep、$frame 等）隐含了典型使用场景，schema 中 pageId 也说明可从 list_pages 获取。但描述没有明确说明何时应使用 eval_js 而非 click/get_text 等替代工具，也没有排除条件（如简单交互优先用专用工具），依赖智能体自行推断。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过 CSS 选择器找到元素并聚焦（focus + focusin），适合输入前把焦点放到指定输入框。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | Yes | CSS 选择器 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral information. It discloses the mechanism (CSS selector) and the exact events fired (focus and focusin). It could mention behavior on missing or hidden elements, but for a simple focus operation this is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one efficient sentence that front-loads the action and purpose. Every part earns its place with no repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a low-complexity tool with full schema coverage and no output schema, so the description is largely sufficient. A minor gap is the lack of error behavior or visibility requirements, but these are not critical for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds little beyond confirming the selector is a CSS selector; it does not elaborate on note or pageId semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies a concrete action: finding an element via CSS selector and focusing it, and even names the events triggered (focus + focusin). This clearly distinguishes it from sibling tools like click, type, and hover.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear use context: place focus into an input before typing. It does not explicitly name alternatives or exclusions, but the intended scenario is clear enough for an agent to select this tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取页面最近的 console 输出与未捕获异常（client.js 会自动捕获上报）。limit 为返回条数（默认 50）；传 since（毫秒时间戳）则只返回该时间之后的日志（增量拉取），返回末尾会附上最新一条的 ts，可作为下次调用的 since 继续拉取，用于区分修改代码前后的日志。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | 返回最近多少条，默认 50 | |
| since | No | 只返回该毫秒时间戳之后的日志（增量拉取，配合返回值末尾的 ts 使用） | |
| pageId | No | 目标页面 id（单页时可省略） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that client.js automatically captures and reports console output, that `limit` defaults to 50, and that the response includes a trailing `ts` for incremental polling. It does not explicitly declare the operation as read-only, but the verb '读取' and lack of mutation language make that reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two efficient sentences. The first states the core purpose, and the second packs parameter behavior, the incremental polling mechanism, and the intended use case without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns and how to iterate with the trailing timestamp, which is essential since there is no output schema. It does not explicitly cover multi-page behavior for `pageId` or exact response formatting, but the schema covers `pageId` and the sibling `list_pages` provides context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by explaining the cursor protocol: the returned `ts` can be passed as the next `since`, which is more informative than the schema's terse '配合返回值末尾的 ts 使用'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: read recent console output and uncaught exceptions. This resource is unique among the sibling tools, so there is no ambiguity with DOM, navigation, or interaction tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: incremental log fetching with a `since` timestamp and using the returned `ts` as the next cursor to distinguish logs before and after code changes. It does not explicitly name alternatives or when-not-to-use conditions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
对指定元素的子树生成「虚拟截图」：每个可见节点一行，含几何（rect）、关键 computed style（颜色/背景/字号/边框/圆角/阴影/透明度/z-index/溢出）、文本，穿 shadow DOM。纯文本、无需任何授权，是验证颜色、布局、定位的首选；需要真实渲染像素（canvas 内容、图片、遮挡观感）时再用 get_screenshot。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| depth | No | 最大递归深度，默认 4，上限 8 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| maxNodes | No | 最多输出的节点数，默认 60，上限 300 | |
| selector | Yes | CSS 选择器（深度查询，穿 shadow DOM），对其子树生成快照 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
无注解，描述承担了行为披露责任。说明这是纯文本操作、无需授权，只输出可见节点，且穿 shadow DOM，这补充了安全性和执行行为。虽然未讨论 maxNodes/depth 截断或返回失败情况，但关键行为已明确。
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
两句话紧凑完成功能说明、输出内容说明、适用场景和替代工具路由，信息密度高且无冗余。关键行为前置，替代方案收尾，结构清晰。
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
无输出 schema，描述说明了输出内容（每行几何、样式、文本），无注解时也覆盖了授权和只读性。5 个参数中必需项在 schema 中已有定义，整体对调用该工具所需上下文已足够；仅缺少对截断或 selector 无效时的行为说明。
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema 描述覆盖率为 100%，参数本身在 schema 中已有完整说明。描述没有额外深化参数语义，但也不构成负担，按 baseline 3 评分合理。
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
描述明确说明对指定元素子树生成「虚拟截图」，包含几何、样式、文本和 shadow DOM 穿透，动词和资源具体。与 get_screenshot 的差异通过「需要真实渲染像素时再用 get_screenshot」直接点出，能清晰区别于兄弟工具。
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
描述明确给出使用场景：验证颜色、布局、定位的首选；并明确列出何时应改用 get_screenshot（canvas 内容、图片、遮挡观感）。提供了 when-to-use 和 when-not-to-use 的清晰指引。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
返回 web-bridge-mcp 的完整使用指南（SKILL.md 全文，含标准工作流、eval_js 写法、预置函数、排错表与踩坑经验）。首次使用本 MCP 的工具前建议先调用它；指南文件更新后无需重启，再次调用即读到最新版。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the return value (SKILL.md full text), the lack of a restart requirement, and the dynamic refresh on re-call. It does not explicitly mention side effects or output size, but for a read-only guide fetch these are minor omissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler; the primary purpose is front-loaded and the parenthetical content list tells the agent exactly what the guide covers. The usage advice and refresh behavior are packed efficiently into the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description tells the agent what it returns, what the guide contains, when to call it, and when to re-call it after updates. Nothing required to invoke this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema coverage, so there is nothing for the description to add beyond the schema. The baseline of 4 applies because parameter semantics are fully determined by the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the verb '返回' (returns) and a specific resource: web-bridge-mcp 的完整使用指南 (full SKILL.md). It lists concrete contents such as workflows, eval_js syntax, preset functions, and troubleshooting, which makes it easy to distinguish from the sibling browser-automation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly recommends calling this tool before first use of the MCP's tools, and states that after the guide file is updated, calling again returns the latest version without a restart. This is a clear when-to-use condition, and no sibling tool competes for this purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过浏览器屏幕捕获（getDisplayMedia）截取真实渲染像素并返回图片。首次调用会在用户浏览器弹出原生授权框（预选当前标签页），用户授权一次后本次页面生命周期内免打扰；页面刷新后需重新授权。传 selector 时按该元素矩形裁剪（深度查询，穿 shadow DOM）。验证颜色/布局/定位请优先用 get_dom_snapshot（文本、免授权、精确到值）；本工具用于需要真实像素的场景（canvas、图片、遮挡观感）。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | No | 可选：只截取该元素（深度查询），不传则截整个视口 | |
| timeoutMs | No | 超时毫秒数，默认 60000（首次调用要等用户在浏览器里点授权） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly explains the authorization prompt, one-time approval per page lifecycle, re-authorization after refresh, selector deep-query behavior through shadow DOM, and timeout implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: core function, authorization side-effect, selector behavior, and alternative tool guidance. It is front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a screenshot tool with 4 parameters and no output schema. It covers purpose, side effects, usage conditions, selector semantics, timeout behavior, and alternative tool routing. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds useful context beyond the schema, such as selector cropping behavior and why timeoutMs matters on first call, elevating it slightly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's specific function: capturing real rendered pixels via getDisplayMedia and returning an image. It also distinguishes itself from get_dom_snapshot, making the tool's unique niche immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to prefer get_dom_snapshot (color/layout/position verification via text) and when to use this tool (real pixel needs like canvas, images, occlusion). This provides clear routing guidance relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取匹配 CSS 选择器元素的 innerText；selector 省略时读取整个 body。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | No | CSS 选择器，默认 body |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description itself must disclose behavior. It does state the read action and default selector, but does not mention whether the operation waits for the element, what happens on no match, or what the returned value looks like beyond being the innerText.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence captures the core behavior and the default case with zero redundancy. It is appropriately compact for such a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple optional-parameter read tool, the description covers the essential behavior and default. It relies on the schema for note/pageId semantics, which is acceptable given 100% schema coverage, though return-value details are not explicitly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds only the default-body behavior for selector, which the schema also already states, providing no meaningful extra semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool reads innerText of the element matching a CSS selector, defaulting to the whole body. This precisely distinguishes it from siblings like get_screenshot, get_dom_snapshot, and get_console.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives such as get_dom_snapshot or get_console. The description only explains mechanics, not selection criteria or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过 CSS 选择器找到元素并派发 mouseover / mouseenter（可触发菜单、tooltip 等悬停行为），会先 scrollIntoView。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | Yes | CSS 选择器 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that events are synthetic (派发 mouseover/mouseenter) and that scrollIntoView happens first, both non-obvious behaviors an agent needs. It does not mention failure/timeout behavior, so it is not perfect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the action, event behavior, use case, and side effect. Every phrase contributes meaning and there is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action tool with one required parameter, no annotations, and no output schema, the description gives purpose, mechanism, and the critical scrollIntoView side effect. It omits return-value or post-hover waiting details, but those are not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents selector, pageId, and note. The description adds little beyond framing selector as the lookup mechanism, which is below the threshold for extra credit but still consistent with schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: find an element via CSS selector and dispatch mouseover/mouseenter events. It also names the intended effect (triggering menus/tooltips), which clearly distinguishes it from sibling tools like click, focus, and scroll_to.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete use cases—'可触发菜单、tooltip 等悬停行为'—so an agent can infer when hover is the right tool. It does not explicitly contrast with click or state when not to use it, but the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出当前通过 client.js 连接到 web-bridge-mcp 的所有浏览器页面（pageId、标题、URL、连接时间）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It clarifies the read-only nature of the operation, the scope of 'currently connected' pages, and the exact data returned. For a simple listing tool, this is sufficient transparency, though it does not explicitly state that no side effects occur.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action, scope, and returned fields without any fluff. Every part of the sentence carries meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with no output schema, the description is complete: it identifies what will be listed, the scope of the listing, and the exact fields included. An agent has enough information to invoke the tool correctly and interpret its result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema confirms this with an empty properties object. With no parameters to document, the description does not need to add parameter-level detail, satisfying the baseline for parameterless tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '列出' (list), the resource (all browser pages currently connected to web-bridge-mcp via client.js), and the exact output fields (pageId, title, URL, connection time). This makes it easy for an agent to distinguish from the sibling interaction tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case: obtaining pageId and connection status before interacting with browser pages through sibling tools. However, it does not explicitly state when to use this tool versus alternatives or mention any prerequisites or exclusions, so usage guidance remains implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过 CSS 选择器找到元素并滚动到可视区域中央（scrollIntoView），返回滚动后的位置信息。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | Yes | CSS 选择器 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of behavioral disclosure. It does disclose the key behaviors: finding by CSS selector, using scrollIntoView, centering in the visible area, and returning position info. It omits potential side effects or return structure details, but for a scroll tool the disclosed behavior is reasonably transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense, front-loaded sentence conveys the action method, targeting mechanism, and return value without any wasted words. Every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, has one required parameter, and a fully documented schema. The description covers the core operation and return value, but since there is no output schema, the vague 'position info' could be more precise about what the returned data actually contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the description need not repeat parameter details. The description adds no real parameter-level meaning beyond the schema; mentioning the CSS selector simply restates what the schema already says.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (scroll to center via scrollIntoView), a specific resource (element found by CSS selector), and a concrete output (post-scroll position info). This clearly distinguishes it from sibling tools like click, hover, or get_screenshot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how the tool operates but gives no guidance on when to use it versus alternatives or when not to use it. An agent gets no explicit context about conditions that should trigger scroll_to instead of eval_js or other navigation-related approaches.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过 CSS 选择器找到输入元素，聚焦并写入文本，随后派发 input / change 事件（兼容 contenteditable）。
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| text | Yes | 要输入的文本 | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | Yes | CSS 选择器 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does disclose meaningful behavior: finds by CSS selector, focuses, writes text, dispatches input/change events, and supports contenteditable. It could add error-handling or waiting behavior, but the core side effects are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with no filler. Every clause adds useful information: selector targeting, focusing, text writing, event dispatch, and contenteditable compatibility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a focused typing tool, the description is largely complete: the targeting mechanism, action, and event behavior are all disclosed, and the schema covers parameters. It omits explicit when-to-use guidance and return/error details, but these are not critical for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with 100% coverage. The description restates the CSS selector and text concepts but does not add new parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the action (write text), the target (input element or contenteditable), and the mechanism (CSS selector, focus, then dispatch events). It is clear about what the tool does, though it does not explicitly differentiate it from sibling tools like focus or click.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this is for editable elements and contenteditable targets, but it does not explicitly state when to use type instead of focus, click, or hover. Usage context is inferable rather than directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在页面上轮询等待条件成立后再返回，避免 SPA 异步渲染导致「元素还没出来就操作」。两种条件二选一：selector（元素出现；absent=true 时改为等待其消失）或 code（返回真值的 JS 表达式，支持 await）。超时仍未满足则报错。轮询间隔 200ms。
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | 与 selector 二选一：返回真值即认为条件成立的 JS 表达式（如 `fetch('/api').then(r=>r.data)`），支持 await | |
| note | No | 操作说明：展示给页面用户的自然语言描述（用户会在页面气泡的操作记录里看到），用用户的语言填写，建议始终提供 | |
| absent | No | 配合 selector：true 表示等待元素消失（默认 false 等待出现） | |
| pageId | No | 目标页面 id（单页时可省略） | |
| selector | No | 要等待的 CSS 选择器（深度查询，穿 shadow DOM）；absent=true 时等待其消失 | |
| timeoutMs | No | 超时毫秒数，默认 10000，上限 120000 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden and does it well: it discloses polling interval (200ms), timeout error behavior, the mutual exclusivity of selector/code, and how absent=true changes the condition. This is substantial operational context for a waiting primitive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: the purpose and use case, the two condition modes, then timeout and polling details. Information is front-loaded and there is zero filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is nearly complete for a wait tool: it explains what, when, how, and failure behavior. Minor gaps are the undefined return value and unspecified behavior if both selector and code are supplied, but these are low-stakes for a synchronization tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already clearly documented. The description adds value by explaining the mutual-exclusion rule and the polling cadence, but it does not add per-parameter meaning beyond the schema—hence the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: polling/waiting on the page until a condition holds before returning. It clearly distinguishes itself from imperative siblings like click, type, or eval_js by framing the tool as a synchronization/readiness check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The opening sentence gives a concrete use case—avoiding operations before SPA async rendering finishes—which tells an agent when to reach for this tool. It does not explicitly name alternatives or exclusion cases, but the context is specific enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.1.2clickeval_jsfocusget_consoleget_dom_snapshotget_guideget_screenshotget_texthoverlist_pagesscroll_totypewait_forEach tool targets a distinct action or read: list_pages enumerates contexts, get_guide is meta-documentation, eval_js is the generic execution escape hatch, and click/type/hover/focus/scroll_to cover specific interactions. Although eval_js could technically perform many of the specialized operations, the specialized tools have clearly separated purposes and the descriptions reinforce the boundaries.
Names are uniformly lowercase and follow a readable functional pattern: get_* for state/read operations, bare verbs for direct actions, and wait_for/scroll_to for prepositional actions. Minor deviations from a strict verb_noun convention (click, type, wait_for) are not confusing but prevent a perfect score.
Thirteen tools is well-scoped for a browser-automation bridge: discovery, execution, console access, DOM reading, waiting, interaction, and two complementary visual verification tools. Each tool has a distinct role and none feels redundant or missing in the immediate set.
The surface covers the core browser workflow well: list pages, execute JS, read logs/text, wait for conditions, interact, focus, scroll, and verify via DOM or screenshot. There is no dedicated navigation, keyboard, or page-lifecycle tool, but eval_js and the existing interaction tools provide reasonable workarounds for those gaps.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Live browser debugging for AI assistants — DOM, console, network via MCP.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for Mint — AI-powered QA that runs your app in a real browser on every PR.
A paid remote MCP for AI agent browser MCP session, built to return verdicts, receipts, usage logs,
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kirakiray/web-bridge-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
