AI原生Web UI工具链

Webmcp仪器🕷️

AI原生Web UI的创作工具链

WebMCP Instrumenter是一个零配置套件，可以自动解析您的React/Vue/HTML组件 生成WebMCP工具它允许任何AI代理（如GitHub Copilot、Claude CLI、Cursor）实时与您的web应用程序进行物理交互——填写表单、单击按钮，并使用LLM生成的处理程序和强大的风险分类安全地驱动UI。

📦 安装

npm install -D webmcp-instrument

或为 维特 项目（推荐）：

npm install -D webmcp-instrument-vite webmcp-instrument-engine webmcp-instrument-runtime

包裹

⚡ 快速入门

通过Vite集成（推荐）

将插件放入Vite构建中，以自动检测组件并动态生成本地代理工具：

1. 安装WebMCP仪器插件：

   复制

   npm install -D webmcp-instrument-vite webmcp-instrument-engine webmcp-instrument-runtime
   

2. 增添 vite.config.ts:

   复制

   import webmcp from 'webmcp-instrument-vite';
   
   export default defineConfig({
     plugins: [
       webmcp({ include: ['src/**/*.tsx', 'src/**/*.vue'] })
     ]
   });
   

3. 在应用程序条目中导入运行时：

   复制

   // src/main.tsx
   import 'webmcp-instrument-runtime';
   import { createRoot } from 'react-dom/client';
   

就是这样！当你奔跑时 npm run dev，您的组件将自动解析为 window.mcp 工具直接从盒子里拿出来。

手动仪表（CLI）

1. 在项目中初始化WebMCP Instrumenter：

   复制

   npx webmcp-instrument init
   

2. 仪器组件：

   复制

   npx webmcp-instrument instrument src/components/ContactForm.tsx
   

   instructor将解析组件AST，找到所有交互式表单/按钮，并使用LLM（OpenAI、GitHub Models或Ollama）生成驱动它们所需的确切JavaScript DOM处理程序。

3. 将生成的文件放入您的应用程序：

   复制

   <!-- Load the generic WebMCP runtime -->
   <script src="https://unpkg.com/webmcp-instrument-runtime"></script>
   
   <!-- Load your new auto-generated tools -->
   <script src="dist/ContactForm.mcp.js"></script>
   

🏗️ 原理

WebMCP Instrumenter分两个阶段运行： 构建时间仪器 和那个 浏览器运行时.

1.构建时引擎

当你将指令指向源文件（React .tsx，视图 .vue，或纯 .html)，发动机通过管道：

1. AST/HTML解析： 用途 ts-morph （对于React）， @vue/compiler-sfc （适用于Vue），或 htmlparser2 （对于HTML）深入了解组件的结构，提取 useState 绑定、输入、文本区域、选择和表单提交边界。
2. 方案建筑： 对相关输入进行分组（例如 <form>)成为有凝聚力的“工具候选人”。
3. 风险分类： 分析按钮标签("Delete Account" 对比 "Save")将工具自动分类为 safe, caution，或 destructive出于安全考虑，默认情况下不包括破坏性工具。
4. 混合发现和确定性哈希： 发动机启动 无头剧作家探测器 针对您的本地开发服务器，提取实时的地面真相可访问性树。它将此与AST相匹配，以三角测量高弹性、自愈的CSS选择器回退。它还严格根据语义意图计算确定性SHA-256工具哈希，确保您的工具在重构CSS布局时不会损坏。
5. 置信阈值策略： 如果提取的工具得分低于 < 0.6 匹配置信度（例如，没有ID的嵌套相同列表循环），引擎会警告开发人员并阻止自主LLM生成，以防止代理幻觉，提示 data-mcp 钩注射。
6. 异步工具缓冲： 生成的工具被严格地沙盒到异步队列中(window.mcp.__toolBuffer).这可以安全地解决任何执行竞争条件，无论Vite或Webpack如何在DOM中排序您的捆绑包脚本。
7. 输出生成： 发出本机第一代码。它将该工具注册到Chrome 146的本地 navigator.modelContext 如果可用，否则退回我们的 webmcp-instrument-runtime 注射。包括绕过DOM设置器的专用框架，如 __mcpSetValue().

2.浏览器运行时(webmcp-instrument-runtime)

轻量级浏览器脚本提供 window.mcp 全局数组，并充当AI Agent的实际通信层。当代理要求“提交联系人表单”时，运行时执行生成的 handler.

🛠️ CLI参考

webmcp-instrument init

生成一个 .webmcprc.json 项目根目录中的配置文件并自动附加 *.mcp.js 到你的 .gitignore.

webmcp-instrument instrument <file>

核心指挥部。分析文件并生成MCP集成。

关键标志：

• --llm <backend>：选择用于生成工具处理程序的AI后端。选项：
  • github-models （登录后免费 gh auth login)
  • openai （需要 OPENAI_API_KEY)
  • ollama （通过本地执行 OLLAMA_BASE_URL)
  • none （回退到静态模板匹配）
• --model <name>：覆盖默认模型（例如。， --model gpt-4o).
• --url <url>：针对Playwright Ground Truth Probe的本地开发服务器（默认值： http://localhost:3000).
• --yes：接受所有没有交互式提示的安全工具。
• --all：包括 destructive 工具（极其小心使用）。
• --dry-run：将建议输出到stdout，而不写入文件。

🚦 框架支持矩阵

🔒 安全与风险分类

指令器自动防止人工智能盲目触发破坏性行为。输出工具根据启发式方法进行分类：

• 🟢 安全： 搜索栏、导航、扩展器。汽车包含在 --yes.
• 🟡 注意： 表单提交、添加项目、保存草稿。需要用户确认或 --yes.
• 🔴 破坏性： 删除资源、重置密码、破坏性突变。默认情况下排除，除非 --all 已通过。

所有定义都可以通过提供 classifications 地图在你的 .webmcprc.json.

🔮 原生WebMCP支持和V2架构

截至2026年初，Chrome 146+已经发布了对 本机WebMCP 通过 navigator.modelContext.

WebMCP Instrumenter完全经得起未来考验，是通往这一新标准的直接桥梁。在代码生成时，我们的工具会执行 原生第一polyfill回退:

1. 如果 navigator.modelContext 如果存在（Chrome 146+已启用标志），该工具将直接注册到规范中。
2. 否则，它将退回到我们的 webmcp-instrument-runtime 脚本注入，使当今所有浏览器都能实现相同的行为。

👨‍💻 开发人员和贡献者指南

WebMCP Instrumenter是一个Turborepo单仓库。

1. npm install
2. npm run build
3. npm run test （运行Vitest核心套件和Playwright E2E套件）

由反重力团队建造。