暴露第一个 WebMCP 工具
通过 WebMCP 暴露一个类型化的只读书籍操作,校验其参数、限定其结果,并检视完整的调用生命周期。
第 17 章建好了契约。本章把它注册给浏览器。
我们的第一个 WebMCP 工具不应发消息、编辑文档或购买任何东西。它应当从我们控制的这本书里读取。我们将暴露 search_book:一个有界的、返回相关章节与段落的操作。
这种克制是刻意的。从一个有界的只读工具开始,能在我们测试注册、发现、schema 处理、执行与追踪时,先移除改变状态的后果。它没有移除披露风险——读取工具仍可能泄漏——所以语料与结果仍然需要显式的边界,这就是第 6 节大部分内容所讲的。
1. 为什么第一级是只读
存在一段能力阶梯,search_book 是它的最低一级:
读取一个受控语料 ← 我们在这里
跨 origin 读取
准备一份草稿
可逆本地写入
外部效应(发送、发布)
每高一级都增加一个下一级不必回答的权威性问题。从底部开始,让我们先把管道做对——浏览器能看到这个工具吗,schema 能往返吗,轨迹能捕获每个阶段吗——然后任何错误才可能离开页面之前。
2. 完整的 search_book 契约
读者应当能讲出这个工具的每个维度:
| 维度 | 值 |
|---|---|
| 标识 | programmer.ie + search_book + 注册实例 |
| 名字 | search_book |
| 描述 | “Search this book for passages related to a query.” |
| 输入 schema | query(string,2–300 字符)、limit(integer,1–10,默认 5)、additionalProperties: false |
| 效应类别 | read,作用域 registered-book-index,network: forbidden |
| Annotations | readOnlyHint: true、consequentialHint: false、untrustedContentHint: false |
| 结果形状 | { chapter, title, url, excerpt } 数组加 truncated |
| 结果边界 | 至多 10 条匹配;摘录上限 180 字符;语料限于本书 |
| 确定性校验 | schema,再领域(query 长度、limit 范围),再结果形状检查 |
| 错误 | query 触发 TypeError,limit 触发 RangeError,无匹配返回空数组 |
| 权威性类别 | 在声明的作用域内自动准入;无需批准界面 |
这些行中的每一行都由应用代码执行。schema 是给智能体关于参数形状的提示;它不是执行边界。
3. WebMCP 注册表面
WebMCP 是一项 origin trial API。下面的语法已于 2026 年 9 月 6 日对照 Chrome for Developers 的 WebMCP 文档重新核查;它从 Chrome 149 起在 origin trial 背后可用,并从 chrome://flags/#enable-webmcp-testing 用于本地开发。
const controller = new AbortController();
await document.modelContext.registerTool(
{
name: "search_book",
description: "Search this book for passages related to a query.",
inputSchema: {
type: "object",
properties: {
query: { type: "string", minLength: 2, maxLength: 300 },
limit: { type: "integer", minimum: 1, maximum: 10 }
},
required: ["query"],
additionalProperties: false
},
annotations: {
readOnlyHint: true,
consequentialHint: false,
untrustedContentHint: false
},
execute: async ({ query, limit = 5 }, { signal }) => {
return searchBook({ query, limit, signal });
}
},
{ signal: controller.signal }
);
三个细节很重要,并且随 API 演进变化过:
- 注册在
document.modelContext.registerTool上,而不是navigator.modelContext。早期草稿用的是navigator路径;手稿与第 18 章的实验元数据在 2026 年 9 月的那次核查中被更正为document。 - 撤回由一个
AbortController驱动。 你向registerTool传{ signal },之后调用controller.abort()撤回该注册。截至 Chrome 153,中止不会打断已在进行中的执行——这个细节 Observatory 应当记录,而不是假定。 execute处理器收到输入对象与一个携带signal的 options 对象。无论平台对 schema 施加(或不施加)什么,处理器都要重新校验(第 5 节),并把该 signal 传进任何可取消的工作中。
要抓住的不变式是:
平台可能约束 + 应用校验 = 实际的执行边界
持久的架构是将比语法活得更久的那部分:一个名字、一条描述、一个类型化输入 schema、安全 annotations、一个生命周期与一个实现。
4. 安全 annotations 做什么、不做什么
readOnlyHint、consequentialHint 与 untrustedContentHint 是沟通,不是执行。
| Annotation | 它告诉智能体什么 | 它不保证什么 |
|---|---|---|
readOnlyHint: true |
作者声明这次调用不改变任何状态 | 实现真的无副作用 |
consequentialHint: true |
该调用有重大或难以逆转的效应,因此消费方智能体或浏览器可以在其运行前要求用户确认 | false 值就可以无人值守地安全运行,或该 annotation 本身就是授权机制 |
untrustedContentHint: true |
结果可能包含需要消毒的外部或用户生成文本 | false 值就不含被注入的指令 |
这些 hint 让行为良好的智能体与浏览器做出更好的默认决策。它们由页面提供,因此 Observatory 把它们存储为 browserAttested: false。对 search_book 真正的约束——无网络、无写入、有界披露——活在实现里与确定性政策层里,后者从自己的注册表赋予效应,无论 annotations 声称什么。
5. 校验两次,然后检查结果
schema 约束模型产出的形状。应用执行领域规则。
function searchBook({ query, limit = 5, signal }) {
if (typeof query !== "string" || query.trim().length < 2) {
throw new TypeError("query must contain at least two characters");
}
if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
throw new RangeError("limit must be between 1 and 10");
}
const matches = index.search(query.trim(), limit, { signal });
return boundResult(matches); // caps count, excerpt length and corpus
}
有五道门,不是两道:
schema validation → 形状良好
domain validation → query 与 limit 满足工具自己的规则
policy validation → 该效应类别在此上下文中可准入
resource limits → 数量、摘录长度、语料作用域
result validation → 返回值符合结果契约
一个通过 schema 的 JSON 参数不是一次有效的操作,一个 resolve 的处理器不是一个有效的结果。最后一道门很重要:一个携带二十条匹配或 4,000 字符摘录的 resolved promise 已经违反了契约,尽管什么都没有抛出。
6. “只读"不等于"可以安全披露一切”
读取工具没有副作用。它仍然可能泄漏。
search_book 的披露边界由四个限制设定:
- 语料作用域 —— 搜索只在本书的已注册索引上运行,不在任意 DOM 文本、文件或另一个 origin 上。
- 摘录大小 —— 每条匹配 180 字符,足以判断相关性,不足以重构一个章节。
- 结果数量 —— 至多 10 条引用,这也保护智能体的上下文窗口不被一次调用淹没。
- 仅公开内容 —— 索引包含已发布的章节摘要;私密或草稿材料绝不会被注册。
“只读"描述的是对状态的效应。披露边界是一个分开的决定,对一个读取私密内容的工具而言,它是更重要的那个。
7. 工具标识是上下文相关的
两个站点可以注册一个都叫 search_book 的工具,一个站点也可以在一次访问中注册、撤回并重新注册它。光凭工具名不是标识。
WebMCP 本身按 origin 与名字给工具编号。为了追踪,我们需要区分同一名字的两次注册,因此 Observatory 给每次注册分配自己的 ID,并把有效的轨迹标识视为:
origin + 工具名 + Observatory 注册 ID
智能体的工具列表是依赖时间的页面状态:注册可能在加载之后出现、被一份新定义替换,或在 controller 中止时被撤回。Observatory 为每次注册存下快照:
- 页面 origin;
- 完整工具定义与一个 schema 哈希;
- 注册时间;
- annotations;
- 来源是声明式(HTML form)还是命令式(
registerTool); - 替换或移除,附带原因。
两次运行之间的行为变化,只有在我们知道工具列表相同——或确切知道它有何不同——时才可解读。
8. 在模型碰到工具之前先测试它
这是本章的方法论核心。在请智能体去发现 search_book 之前,用完全不涉及模型的 fixture 证明这份确定性契约:
| Fixture | 预期结果 | 被锻炼的阶段 |
|---|---|---|
有效查询,limit: 3 |
至多 3 条来自本书的有界匹配 | 执行 + 结果边界 |
| 语料中无匹配的查询 | 空数组,truncated: false —— 绝不捏造文本 |
依据性 |
| 301 字符的查询 | 拒绝 | schema |
limit: 11 |
拒绝 | schema |
额外的 destination 字段 |
拒绝 | schema(additionalProperties: false) |
| 格式错误的 JSON 字符串 | 拒绝 | 解析 |
| 为返回长文本而构造的查询 | 摘录仍被封顶在 180 字符 | 结果验证 |
| 执行中途中止 | 处理器观察到 signal;部分工作被丢弃 |
取消 |
只有当每一行都确定性地通过,我们才转向评估智能体是否会发现并选择该工具。以相反次序运行这些,会让一个工具 bug 伪装成一次推理失败——这是智能体调试出错最常见的单一方式。
9. 这本书变成可寻址的软件
一旦站点暴露一族操作——
search_book
get_chapter
find_concept
compare_chapters
run_experiment
inspect_evidence
——这本书就不再只是渲染在浏览器里的文本。它有了一个语义接口:智能体可以在一份有界契约下检索某个特定章节、比较二者,或定位一个概念,而无需被交予页面的控制权。
这比"这本书是一个智能体"是一个更小的主张。这本书暴露能力。发现并使用它们的是另一套系统,被单独评估,从下一章开始。
10. 运行 WebMCP search-book 实验室
从第 18 章选择 Run with Browser AI 以打开:
/tools/ai/browser-ai-from-first-principles/18-chapter/
实验室有两条分开的路径。live path 调用 document.modelContext.registerTool、检视该表面是否存在,并在不存在时记录确切的失败——origin trial 未激活、flag 未设置——而不是把每种情况都折叠成"不可用”。simulator path 在页面内行使同一份契约;其事件携带 surface: in-page-simulator,且绝不被计为浏览器注册。
无论哪条路径,你都可以运行第 8 节的确定性 fixture、检视身份快照(origin、契约版本、注册 ID、schema 哈希、定义哈希、surface),并逐步查看生命周期事件:检视、注册、提议、参数校验、政策准入、执行、结果验证、替换、移除。
这确立了什么:search_book 契约在可用之处已通过当前 WebMCP 表面注册,其确定性行为被充分测试。什么仍是被规定而非被观察的:policy.modelSelectionClaim 为 not-observed——本章不主张有浏览器智能体发现或选择了该注册。记录中的轨迹仍只显示 Prompt API 生命周期。对发现与选择的行为评估从第 19 章开始。
结论
一个有用的 WebMCP 工具把语义名字、类型化输入、告知而非执行的安全 annotations、有界结果、每道门上的应用侧校验,以及完整的身份与生命周期轨迹组合在一起。
search_book 给了我们一个安全的第一机制。下一个问题是行为性的:当存在几个貌似可用的工具时,智能体会不会发现并选对那个,带着正确的参数,并真正使用它返回的东西?
参考与延伸阅读
- Chrome for Developers, WebMCP.
- Chrome for Developers, WebMCP imperative API.
- Chrome for Developers, WebMCP tool security.
- Model Context Protocol, Specification.
- JSON Schema, Understanding JSON Schema.