如何构建 awesome-llm-apps 的 MCP Apps 让 MCP 工具在聊天中渲染为可交互界面【免费下载链接】awesome-llm-apps100 AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps在 awesome-llm-apps 仓库的generative_ui_agents/mcp-apps-generative-ui-showcase/子项目中有一个可运行的示例MCP 服务器注册search-flights、create-portfolio、create-board等工具每个工具通过_meta[ui/resourceUri]关联一个 HTML/JS 资源。当 Agent 调用这些工具时前端把关联的 HTML 应用挂载到聊天里的沙箱 iframe 中iframe 再通过 JSON-RPCpostMessage回调 MCP 工具——最终效果是多步向导、拖拽看板、实时图表这类完整交互界面直接渲染在聊天里。这个项目基于 CopilotKit、AG-UI 和 MCP Apps ExtensionSEP-1865。本文的任务是在本地跑通这个项目并掌握「给一个 MCP 工具挂上交互 UI」的完整模式让你能照着 server.ts 的结构给自己的工具加 UI。工作原理工具、UI 资源与前端中间件整个链路在 README 中描述为User: Book a flight from JFK to LAX ↓ AI calls search-flights tool ↓ MCPAppsMiddleware intercepts, fetches HTML resource ↓ CopilotKit renders flights-app.html in iframe ↓ User interacts with wizard UI ↓ UI calls MCP tools via postMessage → server拆开看有三个关键点都在源码中有对应实现工具声明 UI 资源server.registerTool()的描述对象里带_meta: { ui/resourceUri: ui://flights/flights-app.html }。server.ts 中定义了协议常量RESOURCE_URI_META_KEY ui/resourceUri。资源声明 MCP App 类型server.registerResource()注册对应 URI 的资源mimeType: text/htmlmcp标记它是一个 MCP Apphandler 返回{ contents: [{ text: htmlContent }] }。前端中间件Next.js 的 API 路由 route.ts 中BuiltInAgent通过.use(new MCPAppsMiddleware({ mcpServers: [{ type: http, url: ... }] }))连接 MCP 服务器拦截工具调用并抓取 HTML 资源交给 CopilotKit 渲染。MCP 服务器本身是 Express StreamableHTTPServerTransportPOST/GET/DELETE 都挂在/mcp路径上另有一个/health健康检查端点默认端口 3001可通过PORT环境变量修改。准备条件Node.js 环境npm 工作区含next、tsx、vite等依赖无系统级依赖要求一个 LLM API Key。根据 route.ts 的determineModel()设置OPENAI_API_KEY时使用openai/gpt-5.5设置ANTHROPIC_API_KEY时使用anthropic/claude-sonnet-4-6设置GOOGLE_API_KEY时使用google/gemini-3.1-pro-preview都没有则默认回落到openai/gpt-5.5。安装与启动以下命令来自 README 的 Quick Start。README 中称为 “mcp-apps directory”在本仓库中对应generative_ui_agents/mcp-apps-generative-ui-showcase/。1. 安装依赖项目根目录 MCP 服务器两个包cd generative_ui_agents/mcp-apps-generative-ui-showcase npm install cd mcp-server npm install cd ..2. 设置环境变量在项目根目录创建.env.localOPENAI_API_KEYsk-...sk-...替换为你自己的 OpenAI Key也可以改用ANTHROPIC_API_KEY或GOOGLE_API_KEY模型选择见上节。3. 构建并运行 MCP 服务器终端 1cd mcp-server npm run build npm run dev # Server runs at http://localhost:3001/mcpnpm run build会执行tsc npm run build:app先编译 TypeScript再用 Vite 依次把flights-app、hotels-app、trading-app、kanban-app四个 HTML 应用打包为单文件自包含 HTML输出到mcp-server/apps/dist/。注意 mcp-server/package.json 中build:app脚本第一步是rm -rf dist即每次构建会删除并重建apps/dist/目录。npm run dev则用tsx watch server.ts以开发模式运行服务器。4. 运行前端终端 2回到项目根目录npm run dev # Frontend at http://localhost:3000结果验证打开http://localhost:3000在聊天框输入 README 给出的示例 Prompt例如Book a flight from JFK to LAX on January 20th for 2 passengers对应search-flights工具、Create a $10,000 tech-focused portfolio对应create-portfolio、Create a kanban board for my software project对应create-board。成功后聊天中会渲染出对应的交互界面多步预订向导、投资组合图表、拖拽看板而不是纯文本结果。健康检查MCP 服务器提供GET http://localhost:3001/health返回形如{ status: ok, server: travel-booking-mcp, sessions: 当前会话数 }的 JSON字段来自 server.ts 的/health端点sessions为实时数值。一个明确的故障信号如果 iframe 中显示占位页The app UI needs to be built. Run: npm run build:app说明apps/dist/下还没有构建产物——loadHtml()在找不到 HTML 时会返回这个占位页。此时回到终端 1 重新执行npm run build即可。给自己的 MCP 工具挂上交互 UI跑通示例后按 README 的 Tool Registration Pattern 和 server.ts 的实际代码扩展一个带 UI 的工具需要四处改动1. 在mcp-server/server.ts中注册 UI 资源。参照现有registerResource调用例如航班的写法server.registerResource( flights-app-template, // 资源名 ui://flights/flights-app.html, // ui:// 开头的资源 URI { name: flights-app-template, uri: ui://flights/flights-app.html, title: Airline Booking, description: Interactive flight search and booking wizard with seat selection, mimeType: text/htmlmcp, // Marks as MCP App }, async (): PromiseReadResourceResult ({ contents: [{ uri: ui://flights/flights-app.html, mimeType: text/htmlmcp, text: htmlContent }], }), );其中htmlContent由loadHtml(flights-app)从apps/dist/读取。2. 注册工具并通过_meta关联 URIserver.registerTool( search-flights, { title: Search Flights, description: Searches for available flights between two airports. Returns an interactive booking wizard UI., inputSchema: { origin: z.string().describe(Origin airport code (e.g., JFK, LAX, LHR)), destination: z.string().describe(Destination airport code), departureDate: z.string().describe(Departure date in YYYY-MM-DD format), passengers: z.number().min(1).max(9).describe(Number of passengers (1-9)), cabinClass: z.enum([economy, business, first]).optional(), }, _meta: { ui/resourceUri: ui://flights/flights-app.html, // 指向上面注册的资源 URI }, }, async ({ origin, destination, departureDate, passengers, cabinClass }) { // 工具逻辑返回 text structuredContent }, );3. 提供 HTML 应用。UI 源文件放在mcp-server/apps/下如 flights-app.html用 Vite vite-plugin-singlefile打包成单文件 HTML。vite.config.ts 通过环境变量选择要打包的入口# 在 mcp-server/apps/ 下构建单个应用 BUILD_APPflights-app vite build新应用需要加入mcp-server/package.json的build:app脚本格式参照现有的四个BUILD_APP... vite build命令否则npm run build不会打包它。4. 告知 Agent 新应用的存在。route.ts 中BuiltInAgent的prompt字段枚举了 4 个应用及其参数、示例 Prompt 和 helper 工具模型靠这段提示词决定何时调用哪个工具。新增工具后应把它的名称、参数、示例 Prompt 补进这段提示词否则模型不会主动渲染新 UI。验证方式与主路径相同重启 MCP 服务器npm run dev是 watch 模式改动server.ts后会自动重载在http://localhost:3000输入对应示例 Prompt确认聊天中出现你的交互界面若出现 “needs to be built” 占位页则先执行第 3 步的构建。限制与注意事项会话与业务状态保存在内存中server.ts 用Map存activePortfolios、activeBoardsMCP 传输使用InMemoryEventStoreMCP 服务器重启后这些状态会丢失。CORS 配置为origin: *且暴露Mcp-Session-Id响应头这是本地开发/演示的配置。前后端分离部署时需要把MCP_SERVER_URL环境变量指向部署后的 MCP 服务器地址route.ts中未设置该变量时默认连接http://localhost:3001/mcpREADME Deployment 一节说明线上演示即为 Web 与 MCP Server 两个独立服务。四个示例应用的数据15 个机场、10 个城市酒店、18 只股票等均为 mcp-server/src/ 下的内置模拟数据用于演示交互不是真实交易或预订。【免费下载链接】awesome-llm-apps100 AI Agents, Agent Skills and RAG Apps - Free and Open Source.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-llm-apps创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考