WebMCP 解释页

WebMCP 让网页能够在页面内部向 agent 暴露 JavaScript tools。

它是面向共享上下文、人机协作工作流的页面级能力模型，而不只是另一种浏览器自动化技巧。

按照当前 proposal，已加载页面可以注册带结构化 schema 和 JavaScript execute handler 的 tools，让 agent 通过页面自有能力边界工作；这些 tools 是对页面内容与 actuation 的增强，而不是替代。

本页内容直接锚定 webmachinelearning/webmcp 仓库中的官方 README 与 proposal.md；生态示例只作为辅助理解，不作为规范性定义。

查看核心对比回到 FastWebMCP 首页

页面内执行

工具在哪里执行

Tool 逻辑运行在网页上下文中，而不只是后端服务。

共享界面

用户和 agent 共享什么

同一套可见 UI、页面状态、认证上下文与产品逻辑。

人在环中

工作流姿态

核心面向 human-in-the-loop 的协作式网页体验。

WebMCP 是什么

可以把 WebMCP 理解为：网页在浏览器上下文中充当 tool provider。

这个提案让页面把能力形状明确的 JavaScript 函数暴露给 agent、浏览器助手或辅助工具。落到 API 上，就是页面通过 navigator.modelContext 注册 tools，并在活页面状态上执行它们，而不是退化成脱离 UI 的后端调用。

Tool 模型

页面暴露的是 tools，不只是可点击控件。

页面可以注册带 name、自然语言 description 与结构化 input schema 的 tools，让 agent 看到稳定能力合同，而不是反向猜 DOM 结构。

执行模型

执行发生在页面上下文中。

执行发生在页面自有 JavaScript 中，因此 tool 能复用前端逻辑、当前页面状态和用户正在使用的会话，而不必强行拆成单独的服务端集成。

工作流模型

用户与 agent 留在同一个可见工作空间里。

用户与 agent 留在同一个可见工作空间里。人类网页界面仍是主界面，tools 只是把重复、结构化的动作做得更快。

重要边界WebMCP 与 backend MCP 及其他协议是协同关系，不是替代关系；它也不是为了取代人类网页界面本身。

提案到底定义了什么

当前 proposal 对运行时形状、API 表面与现阶段边界都写得相当具体。

WebMCP 不只是“网页可以暴露 tools”。提案已经写清浏览上下文、注册 API、tool 合同、用户交互路径，以及若干明确的非目标。

浏览上下文

只有已加载的顶层页面，才能在当前模型里提供 tools。

单个 top-level browsing context（例如浏览器 tab）才是 model context provider。agent 不是从后台常驻服务拿到这些 tools，而是依赖页面本身处于打开状态。

当前提案没有承诺 headless 执行模式。
tools 往往要在页面导航完成后才可发现，并且只在该页面生命周期内存在。

Tool 形状

Tool 注册有明确浏览器 API，而不是口头概念。

页面通过 navigator.modelContext.registerTool(...) 在页面 JavaScript 中声明能力、描述与 schema。

当前 imperative 形状可概括为 registerTool：包含 name、description、inputSchema 与 execute。
unregisterTool(name) 说明 tool 生命周期是 page-scoped、可撤销的。

执行语义

执行留在页面脚本里，UI 一致性仍由应用负责。

execute callback 直接运行在活页面状态上。简单场景可留在主线程，较重任务可以委托给 workers。

提案刻意让 tool 调用在页面上下文中顺序处理。
页面内容与 actuation 不会消失，因此 tool 触发的状态变化必须同步回可见 UI。

同意与协作

同意与确认本身就是 API 的一部分。

在 execute(..., agent) 期间，页面可以通过 agent.requestUserInteraction(...) 请求用户输入，同时浏览器负责仲裁对 tool 的访问。

这就是它为何更适合有监督、人在环中的工作流。
它不是拿来替代 backend MCP，也不是为完全自治 agent 设计的。

当前限制与尚未解决的边缘问题

没有内建 headless 模式：今天仍然需要可见 browsing context。

tool discoverability 仍未解决：客户端通常必须先访问页面，提案只讨论了 manifest-like 的未来方向。

开发者仍然要负责 UI 同步，并且常常需要做一定重构，才能暴露干净、可复用的 tool 边界。

API 形状

真实页面里的 WebMCP 代码大致长什么样。

这个 proposal 故意保持轻量：页面注册 tools，浏览器仲裁访问，execute handler 在活页面状态上运行。下面这段是从官方 proposal 提炼出的 pseudo-code，目的不是逐字复制，而是让团队看到真正的工程边界。

页面侧注册

页面通过 navigator.modelContext.registerTool(...) 发布一个可调用能力，包含 name、description、input schema 与 execute handler。

if ('modelContext' in window.navigator) {
  window.navigator.modelContext.registerTool({
    name: "buy-product",
    description: "购买当前商品",
    inputSchema: productPurchaseSchema,
    async execute(args, agent) {
      return await buyProduct(args, agent)
    }
  })
}

执行期用户交互

在 execute(..., agent) 期间，如果继续执行前需要确认或额外输入，页面可以调用 agent.requestUserInteraction(...)。

async function buyProduct({ productId }, agent) {
  const confirmed = await agent.requestUserInteraction(
    () => openConfirmDialog(productId)
  )

  if (!confirmed) throw new Error('已取消购买')

  await executePurchase(productId)
  syncCheckoutUI()
  return { ok: true }
}

为什么它在工程上重要

tool 是 page-scoped 的：没有已加载页面，就没有这个 tool。
tool 合同必须足够明确，agent 才能不靠 DOM 猜测来选择它。
execute 路径应尽量复用页面逻辑，并把结果同步到可见 UI，便于人复核。

它不是什么

真正理解 WebMCP，关键在于先把边界讲清楚。

有用的区别并不是“AI 能不能用网站”，而是 agent 究竟是通过原始 UI actuation、后端 integration，还是页面自有 tools 来工作。

矩阵视图

每一行都说明 WebMCP 相对于另一种集成模型处于什么位置。

WebMCP 侧

页面定义的 tools，运行在共享 UI 上下文中

对比侧

为同一件事提供的另一种集成姿态

对比 DOM 点击脚本01

WebMCP vs 浏览器自动化

二者都围绕活页面展开，但 WebMCP 把抽象层级从 selectors / gestures 提升到了页面自定义 tools；当页面暴露能力不足时，自动化仍可作为 fallback。

当你希望页面主动定义安全、明确的能力边界时，用 WebMCP；当页面 tools 没覆盖该任务时，浏览器自动化仍可作为 fallback。

WebMCP

调用的是能力形状明确的 tool，而不是回放低层 UI 步骤。
可以复用已有页面逻辑与结构化参数。
并不排斥 automation fallback；它是在页面主动暴露能力时提供更高层路径。

浏览器自动化

主要通过点击、输入、滚动、选择器定位来驱动页面。
当 UI 结构或时序变化时，更容易脆弱。
经常只能从可见控件去反推业务意图。

对比 server-side integration02

WebMCP vs 后端 MCP

二者都能向 agent 暴露 tools，但 WebMCP 是 page-scoped、由浏览器仲裁；backend MCP 则是服务端、常驻型能力。

当页面本身就是工作界面时用 WebMCP；当能力应该在没有已加载页面或浏览器 UI 的情况下存在时，用 backend MCP。

WebMCP

运行在页面上下文中，带共享状态、可见进度与用户监督。
更适合协作型 UI 工作流和 client-heavy 产品。
让浏览器体验保持主场，而不是把 UI 当成事后补丁。

后端 MCP

服务对服务运行，不需要活页面 UI。
更适合 headless、完全委派或服务端主导的操作。
并不天然共享当前页面的实时界面和交互上下文。

概念层 vs 交付层03

WebMCP vs FastWebMCP

WebMCP 解释能力模型；FastWebMCP 解决如何把真实产品安全、可重复地交付成这套能力面。

WebMCP 告诉你页面该暴露什么样的接口；FastWebMCP 帮你把这套接口真正交付进产品。

WebMCP 本身

定义页面级能力暴露这件事应该长什么样。
澄清为什么页面上下文有价值，以及 human-in-the-loop 为什么重要。
它更像协议 / 平台方向，而不是完整产品 rollout 系统。

FastWebMCP

补上 runtime、bridges、adapters、route mapping、telemetry 与 release packaging。
帮助团队在不重建产品的前提下 retrofit 现有路线。
把概念变成一条可进入 CI/CD 的交付路径。

结构视图

三种模型，对应三种不同的控制面。

理解 WebMCP 最快的方法，就是比较 agent 在哪里、逻辑在哪里执行，以及谁拥有可见工作流。

WebMCP

webmcp

Agent 通过页面自有 tools 与活页面协作。

共享 UI 上下文
页面内 tool 执行
可见的协作式工作流

浏览器自动化

automation

Agent 在 DOM 层模仿人类去驱动页面。

依赖 selectors / timing
低层 UI actuation
业务意图需要间接推断

后端 MCP

backend

Agent 直接与后端服务通信，不需要把活页面作为执行面。

服务对服务集成
适合 headless 工作流
不天然共享页面上下文

如何工作

从概念上看，WebMCP 风格流程其实很简单：页面暴露能力，agent 在上下文中调用。

当前 proposal 已经把交互骨架写得很清楚：页面级注册、结构化调用、页面上下文执行，以及在需要时由浏览器仲裁的用户交互路径。

三泳道图

按泳道往下读：用户始终停留在可见 Web 应用里，agent 在页面 tools 中做选择，页面则在活状态下执行，并由浏览器仲裁访问。

页面自有 tool 边界

共享 UI + 状态

人在环中的可见性

Step

用户

Agent

页面

01
暴露 tool
页面调用 navigator.modelContext.registerTool(...) 注册 description、input schema 与 execute handler。
在真实产品界面中提出目标。
把已注册 tool 视为一等能力。
用描述和 schema 声明能力边界。
02
agent 发现它
页面加载后 agent 才能看到这些 tools；与此同时，页面内容与 actuation 仍然可用。
停留在同一个可见工作空间里并可监督。
直接选择 tool，而不是从原始控件反推。
提供当前状态、认证上下文与 route 内逻辑。
03
在页面上下文里调用
execute callback 运行在活页面状态上；如果需要人工确认或输入，可调用 agent.requestUserInteraction(...)。
可以观察进度，并在必要时调整意图。
用结构化参数调用能力。
基于现有页面逻辑和当前会话状态执行。
04
把结果反映到 UI
页面把结果同步回可见 UI，让 human interface 继续保持主界面，用户可以复核、接管或继续协作。
查看更新后的界面状态与下一步选项。
基于更新后的上下文继续，而不是重新解析一切。
把结果直接反映到活页面 UI 上。

适用范围

当网页本身就是任务的一部分，而不只是 API 外壳时，WebMCP 才最有价值。

决定因素是：共享页面上下文和页面自有逻辑，是否会显著改善工作流。

最适合

用户与 agent 应在同一可见界面中协作的复杂 Web 应用。
已经拥有重要前端业务逻辑或交互状态的 client-heavy 产品。
通过页面级能力边界比原始 DOM actuation 更安全、更稳定的流程。

不是首选

纯 headless 的服务对服务操作，页面上下文没有价值。
完全自治的后台工作流：既不需要浏览器 UI，也不需要人工监督。
已经能被直接 backend MCP 或普通 API integration 优雅解决的能力。

开发者仍要承担什么

WebMCP 不会消除实现成本，只是把成本转移到更正确的位置。

这个 proposal 降低了“把页面能力暴露出来”的门槛，但团队仍然要做产品和前端工程工作。忽略这些责任，结果就会停留在 demo，而不是可依赖的产品面。

把页面逻辑重构成可复用的能力边界

如果页面目前只靠 click handler 和局部组件状态运转，开发者通常需要先提炼出稳定函数，tool 才能被干净地暴露。

好的 WebMCP tool 通常对应真实产品动作，而不是零散 UI 碎片。
FastWebMCP 的价值也在这里：它为这些提炼出的能力补上可重复的 bridge 与 rollout 层。

让 tool 触发的状态变化真正同步回可见 UI

proposal 明确强调 tool 调用运行在页面 JavaScript 中，页面应把状态变化反映回 UI。

如果 agent 改了 app state，但 UI 没体现，用户信任会立刻崩塌。
这对 review、undo、approval 与多步骤流程尤其关键。

设计明确的确认、授权与中断路径

浏览器仲裁访问加上 requestUserInteraction(...)，给了页面一个结构化的机会去暂停等待用户确认、登录或补充输入。

确认交互应被当作产品设计问题，而不是简单技术回调。
高风险动作应该始终可检查、可逆，并留在可见界面里。

只在页面上下文真的有价值时才使用 WebMCP

并不是所有能力都适合 page-scoped tool。有些工作仍然更适合 backend MCP、直接 API，或普通浏览器自动化 fallback。

当共享 UI、前端逻辑或人工监督会显著改善流程时，再选择 WebMCP。
不要把本应脱离浏览器也能存在的能力，硬塞进页面 tool。

实施结论

一个 beta 级可用的 WebMCP 产品，不只是“页面有 tools”。它还要有被提炼出的能力边界、同步 UI、明确 consent 模式，以及 page tools、backend integrations、automation fallback 之间的清晰分层。

FastWebMCP 的位置

FastWebMCP 是工程层，帮助团队把 WebMCP 方向变成可交付产品面。

如果 WebMCP 解释的是“页面与 agent 的接口应该长什么样”，那么 FastWebMCP 关注的就是：真实团队如何 retrofit routes、选择执行模式、沉淀 adapters，并通过 CI/CD 交付。

Route-aware runtime

把 capability rollout 映射到真实页面和真实产品面，而不是散落一堆自定义脚本。

Bridge / adapter system

根据产品真实行为，在 markup、callback、endpoint 等执行模式中做工程化选择。

Delivery / release posture

让集成可以被测试、打包、发布，并在远端部署环境中稳定消费。

FastWebMCP

从概念走向可交付产品面

FastWebMCP 把 WebMCP 风格的页面级 tools 思路，继续推进成一条工程交付路径：route-aware runtime、bridge 模式、可复用 adapters、release artifacts，以及可进入 CI/CD 的包消费方式。

回到 FastWebMCP 首页查看 SDK 路径

参考文献

这页内容背后的参考文档

下面这些链接是本解释页锚定的规范性或辅助性材料。前两项最重要，因为它们直接定义了 proposal 当前的语言、API 形状、goals 与 non-goals。

README

2025 年 8 月 13 日

webmachinelearning/webmcp README

高层 explainer，覆盖 motivation、goals、non-goals，以及为什么 WebMCP 面向 human-in-the-loop、page-context 工作流。

作者: Brandon Walderman、Leo Lee、Andrew Nolan、David Bokan、Khushal Sagar、Hannah Van Opstal
日期: 2025 年 8 月 13 日
本页引用用途: 作为高层来源，解释 goals、non-goals、human-in-the-loop 定位，以及页面 tools、actuation、backend integrations 之间的区别。

打开参考文献

proposal.md

2025 年 8 月 13 日

WebMCP API proposal（proposal.md）

核心 API 参考，包含 modelContext、registerTool/unregisterTool、页面侧顺序执行、requestUserInteraction 与当前限制。

作者: Brandon Walderman、Andrew Nolan、David Bokan、Khushal Sagar、Hannah Van Opstal
日期: 2025 年 8 月 13 日
本页引用用途: 作为 API 形状的主要来源：modelContext、registerTool/unregisterTool、requestUserInteraction、页面侧顺序执行，以及明确限制。

打开参考文献

MCP

持续更新文档

Model Context Protocol introduction

用于理解 WebMCP 不在替代什么：backend MCP 仍然适用于服务端与 headless 集成。

作者: Model Context Protocol project
日期: 持续更新文档
本页引用用途: 作为辅助背景，帮助读者理解 backend MCP 擅长什么，从而明白 WebMCP 是互补而非替代服务端 MCP。

打开参考文献

如果上游 proposal 继续演进，这页也应该对照这些文档更新，而不是漂移成纯 marketing copy。