@nvoo/mcp-ui

Nvoo MCP 客户端 UI 与桥接层 —— 消费侧对话面板 + 开发者控制台 + 测试 API。

定位

• 框架无关（vanilla DOM，不依赖 Vue/React）
• 客户端 Bridge：与 BFF 通信、收集 Tool/State、派发 Action
• 消费侧 UI：浮动按钮 + 对话面板
• 开发者控制台：Tools/State/Action Trace 可视化
• 测试 API：programmatic mock LLM 响应

安装

pnpm add @nvoo/mcp-ui

子入口

| 入口 | 说明 | |------|------| | @nvoo/mcp-ui | 全部聚合 | | @nvoo/mcp-ui/bridge | 客户端 Bridge | | @nvoo/mcp-ui/consumer | 消费侧对话面板 | | @nvoo/mcp-ui/dev-console | 开发者控制台 | | @nvoo/mcp-ui/test | programmatic 测试 API |

快速上手

挂载消费侧 UI

import { mountMcpWidget } from '@nvoo/mcp-ui/consumer'

mountMcpWidget({
  endpoint: '/api/mcp',
  getToken: () => localStorage.getItem('token'),
  getState: () => ({ cart: store.cart }),
  getRoute: () => router.currentRoute.value.path,
  getUser: () => ({ id: 'u1', displayName: 'Alice' }),
  locale: 'zh-CN'
})

启用开发者控制台

import { autoOpenDevConsole } from '@nvoo/mcp-ui/dev-console'

// URL 加 `?__mcp_dev=1` 自动打开
autoOpenDevConsole()

或代码中调用：

import { openMcpDevConsole } from '@nvoo/mcp-ui/dev-console'
openMcpDevConsole()

programmatic 测试

import { mcpTester } from '@nvoo/mcp-ui/test'

const result = await mcpTester(tools)
  .given({ cart: [{ sku: 'x', qty: 1 }] })
  .when('user wants to checkout')
  .mockLlmResponse({
    text: 'OK',
    toolCalls: [{ name: 'app.placeOrder', args: { addressId: 'a1' } }]
  })
  .run()

expect(result.actions[0].name).toBe('app.placeOrder')
expect(result.toolResults[0].result).toEqual({ orderId: 'o123' })

直接用 Bridge（自定义 UI）

import { Bridge } from '@nvoo/mcp-ui/bridge'

const bridge = new Bridge({
  endpoint: '/api/mcp',
  sessionId: 's1',
  getState: () => ({ ... }),
  getToken: async () => '...'
})

const result = await bridge.sendTurn({ message: '下单' })
console.log(result.text, result.actions, result.toolResults)

风险操作确认

riskLevel: 'high' 的 Tool 会触发 confirm 流程（默认 window.confirm）：

const bridge = new Bridge({
  endpoint: '/api/mcp',
  sessionId: 's1',
  confirm: async (prompt) => {
    // 自定义 UI 弹窗
    return await myModal.open({ title: '请确认', content: prompt })
  }
})

依赖

• @nvoo/mcp-core —— 协议类型与 Registry
• 浏览器原生 fetch + ReadableStream
• 无框架依赖

许可

MIT