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-skillAbout 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 即可 |
推荐工作流:
- 打开页面:使用
tabs open命令导航到目标 URL。 - 确认状态:使用
state获取导航元数据,确认webmcpTools是否注入完毕。 - 获取页面信息:这是与页面交互最关键的一步!由于
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"}'
- 方式 A(按需搜索):如果你明确知道要寻找的元素特征(例如“登录”按钮),优先使用
- 执行交互:拿到上一步返回的元素索引(
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"
| 字段 | 说明 |
|---|