webmcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WebMCP

Procedures

操作流程

Step 1: Identify the browser integration surface

Inspect the workspace for browser entry points, UI handlers, and any existing app state or form handling layer.
Execute
```
node scripts/find-webmcp-targets.mjs .
```
to inventory likely frontend files and existing WebMCP markers when a Node runtime is available.
If a Node runtime is unavailable, inspect the nearest
```
package.json
```
, HTML entry point, and framework bootstrap files manually to identify the browser app boundary.
If the workspace contains multiple frontend apps, prefer the app that contains the active route, component, or user-requested feature surface.
If the inventory still leaves multiple plausible frontend targets, stop and ask the user which app should receive the WebMCP integration.
If the project is not a browser web app, stop and explain that this skill does not apply.

Step 2: Choose the WebMCP shape

Read
```
references/webmcp-reference.md
```
before writing code.
Read
```
references/declarative-api.md
```
when the feature can be expressed as an HTML form flow or needs agent-invoked submit handling.
Read
```
references/compatibility.md
```
when native availability, Chrome preview setup, or draft-versus-preview behavior matters.
Read
```
references/troubleshooting.md
```
when registration, schema serialization, or agent-driven form execution fails.
Verify that the integration runs in a secure window browsing context.
If the feature must run on the server, in a worker, or headlessly without a visible browsing context, stop and explain the platform limitation.
Choose the imperative API when the tool wraps existing JavaScript logic, requires dynamic registration, or needs
```
ModelContextClient.requestUserInteraction()
```
.
Choose the declarative API when the user flow already maps cleanly to a form submission and the page can keep the human-visible form in sync with agent activity.
Keep tool names, descriptions, and parameters explicit and positive, and prefer atomic tools over overlapping variants.

Step 3: Implement tool registration

Read
```
assets/model-context-registry.template.ts
```
and adapt it to the framework, state model, and file layout in the workspace when using the imperative API.
Register imperative tools with
```
navigator.modelContext.registerTool()
```
using a stable
```
name
```
, a positive
```
description
```
, an object
```
inputSchema
```
, and an
```
execute
```
callback.
Set
```
annotations.readOnlyHint
```
to
```
true
```
only for tools that do not modify state.
Validate business rules inside the tool implementation even when the schema is strict, and return descriptive errors that help the agent retry with corrected input.
Return tool results only after the UI and application state reflect the tool's effect.
If tool availability depends on route, selection, or page state, register tools only while they are valid and unregister stale tools with
```
navigator.modelContext.unregisterTool()
```
.
For declarative tools, annotate the target
```
<form>
```
with
```
toolname
```
and
```
tooldescription
```
, and let form controls define the parameter surface.
Use labels or
```
toolparamdescription
```
to produce clear parameter descriptions for declarative fields.
Use
```
toolautosubmit
```
only when the page should submit automatically after the agent populates the form.

Step 4: Wire agent-driven UX safely

Preserve the normal human interaction path even when the page supports agent invocation.
When an imperative tool needs explicit confirmation or a user-facing step, call
```
client.requestUserInteraction()
```
instead of bypassing the UI.
When customizing declarative submit handling, call
```
preventDefault()
```
before
```
respondWith()
```
and return structured validation errors for agent-invoked submits.
Use preview-only events such as
```
toolactivated
```
,
```
toolcancel
```
,
```
agentInvoked
```
, and WebMCP form pseudo-classes only behind compatibility-aware UI logic.
Keep destructive or sensitive actions gated behind visible user confirmation, even if the agent can prepare the input.
Keep UI state synchronized so the same page accurately reflects changes caused by human input and tool calls.

Step 5: Validate behavior

Test the register and unregister lifecycle, including duplicate-name protection and cleanup on route or state changes.
Test invalid or incomplete inputs to confirm the tool returns corrective errors instead of silently failing.
For declarative tools, verify generated parameter descriptions, required fields, submit behavior, and any custom
```
respondWith()
```
handling.
If the target environment is the current Chrome preview, confirm the required version and flag state from
```
references/compatibility.md
```
before treating runtime failures as application bugs.
Use the Model Context Tool Inspector or equivalent preview tooling only as a validation aid, not as a runtime dependency.
Validate deterministic execution first by inspecting the registered tool set and manually invoking the tool with representative arguments when preview tooling is available.
After deterministic execution is correct, validate natural-language routing so descriptions and parameter shapes guide the agent toward the correct tool.
Run the workspace build, typecheck, or tests after editing.

步骤1：确定浏览器集成范围

检查工作区中的浏览器入口点、UI处理程序，以及所有现有的应用状态或表单处理层。
当有可用Node运行时的情况下，执行
```
node scripts/find-webmcp-targets.mjs .
```
来盘点可能的前端文件和现有WebMCP标记。
若无Node运行时，手动检查就近的
```
package.json
```
、HTML入口文件和框架启动文件，确定浏览器应用边界。
若工作区包含多个前端应用，优先选择包含活跃路由、组件或用户请求功能范围的应用。
若盘点后仍存在多个可能的前端目标，停止操作并询问用户需要给哪个应用集成WebMCP。
若项目不是浏览器端Web应用，停止操作并说明本技能不适用。

步骤2：选择WebMCP实现形式

编写代码前请阅读
```
references/webmcp-reference.md
```
。
如果功能可以通过HTML表单流程实现，或是需要Agent调用的提交处理能力，请阅读
```
references/declarative-api.md
```
。
如果涉及原生可用性、Chrome预览版设置、或是草案版与预览版行为差异相关的问题，请阅读
```
references/compatibility.md
```
。
如果遇到注册、Schema序列化、Agent驱动的表单执行失败的问题，请阅读
```
references/troubleshooting.md
```
。
确认集成运行在安全的窗口浏览上下文中。
如果功能必须运行在服务端、Worker中，或是无可见浏览上下文的无头环境中，停止操作并说明平台限制。
当工具封装了现有JavaScript逻辑、需要动态注册，或是需要使用
```
ModelContextClient.requestUserInteraction()
```
时，选择命令式API。
当用户流程已经可以清晰映射到表单提交，且页面可以让用户可见的表单与Agent活动保持同步时，选择声明式API。
保证工具名称、描述和参数清晰明确、表意正向，优先使用原子化工具而非功能重叠的变体。

步骤3：实现工具注册

使用命令式API时，阅读
```
assets/model-context-registry.template.ts
```
并适配工作区中的框架、状态模型和文件布局。
使用
```
navigator.modelContext.registerTool()
```
注册命令式工具，需传入稳定的
```
name
```
、表意正向的
```
description
```
、对象类型的
```
inputSchema
```
以及
```
execute
```
回调函数。
仅当工具不会修改状态时，将
```
annotations.readOnlyHint
```
设置为
```
true
```
。
即使Schema校验很严格，也要在工具实现内部验证业务规则，并返回描述清晰的错误，帮助Agent使用修正后的输入重试。
仅当UI和应用状态已经反映了工具的执行效果后，再返回工具结果。
如果工具的可用性依赖路由、选中项或页面状态，仅在工具有效时注册，并使用
```
navigator.modelContext.unregisterTool()
```
注销过期的工具。
对于声明式工具，给目标
```
<form>
```
添加
```
toolname
```
和
```
tooldescription
```
注解，由表单控件定义参数范围。
使用标签或
```
toolparamdescription
```
为声明式字段生成清晰的参数描述。
仅当页面需要在Agent填充表单后自动提交时，才使用
```
toolautosubmit
```
。

步骤4：安全接入Agent驱动的用户体验

即使页面支持Agent调用，也要保留正常的人工交互路径。
当命令式工具需要显式确认或面向用户的步骤时，调用
```
client.requestUserInteraction()
```
而非绕过UI。
自定义声明式提交处理逻辑时，在调用
```
respondWith()
```
前先调用
```
preventDefault()
```
，并为Agent触发的提交返回结构化的校验错误。
仅在兼容感知的UI逻辑中使用预览版专属事件，例如
```
toolactivated
```
、
```
toolcancel
```
、
```
agentInvoked
```
以及WebMCP表单伪类。
即使Agent可以准备好输入，也要对破坏性或敏感操作设置可见的用户确认门槛。
保持UI状态同步，使同一个页面能准确反映人工输入和工具调用带来的变更。

步骤5：验证行为

测试注册和注销生命周期，包括重复名称防护以及路由或状态变更时的清理逻辑。
测试无效或不完整的输入，确认工具返回修正错误而非静默失败。
对于声明式工具，验证生成的参数描述、必填字段、提交行为以及所有自定义
```
respondWith()
```
处理逻辑。
如果目标环境是当前Chrome预览版，在将运行时故障判定为应用Bug前，先对照
```
references/compatibility.md
```
确认所需版本和开关状态。
仅将Model Context Tool Inspector或等效的预览版工具作为验证辅助，不要作为运行时依赖。
当有可用的预览版工具时，先通过检查已注册的工具集、使用代表性参数手动调用工具的方式验证确定性执行逻辑。
确定性执行逻辑正确后，验证自然语言路由能力，确保描述和参数结构能引导Agent选择正确的工具。
编辑完成后运行工作区的构建、类型检查或测试流程。

Error Handling

错误处理

If
```
navigator.modelContext
```
is missing, confirm the code is running in a secure browser window context and then check the preview requirements in
```
references/compatibility.md
```
.
If
```
registerTool()
```
throws
```
InvalidStateError
```
, check for duplicate names or empty
```
name
```
or
```
description
```
values.
If
```
registerTool()
```
throws
```
TypeError
```
or JSON serialization errors, replace non-serializable or circular
```
inputSchema
```
values with plain JSON-compatible objects.
If an older demo or article references
```
provideContext
```
,
```
clearContext
```
, or
```
toolparamtitle
```
, treat those surfaces as obsolete for current implementations.
If declarative execution does not update the page correctly, read
```
references/declarative-api.md
```
and
```
references/troubleshooting.md
```
before changing the tool contract.

如果
```
navigator.modelContext
```
不存在，确认代码运行在安全的浏览器窗口上下文中，然后查看
```
references/compatibility.md
```
中的预览版要求。
如果
```
registerTool()
```
抛出
```
InvalidStateError
```
，检查是否存在重复名称，或是
```
name
```
或
```
description
```
值为空。
如果
```
registerTool()
```
抛出
```
TypeError
```
或JSON序列化错误，将不可序列化或存在循环引用的
```
inputSchema
```
值替换为纯JSON兼容对象。
如果旧的演示或文章提及
```
provideContext
```
、
```
clearContext
```
或
```
toolparamtitle
```
，对于当前实现来说这些接口已经废弃。
如果声明式执行没有正确更新页面，在修改工具契约前先阅读
```
references/declarative-api.md
```
和
```
references/troubleshooting.md
```
。