vite-plugin-webmcp-nexus 0.1.9 → 0.1.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +169 -0
- package/README.md +169 -0
- package/package.json +20 -3
package/README.en.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# vite-plugin-webmcp-nexus
|
|
4
|
+
|
|
5
|
+
**The Vite plugin for WebMCP Nexus — generates JSON Schema from TypeScript types and injects it into tool functions during the Vite build.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)
|
|
8
|
+
[](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)
|
|
9
|
+
[](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE)
|
|
10
|
+
|
|
11
|
+
[简体中文](https://github.com/alibaba/webmcp-nexus/blob/main/packages/vite-plugin-webmcp/README.md) | English
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Table of Contents
|
|
18
|
+
|
|
19
|
+
- [Introduction](#introduction)
|
|
20
|
+
- [Features](#features)
|
|
21
|
+
- [Why Use It](#why-use-it)
|
|
22
|
+
- [Installation](#installation)
|
|
23
|
+
- [Usage](#usage)
|
|
24
|
+
- [Options](#options)
|
|
25
|
+
- [Ecosystem](#ecosystem)
|
|
26
|
+
- [Links](#links)
|
|
27
|
+
- [License](#license)
|
|
28
|
+
|
|
29
|
+
## Introduction
|
|
30
|
+
|
|
31
|
+
`vite-plugin-webmcp-nexus` is the **Vite build plugin** for the [WebMCP Nexus](https://github.com/alibaba/webmcp-nexus) toolchain. It hooks into Vite's `transform` lifecycle and delegates to [`webmcp-nexus-core`](https://www.npmjs.com/package/webmcp-nexus-core) to statically analyse WebMCP tool functions, infer JSON Schema from their **TypeScript types and JSDoc**, and inject that schema as a `__webmcpSchema` field on the function object.
|
|
32
|
+
|
|
33
|
+
Used together with [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk): at runtime the SDK reads that field and registers the tools with `navigator.modelContext`, so MCP clients can call them directly.
|
|
34
|
+
|
|
35
|
+
## Features
|
|
36
|
+
|
|
37
|
+
- ⚡ **First-class Vite integration** — hooks into the standard `transform` lifecycle; non-invasive and zero extra config.
|
|
38
|
+
- 🔬 **Types as schema** — function signatures + JSDoc are turned into JSON Schema; one source of truth.
|
|
39
|
+
- 🔁 **HMR-friendly** — change a function signature and the tool schema rebuilds automatically.
|
|
40
|
+
- 🛠️ **Automatic alias merging** — Vite's `resolve.alias` is picked up automatically; you can also extend it.
|
|
41
|
+
- 📂 **Flexible `include` matching** — glob patterns scope analysis to the directories you care about.
|
|
42
|
+
- 🪶 **Zero runtime overhead** — all work happens at build time.
|
|
43
|
+
|
|
44
|
+
## Why Use It
|
|
45
|
+
|
|
46
|
+
| Dimension | Common practice | vite-plugin-webmcp-nexus |
|
|
47
|
+
| ------------------ | ------------------------------------------ | ----------------------------------------------------------------------- |
|
|
48
|
+
| Schema generation | Hand-written JSON Schema | **Automatically inferred from TS types**, with editor-time feedback |
|
|
49
|
+
| Function intrusion | Decorators / wrapper functions | **Non-invasive** — functions are left untouched |
|
|
50
|
+
| Dev experience | Manual sync between types and schema | **HMR rebuilds the schema automatically** |
|
|
51
|
+
| Toolchain coupling | Tightly bound to a runtime SDK | Decoupled from [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk); only injects data into the bundle |
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# pnpm (recommended)
|
|
57
|
+
pnpm add -D vite-plugin-webmcp-nexus
|
|
58
|
+
|
|
59
|
+
# npm
|
|
60
|
+
npm install --save-dev vite-plugin-webmcp-nexus
|
|
61
|
+
|
|
62
|
+
# yarn
|
|
63
|
+
yarn add -D vite-plugin-webmcp-nexus
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
> You also need the runtime SDK:
|
|
67
|
+
>
|
|
68
|
+
> ```bash
|
|
69
|
+
> pnpm add webmcp-nexus-sdk
|
|
70
|
+
> ```
|
|
71
|
+
|
|
72
|
+
## Usage
|
|
73
|
+
|
|
74
|
+
### 1. Configure `vite.config.ts`
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { defineConfig } from 'vite';
|
|
78
|
+
import react from '@vitejs/plugin-react';
|
|
79
|
+
import { vitePluginWebMcp } from 'vite-plugin-webmcp-nexus';
|
|
80
|
+
|
|
81
|
+
export default defineConfig({
|
|
82
|
+
plugins: [
|
|
83
|
+
react(),
|
|
84
|
+
vitePluginWebMcp({
|
|
85
|
+
include: ['src/**/*.ts', 'src/**/*.tsx'],
|
|
86
|
+
}),
|
|
87
|
+
],
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. Write a plain TypeScript function
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
// src/tools/queries.ts
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* Search tasks by keyword.
|
|
98
|
+
* @readonly
|
|
99
|
+
*/
|
|
100
|
+
export async function searchTasks(params: {
|
|
101
|
+
/** Search keyword */
|
|
102
|
+
query: string;
|
|
103
|
+
/** Maximum number of results (default 50) */
|
|
104
|
+
limit?: number;
|
|
105
|
+
}): Promise<{ count: number; tasks: Task[] }> {
|
|
106
|
+
// ... your original business logic
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 3. Register via the SDK
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
// src/main.tsx
|
|
114
|
+
import { registerGlobalTools } from 'webmcp-nexus-sdk';
|
|
115
|
+
import * as queries from './tools/queries';
|
|
116
|
+
|
|
117
|
+
registerGlobalTools(queries);
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Run `pnpm dev` and the plugin infers a JSON Schema from `searchTasks`'s TS types + JSDoc and injects it as `__webmcpSchema` on the function object; the SDK reads it in the browser to complete registration.
|
|
121
|
+
|
|
122
|
+
## Options
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
interface WebMcpPluginOptions {
|
|
126
|
+
/** Glob patterns to scan. Default: ['src/**/*.ts', 'src/**/*.tsx'] */
|
|
127
|
+
include?: string[];
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Extra module path aliases (merged on top of Vite's resolve.alias).
|
|
131
|
+
* Used to resolve module specifiers like `import * as api from '@alias/xxx'`.
|
|
132
|
+
*/
|
|
133
|
+
alias?: Record<string, string>;
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Full example
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
vitePluginWebMcp({
|
|
141
|
+
include: ['src/tools/**/*.ts', 'src/pages/**/tools.ts'],
|
|
142
|
+
alias: {
|
|
143
|
+
'@tools': '/abs/path/to/src/tools',
|
|
144
|
+
},
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
> Debug mode: set `DEBUG=webmcp` to see transform logs in the console.
|
|
149
|
+
|
|
150
|
+
## Ecosystem
|
|
151
|
+
|
|
152
|
+
| Package | Purpose |
|
|
153
|
+
| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
|
154
|
+
| [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) | Runtime SDK exposing `registerGlobalTools` / `useWebMcpTools` |
|
|
155
|
+
| [`webmcp-nexus-core`](https://www.npmjs.com/package/webmcp-nexus-core) | Build-time core: TS extraction + JSON Schema generation |
|
|
156
|
+
| **`vite-plugin-webmcp-nexus`** (this package) | Vite build plugin |
|
|
157
|
+
| [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) | Webpack build plugin (if you're on Webpack) |
|
|
158
|
+
|
|
159
|
+
## Links
|
|
160
|
+
|
|
161
|
+
- 📦 **Main repo on GitHub**: [alibaba/webmcp-nexus](https://github.com/alibaba/webmcp-nexus)
|
|
162
|
+
- 📖 **Full documentation**: [README](https://github.com/alibaba/webmcp-nexus#readme)
|
|
163
|
+
- 🎯 **Demo app**: [apps/demo](https://github.com/alibaba/webmcp-nexus/tree/main/apps/demo) — full Vite example
|
|
164
|
+
- 🌐 **WebMCP standard**: [webmcp.org](https://webmcp.org)
|
|
165
|
+
- 🐛 **Issues**: [GitHub Issues](https://github.com/alibaba/webmcp-nexus/issues)
|
|
166
|
+
|
|
167
|
+
## License
|
|
168
|
+
|
|
169
|
+
[MIT](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE) © Alibaba
|
package/README.md
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# vite-plugin-webmcp-nexus
|
|
4
|
+
|
|
5
|
+
**WebMCP Nexus 的 Vite 插件 —— 在 Vite 构建过程中自动从 TypeScript 类型生成 JSON Schema 并注入到工具函数。**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)
|
|
8
|
+
[](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)
|
|
9
|
+
[](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE)
|
|
10
|
+
|
|
11
|
+
简体中文 | [English](https://github.com/alibaba/webmcp-nexus/blob/main/packages/vite-plugin-webmcp/README.en.md)
|
|
12
|
+
|
|
13
|
+
</div>
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 目录
|
|
18
|
+
|
|
19
|
+
- [简介](#简介)
|
|
20
|
+
- [核心特性](#核心特性)
|
|
21
|
+
- [优势](#优势)
|
|
22
|
+
- [安装](#安装)
|
|
23
|
+
- [使用示例](#使用示例)
|
|
24
|
+
- [配置选项](#配置选项)
|
|
25
|
+
- [生态包](#生态包)
|
|
26
|
+
- [相关链接](#相关链接)
|
|
27
|
+
- [许可证](#许可证)
|
|
28
|
+
|
|
29
|
+
## 简介
|
|
30
|
+
|
|
31
|
+
`vite-plugin-webmcp-nexus` 是 [WebMCP Nexus](https://github.com/alibaba/webmcp-nexus) 工具链的 **Vite 构建插件**。它利用 Vite 的 `transform` 钩子，调用 [`webmcp-nexus-core`](https://www.npmjs.com/package/webmcp-nexus-core) 静态分析源码中的 WebMCP 工具函数，从 **TypeScript 类型 + JSDoc** 反推 JSON Schema，并将其作为 `__webmcpSchema` 字段注入到函数对象上。
|
|
32
|
+
|
|
33
|
+
配合 [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) 使用：在运行时，SDK 会读取该字段并向 `navigator.modelContext` 完成注册，让你的工具被 MCP 客户端直接调用。
|
|
34
|
+
|
|
35
|
+
## 核心特性
|
|
36
|
+
|
|
37
|
+
- ⚡ **Vite 原生集成** —— 通过标准 `transform` 钩子接入，无侵入、无额外配置。
|
|
38
|
+
- 🔬 **类型即 Schema** —— 函数签名 + JSDoc 自动生成 JSON Schema，单一事实源。
|
|
39
|
+
- 🔁 **HMR 友好** —— 修改函数签名后，工具 schema 自动重建，开发体验流畅。
|
|
40
|
+
- 🛠️ **Alias 自动合并** —— 自动读取 Vite 的 `resolve.alias`，并允许用户额外配置。
|
|
41
|
+
- 📂 **灵活的 include 匹配** —— 支持 glob 模式，仅扫描指定目录，构建性能可控。
|
|
42
|
+
- 🪶 **零运行时开销** —— 所有工作都在构建阶段完成，运行时无任何额外成本。
|
|
43
|
+
|
|
44
|
+
## 优势
|
|
45
|
+
|
|
46
|
+
| 维度 | 业内常见做法 | vite-plugin-webmcp-nexus |
|
|
47
|
+
| ---------- | ----------------------------- | ------------------------------------------------------- |
|
|
48
|
+
| Schema 生成 | 手写 JSON Schema | **TS 类型自动反推**，编辑器即时反馈 |
|
|
49
|
+
| 函数侵入度 | 装饰器 / 包装函数 | **零侵入**——保持函数原样 |
|
|
50
|
+
| 开发体验 | 修改类型后需手动同步 schema | **HMR 自动重建** |
|
|
51
|
+
| 工具链耦合 | 通常与 SDK 强绑定 | 与 [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) 解耦，仅在产物注入数据 |
|
|
52
|
+
|
|
53
|
+
## 安装
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# pnpm（推荐）
|
|
57
|
+
pnpm add -D vite-plugin-webmcp-nexus
|
|
58
|
+
|
|
59
|
+
# npm
|
|
60
|
+
npm install --save-dev vite-plugin-webmcp-nexus
|
|
61
|
+
|
|
62
|
+
# yarn
|
|
63
|
+
yarn add -D vite-plugin-webmcp-nexus
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
> 同时需要安装运行时 SDK：
|
|
67
|
+
>
|
|
68
|
+
> ```bash
|
|
69
|
+
> pnpm add webmcp-nexus-sdk
|
|
70
|
+
> ```
|
|
71
|
+
|
|
72
|
+
## 使用示例
|
|
73
|
+
|
|
74
|
+
### 1. 配置 `vite.config.ts`
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { defineConfig } from 'vite';
|
|
78
|
+
import react from '@vitejs/plugin-react';
|
|
79
|
+
import { vitePluginWebMcp } from 'vite-plugin-webmcp-nexus';
|
|
80
|
+
|
|
81
|
+
export default defineConfig({
|
|
82
|
+
plugins: [
|
|
83
|
+
react(),
|
|
84
|
+
vitePluginWebMcp({
|
|
85
|
+
include: ['src/**/*.ts', 'src/**/*.tsx'],
|
|
86
|
+
}),
|
|
87
|
+
],
|
|
88
|
+
});
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 2. 编写一个普通的 TS 函数
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
// src/tools/queries.ts
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* 根据关键词搜索任务。
|
|
98
|
+
* @readonly
|
|
99
|
+
*/
|
|
100
|
+
export async function searchTasks(params: {
|
|
101
|
+
/** 搜索关键词 */
|
|
102
|
+
query: string;
|
|
103
|
+
/** 返回数量上限（默认 50） */
|
|
104
|
+
limit?: number;
|
|
105
|
+
}): Promise<{ count: number; tasks: Task[] }> {
|
|
106
|
+
// ... 你原本的业务实现
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 3. 注册到 SDK
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
// src/main.tsx
|
|
114
|
+
import { registerGlobalTools } from 'webmcp-nexus-sdk';
|
|
115
|
+
import * as queries from './tools/queries';
|
|
116
|
+
|
|
117
|
+
registerGlobalTools(queries);
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
启动 `pnpm dev` 后，构建插件会自动从 `searchTasks` 的 TS 类型 + JSDoc 反推 JSON Schema，并通过 `__webmcpSchema` 字段注入函数对象；SDK 在浏览器中读取该字段完成注册。
|
|
121
|
+
|
|
122
|
+
## 配置选项
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
interface WebMcpPluginOptions {
|
|
126
|
+
/** 扫描范围（glob patterns），默认 ['src/**/*.ts', 'src/**/*.tsx'] */
|
|
127
|
+
include?: string[];
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* 额外的模块路径 alias（合并到 vite 的 resolve.alias 之上）。
|
|
131
|
+
* 用于解析 `import * as api from '@alias/xxx'` 形式的模块说明符。
|
|
132
|
+
*/
|
|
133
|
+
alias?: Record<string, string>;
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### 完整示例
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
vitePluginWebMcp({
|
|
141
|
+
include: ['src/tools/**/*.ts', 'src/pages/**/tools.ts'],
|
|
142
|
+
alias: {
|
|
143
|
+
'@tools': '/abs/path/to/src/tools',
|
|
144
|
+
},
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
> 调试模式：设置环境变量 `DEBUG=webmcp` 即可在控制台查看 transform 处理日志。
|
|
149
|
+
|
|
150
|
+
## 生态包
|
|
151
|
+
|
|
152
|
+
| 包 | 用途 |
|
|
153
|
+
| ------------------------------------------------------------------------------------------ | ---------------------------------------------- |
|
|
154
|
+
| [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) | 运行时 SDK，提供 `registerGlobalTools` / `useWebMcpTools` |
|
|
155
|
+
| [`webmcp-nexus-core`](https://www.npmjs.com/package/webmcp-nexus-core) | 构建时核心：TS 类型抽取 + JSON Schema 生成 |
|
|
156
|
+
| **`vite-plugin-webmcp-nexus`** （本包） | Vite 构建插件 |
|
|
157
|
+
| [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) | Webpack 构建插件（如果你使用 Webpack） |
|
|
158
|
+
|
|
159
|
+
## 相关链接
|
|
160
|
+
|
|
161
|
+
- 📦 **GitHub 主仓库**：[alibaba/webmcp-nexus](https://github.com/alibaba/webmcp-nexus)
|
|
162
|
+
- 📖 **完整文档**：[README](https://github.com/alibaba/webmcp-nexus#readme)
|
|
163
|
+
- 🎯 **示例应用**：[apps/demo](https://github.com/alibaba/webmcp-nexus/tree/main/apps/demo) —— Vite 完整示例
|
|
164
|
+
- 🌐 **WebMCP 标准**：[webmcp.org](https://webmcp.org)
|
|
165
|
+
- 🐛 **Issues**：[GitHub Issues](https://github.com/alibaba/webmcp-nexus/issues)
|
|
166
|
+
|
|
167
|
+
## 许可证
|
|
168
|
+
|
|
169
|
+
[MIT](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE) © Alibaba
|
package/package.json
CHANGED
|
@@ -1,6 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vite-plugin-webmcp-nexus",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.11",
|
|
4
|
+
"description": "Vite plugin for WebMCP Nexus - auto-generates JSON Schema from TypeScript tool definitions at build time",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"webmcp",
|
|
8
|
+
"mcp",
|
|
9
|
+
"model-context-protocol",
|
|
10
|
+
"vite",
|
|
11
|
+
"vite-plugin",
|
|
12
|
+
"ai-tools",
|
|
13
|
+
"typescript",
|
|
14
|
+
"build-plugin"
|
|
15
|
+
],
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "https://github.com/alibaba/webmcp-nexus.git",
|
|
19
|
+
"directory": "packages/vite-plugin-webmcp"
|
|
20
|
+
},
|
|
4
21
|
"type": "module",
|
|
5
22
|
"main": "./dist/index.cjs",
|
|
6
23
|
"module": "./dist/index.js",
|
|
@@ -21,8 +38,8 @@
|
|
|
21
38
|
"dist"
|
|
22
39
|
],
|
|
23
40
|
"dependencies": {
|
|
24
|
-
"webmcp-nexus-core": "0.1.
|
|
25
|
-
"webmcp-nexus-sdk": "0.1.
|
|
41
|
+
"webmcp-nexus-core": "0.1.11",
|
|
42
|
+
"webmcp-nexus-sdk": "0.1.11"
|
|
26
43
|
},
|
|
27
44
|
"peerDependencies": {
|
|
28
45
|
"vite": "^7.0.0 || ^8.0.0"
|