WebMCP 怎么用:把网页功能注册成 Agent 工具

让 Agent 在网页上订餐、填表,现在多半靠它读 DOM、模拟点击,一步猜错就全盘重来。WebMCP 的做法是让网站自己用 JavaScript 把「搜索商品」「加入购物车」这类功能注册成工具,写清名字、说明和 JSON Schema,浏览器里的 Agent 直接调用。Chrome 149 起开了 Origin Trial,Edge 150 也跟进了。下面按 Chrome 官方文档和规范仓库,讲清楚它是什么、registerTool 怎么写、哪些坑文档专门提醒过。
WebMCP 是什么:网页自己当工具提供方
WebMCP 是一个提议中的 Web 标准,规范放在 W3C Web Machine Learning 社区组的 GitHub 仓库(webmachinelearning/webmcp)里讨论。页面是工具的「生产者」,只负责注册;浏览器内置 Agent、扩展、DevTools 和系统级助手是「消费者」,通过浏览器内部机制发现并调用这些工具。页面这边不用写任何调度代码。
和常规 MCP 的区别在于代码跑在哪。常规 MCP 服务器跑在你自己的后端,AI 平台绕过网页直接调你的 API,用户的登录态和页面状态都得在服务器上再搭一份(MCP 基础可以先看站内的 MCP 是什么、怎么配)。WebMCP 的工具是页面里的 JavaScript 函数,执行时直接复用当前登录态,界面同步更新,用户看得见 Agent 做了什么。
| 对比项 | 后端 MCP 服务器 | WebMCP |
|---|---|---|
| 代码在哪 | 你的服务器 | 用户打开的网页 |
| 登录态 | 要在服务端另做授权 | 沿用页面已有会话 |
| 界面 | 被绕开,可能和后端状态对不上 | 工具执行时页面同步更新 |
| 发现方式 | 在 AI 平台里注册 | Agent 得先打开这个页面 |
| 适合 | 无界面的服务端动作 | 有人在旁边的浏览器任务 |
前置条件:浏览器支持和本地开关
- Chrome:Chrome 149 起提供 Origin Trial;本地开发打开
chrome://flags/#enable-webmcp-testing,设为 Enabled 后重启。 - 其他客户端:规范仓库的实现状态页写着 Edge 150 也开了 Origin Trial,ChatGPT 桌面版已支持,Brave 预计在 1.102.2(2027 年 1 月 5 日)给 Leo 加上。Firefox 和 Safari 还停在标准立场讨论阶段。
- HTTPS:WebMCP 只在安全上下文可用,
localhost也算。 - TypeScript:官方类型包
webmcp-types,装好后要手动加到tsconfig.json的types里。
早期教程里的 navigator.modelContext 和 provideContext() 已经废弃:Chromium 150 起 navigator.modelContext 标为废弃,入口改成 document.modelContext,unregisterTool()、clearContext() 也都去掉了。旧代码照抄,在现在的浏览器里跑不起来。
第一步:注册一个只读工具
先做特性检测,再注册。下面是官方指南里的搜索示例,稍作合并:
const SORT_ORDERS = ["newest", "price_low_to_high"];
const controller = new AbortController();
if ("modelContext" in document) {
await document.modelContext.registerTool({
name: "search_products",
description: "Searches the product catalog by keyword. Use when the user wants to find or compare products.",
inputSchema: {
type: "object",
properties: {
query: { type: "string", description: "Words to search for." },
sort: { type: "string", enum: SORT_ORDERS, default: "newest", description: "Order of the results." },
},
required: ["query"],
},
async execute({ query, sort = "newest" }, { signal }) {
if (typeof query !== "string" || !SORT_ORDERS.includes(sort)) {
return { error: "Pass a search query and a supported sort order.", sortOrders: SORT_ORDERS };
}
return await productService.search({ query, sort }, { signal });
},
annotations: { readOnlyHint: true },
}, { signal: controller.signal });
}
// 路由切走、组件卸载时注销
controller.abort();
下面几条都出自文档:description 只说工具干什么、什么时候用,参数类型和枚举值放进 schema,不要在描述里重复;registerTool() 返回 Promise,参数不合法时 Promise 会被拒绝(比如 exposedTo 里写了非 HTTPS 的源,报 SecurityError),记得 await;注销只能靠 abort 注册时传入的 signal。
浏览器不会按 inputSchema 校验参数,也不会替你填默认值,这两件事都得在 execute 里自己做。
第二步:会改数据的工具要打标注
annotations 里有四个提示字段:
readOnlyHint:只读不改,Agent 可以放心调用。consequentialHint(Chrome 154+):订票、转账、发消息、删数据这类不可逆操作,提示 Agent 先找用户确认。untrustedContentHint:返回内容不归你控制,比如用户评论、第三方 API 的结果。debugging(Chrome 156+):给开发调试用的工具,比如导出内部状态、塞测试数据。
文档特别强调,consequentialHint 只是提示,不会拦住执行,老版本浏览器也不会弹确认。页面原本该有的确认对话框一个都别省。
第三步:错误和取消别靠 throw
execute 一旦抛异常,Agent 只收到一个笼统的执行失败,错误信息传不过去。输入不对、找不到商品、接口返回 4xx 这类可恢复错误,要像上面那样返回 { error: "..." },最好再附上可选值,让 Agent 能自己改参数重试。
只有一种情况该重新抛出:执行被取消了(signal.aborted 为 true)。有网络请求或耗时操作的工具,必须把第二个参数里的 signal 传给 fetch();setTimeout、轮询这类不认 signal 的,要在步骤之间调 signal.throwIfAborted()。不然 Agent 已经换了思路,旧请求还在跑,回来把过期数据写进界面。另外要记住,abort 注册信号只是注销工具,已经在跑的调用不会停。
第四步:本地调试和自动化测试
getTools() 和 executeTool() 是给页面内嵌的聊天助手和测试用的,只想把工具暴露给浏览器 Agent 的话,用不着它们。写测试时可以这样模拟一次调用:
const tools = await document.modelContext.getTools();
const tool = tools.find((t) => t.name === "search_products");
const result = await document.modelContext.executeTool(tool, { query: "耳机" });
console.log(result); // 返回的是序列化后的字符串
Chrome 155 起 executeTool() 直接收对象,更早的版本要传 JSON 字符串,官方示例里写了回退。想看真实模型怎么挑工具,可以装官方的 Model Context Tool Inspector 扩展,填一个 Gemini API Key 后用自然语言发指令,默认走 gemini-3.6-flash。DevTools 也能检查浏览器解析出来的 JSON Schema。
用 React、Angular、Vue 的项目,文档要求走框架官方集成,不要在组件里直接调 registerTool:React 用 use-webmcp-tool,Vue 用 @vueuse/core 的 useWebMCP,Angular 用 provideExperimentalWebMcpTools。这些集成会处理特性检测和卸载时注销。
常见坑
- 跨域 iframe 里注册失败。两套 API 都受
tools权限策略控制,默认只允许顶层和同源。嵌入第三方 iframe 时要加allow="tools";要让别的源发现你的工具,还得在注册时写exposedTo,对方用getTools({ fromOrigins: [...] })来查,两边都要开口。 - 把工具当成无人值守的 API。文档写明 WebMCP 主要面向有人在场的本地浏览器流程,无头浏览器里能跑但不是设计目标。Agent 也得先打开你的页面才知道有哪些工具,别指望它像搜索引擎一样爬到。
- 让编程 Agent 帮你写,它却不肯用。谷歌的 Modern Web Guidance 默认挡住 Origin Trial 阶段的 API,要在项目里跑
npx modern-web-guidance@latest set-allow-origin-trials才会给出 WebMCP 写法。 - 以为表单加属性就够了。Chrome 文档提到基于 HTML 表单的声明式 API,规范仓库的 README 则把它放在「探索中」,当前规范围绕
registerTool()。生产代码先用命令式写法。
完成标准
- 页面在 HTTPS 下做了
"modelContext" in document检测,不支持的浏览器照常可用。 - 每个工具的描述只讲用途,参数约束都在 schema 里,
execute里自己校验和补默认值。 - 改数据的工具标了
consequentialHint,页面自带确认环节;只读工具标了readOnlyHint。 - 耗时工具把
signal透传到底,取消后界面能回滚;路由切换时注册信号被 abort。 - 测试里用
executeTool()覆盖了正常返回和{ error }两条路径。
想让 Agent 不止调工具、还能读写组件状态,可以对照站内的 UI SDK 拆解,它就是在 WebMCP 之上包了一层。
最后
挑站里最常被问的一个只读功能(搜索或查订单),按上面的写法注册成工具,打开 Chrome 开关和 Inspector 扩展,看模型能不能一次选对。