@opentiny/tiny-vue-mcp 0.0.5 → 0.0.6-alpha.2

package/dist/src/utils/defineTool.js

@@ -1,7 +1,44 @@
-const o = ({ componentMcpConfig: e, instance: a, server: s, business: t }) => {
-  const r = `${t.id}_${e.name}`, c = `${t.description}-${e.description}`, i = e.paramsSchema || {}, d = (m) => e.cb(a, m);
-  s.registerTool(r, { title: r, description: c, inputSchema: i }, d);
+import { z as f } from "zod";
+import { zodToJsonSchema as g } from "zod-to-json-schema";
+import { initializeBuiltinWebMCP as y } from "@opentiny/next-sdk/core";
+const h = /* @__PURE__ */ new WeakSet(), S = () => {
+  if (typeof document > "u") return;
+  const t = document;
+  if (!h.has(document)) {
+    if (y(), !t.modelContext)
+      throw new Error("[TinyVue WebMCP] Failed to initialize document.modelContext");
+    h.add(document);
+  }
+  return t.modelContext;
+}, w = ({ componentMcpConfig: t, instance: b, server: i, business: s }) => {
+  const o = `${s.id}_${t.name}`, c = `${s.description}-${t.description}`, n = t.paramsSchema || {}, a = (e) => t.cb(b, e);
+  if (i) {
+    const e = i.registerTool(o, { title: o, description: c, inputSchema: n }, a);
+    return () => e.remove();
+  }
+  const m = S();
+  if (!m) return;
+  const l = Object.keys(n).length > 0, d = f.object(n).strict(), u = l ? d.refine((e) => Object.keys(e).length > 0, {
+    message: "At least one component operation is required"
+  }) : d, r = new AbortController(), p = m.registerTool(
+    {
+      name: o,
+      title: o,
+      description: c,
+      // WebMCP 接收 JSON Schema，而非 MCP Server 接收的 Zod shape。
+      inputSchema: {
+        ...g(u, { $refStrategy: "none" }),
+        ...l ? { minProperties: 1 } : {}
+      },
+      execute: async (e) => a(await u.parseAsync(e))
+    },
+    { signal: r.signal }
+  );
+  return Promise.resolve(p).catch((e) => {
+    r.signal.aborted || console.error(`[TinyVue WebMCP] Failed to register ${o}`, e);
+  }), () => r.abort();
 };
 export {
-  o as defineTool
+  w as defineTool,
+  S as ensureWebMcp
 };

package/index.ts

@@ -1,4 +1,4 @@
-import { defineTool } from './src/utils/defineTool'
+import { defineTool, ensureWebMcp } from './src/utils/defineTool'
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import type { Business, ComponentMcpConfig } from './src/utils/defineTool'
 import zhCN from './src/lang/zh-CN'
@@ -148,13 +148,19 @@ import { getWizardConfig } from './src/wizard'
 
 export const createMcpTools = (
   instance: any,
-  { server, business }: { server: McpServer; business: Business },
+  { server, business }: { server?: McpServer; business: Business },
   componentMcpConfig: ComponentMcpConfig
 ) => {
-  defineTool({ business, componentMcpConfig, instance, server })
+  return defineTool({ business, componentMcpConfig, instance, server })
 }
 
 export const getTinyVueMcpConfig = ({ t }: { t?: ((path: string) => string) | null } = {}) => {
+  try {
+    ensureWebMcp()
+  } catch {
+    // 配置也用于不依赖浏览器 WebMCP 的显式 Server 模式。
+    // 未传 server 时，工具注册会重试初始化并报告失败。
+  }
   if (i18n && t) {
     i18n.t = t
   }

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@opentiny/tiny-vue-mcp",
-  "version": "0.0.5",
+  "version": "0.0.6-alpha.2",
   "description": "",
   "author": "",
   "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opentiny/tiny-vue-mcp.git",
+    "directory": "packages/mcp"
+  },
   "keywords": [],
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -11,14 +16,18 @@
     "access": "public"
   },
   "dependencies": {
+    "@opentiny/next-sdk": "0.4.11",
     "zod": "^3.25.23",
+    "zod-to-json-schema": "^3.25.2",
     "@modelcontextprotocol/sdk": "1.23.0"
   },
   "devDependencies": {
+    "vitest": "^3.2.7",
     "vite": "^6.3.1",
     "vite-plugin-dts": "^4.5.4"
   },
   "scripts": {
-    "build": "vite build"
+    "build": "vite build",
+    "test": "vitest run"
   }
 }

package/src/utils/__tests__/webmcp.test.ts

@@ -0,0 +1,153 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import { initializeBuiltinWebMCP } from '@opentiny/next-sdk/core'
+import { defineTool } from '../defineTool'
+import { createMcpTools, getTinyVueMcpConfig } from '../../../index'
+
+vi.mock('@opentiny/next-sdk/core', () => ({ initializeBuiltinWebMCP: vi.fn() }))
+beforeEach(() => {
+  vi.mocked(initializeBuiltinWebMCP).mockReset()
+})
+afterEach(() => vi.unstubAllGlobals())
+
+const business = { id: 'test-grid', description: 'Test grid' }
+const makeConfig = () => ({
+  name: 'grid_component_tools',
+  description: 'Grid operations',
+  paramsSchema: { getTableData: z.boolean().optional() },
+  cb: vi.fn(async () => ({ content: [{ type: 'text', text: 'rows' }] }))
+})
+
+describe('WebMCP component tool adapter', () => {
+  it('registers a descriptor with JSON Schema and awaits validated execution', async () => {
+    const registerTool = vi.fn()
+    vi.stubGlobal('document', { modelContext: { registerTool } })
+    const componentMcpConfig = makeConfig()
+    const instance = { rows: [] }
+    const dispose = defineTool({ instance, business, componentMcpConfig })
+    const [tool, options] = registerTool.mock.calls[0]
+
+    expect(tool.name).toBe('test-grid_grid_component_tools')
+    expect(tool.inputSchema).toMatchObject({
+      type: 'object',
+      properties: { getTableData: { type: 'boolean' } },
+      additionalProperties: false,
+      minProperties: 1
+    })
+    expect(await tool.execute({ getTableData: true })).toEqual({ content: [{ type: 'text', text: 'rows' }] })
+    expect(componentMcpConfig.cb).toHaveBeenCalledWith(instance, { getTableData: true })
+    dispose?.()
+    expect(options.signal.aborted).toBe(true)
+  })
+
+  it('rejects unknown operations, invalid types and empty arguments before invoking the component', async () => {
+    const registerTool = vi.fn()
+    vi.stubGlobal('document', { modelContext: { registerTool } })
+    const componentMcpConfig = makeConfig()
+    defineTool({ instance: {}, business, componentMcpConfig })
+    const [tool] = registerTool.mock.calls[0]
+    await expect(tool.execute({ missing: true })).rejects.toThrow()
+    await expect(tool.execute({ getTableData: 'true' })).rejects.toThrow()
+    await expect(tool.execute({})).rejects.toThrow()
+    expect(componentMcpConfig.cb).not.toHaveBeenCalled()
+  })
+
+  it.each([undefined, {}])(
+    'allows empty arguments for parameterless tools with paramsSchema %j',
+    async (paramsSchema) => {
+      const registerTool = vi.fn()
+      vi.stubGlobal('document', { modelContext: { registerTool } })
+      const componentMcpConfig = { ...makeConfig(), paramsSchema }
+      const instance = {}
+      defineTool({ instance, business, componentMcpConfig })
+      const [tool] = registerTool.mock.calls[0]
+
+      expect(tool.inputSchema).not.toHaveProperty('minProperties')
+      expect(tool.inputSchema).toMatchObject({ type: 'object', properties: {}, additionalProperties: false })
+      expect(await tool.execute({})).toEqual({ content: [{ type: 'text', text: 'rows' }] })
+      expect(componentMcpConfig.cb).toHaveBeenCalledWith(instance, {})
+      await expect(tool.execute({ unexpected: true })).rejects.toThrow()
+      expect(componentMcpConfig.cb).toHaveBeenCalledOnce()
+    }
+  )
+
+  it('does not initialize browser APIs during SSR', () => {
+    vi.stubGlobal('document', undefined)
+    expect(defineTool({ instance: {}, business, componentMcpConfig: makeConfig() })).toBeUndefined()
+    expect(initializeBuiltinWebMCP).not.toHaveBeenCalled()
+  })
+
+  it('injects the Polyfill before registration and only initializes once per document', () => {
+    const registerTool = vi.fn()
+    const browserDocument = { modelContext: undefined as unknown }
+    vi.stubGlobal('document', browserDocument)
+    vi.mocked(initializeBuiltinWebMCP).mockImplementation(() => {
+      browserDocument.modelContext = { registerTool }
+    })
+    expect(getTinyVueMcpConfig().components.Grid).toBeDefined()
+    defineTool({ instance: {}, business, componentMcpConfig: makeConfig() })
+    defineTool({ instance: {}, business: { ...business, id: 'second-grid' }, componentMcpConfig: makeConfig() })
+    expect(initializeBuiltinWebMCP).toHaveBeenCalledOnce()
+    expect(registerTool).toHaveBeenCalledTimes(2)
+    expect(vi.mocked(initializeBuiltinWebMCP).mock.invocationCallOrder[0]).toBeLessThan(
+      registerTool.mock.invocationCallOrder[0]
+    )
+  })
+
+  it('reports initialization failure and allows a later retry', () => {
+    const browserDocument = { modelContext: undefined as unknown }
+    vi.stubGlobal('document', browserDocument)
+    expect(() => defineTool({ instance: {}, business, componentMcpConfig: makeConfig() })).toThrow(
+      'Failed to initialize'
+    )
+    vi.mocked(initializeBuiltinWebMCP).mockImplementation(() => {
+      browserDocument.modelContext = { registerTool: vi.fn() }
+    })
+    expect(() => defineTool({ instance: {}, business, componentMcpConfig: makeConfig() })).not.toThrow()
+    expect(initializeBuiltinWebMCP).toHaveBeenCalledTimes(2)
+  })
+
+  it.each(['missing-context', 'throws'])('keeps explicit-server setup working when initialization %s', (failure) => {
+    vi.stubGlobal('document', {})
+    if (failure === 'throws') {
+      vi.mocked(initializeBuiltinWebMCP).mockImplementation(() => {
+        throw new Error('Polyfill unavailable')
+      })
+    }
+    const config = getTinyVueMcpConfig()
+    const remove = vi.fn()
+    const registerTool = vi.fn(() => ({ remove }))
+    const server = { registerTool } as unknown as NonNullable<Parameters<typeof defineTool>[0]['server']>
+    const dispose = createMcpTools({}, { business, server }, config.components.Grid)
+
+    expect(registerTool).toHaveBeenCalledWith(
+      'test-grid_grid_component_tools',
+      expect.objectContaining({ inputSchema: config.components.Grid.paramsSchema }),
+      expect.any(Function)
+    )
+    expect(initializeBuiltinWebMCP).toHaveBeenCalledOnce()
+    dispose?.()
+    expect(remove).toHaveBeenCalledOnce()
+    // 配置获取允许回退，真正选择 WebMCP 注册时仍重试并报告初始化错误。
+    expect(() => createMcpTools({}, { business }, config.components.Grid)).toThrow(
+      failure === 'throws' ? 'Polyfill unavailable' : 'Failed to initialize'
+    )
+    expect(initializeBuiltinWebMCP).toHaveBeenCalledTimes(2)
+  })
+
+  it('preserves explicit legacy MCP Server registration and removes its tool on disposal', () => {
+    const remove = vi.fn()
+    const registerTool = vi.fn(() => ({ remove }))
+    const server = { registerTool } as unknown as NonNullable<Parameters<typeof defineTool>[0]['server']>
+    const componentMcpConfig = makeConfig()
+    const dispose = defineTool({ instance: {}, business, componentMcpConfig, server })
+    expect(registerTool).toHaveBeenCalledWith(
+      'test-grid_grid_component_tools',
+      expect.objectContaining({ inputSchema: componentMcpConfig.paramsSchema }),
+      expect.any(Function)
+    )
+    dispose?.()
+    expect(remove).toHaveBeenCalledOnce()
+    expect(initializeBuiltinWebMCP).not.toHaveBeenCalled()
+  })
+})

package/src/utils/defineTool.ts

@@ -1,41 +1,112 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-
-/** 开发人员传入的业务信息 id要保证唯一性 */
-export interface Business {
-  id: string
-  description: string
-}
-
-/** 组件所有的功能行为都集中在tool里面 */
-export interface ComponentMcpConfig {
-  name: string
-  description: string
-  paramsSchema?: Record<string, any>
-  cb: (instance: any, args: Record<string, any>) => any
-}
-
-export interface DefineToolOptions {
-  componentMcpConfig: ComponentMcpConfig
-  /** tool 可操纵的上下文的变量和方法集合 */
-  instance: any
-  server: McpServer
-  business: Business
-}
-
-/**
- * 快速定义一个业务tool的方法
- * @param componentMcpConfig 组件的可用工具集
- * @param instance 工具可操作的上下文实例, Vue中是传入实例,其它场景可能传入 {数据, 方法等}
- * @param server MCP 服务器实例
- * @param business 业务信息
- */
-export const defineTool = ({ componentMcpConfig, instance, server, business }: DefineToolOptions) => {
-  const name = `${business.id}_${componentMcpConfig.name}`
-  const description = `${business.description}-${componentMcpConfig.description}`
-  const paramsSchema = componentMcpConfig.paramsSchema || {}
-  const cb = (args: Record<string, any>) => {
-    return componentMcpConfig.cb(instance, args)
-  }
-
-  server.registerTool(name, { title: name, description, inputSchema: paramsSchema }, cb)
-}
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { zodToJsonSchema } from 'zod-to-json-schema'
+import { initializeBuiltinWebMCP } from '@opentiny/next-sdk/core'
+
+const initializedDocuments = new WeakSet<Document>()
+
+// 每个页面只初始化一次，避免后续组件注册时重置已有工具或重复安装桥接。
+// SSR 不触碰浏览器 API；初始化失败时允许下次重试。
+export const ensureWebMcp = () => {
+  if (typeof document === 'undefined') return
+  const currentDocument = document as WebMcpDocument
+  if (!initializedDocuments.has(document)) {
+    initializeBuiltinWebMCP()
+    if (!currentDocument.modelContext) {
+      throw new Error('[TinyVue WebMCP] Failed to initialize document.modelContext')
+    }
+    initializedDocuments.add(document)
+  }
+  return currentDocument.modelContext
+}
+
+/** 开发人员传入的业务信息 id要保证唯一性 */
+export interface Business {
+  id: string
+  description: string
+}
+
+/** 组件所有的功能行为都集中在tool里面 */
+export interface ComponentMcpConfig {
+  name: string
+  description: string
+  paramsSchema?: Record<string, any>
+  cb: (instance: any, args: Record<string, any>) => any
+}
+
+export interface DefineToolOptions {
+  componentMcpConfig: ComponentMcpConfig
+  /** tool 可操纵的上下文的变量和方法集合 */
+  instance: any
+  server?: McpServer
+  business: Business
+}
+
+/**
+ * 快速定义一个业务tool的方法
+ * @param componentMcpConfig 组件的可用工具集
+ * @param instance 工具可操作的上下文实例, Vue中是传入实例,其它场景可能传入 {数据, 方法等}
+ * @param server MCP 服务器实例
+ * @param business 业务信息
+ */
+export const defineTool = ({ componentMcpConfig, instance, server, business }: DefineToolOptions) => {
+  const name = `${business.id}_${componentMcpConfig.name}`
+  const description = `${business.description}-${componentMcpConfig.description}`
+  const paramsSchema = componentMcpConfig.paramsSchema || {}
+  const cb = (args: Record<string, any>) => {
+    return componentMcpConfig.cb(instance, args)
+  }
+
+  // 保留显式传入 MCP Server 的旧调用方式。
+  if (server) {
+    const tool = server.registerTool(name, { title: name, description, inputSchema: paramsSchema }, cb)
+    return () => tool.remove()
+  }
+
+  // WebMCP 注册由组件库内部完成，应用仅需提供业务信息。
+  const modelContext = ensureWebMcp()
+  if (!modelContext) return
+
+  const hasOperations = Object.keys(paramsSchema).length > 0
+  const objectSchema = z.object(paramsSchema).strict()
+  const schema = hasOperations
+    ? objectSchema.refine((args) => Object.keys(args).length > 0, {
+        message: 'At least one component operation is required'
+      })
+    : objectSchema
+  const controller = new AbortController()
+  const registration = modelContext.registerTool(
+    {
+      name,
+      title: name,
+      description,
+      // WebMCP 接收 JSON Schema，而非 MCP Server 接收的 Zod shape。
+      inputSchema: {
+        ...zodToJsonSchema(schema, { $refStrategy: 'none' }),
+        ...(hasOperations ? { minProperties: 1 } : {})
+      },
+      execute: async (args: Record<string, unknown>) => cb(await schema.parseAsync(args))
+    },
+    { signal: controller.signal }
+  )
+  // 原生/Polyfill 可以异步注册；卸载导致的主动取消不作为异常上报。
+  Promise.resolve(registration).catch((error: unknown) => {
+    if (!controller.signal.aborted) console.error(`[TinyVue WebMCP] Failed to register ${name}`, error)
+  })
+  return () => controller.abort()
+}
+
+interface WebMcpDocument extends Document {
+  modelContext?: {
+    registerTool: (
+      tool: {
+        name: string
+        title: string
+        description: string
+        inputSchema: Record<string, unknown>
+        execute: (args: Record<string, unknown>) => Promise<unknown>
+      },
+      options: { signal: AbortSignal }
+    ) => void | Promise<void>
+  }
+}

package/vite.config.ts

@@ -1,29 +1,29 @@
-import { defineConfig } from 'vite'
-import dts from 'vite-plugin-dts'
-
-// https://vite.dev/config/
-export default defineConfig(() => {
-  return {
-    plugins: [
-      // 生成类型声明文件
-      dts()
-    ],
-    // 库模式配置
-    build: {
-      lib: {
-        entry: './index.ts'
-      },
-      rollupOptions: {
-        external: ['zod'],
-        input: ['index.ts'],
-        output: [
-          {
-            format: 'es',
-            entryFileNames: '[name].js',
-            preserveModules: true
-          }
-        ]
-      }
-    }
-  }
-})
+import { defineConfig } from 'vite'
+import dts from 'vite-plugin-dts'
+
+// https://vite.dev/config/
+export default defineConfig(() => {
+  return {
+    plugins: [
+      // 生成类型声明文件
+      dts()
+    ],
+    // 库模式配置
+    build: {
+      lib: {
+        entry: './index.ts'
+      },
+      rollupOptions: {
+        external: ['zod', 'zod-to-json-schema', '@opentiny/next-sdk/core'],
+        input: ['index.ts'],
+        output: [
+          {
+            format: 'es',
+            entryFileNames: '[name].js',
+            preserveModules: true
+          }
+        ]
+      }
+    }
+  }
+})

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/utils/__tests__/*.test.ts']
+  }
+})