WebMCP 核心概念完全图解：Tool、inputSchema 与 execute 回调如何打通 AI 和网页-平芜编程栈

WebMCP 核心概念完全图解：Tool、inputSchema 与 execute 回调如何打通 AI 和网页

【免费下载链接】webmcp🤖 WebMCP项目地址: https://gitcode.com/gh_mirrors/webm/webmcp

WebMCP 是一个让网页把自己变成"AI 工具"的新标准提案：开发者把网页功能注册为带自然语言描述的 Tool，用 inputSchema 声明参数结构，再靠 execute 回调真正执行任务，从而让浏览器内置 AI 或 ChatGPT 等智能体能可靠地替你筛选模板、下单购物、查询状态，彻底告别脆弱的截图识别与模拟点击。

🧭 一句话理解：WebMCP 把每个网页变成一台"页面内的 MCP 服务器"——AI 不再隔着屏幕猜按钮在哪，而是直接调用网站自己提供的"官方接口"。

为什么需要 WebMCP？

今天 AI 助手操作网页的主流方式是：截图 → 识别界面 → 模拟人类点击。这套做法：

慢：一个简单操作可能要跑很多轮
脆：按钮文案一改、页面一改版，AI 就抓瞎
丢上下文：绕开页面 UI 直连后端时，登录态、页面状态都得在服务端重新复制一遍

WebMCP 的思路反过来：既然网站最清楚自己能干什么，那就让网站主动把能力"注册"给 AI。这样用户、网页、AI 三方共享同一个上下文，人随时可以看到并接管 AI 的每一步操作。

完整的背景与动机，见官方说明文档：README.md

核心概念一：Tool（工具）是什么

一个 Tool 就是"一段可被 AI 调用的网页功能"。网页通过document.modelContext.registerTool()注册，等于向 AI 递上一张说明书，说清三件事：

name：工具名，比如add-todo、filter-templates
description：自然语言描述，AI 靠它判断"什么时候该用我"
inputSchema / execute：参数契约 + 执行逻辑

一个最小示例（源自 README.md）：

await document.modelContext.registerTool({ name: "add-todo", description: "Add a new item to the user's active todo list", inputSchema: { type: "object", properties: { text: { type: "string", description: "待办事项的文本内容" } }, required: ["text"] }, async execute({ text }) { await addTodoItemToCollection(text); // 复用页面现有 JS 逻辑 return { content: [{ type: "text", text: `已添加：${text}` }] }; } });

工具随时可以注销（传入AbortController的 signal 即可移除）。因此按页面状态动态增删工具是官方推荐模式——只把当前页面真正能用的能力暴露给 AI，避免工具列表臃肿。

核心概念二：inputSchema（参数契约）

inputSchema是一份 JSON Schema，AI 读它就知道要传什么参数、什么类型、是否必填：

用type约束类型（string / number / object…）
用enum给出可选值，比如纸张规格"Letter" | "Legal" | "A4"
每个属性都建议带description，帮 AI "填对值"

给 AI 写 schema 的 3 个小心机：

做法	例子
接受原始输入，别逼 AI 心算	传"明天下午"，格式归一化留给你的 JS
枚举用自然语言	`shippingMethod: "express"`而不是`shippingId: 1`
描述要正向	"按关键词搜索商品" 优于 "不要用于下单"

核心概念三：execute 回调（真正干活的代码）

execute(args, options)就是工具的"函数体"：AI 按 schema 把参数传进来，你的回调在页面里执行真实逻辑（调接口、改状态、刷新 UI），再把结构化结果返回给 AI。三个关键特性：

可异步：async execute里随便await你的接口
可取消：options.signal携带AbortSignal，用户点"停止"时能中断网络请求
必须同步 UI：工具执行后，页面上的视觉状态要立刻更新——人和 AI 共享同一个浏览器会话，这是协作的基础

一次工具调用的完整流程（图解）

从用户提问到拿到结果，WebMCP 的生命周期共 5 步：

注册 → 发现 → 调用 → 执行 → 响应，全程由浏览器居中调度。跨域 iframe 想参与协作，需要显式授权（allow="tools"+exposedTo来源白名单），保证工具只暴露给可信来源。规范中对每一步的精确算法定义，见 index.bs。

进阶：不写 JS 也行——声明式表单工具

如果某项功能本来就是一个 HTML 表单，WebMCP 提供了"零 JS"的声明式写法：给<form>加几个属性，浏览器就自动把它"编译"成一个 Tool：

<form toolname="search-cars" tooldescription="Perform a car make/model search" toolautosubmit> <input type="text" name="make" toolparamdescription="The vehicle's make (e.g., BMW, Ford)" required> <input type="text" name="model" toolparamdescription="The vehicle's model (e.g., 330i, F-150)" required> <button type="submit">Search</button> </form>

toolname/tooldescription：对应命令式 API 的 name / description
toolautosubmit：允许 AI 填完表单直接提交；不加的话，AI 填完会把提交按钮聚焦，请你人工核对后再提交

表单如何被确定性地"编译"成 inputSchema、结果如何回传给 AI，详见：declarative-api-explainer.md

写出 AI 爱用的工具：最佳实践清单

官方在 README.md 中给出的建议，浓缩成 6 条：

守住"工具预算"：每个工具都会占用 AI 的上下文 token，一两百个工具会让 AI 选择困难，甚至直接失效
单一职责：一个工具只做一件事，避免语义重叠
动态注册：按页面状态增删工具；简单应用则在加载时静态注册即可
动词要精确：create-event（立即执行）≠start-event-creation（跳到表单）
schema 宽松、代码严格：校验失败时返回清晰的错误信息，让 AI 能自我纠正并重试
信任 AI：描述写清"能干什么、需要什么"，而不是用提示词硬控流程

安全侧的考量（权限策略、来源隔离、跨域暴露）可参考：security-privacy-questionnaire.md

现在能用了吗？浏览器支持一览

平台	状态
Chrome 149	Origin Trial 已上线，本地开发可开`about:flags`测试开关
Edge 150	Origin Trial 已上线
ChatGPT Desktop	已支持
Brave	Leo AI 聊天中实验性支持

完整的浏览器与智能体支持矩阵见：implementation-status.md。TypeScript 类型定义已发布为webmcp-typesnpm 包，拿来即用。

再远一点：docs/service-workers.md 还提出了把工具注册到 Service Worker 的扩展方案——即使网站没打开，AI 也能在后台调用工具（比如悄悄帮你把商品加进购物车），需要人工确认的支付环节再弹回窗口交还用户。