用途:mcp-ui-sdk 面向在 MCP 上构建交互式界面的开发,早于 MCP Apps 扩展提出 UI over MCP 方案,现同时实现 MCP Apps 并保留自有动作协议,供 Goose、Postman 等已有宿主使用。
主要能力:服务端 @mcp-ui/server 提供 createUIResource,支持三种内容类型——rawHtml(完整 HTML 字符串内联,渲染为 srcdoc 沙箱 iframe,默认选择)、externalUrl(宿主 iframe 指向你自托管 URL,注入 base 以解析相对路径,代价是 CSP 额外来源与网络跳转)、remoteDom(流式 DOM 描述,由客户端用自身组件库渲染,视觉最统一但控制最少)。可选 metadata 与 uiMetadata,如 preferred-frame-size、initial-render-data。
UI 动作:iframe 通过 postMessage 发送五种动作——tool 指定工具与参数、prompt 触发模型提示、link 请求导航、intent 表达用户意图由宿主路由、notify 通知副作用(必须非关键路径)。同一 UI 面向多宿主时优先 intent。
异步与生命周期:带 messageId 的 ui-request-data 会收到 ui-message-received 与 ui-message-response,需先检查 payload.error;只有 received 无 response 表示宿主接受后失败,应超时降级。iframe 应尽早发送 ui-lifecycle-iframe-ready(在水合前),否则渲染数据可能先于监听器到达。
客户端:@mcp-ui/client 提供 AppRenderer(client、toolName、toolInput、toolResult、sandbox、onOpenLink、onMessage);旧动作协议用 UIResourceRenderer 与 onUIAction 分派 tool、prompt、link、intent、notify。Ruby 有 mcp_ui_server。
互操作:同一服务端可同时服务两类宿主,MCP Apps 用 RESOURCE_MIME_TYPE(text/html;profile=mcp-app)与 _meta.ui.resourceUri,mcp-ui 用 createUIResource 输出,其帮助函数可与 ext-apps/server 的 registerAppTool、registerAppResource 组合;面向双宿主时以 MCP Apps 桥为主,在 getHostCapabilities 为空时回退 mcp-ui 动作。
限制:沙箱代理来源决定隔离效果,切勿指向自身域,否则不受信标记会获得 cookie;externalUrl 增加来源与延迟;remoteDom 控制最少;notify 不保证送达。收费、价格、平台等事实暂未提供。