Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

webmcp-cli-skill

面向第三方 AI Agent 的安装与执行指南:如何使用 webmcp-cli 与浏览器页面交互。包含已注入 WebMCP 工具的页面领域专用工具说明。

opentiny · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add opentiny/agent-skills --skill webmcp-cli-skill

About this skill


name: webmcp-cli-skill description: 面向第三方 AI Agent 的安装与执行指南:如何使用 webmcp-cli 与浏览器页面交互。包含已注入 WebMCP 工具的页面领域专用工具说明。 license: MIT metadata: author: opentiny version: '1.2.0'

WebMCP CLI Skill

本 Skill 为第三方 AI Agent 提供完整说明,介绍如何通过 Model Context Protocol(MCP)使用 webmcp-cli 与浏览器页面交互。

何时使用

  • 需要与网页交互(点击元素、填写表单、滚动页面)时。
  • 需要读取当前 DOM 结构并识别可交互元素时。
  • 在已注入领域专用工具的页面上操作时(例如 Excalidraw 绘图工具)。

安装

用户环境通常都已经安装好 webmcp-cli 工具,当shell终端提示找不到工具时,才进行下面的安装:

npm install -g @opentiny/webmcp-cli

命令

1. 管理浏览器标签页 webmcp-cli tabs

所有子级命令如下:

webmcp-cli tabs open https://excalidraw.com    # 打开新网页
webmcp-cli tabs close <tabid>                  # 关闭指定标签页
webmcp-cli tabs switch <tabid>                 # 切换到指定标签页
webmcp-cli tabs back                           # 当前标签页后退
webmcp-cli tabs back <tabid>                   # 指定标签页后退
webmcp-cli tabs forward                        # 当前标签页前进
webmcp-cli tabs forward <tabid>                # 指定标签页前进

2. 查询浏览器当前状态 webmcp-cli state

它返回当前浏览器的导航元数据(url、title、activeTabid、webmcpTools、所有已打开页签),是确认当前页面有哪些可用工具(webmcpTools)的唯一方式。

注意:state 不返回页面 DOM 内容(没有 content 字段)。需要获取可交互元素或页面信息状态时,请显式调用 page-agent-tool 的 browserState 或 searchTree 动作。

webmcp-cli state
webmcp-cli state -t <targetId>   # target a specific tab by its real Chrome target ID

输出示例:

{
  "url": "https://www.baidu.com/",
  "title": "百度一下,你就知道",
  "activeTabid": "2EA73ED323E46E5E108D4E46DA4E4AA7",
  "webmcpTools": [{ "name": "page-agent-tool" }, { "name": "baidu_search" }],
  "tabs": [
    { "tabid": "2EA73ED323E46E5E108D4E46DA4E4AA7", "title": "百度一下,你就知道", "url": "https://www.baidu.com/" }
  ]
}

返回值中, tabs 属性值是浏览器当前打开的全部标签页的信息,其它属性为当前激活页面的URL、标题、已注入的 MCP 工具列表(webmcpTools)。

tabid 是 真实的 Chrome target ID(UUID)。配合 -t 可指定某个标签页。

webmcpTools的值的数组中如果有 system-overview的工具,并且在本轮对话中,该域名下没有调用过它,那么一定要立即执行一下 。system-overview工具的返回值能指导后续的操作,比如会包含网站的模块 & 路由 & 页面工具 &使用规范等等内容。

webmcp-cli run system-overview '{}'

何时必须调用 state

时机是否必须先 state说明
执行 tabs open 之前否tabs open 是唯一可在未先 state 的情况下直接执行的命令
执行 tabs 之后是新页面加载并注入工具后,须用 state 获取新页面的 webmcpTools
执行 run 之前是须先通过 state 确认工具列表,再用 browserState 或 searchTree 获取页面可交互元素
连续多次 run 之间视情况若需重新确认工具列表或当前页面,才需再次 state;仅获取 DOM 变化直接使用 page-agent-tool 相关 action 即可

推荐工作流:

  1. 打开页面:使用 tabs open 命令导航到目标 URL。
  2. 确认状态:使用 state 获取导航元数据,确认 webmcpTools 是否注入完毕。
  3. 获取页面信息:这是与页面交互最关键的一步!由于 state 不包含 DOM 内容,你必须通过 page-agent-tool 来获取页面的可交互元素。请根据实际情况自主思考并选择获取方式:
    • 方式 A(按需搜索):如果你明确知道要寻找的元素特征(例如“登录”按钮),优先使用 searchTree 以节省大量上下文 Token。 webmcp-cli run page-agent-tool '{"action": "searchTree", "query": "登录"}'
    • 方式 B(全量获取):如果你需要全面了解页面结构,或者不知道页面上具体有什么元素,请使用 browserState 抓取完整的无障碍树。 webmcp-cli run page-agent-tool '{"action": "browserState", "responseMode": "full"}'
  4. 执行交互:拿到上一步返回的元素索引(index)后,再执行 click、fill 等具体操作。

执行 page-agent-tool 操作(点击、填写、滚动等)时,必须 依据 browserState 或 searchTree 返回的元素索引确定元素 index,切勿沿用过期猜测的索引。

3. 执行页面上的工具 webmcp-cli run <tool-name> '<json-args>'

在当前活动页面上执行 MCP 工具, json-args 要提前转义为有效的cli参数。

调用规范

该工具可以在多种终端下运行,但优先使用 bash shell 来运行。 不同终端传入 json-args 参数时,请严格依照下面规则传入:

  • bash终端: 使用单引号包裹json-args , eg. '{"action": "fill", "index": 0, "text": "你的幽默风趣技术标题"}'
  • cmd终端: 使用双引号包裹json-args, 且里面的双引号需要转义, eg. "{"action": "fill", "index": 0, "text":"你的幽默风趣技术标题"}"
  • powershell 终端: 使用单引号包裹json-args, 且里面的双引号需要转义, eg. `{"action": "fill", "index": 0, "text":"你的幽默风趣技术标题"}'

在遇到控制台报错: executing run command: 参数不是有效的 JSON时, 一定要检查json-args 参数的格式是否符合上面的规则。

3.1 page-agent-tool

它是一个自动化操作网页的工具,每一个页面都会存在,可以直接调用。支持以下动作(action): browserState、searchTree、click、fill、select、scroll、executeJavascript。

此外,该工具接收配置参数 responseMode,用于控制操作后返回的页面状态形式:

  • diff(默认):仅返回自上一次状态以来的增量 DOM 差异,极大节省 Token。
  • full:返回当前视口中完整的语义化 ARIA YAML 树。
  • both:同时返回全量树和增量差异。

执行 click、fill、select、scroll 等操作后,工具会自动以指定 responseMode(默认 diff)返回最新页面状态,无须再次手动调用 browserState。

示例:

# 1. 首次获取全量页面状态
webmcp-cli run page-agent-tool '{"action": "browserState", "responseMode": "full"}'

# 2. 点击索引为 18 的元素,自动返回 diff
webmcp-cli run page-agent-tool '{"action": "click", "index": 18}'

# 3. 填充文本框
webmcp-cli run page-agent-tool '{"action": "fill", "index": 13, "text": "Hello"}'

# 4. 选择下拉框选项
webmcp-cli run page-agent-tool '{"action": "select", "index": 7, "value": "option_value"}'

# 5. 滚动页面,同时获取全量与增量
webmcp-cli run page-agent-tool '{"action": "scroll", "down": true, "numPages": 1, "responseMode": "both"}'

# 6. 执行 JavaScript
webmcp-cli run page-agent-tool '{"action": "executeJavascript", "script": "document.title"}'

# 7. 对指定标签页操作
webmcp-cli run page-agent-tool '{"action": "browserState"}' -t <targetId>

3.1.1 Browser State:页面无障碍树格式说明

browserState 返回当前页面的语义化 YAML 无障碍树,格式如下:

- region:
    - main:
        - button #9 [cursor=pointer] "产品文档"
        - button #47 [selected] [cursor=pointer] "40元/月 2核CPU 2GB内存"
        - radio #53 [checked] [cursor=pointer] "自动生成密码"
        - button #74 [cursor=pointer] "立即购买"
        - generic #6 [cf-uba="serviceList..Flexus云服务"] "Flexus云服务"

节点格式:- role #N [token1] [token2] "accessible name"

字段说明
Read the complete source ↗