教程2026-11-20 · 智涌AI

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

WebMCP 教程头图:左侧大字 WebMCP 上手教程与 Chrome 149 起 Origin Trial、4 个工具标注字段、Edge 150 跟进三张数据卡,右侧终端展示 document.modelContext.registerTool 注册 search_products 工具、inputSchema、execute 带 signal、readOnlyHint 标注,以及浏览器 Agent 调用和 abort 注销

让 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 得先打开这个页面
适合无界面的服务端动作有人在旁边的浏览器任务

前置条件:浏览器支持和本地开关

早期教程里的 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 里有四个提示字段:

文档特别强调,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。这些集成会处理特性检测和卸载时注销。

常见坑

完成标准

想让 Agent 不止调工具、还能读写组件状态,可以对照站内的 UI SDK 拆解,它就是在 WebMCP 之上包了一层。

最后

挑站里最常被问的一个只读功能(搜索或查订单),按上面的写法注册成工具,打开 Chrome 开关和 Inspector 扩展,看模型能不能一次选对。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。