用途
build-mcp-app 用于在标准 MCP 服务器之上添加交互式 UI 小部件(widgets),使工具结果能以 iframe 形式内联渲染在聊天界面中。用户可以在构建 MCP 应用、为 MCP 服务器添加交互式 UI 或小部件、在聊天中渲染组件等场景下使用该技能。
主要能力
- 在工具声明中通过 _meta.ui.resourceUri 关联 UI 资源,工具处理函数返回纯文本/JSON 数据,资源单独注册并返回 HTML。
- 支持 Antigravity 宿主相关配置:visibility 隐藏辅助工具、prefersBorder 去除边框、csp 声明外部来源、hostContext.safeAreaInsets 适配刘海屏和输入框覆盖。
- 提供小部件运行时 App 类,支持接收工具结果(ontoolresult)、接收工具输入(ontoolinput)、发送用户消息(sendMessage)、更新模型上下文(updateModelContext)、调用服务器工具(callServerTool)、打开链接(openLink)、获取宿主上下文与主题、请求显示模式、下载文件等。
- 支持两种部署形态:远程流式 HTTP 服务器和本地 MCPB 打包应用。
- 提供最小联系人选择器脚手架,包含服务器和 HTML 小部件示例。
- 提供测试方式:Antigravity Desktop 配置、mcp-remote 包装、无头 JSON-RPC 循环测试。
使用方式
- 判断是否真的需要小部件:结构化输入无法可靠推断时用表单;需要从列表选择时用选择器/表格;破坏性或计费操作需要确认时用确认对话框;输出为空间或视觉内容时用展示小部件;长时间任务需要观看时用进度/实时状态。若 Elicitation 已覆盖(如是/否确认、短枚举选择、扁平表单),则优先使用 Elicitation,不必构建小部件。
- 注册工具和资源:使用 registerAppTool 注册工具并通过 _meta.ui.resourceUri 声明 UI 资源,工具返回数据;使用 registerAppResource 单独注册资源并返回 HTML,MIME 类型必须为 RESOURCE_MIME_TYPE(text/html;profile=mcp-app)。
- 在小部件 HTML 中内联 ext-apps 浏览器包,使用 App 类连接宿主并设置事件处理器,注意 CSP 限制,远程资源需通过 callServerTool 中转,外链使用 app.openLink。
- 部署:远程场景使用流式 HTTP 传输;本地场景使用 StdioServerTransport 并通过 build-mcpb 技能打包。
- 测试:Antigravity Desktop 使用 command/args 配置并通过 mcp-remote 包装;也可使用无头 JSON-RPC 循环快速迭代。
适用场景
- 工具需要结构化输入而 Antigravity 无法可靠推断。
- 用户需要从大列表或可搜索列表中选择。
- 需要显式确认破坏性或计费操作。
- 输出包含图表、地图、差异对比、预览等视觉或空间内容。
- 需要展示长时间任务的进度或实时状态。
限制
- 小部件不能访问宿主页面的 DOM、cookie 或存储。
- 小部件不能向任意来源发起网络请求(受 CSP 限制),需通过 callServerTool 中转。
- 小部件不能打开弹窗或直接导航,需使用 app.openLink。
- 远程图片需在服务端内联为 data: URL。
- 宿主若不支持 apps surface,会忽略 _meta.ui 并正常渲染工具返回的文本内容,小部件退化为普通文本展示。
- 目录提交要求 OAuth 或无认证(none),静态 bearer 仅限私有部署;另需工具注解和 3–5 张 PNG 截图。
- Antigravity Desktop 当前构建仍要求 command/args 配置形式,不支持原生 type: http;Desktop 会积极缓存 UI 资源,修改小部件 HTML 后需完全退出并重启以强制重新获取。