WebMCP Nexus
面向 WebMCP 标准的零侵入前端集成方案。
让任何 React 应用在数分钟内成为 MCP 客户端可直接驱动的对象。
简体中文 | English
Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดWebMCP 是 W3C 浏览器标准提案(由 Google 与 Microsoft 联合推动),允许网页通过 document.modelContext.registerTool() 将自身能力暴露为 MCP(Model Context Protocol)客户端可调用的工具。WebMCP Nexus 是围绕该标准的一套生产可用的前端工程化方案:
registerGlobalTools / useWebMcpTools),覆盖全局、路由、组件三种生命周期。一句话:写一个普通的 TypeScript 函数,加一行 JSDoc,它就能被任意 MCP 客户端调用。
registerGlobalTools + useWebMcpTools,30 秒看懂、5 分钟接入。ts-morph 静态分析,函数签名 = JSON Schema,无运行时开销。document.modelContext(146–149 由 polyfill 做入口桥接);其他环境自动启用 @mcp-b/[email protected]。@mcp-b/webmcp-local-relay,Claude Desktop / Cursor / VS Code 等本地 MCP 客户端可直接驱动 Web 应用。webmcp-nexus/
├── apps/
│ └── demo/ # 最佳实践示例(Vite + Webpack 双构建)
├── packages/
│ ├── webmcp-core/ # 构建时核心:TS 类型抽取 + JSON Schema 生成
│ ├── webmcp-sdk/ # 运行时 SDK(2 个 API + Polyfill)
│ ├── vite-plugin-webmcp/ # Vite 插件
│ └── webpack-plugin-webmcp/ # Webpack 插件
└── skill/
└── SKILL.md # 面向 AI 编码 Agent 的接入 Skill
发布到 npm 公网 registry 的包:
前置条件:Node.js 18+,推荐 pnpm。
pnpm add webmcp-nexus-sdk
pnpm add -D vite-plugin-webmcp-nexus # 或 webpack-plugin-webmcp-nexus
Vite
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { vitePluginWebMcp } from 'vite-plugin-webmcp-nexus';
export default defineConfig({
plugins: [react(), vitePluginWebMcp({ include: ['src/**/*.ts', 'src/**/*.tsx'] })],
});
Webpack
// webpack.config.ts
import { WebMcpPlugin } from 'webpack-plugin-webmcp-nexus';
import type { Configuration } from 'webpack';
const config: Configuration = {
// ... entry / module / resolve 等常规配置
plugins: [new WebMcpPlugin({ include: ['src'] })],
};
export default config;
完整双构建示例参见 apps/demo/vite.config.ts 与 apps/demo/webpack.config.ts。
// src/tools/queries.ts
/**
* 根据关键词搜索任务。
* @readonly
*/
export async function searchTasks(params: {
/** 搜索关键词 */
query: string;
/** 返回数量上限(默认 50) */
limit?: number;
}): Promise<{ count: number; tasks: Task[] }> {
// ... 你原本的业务实现,不需要任何包装
}
// src/main.tsx
import { registerGlobalTools } from 'webmcp-nexus-sdk';
import * as queries from './tools/queries';
registerGlobalTools(queries);
构建插件会自动从 searchTasks 的 TS 类型 + JSDoc 反推出 JSON Schema,并通过 __webmcpSchema 字段注入到函数对象上;SDK 在运行时读取该字段向 document.modelContext 完成注册。
路由 / 组件级注册示例:
import { useWebMcpTools } from 'webmcp-nexus-sdk';
export default function TasksPage() {
const { createTask, updateTask, deleteTask } = useTodoStore();
useWebMcpTools({ createTask, updateTask, deleteTask });
return /* … */;
}
组件卸载时同名工具自动从 modelContext 注销,避免 Agent 在错误的页面调用错误的工具。
仓库内 apps/demo 是一个完整的 Todo / 项目管理应用,演示了所有典型集成模式:全局查询工具、组件级表单工具、路由跳转工具、HMR 调试面板等。
🌐 在线预览:https://alibaba.github.io/webmcp-nexus/ (由 GitHub Pages 自动部署,跟随
main分支更新)
pnpm install
pnpm dev # 启动 Vite demo(http://localhost:5173)
pnpm dev:webpack # 启动 Webpack demo(http://localhost:3001)
打开应用后按 ⌘ + \ 唤起内置 Debug Panel,可实时查看已注册的工具、参数 schema 与调用结果。
关键代码索引:
借助官方 @mcp-b/webmcp-local-relay,Claude Desktop、Cursor、VS Code 等本地 MCP 客户端可以直接调用浏览器中正在运行的 Web 应用——你的应用就此成为 Agent 的"双手"。
flowchart LR
A["Local MCP Client<br/>(Claude Desktop / Cursor / VS Code)"]
B["webmcp-local-relay<br/>(npx CLI on host)"]
C["Your Web App<br/>(webmcp-nexus-sdk)"]
D["Hidden Iframe<br/>(injected by embed.js)"]
A <-- "stdio · MCP / JSON-RPC" --> B
B <-- "WebSocket · ws://127.0.0.1:9333" --> D
C -- "document.modelContext.registerTool()" --> D
D -- "tool call" --> C
C -- "result" --> D
webmcp-local-relay 在本机以 stdio MCP server 形式运行,由桌面 Agent 拉起;localhost:9333 暴露一个 WebSocket 端点;embed.js,在页面注入一个隐藏 iframe,由该 iframe 与 relay 建立 WebSocket 连接,并把 document.modelContext 上注册的全部工具实时上报给桌面 Agent。前置要求:relay CLI 的
engines是 Node 22+(npx -y @mcp-b/webmcp-local-relay@latest在 Node 20 下会直接失败);页面侧需@mcp-b/webmcp-polyfill5.x(本 SDK 声明为dependencies,由你的打包器解析安装,并未内联进产物)或原生 Chrome 149+。
1. 在页面中引入 @mcp-b/webmcp-local-relay 的 embed.js
在 Web 应用的入口 HTML(如 apps/demo/index.html)追加一行:
<script src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"></script>
该脚本会注入一个隐藏的 blob iframe,读 document.modelContext,通过 getTools() 发现工具、executeTool() 调用工具(每次调用前重新拉取 descriptor,避免陈旧对象),并建立到本机 relay 的 WebSocket 通道。业务代码与 SDK 调用方式完全无需改动。
三条硬约束:
@latest,且页面侧与本机 relay server 侧必须同策略:nexus 只控制得了 embed 的版本,relay server 的版本在每个用户自己的 MCP 客户端配置里。钉任何固定版本都会让页面侧成为错配关系中唯一固定的那一端 —— @5 embed × @latest(6.0.0) server 的错配就会让全部工具执行失败。SDK 的双轴归一层(见「浏览器兼容」)吸收 embed 5.x/6.x 的入参与 schema 形态差异,但 embed 与本地 relay server 的大版本一致性由消费方保证。<script>:embed.js 靠 document.currentScript 读 data-* 属性,加 type="module" / defer / async 会让全部属性静默回落默认值。widget.html:embed.js 会 fetch 它并构造 blob iframe,fetch 失败则 relay fails closed(只有一条 console.error,工具完全不上报)。跨源托管需允许 CORS。若使用国内镜像,请镜像整个 dist/browser/ 目录而非单个文件。完整的 data-* 属性(embed.js 6.0.0):
CSP 要求:
frame-src blob:、script-src blob:(blob iframe 内联了配置 script)、connect-src ws://127.0.0.1:9333-9348。限制性 CSP 的站点会静默失败。
2. 在 MCP 客户端中安装 relay
首选:MCPB 一键安装。从 GitHub Releases 下载 .mcpb 文件双击安装,零配置、无需终端,默认就是 loopback + 自动端口发现 + 允许全部页面 origin。
次选:JSON 配置。以 Claude Desktop 为例,编辑 claude_desktop_config.json:
{
"mcpServers": {
"webmcp-local-relay": {
"command": "npx",
"args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
}
}
}
Cursor、VS Code 的 MCP 配置方式相同,差异仅在配置文件位置。也可以直接跑 CLI:npx @mcp-b/webmcp-local-relay。
3. 启动 Web 应用并在 Agent 端驱动
pnpm dev # 任何接入了 webmcp-nexus-sdk 的应用即可
重启 Claude Desktop / Cursor,新会话中即可看到来自浏览器的工具。例如对 demo 应用说:
"把所有 todo 状态的任务按截止日期升序展示,然后把第一条标记为已完成。"
Agent 会依次调用 listTasks → setTaskSort → setTaskStatus,并在浏览器中可视化地完成全部操作。
3 个静态管理工具(relay 自带,与你的工具并列):
工具名会被 relay 改写,这不是 bug:
sanitizeName 把 [^a-zA-Z0-9_] 全部替换为 _。WebMCP 协议允许工具名含 . 与 -,但 MCP 客户端看到的会是 get_canvas_info 而非 get-canvas-info。因此工具名请只用 camelCase(见 skill/SKILL.md)。_<4 位 tabId> 后缀(如 search_ed93、search_a1b2),冲突再追加 _2/_3。关掉多余的标签页即可消除后缀。排错请优先参考 relay 的 Troubleshooting 表(不在此复制,避免上游更新后两边漂移)。nexus 特有的一条:若 MCP 客户端看不到工具,先打开 demo 的 DebugPanel(Cmd/Ctrl + \)确认工具已在页面内注册,再给 embed.js 加 data-debug 看 [webmcp-relay-embed] 日志。
仓库 skill/SKILL.md 是一份为 AI 编码 Agent 量身打造的 Skill 文档,覆盖:
# 项目级(仅当前仓库生效)
mkdir -p .claude/skills
cp skill/SKILL.md .claude/skills/webmcp-nexus.md
# 用户级(所有项目生效)
mkdir -p ~/.claude/skills
cp skill/SKILL.md ~/.claude/skills/webmcp-nexus.md
mkdir -p .cursor/rules
cp skill/SKILL.md .cursor/rules/webmcp-nexus.mdc
或在 Settings → Rules 中粘贴 skill/SKILL.md 的全部内容。
将 skill/SKILL.md 作为 Rule / Context 文档导入到 IDE 的 AI 配置中即可。所有触发词均已写入 frontmatter 的 description 字段,主流 Agent 框架可自动按需加载。
"把
apps/demo/src/store/TodoStore.tsx里的createTask改造成 WebMCP 工具,注册到任务列表页。"
Agent 会按 Skill 中规定的流程,自动补齐 JSDoc、调整参数为对象形态、在对应组件挂载点调用 useWebMcpTools,且不修改任何业务逻辑。
WebMCP 草案在 2026-05-27 把 modelContext getter 从 Navigator 移到 Document(webmcp#173 / #184),Chrome 150 已废弃 navigator.modelContext。SDK 全链路 document 优先、navigator 兜底,业务代码无感。
nexus 会在原生档改写宿主对象。 为吸收 Chrome 155 的入参形态变更与 relay 6.x 的 schema 守卫,SDK 在
getTools/executeTool上装不可枚举的形态归一包装 ——Object.keys(document.modelContext)仍为[],polyfill 刻意维持的「实例无 own enumerable keys」WebIDL 保真不变量保持。已知偏差:polyfill 档的for...in不再产出这两个方法(Object.keys、spread、instanceof均不受影响)。registerTool一律不包装,arity 仍为 1。
双轴形态归一。 Chrome 155 把原生
executeTool第二参从 JSON 字符串改成对象;relay 6.x 随之改传对象,并删掉了对字符串inputSchema的容忍度 —— 字符串 schema 的工具在发现阶段就被丢弃(console.warn一条 "input schema is malformed"),Agent 侧看到零个工具,比执行失败更隐蔽。SDK 因此做两轴归一:轴一按宿主实际期望转换executeTool入参,轴二逐工具把字符串inputSchema转成对象(上游webmcp-types明文要求 "Consumers that support both generations must branch ontypeof")。效果与边界:nexus 侧对 embed 5.x/6.x 均可发现并执行工具,业务代码传对象或字符串都可以,无需感知宿主代际。其中 Chrome 155+ 与 polyfill 自持档已实测,Chrome 149–154 档基于上游类型声明推定、未在本机实证。另外 embed 与本机 relay server 的大版本一致性 nexus 控制不了(server 版本在每个用户自己的 MCP 客户端配置里),两侧请同策略跟随
@latest;relay 7.x 若引入新的形态轴,需重新核对。relay 2.x 仅可在 polyfill 自持档与 146–148 档使用,新接入不要用。
inputSchema的形态不按浏览器版本干净分档。polyfill 5.x 自持 context 时返回 JSON Schema 对象;Chrome 149–153(Origin Trial 主体人群)与 154 的 same-document 工具返回序列化字符串;webmcp#241 的对象化自 Chrome 154.0.8013 起 cross-document 先行滚动发布,Chrome 155 起 same-document 也是对象(实测 20/20),而 nexus 注册的全是 same-document 工具。上游类型因此是InputSchema | string。SDK 对 string / object / 缺键 三种形态全部兼容,一律特征检测、不做版本嗅探。
polyfill 5.x 与原生 Chrome 都会在 registerTool / getTools / executeTool 入口跑一整套准入校验(2.x 不校验)。不满足时工具会注册失败,SDK 按 error.name 给出可诊断提示:
注册失败不会阻断 UI 渲染,失败的工具也不会出现在 widget 推送里(幽灵工具防护)。
完整变更见 CHANGELOG.md。要点:
registerGlobalTools / useWebMcpTools / withWebMcpTools 的签名与行为保持不变,业务代码与构建插件配置均无需改动。navigator.modelContext 迁到 document.modelContext(SDK 内部已完成,无感)。unregisterTool 已从协议移除 → 注销统一走 registerTool(tool, { signal }) 的 AbortSignal(SDK 内部已完成)。registerTool 现为异步且失败不阻断 UI。async (params, { signal }) => {...}。现有单参工具零改动。@title <文本>、@untrusted、@consequential,与既有的 @readonly 同构。__webmcpSchema 从三字段扩为六字段。pnpm build 直接报错(而非静默产出不可注册的工具)。embed.js 跟随 @latest(见上方接入步骤),且需与本机 relay server 同策略。@mcp-b/ 其他包的关系@mcp-b/global 不可与本 SDK 同时引入。它 import 即自动初始化,用 value 描述符把 document / navigator 两个面替换为 BrowserMcpServer,会摧毁 nexus 在旧宿主档的兼容层。两者二选一。@mcp-b/webmcp-local-relay 只读 document.modelContext、只认 getTools() + executeTool()。relay 2.x 仅在 polyfill 自持 context 的浏览器(Chrome <146 / Firefox / Safari)下可用 —— 因为 installTestingShim 提供的 navigator.modelContextTesting 只在 polyfill 自持 context 时安装,原生 Chrome 下 polyfill 会提前 return。新接入请直接用 relay 5.x/6.x。relay 的「Runtime Compatibility」列了三种受支持运行时(@mcp-b/global / 「current native Chrome with object-input executeTool()」即 Chrome 155+ / @mcp-b/webmcp-polyfill),上游文档另建议「页面 runtime 与 embed 同大版本」。nexus 的 polyfill 停在 5.1.0,属该建议之外的组合,靠 SDK 的双轴形态归一层吸收差异(见「浏览器兼容」)—— 这是有意偏离,不是上游支持矩阵覆盖的范围。usewebmcp / react-webmcp / webmcp-ts-sdk 是上游的同类方案,与 nexus 定位不同:nexus 的差异化价值是构建时从 TS 类型 + JSDoc 反推 schema、三级作用域与 scope ownership registry,这三者上游都没有。nexus 不依赖它们。<form toolname tooldescription toolautosubmit toolparamdescription>、SubmitEvent.agentInvoked / respondWith())。这类工具由 polyfill 直接注册进宿主,不经 nexus 的所有权镜像,因此会出现在 document.modelContext.getTools() 与 demo 的 DebugPanel 中,但不出现在 nexus 的 widget 推送里。window 上的 toolactivated / toolcancel 事件与 CSS :tool-form-active / :tool-submit-active 伪类仅原生 Chrome 支持,polyfill 不模拟。Element.prototype.attachShadow 与 HTMLFormElement.prototype.submit。使用 shadow DOM 或自定义表单提交逻辑的项目需评估。@mcp-b/[email protected] 作为类型依赖引入(import type,不进浏览器产物),提供 Document.modelContext / Navigator.modelContext / SubmitEvent.agentInvoked 的全局声明(5.1.0 已全部改为可选)。SDK 内部维护 scope ownership registry,记录每个工具名的注册来源(scope + scopeId):
最佳实践:使用语义化的唯一工具名,不同层级避免同名冲突。
已稳定支持
string / number / boolean)'a' | 'b' | 'c' → enum)prop? → 不进入 required)不建议依赖
Record、Partial、Pick 等)ts-morph 驱动的构建时类型抽取pnpm install # 安装依赖
pnpm dev # 启动 Vite demo
pnpm dev:webpack # 启动 Webpack demo
pnpm build # 构建所有包
pnpm test # 运行全部包的测试
pnpm lint # ESLint
pnpm format # Prettier
pnpm changelog # 从 git log 生成/更新根 CHANGELOG.md
pnpm changelog:preview # 只预览不写入
VERSION=major pnpm release # 升版 + 生成 CHANGELOG + 构建 + 发布(DRY_RUN=1 可预检)
WebMCP Nexus 的核心 API(registerGlobalTools / useWebMcpTools)与构建插件已在生产应用中稳定运行。底层 WebMCP 标准本身仍在 W3C 推进中,建议同步关注上游进展:
@mcp-b/[email protected] ・ @mcp-b/[email protected]@mcp-b/[email protected]欢迎通过 Issue 与 Pull Request 参与项目:
pnpm lint && pnpm test,并保持每个 commit 聚焦单一变更。提交 PR 即视为同意以 MIT License 授权你的贡献。
面向 WebMCP 标准的非侵入式前端集成套件:写一个普通 TS 函数加一段 JSDoc,即可被任意 MCP 客户端调用 —— 含 SDK、Vite/Webpack 插件与 AI 编码 Skill。
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Webmcp Nexus ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-05 面向 WebMCP 标准的非侵入式前端集成套件:写一个普通 TS 函数加一段 JSDoc,即可被任意 MCP 客户端调用 —— 含 SDK、Vite/Webpack 插件与 AI 编码 Skill。