webmcp-gen

WebMCP Gen

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

此技能不会调用嵌套 Agent。你需要负责探索页面、编写 manifest.json，并根据验证输出反复调整。

设置检查

在技能目录中，如果尚未安装依赖，请安装：

cd skills/webmcp-gen
pnpm install

这会安装固定版本的 Stagehand 软件包，以及用于运行生成的 stagehand-example.ts 的 TypeScript 工具链（tsx、 typescript、@types/node）。

工作流

1. 选择一个恰好包含一个斜杠的制品 slug：

<domain>/<task>

示例：

example.com/page-context

2. 创建制品脚手架：

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

3. 使用 browse CLI 探索目标页面：

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。

4. 编辑 artifacts/<domain>/<task>/manifest.json。清单是唯一可信来源。

5. 编译：

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

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

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

7. 验证：

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

8. 如果验证失败，请检查 eval.json 和 eval-report.md，修补 manifest.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": {}
    }
  ]
}

编写规则

• 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 工具。

输出布局

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" }) 加载）。