webmcp-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WebMCP Gen

WebMCP 生成工具

Author website-specific WebMCP tools by writing a manifest, compiling it to an init script, and validating that Chrome registers and invokes the tools.

This skill does not call a nested agent. You are responsible for exploring the page, writing

manifest.json

, and iterating based on validation output.

通过编写清单文件、将其编译为初始化脚本，并验证Chrome是否能注册和调用这些工具，来编写特定网站的WebMCP工具。

该技能不会调用嵌套Agent。你需要负责探索页面、编写

manifest.json

，并根据验证输出进行迭代优化。

Setup check

环境检查

From the skill directory, install dependencies if they are not already installed:

bash

cd skills/webmcp-gen
pnpm install

This installs the pinned Stagehand package plus the TypeScript toolchain (

tsx

typescript

@types/node

) used to run the generated

stagehand-example.ts

如果尚未安装依赖项，请从技能目录执行以下命令进行安装：

bash

cd skills/webmcp-gen
pnpm install

此命令会安装指定版本的Stagehand包，以及运行生成的

stagehand-example.ts

所需的TypeScript工具链（

tsx

、

typescript

、

@types/node

）。

Workflow

工作流程

Pick an artifact slug with exactly one slash:

text

<domain>/<task>

Example:

text

example.com/page-context

Scaffold the artifact:

bash

node scripts/scaffold.mjs example.com/page-context --url https://example.com

Explore the target page with the
```
browse
```
CLI:

bash

browse open https://example.com --local
browse snapshot
browse get title
browse get url
browse get text body
browse get html body

Prefer

browse snapshot

, page text, and DOM inspection over screenshots unless visual layout matters. Use

browse stop

when exploration is complete.

Edit
```
artifacts/<domain>/<task>/manifest.json
```
. The manifest is the source of truth.
Compile:

bash

node scripts/compile.mjs artifacts/example.com/page-context

Generate a runnable Stagehand example (
```
stagehand-example.ts
```
) and run it with
```
tsx
```
:

bash

node scripts/generate-stagehand-example.mjs artifacts/example.com/page-context
npx tsx artifacts/example.com/page-context/stagehand-example.ts

Validate:

bash

node scripts/validate.mjs artifacts/example.com/page-context

If validation fails, inspect
```
eval.json
```
and
```
eval-report.md
```
, patch
```
manifest.json
```
, then compile and validate again.

选择一个包含且仅包含一个斜杠的产物标识：

text

<domain>/<task>

示例：

text

example.com/page-context

生成产物脚手架：

bash

node scripts/scaffold.mjs example.com/page-context --url https://example.com

使用
```
browse
```
命令行工具探索目标页面：

bash

browse open https://example.com --local
browse snapshot
browse get title
browse get url
browse get text body
browse get html body

除非视觉布局很重要，否则优先使用

browse snapshot

、页面文本和DOM检查，而非截图。探索完成后使用

browse stop

命令结束。

编辑
```
artifacts/<domain>/<task>/manifest.json
```
。该清单文件是核心数据源。
编译：

bash

node scripts/compile.mjs artifacts/example.com/page-context

生成可运行的Stagehand示例文件（
```
stagehand-example.ts
```
），并使用
```
tsx
```
运行：

bash

node scripts/generate-stagehand-example.mjs artifacts/example.com/page-context
npx tsx artifacts/example.com/page-context/stagehand-example.ts

验证：

bash

node scripts/validate.mjs artifacts/example.com/page-context

如果验证失败，请检查
```
eval.json
```
和
```
eval-report.md
```
，修改
```
manifest.json
```
后重新编译并验证。

Manifest contract

清单文件规范

json

{
  "domain": "example.com",
  "task": "page-context",
  "url": "https://example.com",
  "generatedAt": "2026-06-04T00:00:00.000Z",
  "tools": [
    {
      "name": "example_com_page_context",
      "description": "Returns page context.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      },
      "implementation": {
        "kind": "dom",
        "source": "return { success: true, title: document.title, url: location.href };"
      },
      "fixtureInput": {}
    }
  ]
}

json

{
  "domain": "example.com",
  "task": "page-context",
  "url": "https://example.com",
  "generatedAt": "2026-06-04T00:00:00.000Z",
  "tools": [
    {
      "name": "example_com_page_context",
      "description": "Returns page context.",
      "inputSchema": {
        "type": "object",
        "properties": {},
        "required": []
      },
      "implementation": {
        "kind": "dom",
        "source": "return { success: true, title: document.title, url: location.href };"
      },
      "fixtureInput": {}
    }
  ]
}

Authoring rules

编写规则

```
implementation.source
```
is inserted inside
```
async (input) => { ... }
```
; write JavaScript statements, not a full function wrapper.
Return a JSON-serializable object.
WebMCP code runs inside the browser page. Use browser-native APIs:
```
document
```
,
```
location
```
,
```
navigator
```
, and same-origin
```
fetch
```
.
Do not use Playwright, Puppeteer, Stagehand, XPath helpers, or agent/browser commands inside
```
implementation.source
```
.
```
document.querySelector
```
and
```
querySelectorAll
```
must receive valid browser CSS selectors only.

To find visible text, use

Array.from(document.querySelectorAll(...)).find((el) => (el.textContent || "").includes("..."))

Do not include API keys, bearer tokens, cookies, localStorage secrets, or user credentials.
Do not use
```
eval
```
or
```
new Function
```
.
Avoid destructive actions unless the user explicitly asked for them.
Make implementations defensive: check for missing elements and return structured
```
{ success: false, error: "..." }
```
responses.
Generated init scripts register WebMCP tools only in the top frame.

```
implementation.source
```
的内容会被插入到
```
async (input) => { ... }
```
内部；只需编写JavaScript语句，无需完整的函数包装。
返回一个可JSON序列化的对象。
WebMCP代码在浏览器页面内运行。请使用浏览器原生API：
```
document
```
、
```
location
```
、
```
navigator
```
以及同源
```
fetch
```
。
请勿在
```
implementation.source
```
中使用Playwright、Puppeteer、Stagehand、XPath辅助工具或Agent/浏览器命令。
```
document.querySelector
```
和
```
querySelectorAll
```
必须仅接收有效的浏览器CSS选择器。

如需查找可见文本，请使用

Array.from(document.querySelectorAll(...)).find((el) => (el.textContent || "").includes("..."))

。

请勿包含API密钥、Bearer令牌、Cookie、localStorage机密或用户凭证。
请勿使用
```
eval
```
或
```
new Function
```
。
除非用户明确要求，否则避免执行破坏性操作。
实现需具备防御性：检查缺失元素，并返回结构化的
```
{ success: false, error: "..." }
```
响应。
生成的初始化脚本仅在顶层框架中注册WebMCP工具。

Output layout

输出目录结构

text

artifacts/<domain>/<task>/
  manifest.json
  webmcp.init.js
  stagehand-example.ts
  eval.json
  eval-report.md

To turn the example into a standalone project, scaffold a Stagehand app with

npx create-browser-app

and drop the generated

webmcp.init.js

into it (load it with

page.addInitScript({ path: "webmcp.init.js" })

text

artifacts/<domain>/<task>/
  manifest.json
  webmcp.init.js
  stagehand-example.ts
  eval.json
  eval-report.md

如需将示例转换为独立项目，请使用

npx create-browser-app

生成Stagehand应用脚手架，然后将生成的

webmcp.init.js

放入其中（通过

page.addInitScript({ path: "webmcp.init.js" })

加载）。