WebMCP Nexus

What It Does

WebMCP Nexus is a frontend integration kit from Alibaba that turns ordinary TypeScript functions into MCP tools, callable by any MCP client. It targets React developers who want their web applications to be drivable by AI agents without writing server-side MCP server code. The toolkit includes a runtime SDK (two APIs: registerGlobalTools and useWebMcpTools), build plugins for Vite and Webpack that infer JSON Schema from TypeScript types at compile time via ts-morph, a polyfill for browsers without native WebMCP support, and a 681-line SKILL.md that teaches AI coding agents how to write compliant tool functions and safely refactor existing ones.

The Good

Build-time type inference eliminates schema boilerplate. The core innovation is that the Vite and Webpack plugins use ts-morph to statically analyze TypeScript function signatures and JSDoc comments, then inject a __webmcpSchema field at build time. Developers never write JSON Schema by hand. The schema stays in sync with the TypeScript types automatically. This is the "single source of truth" pattern done correctly: the TypeScript interface IS the schema.

Two-API surface is minimal. The SDK exposes exactly two functions: registerGlobalTools() for app-wide tools and useWebMcpTools() for component/route-scoped tools. That covers global, route, and component lifecycles with automatic deregistration on unmount. The three-tier scoping (global, route, component) with collision-aware ownership tracking prevents ghost tools from lingering in the agent's context.

The SKILL.md is one of the most thorough agent skill docs reviewed. At 681 lines, it covers function signature constraints (MUST/SHOULD/MAY severity levels), a zero-risk refactor workflow for existing functions (with a "red line" that forbids touching business logic), 5 concrete refactoring scenarios with before/after code, a self-check table, and an FAQ section. The refactoring guidance is particularly notable: it explicitly forbids agents from "optimizing" code during refactoring, with a table of specific anti-patterns like "don't swap fetch for axios" and "don't add try/catch where there wasn't one."

Test coverage is solid for a young project. The repo contains 11 test files totaling 1,975 lines across the 4 packages. All 119 tests pass: 57 in webmcp-core (type extraction, schema generation, transform), 48 in webmcp-sdk (registration, hooks, polyfill, registry), and 14 in the webpack plugin. The Vite plugin has no tests, which is a gap. Tests use realistic scenarios including HMR, scope collision, and polyfill fallback.

Non-invasive design philosophy. Functions remain ordinary TypeScript. No decorators, no wrapper functions, no explicit schema config. Existing call sites are untouched when using the object-literal registration pattern. The polyfill loads lazily and only when the native API is unavailable. The SDK is a no-op in SSR environments.

The Bad

Depends on an unfinished W3C standard. The entire toolkit is built on top of WebMCP (navigator.modelContext.registerTool()), which is a W3C browser standard proposal still progressing through the standards process. If the spec changes significantly or stalls, this toolkit could need substantial rework. The README acknowledges this with an "early access" status badge. The polyfill mitigates the risk somewhat, but a standards-level pivot would break the core API contract.

The SKILL.md is entirely in Chinese. While the README and per-package docs are bilingual (Chinese and English), the 681-line SKILL.md is written entirely in Chinese. This limits accessibility for non-Chinese-speaking developers and for AI agents whose training data is primarily English. Given that the skill targets international AI coding agents (Claude Code, Cursor, Codex), an English version would significantly broaden adoption.

No tests for the Vite plugin. The vite-plugin-webmcp package has zero test files, while its webpack counterpart has 14 tests covering the loader and plugin. Since Vite is the more popular build tool for new React projects, this is a meaningful gap. The plugin source is only 101 lines, but the lack of automated verification means regressions could slip through.

Requires React for component-level tools. The useWebMcpTools hook is React-specific. While global registration (registerGlobalTools) is framework-agnostic, the component/route scoping depends on React's lifecycle. Vue, Svelte, and Solid developers get only the global tier. The README does not mention this limitation explicitly.

The pnpm workspace dependency on esbuild requires approval. Running pnpm install produces [ERR_PNPM_IGNORED_BUILDS] and requires pnpm approve-builds esbuild before tests or builds can run. This is a minor friction point for first-time contributors, though it only affects development, not end users installing from npm.

Smoke Test Results

All testing was performed on macOS (host) with Node.js v24.13.1 and pnpm installed via npm.

Run A. Clone and build from source

$ cd /tmp && git clone --depth 1 https://github.com/alibaba/webmcp-nexus.git
Cloning into 'webmcp-nexus'... ✅

$ pnpm install
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.27.7 ✅ (resolved with approve-builds)

$ pnpm approve-builds esbuild
.../esbuild@0.27.7 postinstall: Done ✅

$ pnpm build
packages/webmcp-core build: Done ✅
packages/webmcp-sdk build: Done ✅
packages/vite-plugin-webmcp build: Done ✅
packages/webpack-plugin-webmcp build: Done ✅
apps/demo build: ✓ built in 2.91s ✅

Pass rate: 6 of 6. All packages and the demo app build successfully.

Run B. Test suite

$ cd packages/webmcp-core && npx vitest run
Test Files 5 passed (5), Tests 57 passed (57) ✅

$ cd packages/webmcp-sdk && npx vitest run
Test Files 4 passed (4), Tests 48 passed (48) ✅

$ cd packages/webpack-plugin-webmcp && npx vitest run
Test Files 2 passed (2), Tests 14 passed (14) ✅

$ cd packages/vite-plugin-webmcp && npx vitest run
No test files found, exiting with code 1 ❌

Pass rate: 3 of 4 package test suites. Total: 119 tests passing. The Vite plugin has no tests.

Run C: npm install verification

$ mkdir /tmp/webmcp-test && npm init -y && npm install webmcp-nexus-sdk
added 6 packages, audited 7 packages in 2s
found 0 vulnerabilities ✅

$ ls node_modules/webmcp-nexus-sdk/dist/
index.cjs index.cjs.map index.d.cts index.d.ts index.js index.js.map ✅

Pass rate: 2 of 2. SDK installs cleanly with CJS and ESM entry points and type declarations.

What the runs tell you

The monorepo builds cleanly, 119 tests pass across the three tested packages, and the published npm package installs with zero vulnerabilities. The only gap is the untested Vite plugin. Functional verification is limited because the core value (registering tools that MCP clients can call) requires a browser environment with WebMCP support or the polyfill, plus an MCP client to drive the tools.

Setup Walkthrough

1. Install the SDK: pnpm add webmcp-nexus-sdk (or npm install webmcp-nexus-sdk).
2. Install the build plugin: pnpm add -D vite-plugin-webmcp-nexus for Vite projects, or pnpm add -D webpack-plugin-webmcp-nexus for Webpack projects.
3. Configure the plugin in your build config. For Vite: add vitePluginWebMcp() to the plugins array. For Webpack: add new WebMcpPlugin() to the plugins array.
4. Write a TypeScript function with a single object parameter and JSDoc comments. The build plugin infers the schema.
5. Register the function: call registerGlobalTools({ myFunction }) in your app entry point, or useWebMcpTools({ myFunction }) inside a React component.
6. For desktop agent integration, add the @mcp-b/webmcp-local-relay embed script to your HTML and configure the relay in your MCP client's config.

Post-install gotcha: the WebMCP standard is still in progress. Browsers without native support need the polyfill, which the SDK loads lazily. Chrome 146+ has native support. Other browsers rely on the polyfill.

Alternatives

1. @anthropics/frontend-design - Anthropic's Smithery skill for generating frontend UI. Focuses on generating code, not bridging running apps to MCP. Different use case (code generation vs. runtime tool exposure).
2. browserbase/skills - Browser automation skills that control the browser from outside. WebMCP Nexus is the inverse: the browser exposes its own capabilities to agents from inside.
3. Direct MCP server implementation - Building a standalone MCP server that exposes your API endpoints. More control but requires server infrastructure. WebMCP Nexus avoids the server entirely by using the browser as the MCP host.