当前位置： 首页 > news >正文

MCP-UI平台适配器详解：让AI应用在ChatGPT、Goose等平台无缝运行

news 2026/5/12 19:49:41

MCP-UI平台适配器详解：让AI应用在ChatGPT、Goose等平台无缝运行

【免费下载链接】mcp-uiUI over MCP. Bring rich AI experiences to the agents!项目地址: https://gitcode.com/gh_mirrors/mcp/mcp-ui

MCP-UI平台适配器是Model Context Protocol UI SDK的核心功能，它让开发者能够构建一次AI应用界面，然后在多个AI平台（如ChatGPT、Goose、LibreChat等）上无缝运行。本文将深入解析MCP-UI平台适配器的工作原理、配置方法和最佳实践，帮助您快速掌握这一强大的跨平台UI解决方案。😊

什么是MCP-UI平台适配器？

MCP-UI平台适配器是一种智能的协议转换层，它能够在不同的AI平台之间自动翻译UI通信协议。当您的AI工具需要在ChatGPT、Goose、LibreChat等多个平台上运行时，适配器确保您的UI代码无需修改就能在所有平台上正常工作。

适配器的工作原理

MCP-UI平台适配器通过以下机制实现跨平台兼容性：

  1. 协议检测：自动识别当前运行环境（MCP Apps主机或传统MCP-UI主机）
  2. 协议转换：将MCP-UI的postMessage协议转换为目标平台支持的格式
  3. 自动注入：在HTML资源中注入必要的桥接脚本
  4. 双向通信：处理UI与主机之间的双向消息传递

支持的平台适配器类型

MCP-UI目前提供两种主要的平台适配器：

1. MCP Apps适配器

针对遵循MCP Apps标准的主机（如Claude、VSCode、Postman等），这个适配器将MCP-UI协议转换为MCP Apps JSON-RPC格式。配置方法如下：

const widgetUI = await createUIResource({ uri: 'ui://my-server/widget', encoding: 'text', content: { type: 'rawHtml', htmlString: '<h1>我的交互式小部件</h1>', }, adapters: { mcpApps: { enabled: true, config: { timeout: 60000, // 异步操作超时时间 }, }, }, });

2. Apps SDK适配器

专门为ChatGPT的Apps SDK环境设计，将MCP-UI协议转换为Apps SDK API调用。配置示例如下：

const appsSdkTemplate = await createUIResource({ uri: 'ui://widgets/weather', encoding: 'text', content: { type: 'rawHtml', htmlString: renderForecastWidget(), }, metadata: { 'openai/widgetDescription': '交互式天气小部件', 'openai/widgetPrefersBorder': true, }, adapters: { appsSdk: { enabled: true, }, }, });

协议转换对照表

从MCP-UI到主机平台

MCP-UI操作MCP Apps方法Apps SDK调用描述
tooltools/callwindow.openai.tools.call调用其他工具
promptui/messagewindow.openai.ui.message发送对话消息
linkui/open-linkwindow.openai.ui.openLink打开URL链接
notifynotifications/messagewindow.openai.notifications.message发送通知消息
intentui/messagewindow.openai.ui.message发送意图（转换为消息）
ui-size-changeui/notifications/size-changedwindow.openai.ui.notifications.sizeChanged请求调整UI尺寸

从主机平台到MCP-UI

主机通知MCP-UI消息描述
ui/notifications/tool-inputui-lifecycle-iframe-render-data完整的工具参数
ui/notifications/tool-input-partialui-lifecycle-iframe-render-data流式部分参数
ui/notifications/tool-resultui-lifecycle-iframe-render-data工具执行结果
ui/notifications/host-context-changedui-lifecycle-iframe-render-data主题、语言环境等变更
ui/notifications/size-changedui-lifecycle-iframe-render-data主机尺寸限制通知
ui/resource-teardownui-lifecycle-teardown主机通知UI即将销毁

快速配置指南

步骤1：创建UI资源并启用适配器

在您的MCP服务器中，首先创建UI资源并启用相应的适配器：

import { createUIResource } from '@mcp-ui/server'; import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server'; // 创建支持MCP Apps的UI资源 const mcpAppsUI = await createUIResource({ uri: 'ui://my-server/widget-mcp-apps', encoding: 'text', content: { type: 'rawHtml', htmlString: ` <html> <body> <div id="app">加载中...</div> <script> window.addEventListener('message', (event) => { if (event.data.type === 'ui-lifecycle-iframe-render-data') { const { toolInput } = event.data.payload.renderData; document.getElementById('app').textContent = JSON.stringify(toolInput, null, 2); } }); window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*'); </script> </body> </html> `, }, adapters: { mcpApps: { enabled: true }, }, });

步骤2：注册资源和工具

将UI资源注册到MCP服务器，并将工具与UI资源关联：

// 注册UI资源 registerAppResource( server, 'widget_ui', mcpAppsUI.resource.uri, {}, async () => ({ contents: [mcpAppsUI.resource] }) ); // 注册工具并关联UI registerAppTool( server, 'my_widget', { description: '交互式小部件', inputSchema: { query: z.string().describe('用户查询'), }, _meta: { ui: { resourceUri: mcpAppsUI.resource.uri } } }, async ({ query }) => { return { content: [{ type: 'text', text: `处理: ${query}` }], }; } );

步骤3：支持传统MCP-UI主机

对于不支持MCP Apps的传统主机，需要创建嵌入式资源：

async ({ query }) => { // 为传统MCP-UI主机创建嵌入式资源 const embeddedResource = await createUIResource({ uri: `ui://my-server/widget/${query}`, encoding: 'text', content: { type: 'rawHtml', htmlString: renderWidget(query), }, // 注意：不要为嵌入式资源启用适配器 }); return { content: [ { type: 'text', text: `处理: ${query}` }, embeddedResource // 为传统主机包含嵌入式资源 ], }; }

高级配置技巧

1. 同时支持多个平台

由于适配器互斥，您需要为不同平台创建独立的资源：

// MCP Apps主机资源 const mcpAppsResource = await createUIResource({ uri: 'ui://my-server/widget-mcp-apps', content: { type: 'rawHtml', htmlString: widgetHtml }, adapters: { mcpApps: { enabled: true } }, }); // ChatGPT Apps SDK资源 const appsSdkResource = await createUIResource({ uri: 'ui://my-server/widget-apps-sdk', content: { type: 'rawHtml', htmlString: widgetHtml }, adapters: { appsSdk: { enabled: true } }, metadata: { 'openai/widgetDescription': '小部件描述', 'openai/widgetPrefersBorder': true, }, });

2. 处理UI操作

在您的HTML小部件中，使用标准的MCP-UI消息格式，适配器会自动转换：

// 发送提示消息 window.parent.postMessage({ type: 'prompt', payload: { prompt: '今天天气怎么样？' } }, '*'); // 打开链接 window.parent.postMessage({ type: 'link', payload: { url: 'https://example.com' } }, '*'); // 调用其他工具 window.parent.postMessage({ type: 'tool', payload: { toolName: 'get_weather', params: { city: '北京' } } }, '*');

3. 接收主机数据

监听来自适配器的渲染数据：

window.addEventListener('message', (event) => { if (event.data.type === 'ui-lifecycle-iframe-render-data') { const { renderData } = event.data.payload; // 工具输入参数 const toolInput = renderData.toolInput; // 工具执行结果 const toolOutput = renderData.toolOutput; // 小部件状态 const widgetState = renderData.widgetState; // 主机上下文 const theme = renderData.theme; // 'light' | 'dark' | 'system' const locale = renderData.locale; // 例如 'zh-CN' const displayMode = renderData.displayMode; // 'inline' | 'fullscreen' | 'pip' // 使用数据更新UI updateWidget(renderData); } });

实际应用示例

天气小部件示例

以下是一个完整的天气小部件示例，展示如何在多个平台上运行：

// 在服务器端创建UI资源 const weatherUI = await createUIResource({ uri: 'ui://weather-server/dashboard', encoding: 'text', content: { type: 'rawHtml', htmlString: ` <!DOCTYPE html> <html> <head> <style> body { font-family: system-ui; padding: 20px; } .weather-card { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 20px; border-radius: 16px; } </style> </head> <body> <div class="weather-card" id="weatherDisplay"> <h2>天气信息</h2> <div id="data">等待数据...</div> <button onclick="refreshWeather()">刷新天气</button> </div> <script> function refreshWeather() { window.parent.postMessage({ type: 'tool', payload: { toolName: 'get_current_weather', params: { city: '北京' } } }, '*'); } window.addEventListener('message', (event) => { if (event.data.type === 'ui-lifecycle-iframe-render-data') { const data = event.data.payload.renderData; if (data.toolOutput) { document.getElementById('data').innerHTML = \`<p>温度: \${data.toolOutput.temperature}°C</p> <p>天气: \${data.toolOutput.condition}</p>\`; } } }); window.parent.postMessage({ type: 'ui-lifecycle-iframe-ready' }, '*'); </script> </body> </html> `, }, adapters: { mcpApps: { enabled: true }, }, });

调试和故障排除

启用调试日志

适配器会在浏览器控制台输出调试信息：

[MCP Apps Adapter] 初始化适配器... [MCP Apps Adapter] 发送 ui/initialize 请求 [MCP Apps Adapter] 收到 JSON-RPC 消息: {...} [MCP Apps Adapter] 拦截 MCP-UI 消息: prompt

常见问题解决

  1. 适配器未启用：确保在createUIResource中正确配置适配器
  2. 协议不匹配：检查主机是否支持您配置的适配器类型
  3. 资源URI错误：确保工具_meta.ui.resourceUri与注册的资源URI匹配
  4. MIME类型问题：适配器会自动设置正确的MIME类型（text/html;profile=mcp-app）

最佳实践建议

1. 渐进式适配策略

从传统MCP-UI开始，逐步添加平台适配器支持：

  1. 首先确保在传统MCP-UI主机上正常工作
  2. 添加MCP Apps适配器支持
  3. 最后添加Apps SDK适配器支持

2. 平台特性检测

在UI代码中检测当前运行环境：

// 检测是否在Apps SDK环境中 const isAppsSDK = typeof window.openai !== 'undefined'; // 检测是否在MCP Apps环境中 const isMCPApps = window.parent !== window && !isAppsSDK && typeof window.parent.postMessage === 'function'; if (isAppsSDK) { // 使用Apps SDK特定功能 } else if (isMCPApps) { // 使用MCP Apps特定功能 } else { // 传统MCP-UI环境 }

3. 性能优化

  • 资源缓存：对静态UI资源启用缓存
  • 懒加载：大型UI组件按需加载
  • 代码分割：将适配器代码与业务逻辑分离

总结

MCP-UI平台适配器为AI工具开发者提供了强大的跨平台UI兼容性解决方案。通过智能的协议转换机制，您只需编写一次UI代码，就能在ChatGPT、Goose、LibreChat等多个AI平台上无缝运行。

核心优势：

  • ✅一次开发，多平台运行：减少重复开发工作
  • ✅自动协议转换：无需手动处理平台差异
  • ✅向后兼容：同时支持新旧平台版本
  • ✅灵活配置：根据目标平台启用不同适配器

适用场景：

  • 🔧多平台AI工具：需要在ChatGPT、Claude、Goose等多个平台部署的工具
  • 🚀快速原型开发：快速验证UI在不同平台的表现
  • 🔄渐进式迁移：从传统MCP-UI平滑迁移到MCP Apps标准

通过合理使用MCP-UI平台适配器，您可以显著提升AI工具的开发效率和用户体验，让您的创新应用在更多平台上绽放光彩！✨

相关资源：

  • 官方文档：docs/src/guide/mcp-apps.md
  • 示例代码：examples/mcp-apps-demo/src/index.ts
  • SDK源码：sdks/typescript/server/src/index.ts

【免费下载链接】mcp-uiUI over MCP. Bring rich AI experiences to the agents!项目地址: https://gitcode.com/gh_mirrors/mcp/mcp-ui

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

http://www.jsqmd.com/news/549596/

相关文章：

  • rcm疑难问题解决方案：从安装到部署的完整排错手册
  • 戴森球计划模块化生产指南：从新手到专家的工厂搭建手册
  • 终极Web-Check备份恢复指南：数据安全保障策略详解
  • 鸿蒙版瑞幸咖啡开发实战：购物车结算栏的交互设计与实现
  • Mac Mouse Fix终极指南：3种部署方案深度对比与实战配置
  • TabNine自定义补全规则性能影响评估：终极优化指南
  • FreeSWITCH实战：从零部署到高效网关配置全解析
  • 文墨共鸣快速上手：无需Python环境，纯Docker镜像启动水墨风语义分析系统
  • Elixir代码格式化终极指南：如何用mix format提升代码质量
  • 如何用Umi-OCR实现高效文字识别：从截图到批量处理的全流程解决方案
  • 逆向工程师的日常：我是如何修复被恶意篡改的二进制文件的
  • 终极Faker.js南美开发指南：5个西班牙语和葡萄牙语数据生成技巧
  • AnythingLLM：构建智能知识库的革命性工具，让文档对话变得简单
  • Mantine性能基准测试终极指南：10个组件库性能优化技巧
  • 2026防火门厂家实力推荐：河北宏安防火门有限公司，免漆/钢质/乙级/卷帘式防火门全系供应 - 品牌推荐官
  • GLM-4-9B-Chat-1M开源镜像优势：免编译、免量化、原生支持1M上下文
  • 当STM32G431遇上磁链观测器：一场硬核玩家的电机控制实验
  • 深度解析AI代码分析工具：从入门到实战的完整指南
  • Obsidian Tasks未来路线图：即将推出的新功能和改进计划
  • Auxio高级播放技巧：无缝播放、ReplayGain调整与音频质量优化
  • 2026年郑州激光清洗机排名，朋朋激光在行业内的地位如何 - 工业品网
  • VibeVoice Pro流式TTS参数调优指南：Infer Steps 5~20音质-速度平衡点
  • 飞书机器人接入OpenClaw：ollama-QwQ-32B对话式任务触发器配置
  • 终极指南：Emscripten与WebAssembly异常处理实现高性能跨语言错误管理
  • 2026年贝贝南瓜/柑橘/菠萝/苹果分选机厂家推荐：山东松木自动化设备有限公司全品类覆盖 - 品牌推荐官
  • Hocus工作空间生命周期管理：创建、启动、停止、删除全流程指南
  • Ultimate Vocal Remover GUI：AI驱动的音频分离工具 内容创作者的声音提取解决方案
  • Pixel Dimension Fissioner 技术生态：OpenAI Codex与Claude API对比集成
  • Apache Dubbo过滤器链开发终极指南：如何实现自定义业务逻辑埋点
  • 别再手动调格式了！EndNote X9搭配Word搞定SCI论文参考文献（附GB/T 7714国标格式设置）