add-webmcp-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Add WebMCP Tools with webmcp-kit

使用webmcp-kit添加WebMCP工具

When to Use This Skill

何时使用此技能

Use this skill when the request is about WebMCP tools in a website codebase:

Add a new tool using
```
defineTool(...)
```
Edit existing tool behavior, schema, or annotations
Debug tools that do not appear or fail at runtime
Test tools with webmcp-kit dev panel or direct execution

Do not use this skill for unrelated frontend/backend feature work that does not involve WebMCP tool definitions.

当请求涉及网站代码库中的WebMCP工具时，使用此技能：

使用
```
defineTool(...)
```
添加新工具
编辑现有工具的行为、架构或注释
调试未显示或运行时失败的工具
使用webmcp-kit开发面板或直接执行来测试工具

不要将此技能用于不涉及WebMCP工具定义的无关前端/后端功能开发。

Preflight

前置检查

Run these checks before changing code:

Confirm dependencies and framework

Check
```
package.json
```
for
```
webmcp-kit
```
and
```
zod
```
If missing, install with
```
npm install webmcp-kit zod
```

Find likely tool files

Search for existing tools and registration:

```
rg -n "defineTool\(|\.register\(" src
```
```
rg -n "enableDevMode\(" src
```

Prioritize common locations:

```
src/mcp-tools.ts
```
```
src/lib/mcp-tools.ts
```
```
src/mcp/*.ts
```

Locate app entrypoint

Identify where browser app bootstraps and where tool
```
.register()
```
calls belong
Ensure
```
enableDevMode()
```
is enabled for local debugging when requested

在修改代码前运行以下检查：

确认依赖项和框架

检查
```
package.json
```
中是否有
```
webmcp-kit
```
和
```
zod
```
如果缺失，使用
```
npm install webmcp-kit zod
```
安装

查找可能的工具文件

搜索现有工具和注册信息：

```
rg -n "defineTool\(|\.register\(" src
```
```
rg -n "enableDevMode\(" src
```

优先检查常见位置：

```
src/mcp-tools.ts
```
```
src/lib/mcp-tools.ts
```
```
src/mcp/*.ts
```

定位应用入口点

确定浏览器应用的引导位置，以及工具
```
.register()
```
调用的所属位置
当用户要求本地调试时，确保
```
enableDevMode()
```
已启用

Playbooks

操作指南

1) Add New Tool

1) 添加新工具

Entry condition: No existing tool satisfies the requested capability.

Steps:

Create or update the tool module.
Define tool with specific camelCase name and clear description.
Add strict
```
inputSchema
```
with
```
.describe()
```
for every field and
```
.default()
```
for optional defaults.
Implement
```
execute
```
and return either string or response helper (
```
textContent
```
,
```
jsonContent
```
,
```
errorContent
```
).
Register the tool in the app flow with
```
.register()
```
.
Verify with dev panel and direct execution.

Reference template:

typescript

import { defineTool, jsonContent } from 'webmcp-kit';
import { z } from 'zod';

export const searchProducts = defineTool({
  name: 'searchProducts',
  description: 'Search products by query',
  inputSchema: z.object({
    query: z.string().describe('Search text entered by user'),
    limit: z.number().min(1).max(50).default(10).describe('Maximum results'),
  }),
  execute: async ({ query, limit }) => {
    const results = await db.products.search(query, limit);
    return jsonContent(results);
  },
});

searchProducts.register();

Completion checks:

Tool appears in dev panel list
Valid inputs execute successfully
Invalid inputs return schema validation errors

触发条件：没有现有工具能满足所需功能。

步骤：

创建或更新工具模块。
使用特定的小驼峰式名称和清晰的描述定义工具。
为每个字段添加带
```
.describe(...)
```
的严格
```
inputSchema
```
，为可选参数添加
```
.default()
```
。
实现
```
execute
```
并返回字符串或响应助手（
```
textContent
```
、
```
jsonContent
```
、
```
errorContent
```
）。
在应用流程中使用
```
.register()
```
注册工具。
通过开发面板和直接执行进行验证。

参考模板：

typescript

import { defineTool, jsonContent } from 'webmcp-kit';
import { z } from 'zod';

export const searchProducts = defineTool({
  name: 'searchProducts',
  description: 'Search products by query',
  inputSchema: z.object({
    query: z.string().describe('Search text entered by user'),
    limit: z.number().min(1).max(50).default(10).describe('Maximum results'),
  }),
  execute: async ({ query, limit }) => {
    const results = await db.products.search(query, limit);
    return jsonContent(results);
  },
});

searchProducts.register();

完成检查：

工具出现在开发面板列表中
有效输入能成功执行
无效输入返回架构验证错误

2) Edit Existing Tool

2) 编辑现有工具

Entry condition: Tool exists and user requests schema/behavior changes.

Steps:

Update only the target tool definition (
```
description
```
,
```
inputSchema
```
,
```
execute
```
,
```
annotations
```
).
Keep input changes backward-compatible unless user explicitly requests breaking changes.
Re-run dev panel execution with old and new input shapes when relevant.
Confirm
```
.register()
```
path still executes at app startup.

Common edits:

Schema constraints (
```
.min()
```
,
```
.max()
```
,
```
.regex()
```
,
```
z.enum(...)
```
)
Output formatting (
```
jsonContent
```
vs string)
Optional params (
```
.optional()
```
/
```
.default()
```
)
Confirmation hints for sensitive actions

Completion checks:

Existing intended flow still works
Updated behavior matches user request

触发条件：工具已存在，用户要求修改架构/行为。

步骤：

仅更新目标工具的定义（
```
description
```
、
```
inputSchema
```
、
```
execute
```
、
```
annotations
```
）。
除非用户明确要求破坏性变更，否则保持输入变更向后兼容。
当相关时，使用旧的和新的输入形状重新运行开发面板执行。
确认
```
.register()
```
路径仍在应用启动时执行。

常见编辑内容：

架构约束（
```
.min()
```
、
```
.max()
```
、
```
.regex()
```
、
```
z.enum(...)
```
）
输出格式（
```
jsonContent
```
vs 字符串）
可选参数（
```
.optional()
```
/
```
.default()
```
）
敏感操作的确认提示

完成检查：

现有预期流程仍能正常工作
更新后的行为符合用户要求

3) Debug Missing or Broken Tool

3) 调试缺失或损坏的工具

Entry condition: Tool does not show up or throws errors.

Steps:

If tool is missing in panel:

Verify
```
.register()
```
executes
Verify
```
enableDevMode()
```
runs in browser entry
Check browser console for
```
[webmcp-kit]
```
diagnostics

If validation fails:

Match failing field to
```
inputSchema
```
Add/adjust bounds, optionals, defaults, descriptions

If execution fails:

Isolate failing logic in
```
execute
```
Add guarded error handling and clearer error messages

Confirm environment mode:

Native mode: real
```
navigator.modelContext
```
available
Mock mode: fallback message is expected and dev panel still works

Expected fallback log (normal in unsupported browsers):

[webmcp-kit] Using mock modelContext for tool "toolName". Native WebMCP not available.

Completion checks:

Root cause identified and fixed
Tool now appears/executes in expected mode

触发条件：工具未显示或抛出错误。

步骤：

如果工具未在面板中显示：

验证
```
.register()
```
已执行
验证
```
enableDevMode()
```
在浏览器入口中运行
检查浏览器控制台中的
```
[webmcp-kit]
```
诊断信息

如果验证失败：

将失败字段与
```
inputSchema
```
匹配
添加/调整边界、可选参数、默认值、描述

如果执行失败：

隔离
```
execute
```
中的失败逻辑
添加受保护的错误处理和更清晰的错误消息

确认环境模式：

原生模式：提供真实的
```
navigator.modelContext
```
模拟模式：预期会有回退消息，开发面板仍能正常工作

预期的回退日志（在不支持的浏览器中属于正常情况）：

[webmcp-kit] Using mock modelContext for tool "toolName". Native WebMCP not available.

完成检查：

已识别并修复根本原因
工具现在能在预期模式下显示/执行

4) Test Tool (Dev Panel + Direct Execution)

4) 测试工具（开发面板 + 直接执行）

Entry condition: New or changed tool needs verification.

Steps:

Dev panel test:

Enable
```
enableDevMode()
```
Open panel, select tool, run with valid and invalid payloads

Direct execution test:

typescript

const result = await searchProducts.execute({ query: 'pizza', limit: 5 });

Schema inspection when needed:

typescript

console.log(searchProducts.inputSchema); // JSON Schema
console.log(searchProducts.schema);      // original Zod schema

Completion checks:

Dev panel path works
Direct invocation works
Validation errors are understandable

触发条件：新工具或修改后的工具需要验证。

步骤：

开发面板测试：

启用
```
enableDevMode()
```
打开面板，选择工具，使用有效和无效的负载运行

直接执行测试：

typescript

const result = await searchProducts.execute({ query: 'pizza', limit: 5 });

必要时检查架构：

typescript

console.log(searchProducts.inputSchema); // JSON Schema
console.log(searchProducts.schema);      // original Zod schema

完成检查：

开发面板路径正常工作
直接调用正常工作
验证错误易于理解

Destructive or Sensitive Actions

破坏性或敏感操作

For delete/checkout/payment/account changes:

Add

annotations: { destructiveHint: true }

(or

confirmationHint: true

)

Request user confirmation in
```
execute
```
before mutation
Return cancellation result when confirmation is denied

Pattern:

typescript

const deleteItem = defineTool({
  // ...
  annotations: { destructiveHint: true },
  execute: async (input, agent) => {
    const { confirmed } = await agent.requestUserInteraction({
      prompt: 'Are you sure?',
      type: 'confirmation',
    });
    if (!confirmed) return 'Cancelled';
    // perform mutation
  },
});

对于删除/结账/支付/账户变更操作：

添加

annotations: { destructiveHint: true }

（或

confirmationHint: true

）

在
```
execute
```
中执行变更前请求用户确认
当确认被拒绝时返回取消结果

模式：

typescript

const deleteItem = defineTool({
  // ...
  annotations: { destructiveHint: true },
  execute: async (input, agent) => {
    const { confirmed } = await agent.requestUserInteraction({
      prompt: 'Are you sure?',
      type: 'confirmation',
    });
    if (!confirmed) return 'Cancelled';
    // perform mutation
  },
});

Validation Checklist

验证清单

Tool name is specific, camelCase, and action-oriented
```
description
```
explains when an agent should call the tool
Every schema field has
```
.describe(...)
```
Optional inputs use
```
.optional()
```
or
```
.default(...)
```
Tool is registered with
```
.register()
```
in startup path
```
enableDevMode()
```
is enabled when local testing is requested
Native vs mock behavior is explicitly validated
Sensitive actions require confirmation flow

工具名称具体、采用小驼峰式且面向操作
```
description
```
说明代理应何时调用该工具
每个架构字段都有
```
.describe(...)
```
可选输入使用
```
.optional()
```
或
```
.default()
```
工具在启动路径中使用
```
.register()
```
注册
当要求本地测试时启用
```
enableDevMode()
```
明确验证原生与模拟行为
敏感操作需要确认流程

Expected Output

预期输出

When using this skill, report results in this structure:

Summary

What was added/edited/debugged

Files changed

Exact paths touched
What changed in each file

Verification

Commands/tests/manual checks run
Native or mock mode used

Remaining risks

Open issues, follow-up tests, or assumptions

使用此技能时，按以下结构报告结果：

摘要

添加/编辑/调试的内容

修改的文件

确切的修改路径
每个文件中的修改内容

验证

运行的命令/测试/手动检查
使用的原生或模拟模式

剩余风险

未解决的问题、后续测试或假设