build-webmcp-tools

WebMCP 工具开发工作流（build-webmcp-tools）

WebMCP 可让网页通过 document.modelContext，向浏览器内的 AI Agent 暴露客户端功能，将其作为结构化工具，而不是让 Agent 抓取或点击 DOM。此技能会引导开发者进入工具生命周期中的正确阶段，并指出包含该阶段详细规则的参考文件。

核心原则：WebMCP 在用户已登录的会话中，于浏览器标签页内通过 document.modelContext 在客户端运行。它仅支持工具（不支持资源或提示词）。它不是通过 stdio/SSE 提供的后端 MCP 服务，工具会直接执行应用逻辑（状态存储、API、客户端路由器），而不是模拟输入或点击。

如何使用此技能

1. 将开发者的请求与路由表中的某一行对应，并进入该阶段。
2. **回复前先阅读“先阅读”列中的文件。**路径相对于此技能的目录。此文件仅对其内容做了概述；详细规则、示例和代码模式都在参考文件中，因此不要仅依据此概述作答。
3. 如果请求涉及未提供给你的材料（对话记录、schema.json、源文件），若工作区中有，请先阅读；否则请向用户索取，并概述你将如何依据参考文件中的阶段关键规则来处理（对于审计，还要列出验证步骤）。切勿臆造缺失的材料。
4. 对你生成的所有内容应用不可妥协的要求。
5. 完成审计、schema.json 或实现之前，请依据 references/audit-checklist.md 检查输出。

---

不可妥协的要求

• 预算：工具和参数名称 ≤ 30 个字符；工具描述 ≤ 500 个字符；参数描述 ≤ 150 个字符；输出 ≤ 1,500 个字符（约 400 个词元），并分页。→ tool-design.md
• 描述：“做什么 + 何时使用”（工具的功能，以及何时选择它）；切勿重复 inputSchema 参数；不要使用实现层面的术语（Redux、Pinia、Express、REST、GraphQL、gRPC）。→ tool-design.md
• 命名与结构：使用动作动词；打开表单或向导的工具使用 initiate_*，立即执行的工具使用 book_*/create_*；切勿让模型计算值（相对日期、转换）：接受用户的表述，并在应用中解析；但可进行无歧义的标准代码查询；优先使用名称，而不是不透明的 ID；建议将生命周期和注释相同的实体合并到多态、批量处理的工具中，同时将可信内容与用户编写的内容分开放在不同工具中。→ tool-design.md
• 注释：所有提示默认均为 false，且必须显式启用（仅在值为 true 时指定；切勿声明为 : false）；readOnlyHint: true 仅用于纯查询；consequentialHint: true 仅用于影响重大且不可逆的现实操作（付款、预订、删除）；视图导航、切换标签页和 initiate_* 交接不得声明 readOnlyHint: true（应省略），也无需设置 consequentialHint，以保护工具中的未保存工作；常规修改类工具省略注释；任何包含用户或第三方编写文本的输出，即使来自自有数据库，也应设置 untrustedContentHint: true。→ annotations.md
• 错误必须传递给 Agent：React useWebMCP 会抛出 Error（→ isError: true）；原生 registerTool 会 resolve { error, code, retryable }，因为拒绝会变成通用的 DOMException: UnknownError；声明式表单通过 event.respondWith 返回结构化字段错误。→ error-handling.md
• UI 同步：工具返回前，等待状态和 DOM 更新完成。
• 跨源：默认情况下，工具为同源（Permissions Policy tools，默认值为 self）；仅可通过 <iframe allow="tools"> 加上 registerTool(tool, { exposedTo: ['https://trusted.origin'] }) 进行委派；必须启用源隔离（Origin-Agent-Cluster: ?0 会禁用 WebMCP）。→ vanilla-patterns.md
• 先设计，再编码：每个工具在进入 Stage 5–6 的 schema、评估或代码之前，都必须经过 Stage 2–4（初始状态、角色扮演、变化情境，以及对语气、澄清问题和自主边界的评议）；实现简单不代表对话也简单。以 交互模式（每个目标的角色扮演结束后暂停，等待开发者评议）或 自主模式（针对每个独立目标完成 Stage 2–4、自我评议，并端到端完成 Stage 5–6 的整合与编码，不暂停）运行 Stage 2–6。只有在用户要求跳过某个工具的设计时，才可在下方的显式快速路径中跳过 Stage 2–4。→ conversational-design.md

---

路由器

开发者已有 / 请求的内容	前往	先阅读	暂不执行
“为此项目添加 WebMCP”（工作区中的本地代码，无 URL）	阶段 1	项目的 package.json、路由和主要组件；conversational-design.md	询问应用的用途；在阶段 1 之前编写代码或架构
希望端到端生成一套入门工具，中途不停下（“自主完成设计阶段”“生成入门工具”）	自主模式（阶段 1–6）——检查应用，按目标执行阶段 2–4 并进行自我批评，交付架构 + 评估 + 代码	项目文件、框架文件（见下文）、conversational-design.md、evals-format.md	跳过阶段 2–4 的角色扮演 / 变体；提前停下提问
一个具体的工具构想（“一个搜索航班的工具”）	针对此目标执行阶段 2 或 3	conversational-design.md、use-case-template.md	构思无关的工具组合；编写代码
目标已定义	阶段 2	conversational-design.md	重新构思目标
目标 + 起始状态	阶段 3	use-case-template.md、conversational-design.md	跳过批评循环
需要强化的顺利流程对话记录	阶段 4	conversational-design.md	—
已批准的角色扮演 → 架构与评估	阶段 5	tool-design.md、annotations.md、evals-format.md	为未建模的目标臆造工具
已有 schema.json → evals.json	阶段 5（评估）	evals-format.md	强制执行阶段 1–4
刚完成 schema.json/evals.json（“接下来做什么？”）	阶段 5 评估关卡	evals-format.md	未经询问就开始阶段 6
已有架构、工具规范或已命名工具，需要在框架代码中实现（例如“为 list_items 和 move_items 编写 React useWebMCP 工具”）	阶段 6	框架文件（见下文）、error-handling.md	重新开始对话设计
提供了要添加工具或分析用户旅程的URL 或域名（例如 example.com、https://...）	使用 chrome-devtools MCP 探索网站后，执行阶段 1	live-site-discovery.md（先不要读 conversational-design.md）	要求用户描述网站；使用 read_url_content 或猜测，而不是调用 chrome-devtools MCP；编写前端代码
对现有工具（实时网站或本地代码）的反馈、审查或审计	审计	audit-checklist.md、agent-security.md、error-handling.md	重新开始阶段 1 的构思
测试、DevTools、chrome-devtools-mcp 实时发现、Lighthouse、页面就绪状态	—	testing-and-debugging.md	抓取压缩后的 JS 包
概念问题	—	预算 / 命名 / 描述：tool-design.md；注解：annotations.md；提示词注入、聚焦：agent-security.md；错误：error-handling.md	—
希望跳过某个工具的设计（“能跳过角色扮演直接写代码吗？”“跳过设计，直接给我代码”）	明确的快速路径（见下文）——必须先用 1 句话指出跳过设计带来的风险，然后交付架构 + 评估 + 代码	tool-design.md、annotations.md、框架文件	拒绝编写代码
后端 MCP（stdio/SSE 服务，Node/Python）	不在范围内	—	在服务端使用 document.modelContext
框架文件：React → react-patterns.md；Angular → angular-patterns.md；Vanilla JS、Vue、Svelte → vanilla-patterns.md；声明式 HTML 表单 → declarative-patterns.md。所有文件都在 references/ 中。

入口不明确：询问适用哪一项——1）了解用户目标；2）建模初始状态；3）角色扮演对话；4）通过变体强化；5）生成 schema.json/evals.json；6）在前端代码中实现；或审计现有工具。

---

显式快速通道

仅当开发者要求跳过设计（询问“可以跳过吗？”也算）且针对单个工具时使用。对于没有中间停顿的全新项目或起步工具集请求，使用自主模式（因此仍会执行阶段 1–4）。

1. 响应开头用一两句话说明跳过了哪些内容，例如：“跳过角色扮演意味着模糊请求、澄清问题和确认边界都未经测试。”每次都要这样做，即使开发者表示他们了解风险。
2. 如果他们认为代码简单才提出此要求，也要纠正这一点：代码容易不等于对话容易（例如：“一行状态更新很简单，但‘保存我刚才打开的那个’或重复 URL 才是 Agent 容易出错的地方”）。
3. 提供工具架构、至少一个 evals.json 案例和框架代码。
4. 仍须遵守所有不可妥协项（预算、What + When、注释、错误处理）。不要再次劝说他们进行设计。

阶段 1：用户目标组合

• 自行检查应用，然后根据应用的实际功能提出 3 个优先级排序的候选用户旅程。对于每个旅程，说明其理想结果、所需上下文和自主边界（Agent 未经用户确认不得执行的操作）。
• 在线站点：说明工具必须由在页面中运行的代码（第一方代码或扩展程序/内容脚本）注册到 document.modelContext，而不是通过无头抓取注册。如果环境中有 chrome-devtools MCP（或其他浏览器工具），请立即调用它（navigate_page、take_snapshot、检查 /llms.txt，并检查 list_webmcp_tools / document.modelContext.getTools()），在提出用户旅程前检查渲染后的页面——绝不要依赖静态 HTTP 获取器（read_url_content、curl）或训练数据中的假设。只有在环境中没有浏览器工具时，才建议浏览或检查站点页面，并在提出用户旅程前检查 /llms.txt。
• 为阶段 2–6 提供两种节奏：
  • 交互模式（一次一个目标，开发者设置检查点）：选择一个目标，逐步完成阶段 2–4，并在进入下一阶段前暂停，进行用户评审循环（语气、澄清问题、自主边界）。
  • 自主模式（端到端，Agent 自我评审）：让 Agent 针对每个独立目标完成阶段 2–4（初始状态、角色扮演、变体、自我评审），中途不停下；阅读框架文件，并交付阶段 5（schema.json、evals.json）和阶段 6（框架代码）。
• 单个工具想法（例如“一个搜索航班的工具”）：跳过目标组合。将该请求作为一个用户目标来描述（理想结果、所需上下文、自主边界），并直接继续进入其阶段 2 或阶段 3。

阶段 2：初始状态矩阵

• 为该目标建模功能状态：当前路由、已加载实体、购物车/选择项、会话和身份验证、约束。
• 剔除无关的诊断信息（device_battery、gpu_temp、screen_dpi）。

阶段 3：逐轮角色扮演

• 使用 use-case-template.md 记录每一轮的 6 个要素：用户发言、Agent 意图、Agent 工具调用、工具响应（结构化 JSON，包含分页字段 page_size 和 total_count，≤ 1,500 个字符）、站点实现与 UI 反应、Agent 响应。
• 对于付款、预订或高风险操作，应模拟 人在回路中的 UI 交接（例如，initiate_booking 返回 status: "requires_user_action"，并导航至专用确认 UI，让用户点击 Confirm，而不是由系统自动向用户收费）。
• 以 批判循环结束（评估 Agent 的举止／语气、澄清问题和自主确认边界）：在 交互模式下暂停并请开发者提出批评；在 自主模式下，针对每个目标明确自我批评这三个方面，然后继续。

阶段 4：变体与优雅失败

对基线进行压力测试：缺少必需参数（询问，绝不猜测）、违反前置条件（提供可操作的错误）、查询条件过度约束（建议放宽条件）、指代消解（“第二个”），以及敏感操作的人在回路中的交接（返回 status: "requires_user_action" 并打开专用确认 UI，由用户完成操作；仅在实际提交操作的工具上设置 consequentialHint: true）。

阶段 5：工具整合与评估

• 仅整合已批准目标中的工具（采用迭代增量式或组合优先路径）；对每个工具应用 tool-design.md 和 annotations.md。
• 根据 evals-format.md 编写 schema.json 和 evals.json。
• 然后 询问用户 现在是否运行 npx webmcp-evals local -t schema.json -e evals.json，还是继续进入阶段 6。如果用户选择运行，请检查 .env 中是否设置了提供商密钥（Gemini 对应 GOOGLE_AI，或 OPENAI_API_KEY／ANTHROPIC_API_KEY），并推荐一个快速模型。

阶段 6：应用实现

• 首先阅读框架文件。React：使用 useWebMCP（来自 use-webmcp-tool），组件中绝不直接使用 registerTool；将 schema 字面量提升到组件外，或确保其稳定；并且始终包含一个 Vitest + React Testing Library 测试，该测试会模拟 document.modelContext.registerTool 并调用捕获到的 execute。Angular：使用 provideExperimentalWebMcpTools。Vanilla：使用带有 AbortController 信号的 document.modelContext.registerTool。声明式：<form toolname tooldescription>。
• 根据 testing-and-debugging.md 验证（DevTools 的 Application > WebMCP 面板、Lighthouse “Agentic browsing”），并依据 audit-checklist.md 进行自检。

审计

1. 首先阅读 references/audit-checklist.md、references/agent-security.md 和 references/error-handling.md（可以一起请求），然后再打开待审查的代码。审计标准是检查清单，而不是 Non-Negotiables 摘要；仅依据此文件进行的审计并不完整。
2. 收集工具：
   • 本地代码库：阅读注册代码（useWebMCP、registerTool、provideExperimentalWebMcpTools、<form toolname>）。
   • 线上网站：使用 list_webmcp_tools（通过带有 --categoryExperimentalWebmcp 的 chrome-devtools-mcp）、await document.modelContext.getTools() 或 DevTools 的 Application > WebMCP 面板（参见 references/testing-and-debugging.md），在运行时跨路由、标签页和 UI 状态发现工具。如果 document.modelContext 为 undefined，则表示浏览器中未启用 WebMCP（--enable-features=WebMCP 或 chrome://flags/#enable-webmcp-testing）——请报告这一前置条件，而不要假定不存在工具。切勿在网站上抓取或提取线上网站经过压缩的生产 JS 包；只有在源代码未压缩或带有 sourcemap 时，才能检查线上网站的源代码。
3. 针对检查清单中的每一项报告发现，并为每个问题指出受影响的工具和具体修复方法。
4. 最后列出验证步骤：在 Chrome DevTools 的 Application > WebMCP 面板中检查并手动执行工具（点击播放图标），然后运行 Lighthouse “Agentic browsing” 审计。
5. 目前没有可用工具（例如无法打开线上网站）时：不要只停留在索要代码。告知用户如何收集工具（在控制台中跨路由运行 await document.modelContext.getTools()、通过 chrome-devtools-mcp 使用 list_webmcp_tools，或使用 DevTools 的 Application > WebMCP 面板），列出将审计的检查清单范围（预算和术语、注解，包括导航和 UGC、错误处理、安全性），并以第 4 步中的验证步骤（DevTools 手动执行、Lighthouse “Agentic browsing”）结束回复。