WebMCP Nexus
面向 WebMCP 标准的零侵入前端集成方案。
让任何 React 应用在数分钟内成为 MCP 客户端可直接驱动的对象。
简体中文 | English
Power your agent
पब्लिशर का इंस्टॉल। PlugMCP एंडपॉइंट नहीं।
Host a copy with our keys and logs.
रजिस्ट्री में अभी कोई पैकेज्ड रिलीज़ नहीं है। रिपॉज़िटरी का README देखें.
रिमोट 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
इस पेज पर Cursor, Claude Desktop, Claude Code या VS Code के लिए stdio कॉन्फ़िग कॉपी करें। यह पब्लिशर का इंस्टॉल इस्तेमाल करता है, PlugMCP प्रॉक्सी नहीं।
इस रिकॉर्ड में कोई ज़रूरी एनवायरनमेंट वेरिएबल दर्ज नहीं है।
Webmcp Nexus stdio पर लोकल चलता है।
पिछली जाँच 2026-11-05 को हुई। 面向 WebMCP 标准的非侵入式前端集成套件:写一个普通 TS 函数加一段 JSDoc,即可被任意 MCP 客户端调用 —— 含 SDK、Vite/Webpack 插件与 AI 编码 Skill。