webmcp-designer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WebMCP Designer

WebMCP设计指南

Use this skill when the project needs WebMCP design doctrine, not just ad hoc tool registration.

当项目需要遵循WebMCP设计原则，而非仅进行临时工具注册时，可使用本技能。

Layout

目录结构

```
doctrine/
```
contains the portable doctrine for designing WebMCP on an existing human-facing product.
```
stack/
```
contains the house blueprint for instrumenting a React or JavaScript SPA with
```
WebMCP/
```
directories, module-local tool wrappers, and thin execute bodies.

```
doctrine/
```
包含为面向用户的现有产品设计WebMCP的通用原则。
```
stack/
```
包含为React或JavaScript SPA进行WebMCP集成的架构蓝图，包括
```
WebMCP/
```
目录结构、模块级工具包装器以及轻量执行逻辑。

First move

初始步骤

Do not guess the runtime surface or memorize API details.

Ask whether the MCP-B docs server at
```
docs.mcp-b.ai/mcp
```
is available in the user's MCP client.
If it is available, inspect that server and use it as the source of truth for exact tool syntax and package details.
If it is not available, read the first-party docs at
```
https://docs.mcp-b.ai/
```
before making implementation claims.
Use this skill for architecture, tool shape, workflow design, and scope decisions.
Use the docs server or first-party docs for exact package names, hook signatures, polyfill choices, and annotation details.

不要猜测运行时接口或死记硬背API细节。

询问用户的MCP客户端是否可访问位于
```
docs.mcp-b.ai/mcp
```
的MCP-B文档服务器。
如果可访问，查看该服务器内容，并将其作为工具语法和包细节的权威来源。
如果不可访问，在做出实现声明前，先阅读官方文档
```
https://docs.mcp-b.ai/
```
。
使用本技能进行架构设计、工具形态定义、工作流设计和范围决策。
使用文档服务器或官方文档获取确切的包名、钩子签名、polyfill选择和注解细节。

Reading order

阅读顺序

Normal task:

Read this file first.
Decide whether the task needs only portable doctrine or the full house blueprint.
Load the smallest relevant set of doctrine files.
Treat the rest of the skill as reference material.

If the task is implementing WebMCP in a React or JavaScript SPA with this house layout, read

stack/start-here.md

before the route-specific doctrine files.

Full design pass, full review pass, or editing this skill:

Read every file in

doctrine/

in this order:

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/stage-forms-then-commit.md
```

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

doctrine/user-stories-drive-web-skills.md

If the task is a full implementation blueprint for the house stack, then read all of:

```
stack/start-here.md
```
```
stack/one-pass-instrumentation-plan.md
```
```
stack/implementation-patterns.md
```

Default backbone for most app work:

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

doctrine/user-stories-drive-web-skills.md

常规任务：

先阅读本文档。
判断任务仅需通用原则，还是完整的架构蓝图。
加载最小范围的相关原则文档。
将本技能的其余内容作为参考资料。

如果任务是基于本架构蓝图在React或JavaScript SPA中实现WebMCP，请先阅读

stack/start-here.md

，再阅读路由相关的原则文档。

完整设计、完整审核或编辑本技能：

按以下顺序阅读

doctrine/

下的所有文档：

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/stage-forms-then-commit.md
```

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

doctrine/user-stories-drive-web-skills.md

如果任务是完整实现本架构蓝图，请阅读以下所有内容：

```
stack/start-here.md
```
```
stack/one-pass-instrumentation-plan.md
```
```
stack/implementation-patterns.md
```

大多数应用工作的核心原则：

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

doctrine/user-stories-drive-web-skills.md

Task Router

任务路由

Use the smallest relevant set.

使用最小范围的相关文档。

Decide whether WebMCP is the right fit

判断WebMCP是否适配

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/design-for-agent-accessibility.md

```
doctrine/route-maps-drive-discovery.md
```

Instrument a route map or top-level navigation layer

集成路由映射或顶层导航层

```
doctrine/route-maps-drive-discovery.md
```

doctrine/user-stories-drive-web-skills.md

doctrine/tool-descriptions-are-local-contracts.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/user-stories-drive-web-skills.md

doctrine/tool-descriptions-are-local-contracts.md

Add read-only tools for data inspection

添加数据检查用只读工具

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/read-tools-live-at-data-boundaries.md

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/read-tools-live-at-data-boundaries.md

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

Add sub-navigation, tabs, or other SPA context switches

添加子导航、标签页或其他SPA上下文切换功能

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/route-maps-drive-discovery.md
```

Add forms, mutations, or other state-changing flows

添加表单、状态变更或其他修改状态的流程

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/stage-forms-then-commit.md
```

doctrine/capabilities-over-click-targets.md

```
stack/implementation-patterns.md
```

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/tool-types-have-clear-boundaries.md

```
doctrine/stage-forms-then-commit.md
```

doctrine/capabilities-over-click-targets.md

```
stack/implementation-patterns.md
```

Improve schemas, names, and descriptions

优化Schema、命名和描述

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

doctrine/first-party-docs-define-runtime-syntax.md

doctrine/capabilities-over-click-targets.md

doctrine/tool-descriptions-are-local-contracts.md

Implement the house React or JavaScript blueprint

实现React或JavaScript架构蓝图

```
stack/start-here.md
```
```
stack/implementation-patterns.md
```
```
stack/one-pass-instrumentation-plan.md
```
```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

```
stack/start-here.md
```
```
stack/implementation-patterns.md
```
```
stack/one-pass-instrumentation-plan.md
```
```
doctrine/route-maps-drive-discovery.md
```

doctrine/read-tools-live-at-data-boundaries.md

doctrine/tool-types-have-clear-boundaries.md

Author prompt-driven guidance or reusable app workflows

编写基于提示的指引或可复用应用工作流

doctrine/user-stories-drive-web-skills.md

```
doctrine/route-maps-drive-discovery.md
```

doctrine/user-stories-drive-web-skills.md

```
doctrine/route-maps-drive-discovery.md
```

One-Shot Implementation Contract

一次性实现规范

Use this when the goal is: "instrument this existing app with WebMCP in one pass."

Read this file.
Read
```
stack/one-pass-instrumentation-plan.md
```
.
Pull exact runtime syntax from the MCP-B docs server or first-party docs.
Map the app into route areas and user stories before registering feature tools.
Create the route layer first.
Add
```
WebMCP/
```
directories module by module.
Read
```
stack/implementation-patterns.md
```
before drafting wrappers.
Add read tools before navigation helpers and write tools.
Keep tool execute bodies thin and route all real logic through existing app functions.
Write web-skill workflow guidance after the tool surface exists.
Validate that the WebMCP surface mirrors the human product rather than bypassing it.

If the app is large, do not try to instrument every route at once. Start with the highest-value user story and make the pattern repeatable.

当目标是“一次性完成现有应用的WebMCP集成”时，遵循以下步骤：

阅读本文档。
阅读
```
stack/one-pass-instrumentation-plan.md
```
。
从MCP-B文档服务器或官方文档获取确切的运行时语法。
在注册功能工具前，先将应用映射为路由区域和用户故事。
先创建路由层。
按模块添加
```
WebMCP/
```
目录。
在编写包装器前，阅读
```
stack/implementation-patterns.md
```
。
先添加只读工具，再添加导航助手和写入工具。
保持工具执行逻辑轻量，所有实际逻辑都通过现有应用函数处理。
在工具接口完成后，编写Web技能工作流指引。
验证WebMCP接口是否与用户产品镜像一致，而非绕过原有产品逻辑。

如果应用规模较大，不要尝试一次性集成所有路由。从价值最高的用户故事开始，确保模式可复用。

Defaults

默认准则

Prefer WebMCP for making an existing human-facing product legible to agents.
Prefer this skill for stable concepts and first-party docs for exact syntax.
Prefer route-aware progressive disclosure over one giant tool surface.
Prefer read tools near the data boundary that already shapes the UI.
Prefer separating read, navigation, and mutation concerns even when one user story spans all three.
Prefer staging form state before committing irreversible actions.
Prefer fewer, more parameterized tools over one tool per button.
Prefer thin WebMCP wrappers over new tool-only business logic.
Prefer
```
WebMCP/
```
directories scoped by module over one global pile of tools.
Prefer descriptions that explain the tool itself, not cross-tool choreography.
Prefer user-story references that explain where to go and what to confirm, not brittle tool-name scripts.
Prefer stable primitives and small examples over large copied API snapshots that may churn.

优先使用WebMCP让面向用户的现有产品对Agent可见。
优先使用本技能获取稳定概念，优先使用官方文档获取确切语法。
优先使用路由感知的渐进式暴露，而非单一庞大的工具接口。
优先在已塑造UI的数据边界附近添加只读工具。
即使单个用户故事涵盖读、导航和变更操作，也优先分离这三类关注点。
优先在提交不可逆操作前暂存表单状态。
优先使用数量更少、参数化程度更高的工具，而非为每个按钮创建单独工具。
优先使用轻量WebMCP包装器，而非新增仅用于工具的业务逻辑。
优先使用按模块划分的
```
WebMCP/
```
目录，而非单一全局工具集合。
优先编写解释工具本身的描述，而非跨工具编排逻辑。
优先引用用户故事来说明操作路径和确认点，而非脆弱的工具名称脚本。
优先使用稳定原语和小型示例，而非可能变更的大型API快照。