SuperAPI AI 工具集

migrate-oai-app

智能体与模型

查看项目

更新于 10-16 09:33

技能介绍

用途:把现有 OpenAI Apps SDK 应用迁移到 MCP Apps SDK(@modelcontextprotocol/ext-apps),后者为对话客户端中的交互式 UI 提供标准化开放协议。

主要能力:提供从 OpenAI Apps SDK 到 MCP Apps SDK 的迁移参考指南(含 before/after 映射表)、SDK 源码 JSDoc(App 类、registerAppTool、registerAppResource、useApp 等)、按前端框架组织的示例(vanillajs、react、vue、svelte、preact、solid),以及迁移完成前的检查清单,用于扫描残留的 OpenAI 模式。

参考代码获取:git clone --branch "v$(npm view @modelcontextprotocol/ext-apps version)" --depth 1 https://github.com/modelcontextprotocol/ext-apps.git /tmp/mcp-ext-apps。迁移指南位于 /tmp/mcp-ext-apps/docs/migrate_from_openai_apps.md。依赖建议用包管理器安装(npm install、pnpm add、yarn add),不要手写版本号。

关键概念变化:服务端用 registerAppTool() 和 registerAppResource() 替代裸的 server.registerTool()/server.registerResource();客户端从同步全局对象 window.openai(toolInput、theme 等)改为 App 实例加异步事件处理器(ontoolinput、ontoolresult、onhostcontextchanged),须在 connect() 前注册处理器,通过 app.getHostContext() 获取主题、语言等宿主环境;React 应用可用 useApp 管理生命周期。

CSP 与 CORS:MCP Apps HTML 作为 MCP 资源提供,运行在无同源服务器的沙箱 iframe 中,每个 origin(含本地 JS/CSS 打包源与生产 CDN)都必须声明到 CSP,缺失会静默失败;需按 resourceDomains、connectDomains、frameDomains 分类整理,并区分通用、仅开发、仅生产。MCP 客户端会发跨域请求,Express 可用 app.use(cors()),裸 HTTP 服务需额外允许 mcp-session-id、mcp-protocol-version、last-event-id 头并暴露 mcp-session-id。

尚未提供对应能力:进度指示、widgetDescription、widgetState/setWidgetState、文件上传与下载、requestModal/requestClose、view 等暂无可直接替代,资料给出部分临时方案(如用 localStorage 或服务端状态、用 app.updateModelContext())。

测试:用 basic-host 示例验证,先在服务端目录执行 npm run build && npm run serve,再在 /tmp/mcp-ext-apps/examples/basic-host 执行 npm install 及 SERVERS='["http://localhost:3001/mcp"]' npm run start,打开 http://localhost:8080 检查控制台错误、ontoolinput 与 ontoolresult 是否触发。适用场景:已有 OpenAI Apps SDK 应用需迁移到开放 MCP 协议的开发者。限制:部分 OpenAI 特性尚无对应实现,CSP 缺失会静默失败,其余细节暂未提供。