企业官网建设流程全解析

1. MCP Apps 交互式 GUI 基础概念

MCP Apps 是一种用于构建交互式用户界面的标准协议，它允许开发者在 AI 工具和应用程序中创建丰富的动态界面。这个标准最初源自 MCP-UI 项目，现在已经发展成为 MCP 生态系统中的官方交互式 UI 标准。

1.1 MCP Apps 的核心特性

MCP Apps 提供了几个关键特性，使其在构建交互式 GUI 时具有独特优势：

安全沙箱机制：所有远程代码都在隔离的 iframe 中执行，确保主机和用户的安全。这种设计既保护了宿主环境，又允许丰富的交互功能。

跨平台兼容：MCP Apps 支持与各种宿主环境集成，包括传统的 MCP-UI 宿主和新的 MCP Apps 宿主。这意味着开发者可以构建一次界面，然后在多种环境中运行。

灵活的 UI 组件：系统支持 HTML 内容，允许开发者使用熟悉的 Web 技术构建界面。同时提供了专门的组件库，如 AppRenderer，简化了 UI 集成过程。

双向通信能力：MCP Apps 不仅能够展示界面，还支持界面与宿主应用之间的双向消息传递，实现真正的交互体验。

1.2 MCP Apps 的架构组成

MCP Apps 生态系统主要由三个核心部分组成：

1. 客户端 SDK：提供在宿主应用中渲染和交互 UI 的能力，包括 AppRenderer 等核心组件。

2. 服务器 SDK：用于创建和托管交互式 UI 资源，包括工具注册和资源管理功能。

3. 协议标准：定义了客户端和服务器之间的通信规范，确保不同实现的互操作性。

这种架构设计使得 MCP Apps 既保持了灵活性，又能确保不同组件之间的可靠协作。

2. MCP Apps 开发环境搭建

2.1 基础工具链准备

要开始开发 MCP Apps 交互式 GUI，首先需要配置开发环境。以下是推荐的工具链：

• Node.js(v16+): 用于运行客户端和服务器端 JavaScript 代码
• TypeScript(v4.7+): MCP Apps SDK 主要使用 TypeScript 开发
• 包管理器(npm/yarn/pnpm): 用于管理依赖项
• 代码编辑器(VS Code/WebStorm): 提供良好的 TypeScript 支持

安装核心 SDK 包：

npm install @mcp-ui/client @mcp-ui/server @modelcontextprotocol/sdk

2.2 项目结构规划

一个典型的 MCP Apps 项目通常采用以下目录结构：

mcp-app-project/ ├── client/ # 客户端代码 │ ├── src/ │ │ ├── components/ # UI组件 │ │ └── app.tsx # 主应用入口 ├── server/ # 服务器代码 │ ├── src/ │ │ ├── resources/ # UI资源定义 │ │ └── server.ts # 服务器入口 ├── shared/ # 共享代码 └── package.json # 项目配置

这种结构清晰地分离了客户端和服务器端代码，同时提供了共享代码的空间，便于维护和扩展。

2.3 开发服务器配置

为了高效开发 MCP Apps，建议配置以下开发服务器：

1. 客户端开发服务器：使用 Vite 或 Webpack 提供热重载支持
2. MCP 服务器：运行实际的 MCP Apps 后端服务
3. 代理服务器：在开发环境中处理跨域请求

一个基本的 Vite 配置示例：

// vite.config.js import { defineConfig } from 'vite' import react from '@vitejs/plugin-react' export default defineConfig({ plugins: [react()], server: { proxy: { '/mcp': { target: 'http://localhost:3000', changeOrigin: true } } } })

3. 创建第一个 MCP Apps 交互界面

3.1 定义 UI 资源

在 MCP Apps 中，所有交互式界面都作为资源定义在服务器端。以下是创建基本 UI 资源的步骤：

import { createUIResource } from '@mcp-ui/server'; const simpleUI = createUIResource({ uri: 'ui://my-server/simple', // 唯一资源标识符 content: { type: 'rawHtml', htmlString: ` <div style="padding: 20px; background: #f0f0f0;"> <h1>欢迎使用 MCP Apps</h1> <button onclick="sendMessage({action:'click'})">点击我</button> </div> ` }, encoding: 'text' });

这个例子创建了一个简单的 HTML 界面，包含一个标题和一个按钮。sendMessage是 MCP Apps 提供的客户端 API，用于向宿主应用发送消息。

3.2 注册工具和关联 UI

创建 UI 资源后，需要将其与特定的工具关联：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp'; import { registerAppTool, registerAppResource } from '@modelcontextprotocol/ext-apps/server'; import { z } from 'zod'; const server = new McpServer({ name: 'my-server', version: '1.0.0' }); // 注册UI资源处理器 registerAppResource(server, 'simple_ui', simpleUI.resource.uri, {}, async () => ({ contents: [simpleUI.resource] })); // 注册工具并关联UI registerAppTool(server, 'show_simple_ui', { description: '显示简单交互界面', inputSchema: { name: z.string().optional() }, _meta: { ui: { resourceUri: simpleUI.resource.uri, height: '300px' // 可选：指定UI高度 } } }, async ({ name }) => { return { content: [{ type: 'text', text: `你好, ${name || '访客'}! 界面已加载。` }] }; });

在这个例子中，我们创建了一个名为show_simple_ui的工具，当调用这个工具时，它会加载我们之前定义的简单 UI 界面。

3.3 客户端渲染 UI

在客户端应用中，使用 AppRenderer 组件来显示交互式界面：

import { AppRenderer } from '@mcp-ui/client'; function SimpleToolUI({ client, toolName, input }) { return ( <div style={{ border: '1px solid #ddd', borderRadius: '8px', overflow: 'hidden' }}> <AppRenderer client={client} toolName={toolName} sandbox={{ url: 'https://mcp-ui-sandbox.example.com' }} toolInput={input} onMessage={async (params) => { console.log('收到来自UI的消息:', params); if (params.action === 'click') { alert('按钮被点击了!'); } }} /> </div> ); }

AppRenderer 组件负责处理 UI 的渲染和与服务器端的通信。onMessage回调允许宿主应用响应来自 UI 的交互事件。

4. 高级 MCP Apps 功能开发

4.1 动态内容更新

MCP Apps 支持在 UI 加载后动态更新内容。以下是实现动态更新的方法：

服务器端：

registerAppTool(server, 'dynamic_ui', { description: '动态内容演示', inputSchema: z.object({}), _meta: { ui: { resourceUri: dynamicUI.resource.uri, updateMode: 'push' // 启用服务器推送更新 } } }, async (input, { sendUpdate }) => { // 初始响应 const initialResponse = { content: [{ type: 'text', text: '初始内容' }] }; // 5秒后发送更新 setTimeout(() => { sendUpdate({ content: [{ type: 'text', text: '这是5秒后的更新内容' }] }); }, 5000); return initialResponse; });

客户端处理更新：

<AppRenderer client={client} toolName="dynamic_ui" onUpdate={(update) => { console.log('收到UI更新:', update); // 处理更新内容 }} />

这种机制非常适合需要实时更新数据的场景，如仪表盘或监控界面。

4.2 复杂交互模式

对于需要复杂交互的应用程序，可以使用 MCP Apps 的消息传递系统：

UI 端发送消息：

<script> function sendComplexData() { sendMessage({ action: 'submit_form', data: { username: document.getElementById('username').value, preferences: { theme: document.querySelector('input[name="theme"]:checked').value, notifications: document.getElementById('notifications').checked } } }); } </script> <form onsubmit="event.preventDefault(); sendComplexData();"> <!-- 表单字段 --> </form>

客户端处理消息：

<AppRenderer onMessage={async (params) => { if (params.action === 'submit_form') { console.log('收到表单数据:', params.data); // 验证和处理数据 await client.executeTool('process_form', params.data); } }} />

这种模式允许构建复杂的表单和数据输入界面，同时保持与宿主应用的紧密集成。

4.3 自定义样式和主题

MCP Apps 支持通过多种方式自定义 UI 外观：

1. 内联样式：直接在 HTML 内容中使用 style 属性
2. CSS 资源：将 CSS 文件作为独立资源加载
3. 主题变量：使用 CSS 变量实现主题化

示例：主题化 UI

const themedUI = createUIResource({ uri: 'ui://my-server/themed', content: { type: 'rawHtml', htmlString: ` <style> :root { --primary-color: ${theme.primary}; --text-color: ${theme.text}; } .container { background: var(--primary-color); color: var(--text-color); padding: 20px; } </style> <div class="container"> <h1>主题化界面</h1> <p>这个界面会根据主题变量改变外观</p> </div> ` } });

动态更新主题：

<AppRenderer sandbox={{ url: sandboxUrl, styles: { '--primary-color': isDarkMode ? '#2c3e50' : '#3498db', '--text-color': isDarkMode ? '#ecf0f1' : '#2c3e50' } }} />

这种方法使得 UI 能够动态适应宿主应用的主题变化，提供一致的用户体验。

5. MCP Apps 最佳实践与性能优化

5.1 安全最佳实践

在开发 MCP Apps 时，安全应该是首要考虑因素：

1. 输入验证：始终验证从 UI 接收的所有消息和数据

   onMessage={async (params) => { if (typeof params !== 'object') return; if (params.action === 'buy' && isValidProduct(params.productId)) { // 处理购买逻辑 } }}

2. 沙箱配置：使用严格的沙箱策略限制 UI 的能力

   <AppRenderer sandbox={{ url: sandboxUrl, policies: { allowScripts: true, allowForms: false, allowSameOrigin: false } }} />

3. 内容安全策略：为 UI 资源实施 CSP

   createUIResource({ // ... security: { csp: "default-src 'self'; script-src 'unsafe-inline' 'self'" } });

4. 敏感操作确认：对于关键操作，要求在宿主应用中确认

   onMessage={async (params) => { if (params.action === 'delete_account') { const confirmed = await showConfirmationDialog( '确定要删除账户吗？此操作不可撤销。' ); if (confirmed) { await deleteAccount(params.userId); } } }}

5.2 性能优化技巧

1. 资源懒加载：延迟加载非关键 UI 资源

   registerAppResource(server, 'heavy_ui', heavyUI.uri, { preload: false // 不预加载 });

2. UI 分块：将复杂界面拆分为多个资源

   const mainUI = createUIResource({ /* 主界面 */ }); const settingsUI = createUIResource({ /* 设置面板 */ }); // 在需要时动态加载设置面板 sendMessage({ action: 'load_settings' });

3. 缓存策略：合理设置缓存头减少重复加载

   createUIResource({ // ... cache: { maxAge: 3600 // 1小时缓存 } });

4. 虚拟滚动：对于长列表使用虚拟滚动技术

   <div style="height: 500px; overflow-y: auto;"> <!-- 只渲染可见项 --> </div>

5. 资源压缩：压缩 HTML、CSS 和 JavaScript 资源

   createUIResource({ // ... encoding: 'gzip', // 启用压缩 content: { type: 'rawHtml', htmlString: minifiedHTML } });

5.3 调试与测试策略

1. UI 检查器：使用 MCP-UI Inspector 调试界面

   import { enableInspector } from '@mcp-ui/client/debug'; enableInspector();

2. 日志记录：实现详细的日志记录

   registerAppTool(server, 'debug_tool', { // ... }, async (input, context) => { context.logger.debug('工具被调用', { input }); // ... });

3. 自动化测试：编写端到端测试

   describe('MCP Apps 交互测试', () => { it('应该正确处理表单提交', async () => { await renderTool('form_tool'); await fillForm({ name: 'Test' }); await submitForm(); expect(getLastMessage()).toMatchObject({ action: 'form_submitted', data: { name: 'Test' } }); }); });

4. 性能分析：使用浏览器开发者工具分析性能

   // 在UI资源中添加性能标记 performance.mark('ui-start'); // ... performance.mark('ui-end'); performance.measure('ui-render', 'ui-start', 'ui-end');

5. 错误边界：实现错误处理机制

   function ToolContainer({ toolName }) { const [error, setError] = useState(null); if (error) { return <ErrorFallback error={error} />; } return ( <ErrorBoundary onError={setError}> <AppRenderer toolName={toolName} /> </ErrorBoundary> ); }

6. 实际应用案例与进阶模式

6.1 数据可视化仪表盘

MCP Apps 非常适合构建数据可视化界面。以下是一个仪表盘案例的实现要点：

服务器端数据提供：

registerAppTool(server, 'dashboard', { description: '实时数据仪表盘', _meta: { ui: { resourceUri: dashboardUI.uri, updateMode: 'push', updateInterval: 5000 // 每5秒更新一次 } } }, async (_, { sendUpdate }) => { // 获取实时数据 const metrics = await fetchMetrics(); // 初始响应 const initialResponse = { content: [{ type: 'json', data: metrics }] }; // 设置定期更新 const interval = setInterval(async () => { const updatedMetrics = await fetchMetrics(); sendUpdate({ content: [{ type: 'json', data: updatedMetrics }] }); }, 5000); // 清理函数 return { ...initialResponse, _meta: { cleanup: () => clearInterval(interval) } }; });

客户端图表渲染：

<!-- 在UI资源中使用Chart.js渲染图表 --> <script src="https://cdn.jsdelivr.net/npm/chart.js"></script> <canvas id="metricsChart"></canvas> <script> let chart; onMessage(({ data }) => { if (!chart) { chart = new Chart(document.getElementById('metricsChart'), { type: 'line', data: { labels: data.labels, datasets: [{ label: '性能指标', data: data.values }] } }); } else { chart.data.labels = data.labels; chart.data.datasets[0].data = data.values; chart.update(); } }); </script>

6.2 多步骤工作流向导

对于复杂操作，可以实现多步骤向导界面：

服务器端状态管理：

registerAppTool(server, 'setup_wizard', { description: '系统设置向导', _meta: { ui: { resourceUri: wizardUI.uri, width: '800px', height: '600px' } } }, async (input, { sendUpdate }) => { let currentStep = input.step || 1; let formData = input.data || {}; // 根据当前步骤返回不同的UI状态 return { content: [{ type: 'json', data: { currentStep, formData } }] }; });

客户端向导控制：

<div id="wizard-container"> <!-- 步骤内容动态加载 --> </div> <script> let currentData = {}; function renderStep(step, data) { // 根据步骤渲染不同UI const container = document.getElementById('wizard-container'); switch(step) { case 1: container.innerHTML = ` <h2>步骤1: 基本信息</h2> <input id="username" placeholder="用户名"> <button onclick="nextStep()">下一步</button> `; break; case 2: container.innerHTML = ` <h2>步骤2: 偏好设置</h2> <!-- 更多表单字段 --> <button onclick="prevStep()">上一步</button> <button onclick="nextStep()">下一步</button> `; break; // 更多步骤... } } function nextStep() { // 收集当前步骤数据 currentData = gatherFormData(); sendMessage({ action: 'wizard_next', data: currentData }); } function prevStep() { sendMessage({ action: 'wizard_prev', data: currentData }); } onMessage(({ currentStep, formData }) => { currentData = formData; renderStep(currentStep, formData); }); </script>

6.3 与外部服务集成

MCP Apps 可以轻松集成外部服务，例如支付网关或第三方API：

支付集成示例：

registerAppTool(server, 'payment', { description: '支付处理', _meta: { ui: { resourceUri: paymentUI.uri, height: '500px' } } }, async ({ amount, currency }, { sendUpdate }) => { // 初始化支付会话 const paymentSession = await createPaymentSession({ amount, currency }); return { content: [{ type: 'json', data: { paymentUrl: paymentSession.url, sessionId: paymentSession.id } }] }; });

客户端支付处理：

<div id="payment-container"> <iframe id="payment-frame" sandbox="allow-forms allow-scripts"></iframe> <div id="payment-status"></div> </div> <script> onMessage(({ paymentUrl, sessionId }) => { const frame = document.getElementById('payment-frame'); frame.src = paymentUrl; // 监听支付结果 const checkInterval = setInterval(async () => { const result = await checkPaymentStatus(sessionId); if (result.completed) { clearInterval(checkInterval); document.getElementById('payment-status').innerHTML = '支付成功!'; sendMessage({ action: 'payment_completed', data: result }); } }, 2000); }); </script>

7. MCP Apps 与其他技术的集成

7.1 与传统 Web 应用集成

将 MCP Apps 集成到现有 Web 应用中需要考虑几个关键点：

1. 身份验证传递：安全地将用户会话传递给 MCP Apps

   <AppRenderer sandbox={{ url: sandboxUrl, headers: { 'Authorization': `Bearer ${authToken}` } }} />

2. 样式协调：确保 MCP Apps UI 与宿主应用风格一致

   /* 在宿主应用中定义共享样式变量 */ :root { --primary-color: #4285f4; --font-family: 'Roboto', sans-serif; } /* 在MCP Apps UI中使用这些变量 */ body { font-family: var(--font-family); color: var(--text-color); }

3. 路由同步：保持浏览器历史记录同步

   onMessage(({ action, url }) => { if (action === 'navigate') { history.pushState(null, '', url); } });

7.2 与桌面应用集成

使用 Electron 或其他桌面技术集成 MCP Apps：

Electron 主进程配置：

const { BrowserWindow } = require('electron'); function createMcpWindow() { const win = new BrowserWindow({ webPreferences: { sandbox: true, contextIsolation: true, webSecurity: true } }); // 加载MCP Apps宿主页面 win.loadURL('app://mcp-host/index.html'); // 处理来自MCP Apps的链接点击 win.webContents.on('will-navigate', (event, url) => { if (!url.startsWith('app://')) { event.preventDefault(); shell.openExternal(url); } }); }

处理系统集成：

onMessage(({ action, payload }) => { if (action === 'system_action') { if (payload.type === 'print') { ipcRenderer.send('print-document', payload.content); } } });

7.3 与移动应用集成

在 React Native 或其他移动框架中使用 MCP Apps：

React Native WebView 集成：

import { WebView } from 'react-native-webview'; function McpAppRenderer({ toolName, input }) { const [webViewRef, setWebViewRef] = useState(null); const handleMessage = (event) => { const message = JSON.parse(event.nativeEvent.data); // 处理来自MCP Apps的消息 }; const postMessage = (message) => { webViewRef.postMessage(JSON.stringify(message)); }; return ( <WebView ref={setWebViewRef} source={{ uri: `https://mcp-host/tool/${toolName}` }} onMessage={handleMessage} injectedJavaScript={` window.MCP_HOST = { postMessage: (msg) => window.ReactNativeWebView.postMessage(JSON.stringify(msg)), toolInput: ${JSON.stringify(input)} }; true; `} /> ); }

Android/iOS 原生集成：

// Android 示例 webView.settings.javaScriptEnabled = true webView.addJavascriptInterface(McpHostInterface(), "MCP_HOST") class McpHostInterface { @JavascriptInterface fun postMessage(json: String) { val message = JSONObject(json) // 处理消息 } }

8. MCP Apps 的未来发展与社区资源

8.1 生态系统发展趋势

MCP Apps 生态系统正在快速发展，几个值得关注的趋势包括：

1. 组件库扩展：社区正在构建更丰富的预制组件库，覆盖更多使用场景
2. 开发工具增强：专门的 IDE 插件和调试工具正在涌现
3. 性能优化：新的渲染策略和资源加载机制不断被引入
4. 标准化进程：MCP Apps 正在成为更广泛采用的行业标准

8.2 学习资源推荐

要深入掌握 MCP Apps 开发，可以参考以下资源：

1. 官方文档： MCP Apps 标准文档
2. 示例仓库： GitHub 官方示例
3. 社区论坛： MCP 开发者社区
4. 视频教程：官方 YouTube 频道的入门系列
5. 书籍：《MCP Apps 高级开发指南》(预计2024年出版)

8.3 参与贡献

MCP Apps 是一个开源项目，欢迎社区贡献：

1. 代码贡献：从 GitHub 提交 Pull Request
2. 文档改进：帮助完善文档或翻译
3. 示例创作：分享你的实现案例
4. 问题报告：提交 Issue 帮助改进项目
5. 社区支持：在论坛帮助其他开发者

参与贡献不仅是回馈社区的好方式，也是深入学习技术的有效途径。