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 中使用

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

1. 全局安装包：

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

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

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

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

1. 构建项目：

npm run build

2. 使用绝对路径配置：

{
  "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" 错误：

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

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

2. 测试 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

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

   node --version

4. 清理缓存并重新安装：

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

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

常见问题：

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

3. 重启 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