@biliboyvansama/mcp-ui-client-simplified

MCP-UI Client (Simplified)

简化版的 MCP-UI 客户端 SDK，专注于 HTML 和 URL 资源渲染，移除了 RemoteDom 支持以减少包大小和复杂度。

特性

• ✅ HTML 内容渲染 (text/html)
• ✅ 外部 URL 渲染 (text/uri-list)
• ✅ Web Component 支持
• ✅ TypeScript 支持
• ✅ 浏览器兼容性优化
• ✅ 轻量化设计（相比完整版减少 3 个依赖）
• ❌ 不支持 RemoteDom 渲染

安装

npm install @biliboyvansama/mcp-ui-client-simplified

基础使用

React 组件

import { UIResourceRenderer } from '@biliboyvansama/mcp-ui-client-simplified';

function App() {
  const resource = {
    mimeType: 'text/html',
    text: '<h1>Hello World</h1>'
  };

  const handleUIAction = async (action) => {
    console.log('UI Action:', action);
  };

  return (
    <UIResourceRenderer 
      resource={resource}
      onUIAction={handleUIAction}
    />
  );
}

Web Component

<!-- 引入 Web Component 脚本 -->
<script src="./node_modules/@biliboyvansama/mcp-ui-client-simplified/dist/ui-resource-renderer.wc.js"></script>

<!-- 使用 Web Component -->
<ui-resource-renderer id="renderer"></ui-resource-renderer>

<script>
  const renderer = document.getElementById('renderer');
  
  // 设置资源
  renderer.resource = {
    mimeType: 'text/html',
    text: '<h1>Hello from Web Component</h1>'
  };
  
  // 监听 UI 动作
  renderer.addEventListener('onUIAction', (event) => {
    console.log('UI Action:', event.detail);
  });
</script>

支持的资源类型

HTML 内容 (text/html)

const htmlResource = {
  mimeType: 'text/html',
  text: '<div><h1>HTML Content</h1><p>This is rendered in an iframe.</p></div>'
};

外部 URL (text/uri-list)

const urlResource = {
  mimeType: 'text/uri-list',
  text: 'https://example.com'
};

API 参考

UIResourceRenderer Props

属性	类型	描述
resource	Partial<Resource>	要渲染的资源对象
onUIAction	(action: UIActionResult) => Promise<unknown>	UI 动作回调函数
supportedContentTypes	ResourceContentType[]	支持的内容类型过滤器
htmlProps	HTMLResourceRendererProps	HTML 渲染器的额外属性

HTMLResourceRenderer Props

属性	类型	描述
resource	Partial<Resource>	要渲染的资源对象
onUIAction	(action: UIActionResult) => Promise<unknown>	UI 动作回调函数
style	React.CSSProperties	iframe 样式
className	string	CSS 类名
proxy	string	代理服务器 URL（仅用于外部 URL）
renderOptions	RenderOptions	渲染选项

RenderOptions

属性	类型	描述
autoResize	boolean	是否自动调整 iframe 大小
sandbox	string[]	iframe 沙箱权限

构建

# 安装依赖
npm install

# 构建库
npm run build

# 构建 Web Component
npm run build:wc

# 运行测试
npm test

MCP 服务器支持

本包还提供了 Model Context Protocol (MCP) 服务器功能，允许 LLM 应用程序通过标准化协议访问 UI 渲染工具。

启动 MCP 服务器

# 开发模式（使用 tsx 直接运行 TypeScript）
npm run mcp:dev

# 生产模式（需要先构建）
npm run build
npm run mcp:start

可用的 MCP 工具

1. render-html

渲染 HTML 内容为可视化组件

参数：

• html (string, 必需): 要渲染的 HTML 内容
• title (string, 可选): 页面标题
• allowedContentTypes (string[], 可选): 允许的内容类型

2. render-url

渲染 URL 资源为可视化组件

参数：

• url (string, 必需): 要渲染的 URL 地址
• title (string, 可选): 页面标题
• allowedContentTypes (string[], 可选): 允许的内容类型

3. generate-web-component

生成独立的 Web Component

参数：

• content (object, 必需): 要转换的内容
  • type ("html" | "url"): 内容类型
  • data (string): 内容数据
• elementName (string, 可选): 自定义元素名称

浏览器兼容性

本包已针对浏览器环境进行优化，解决了 Node.js 特定 API 在浏览器中的兼容性问题：

• ✅ 移除了对 process 对象的依赖
• ✅ 提供专用的浏览器入口点
• ✅ 优化了构建配置以确保浏览器兼容性
• ✅ 支持现代浏览器的 ES 模块

在 Claude Desktop 中使用

方案一：使用本地安装（推荐）

• 全局安装包：

npm install -g @biliboyvansama/mcp-ui-client-simplified@latest

• 在 Claude Desktop 配置文件中添加服务器配置：

{
  "mcpServers": {
    "mcp-ui-renderer": {
      "command": "mcp-ui-renderer"
    }
  }
}

方案二：使用本地路径（开发推荐）

• 构建项目：

npm run build

• 使用绝对路径配置：

{
  "mcpServers": {
    "mcp-ui-renderer-local": {
      "command": "node",
      "args": ["/Users/your-username/path/to/project/dist/mcp/cli.js"]
    }
  }
}

方案三：使用 npx（可能不稳定）

{
  "mcpServers": {
    "mcp-ui-renderer-npx": {
      "command": "npx",
      "args": [
        "-y",
        "@biliboyvansama/mcp-ui-client-simplified@latest"
      ]
    }
  }
}

故障排除

如果遇到 "MCP error -32000: Connection closed" 错误：

• 检查命令路径：确保 CLI 文件存在且可执行

  # 检查全局安装
  which mcp-ui-renderer
  
  # 检查本地文件
  ls -la /path/to/your/project/dist/mcp/cli.js
  

• 测试 CLI 是否正常工作：

  # 测试全局安装
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}' | mcp-ui-renderer
  
  # 测试本地文件
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}' | node /path/to/cli.js
  

• 检查 Node.js 版本：确保使用 Node.js 18+

  node --version
  

• 清理缓存并重新安装：

  npm cache clean --force
  npm uninstall -g @biliboyvansama/mcp-ui-client-simplified
  npm install -g @biliboyvansama/mcp-ui-client-simplified@latest
  

• 检查 Claude Desktop 日志：查看 Claude Desktop 的错误日志获取更详细的错误信息

常见问题：

• npx 方式可能因为权限或缓存问题导致连接失败
• 建议优先使用全局安装或本地路径方式
• 确保路径中没有空格或特殊字符

• 重启 Claude Desktop，即可在对话中使用 UI 渲染工具。

编程方式使用 MCP 服务器

import { createServer } from '@biliboyvansama/mcp-ui-client-simplified/src/mcp/server/server.js';
import { createStdioTransport, startStdioServer } from '@biliboyvansama/mcp-ui-client-simplified/src/mcp/transport/stdio.js';

// 创建 MCP 服务器实例
const server = createServer();

// 创建标准输入输出传输层
const transport = createStdioTransport();

// 启动服务器
await startStdioServer(server, transport);

版本历史

v1.0.5 (最新)

• 🔧 修复浏览器兼容性问题
• 🔧 移除对 process 对象的依赖
• 🔧 添加专用浏览器入口点 (src/browser.ts)
• 🔧 优化 Vite 构建配置
• 📝 更新文档和示例

v1.0.4 及之前

• ✨ 基础功能实现
• ✨ MCP 服务器支持
• ✨ Web Component 支持

与完整版的区别

特性	简化版	完整版
HTML 渲染	✅	✅
URL 渲染	✅	✅
RemoteDom 渲染	❌	✅
MCP 服务器支持	✅	❌
浏览器兼容性	✅ 优化	❓ 未知
依赖数量	4 个	7 个
包大小	更小	更大
复杂度	低	高

许可证

Apache-2.0