webmcp-gen: 从 TypeScript 生成 Chrome WebMCP 工具定义 - DEV Community

Dev.to AI 2026-06-28T09:17:05.713934

Chrome 149 发布了 WebMCP —— 一种浏览器原生 API，让网页能够通过 navigator.modelContext 向 AI 代理暴露结构化工具。相关生态系统正在迅速形成：webmcp-core 爬取在线站点以自动生成工具定义，@webmcp-registry/kit 则提供了一个基于 Zod 的 defineTool() 运行时 SDK。

目前缺少的是从现有 TypeScript 进行构建时代码生成。如果你已经为 API 定义了类型接口，就不应该重新将其写成 Zod 模式，或者等待爬虫去发现它们。

webmcp-gen 填补了这一空白。将你的 API 编写为 TypeScript 接口，运行一条命令，即可获得符合规范的 WebMCP 工具定义 + 带有内置安全最佳实践的处理程序存根。

适用场景

工具	方法	何时使用
webmcp-core	爬取在线 URL	你有站点，希望工具被自动发现
@webmcp-registry/kit	运行时的 Zod 模式	你需要运行时注册 + React 钩子
webmcp-gen	构建时的 TypeScript 接口	你有带类型的 TS，想要静态 JSON + 存根

它们是互补的——为不同工作流程提供不同层次。

快速示例

// api.ts

/** 按关键字搜索产品。 */
interface SearchProducts {
  query: string;
  category?: "electronics" | "clothing" | "home";
  limit?: number;
}

npx webmcp-gen --api api.ts

输出：一个 .webmcp.json 定义文件 + 一个 .handler.ts 存根，其中已配置好 navigator.modelContext.registerTool()，可直接实现。

功能

通过 ts-morph 解析 TypeScript 接口和类型别名
将 TS 类型映射为 JSON Schema（字符串、数字、枚举、数组、嵌套对象、可选属性）
从 JSDoc 注释中提取描述
根据 WebMCP 规范验证输出
生成带有谷歌安全建议的处理程序存根：
对修改性工具添加 requestUserInteraction() 提示
对自由格式字符串输入添加输入清理警告
对只查询工具添加 readOnlyHint 注解

默认安全

WebMCP 允许 AI 代理执行影响在线 Web 应用程序的工具。谷歌建议使用人在回路中的钩子，并防范间接提示注入。webmcp-gen 将这一点内置到每个生成的处理程序存根中——修改性工具会得到 requestUserInteraction() 提示，自由格式输入会得到清理警告。安全默认值，而非事后补救。

安装

npm install -g webmcp-gen

包含 4 个入门模板（CRUD、搜索、表单处理、数据转换），帮助你快速上手：

webmcp-gen --template crud-api
webmcp-gen --api crud-api.ts

采用 MIT 许可证。欢迎贡献。

v1.2.0 —— 安全加固版本

当前 npm 版本（v1.2.0）经过了 4 个代理的安全审计，涵盖逐行差异扫描、跨文件追踪、已移除行为分析以及专门的安全审查。在公开发布前修复了 10 个发现的问题，包括生成的代码中的注入加固、路径遍历防护以及 Chrome 150 兼容性（试验性 API 从 navigator.modelContext 迁移到了 document.modelContext）。完整的变更日志见 README。

GitHub: oliuntangled/webmcp-gen
npm: webmcp-gen

与谷歌或 W3C 无关联或背书。使用 AI 辅助构建。

查看原文