内容
# UI5con 2026 MCP 应用示例
五个可运行的示例，用于学习 MCP 工具如何返回确定性、交互式的 UI。
示例从纯 HTML 进阶到 UI5 Web 组件、UI 集成卡片、UI5 校验工作流和主机编排的 SAP 传输数据。
本仓库包含可重用的示例代码和学习材料。演讲者笔记、演示文稿文件、编辑器特定的 MCP 配置、生成的输出、帮助脚本和原始测试套件不包含在此发布副本中。
## MCP 应用的作用
普通的 MCP 工具可以返回文本和结构化数据。MCP 应用添加了一个预建的 Web UI，主机会在沙盒 iframe 中渲染：
```text
用户请求某些内容
-> 模型选择 MCP 工具
-> 服务器返回内容 + 结构化内容
-> 工具元数据指向 ui:// 资源
-> 主机加载预建的 UI
-> 主机桥将工具结果传递给 iframe
-> 应用渲染结构化内容，并可能调用另一个工具
```
模型选择和连接工具；它不会为每个请求生成接口。
这种分离保持了 UI 的可预测性，并允许非 UI 主机回退到 `内容`。
## 学习路径
| 步骤 | 包 | 主要工具 | 演示内容 |
| --- | --- | --- | --- |
| 00 | [`00-html-time`](packages/00-html-time/README.md) | `show_time` | 最小的完整 MCP 应用和应用到服务器的回调。 |
| 01 | [`01-ui5-webc-project-overview`](packages/01-ui5-webc-project-overview/README.md) | `show_ui5_project_overview` | UI5 Web 组件、主机主题同步和结构化渲染。 |
| 02 | [`02-ui5-card-project-overview`](packages/02-ui5-card-project-overview/README.md) | `show_ui5_project_cards` | 声明式对象和列表 UI 集成卡片。 |
| 03 | [`03-ui5-lint-findings`](packages/03-ui5-lint-findings/README.md) | `show_ui5_lint_findings` | 实时开发工具、服务器组合、回调和窄文件写入。 |
| 04 | [`04-arc1-transport`](packages/04-arc1-transport/README.md) | `show_arc1_transport_list`, `show_arc1_transport` | 主机编排的 ARC-1 数据和确认门控 SAP 操作。 |
不熟悉 MCP 或 MCP 应用？请先阅读 [`LEARNING.md`](LEARNING.md)，然后按数字顺序阅读软件包的 README。
## 先决条件
- Node.js 22 和 npm。
- 支持 MCP 应用的主机，例如 Cursor、Claude Desktop 或 MCPJam。
- 安装 npm 依赖的网络访问。
- 示例 03 还使用 `npx` 启动 `@ui5/mcp-server`，并可以使用本地 `ui5lint` 回退。
- 示例 04 需要单独配置的 ARC-1 服务器来获取实时 SAP 数据。其 `demo-data/` 目录提供了一个明确标记的离线排练回退。
## 安装和构建
```bash
git clone https://github.com/marianfoo/UI5con_2026_MCPApps.git
cd UI5con_2026_MCPApps
npm ci
npm run build
```
构建有两个输出：
- Vite 将每个 iframe 应用捆绑到单个 `packages/<sample>/app/dist/index.html`。
- TypeScript 将 MCP 服务器编译到 `dist/`。
在更改应用或服务器源代码后重新构建。生成的构建输出被 Git 忽略。
## 连接 MCP 主机
### 标准输入/输出：所有示例
在浏览仓库时使用根聚合器：
```text
命令：node
参数：/绝对路径/到/UI5con_2026_MCPApps/dist/src/stdio.js
```
确切的配置屏幕因主机而异。此仓库不故意附带 `mcp.json`，因为绝对路径和本地服务器凭证是特定于机器的。
对于集中的演示，只需使用编译后的入口点公开一个示例：
| 示例 | 命令（在 `npm run build` 之后） |
| --- | --- |
| 00 | `npm run start:stdio:00` |
| 01 | `npm run start:stdio:01` |
| 02 | `npm run start:stdio:02` |
| 03 | `npm run start:stdio:03` |
| 04 | `npm run start:stdio:04` |
当主机自己启动进程时，使用相应的绝对 `dist/packages/<sample>/src/stdio.js` 路径配置 `node`，而不是手动运行 npm 命令。
### 可流式 HTTP
启动聚合服务器：
```bash
npm run start
```
然后将支持 HTTP 的客户端连接到：
```text
http://127.0.0.1:3000/mcp
```
每个包还有一个独立的 HTTP 命令，从 `npm run start:00` 到 `npm run start:04`；它们的端口分别是 `3010` 到 `3014`。
## 尝试的第一个提示
```text
调用 show_time。
```
```text
调用 show_ui5_project_overview。
```
```text
调用 show_ui5_project_cards。
```
```text
调用 show_ui5_lint_findings。
```
示例 04 需要 ARC-1 数据；其 README 包含完整的安全编排提示。
## 验证发布副本
基本的本地验证是：
```bash
npm ci
npm run build
```
对于 MCP 应用协议一致性，在一个终端启动聚合 HTTP 服务器，并在另一个终端运行 MCPJam 检查：
```bash
npm run start
npm run test:mcpjam
```
一致性验证协议行为，但不能保证在每个主机上实现相同的渲染或 CSP 行为。在您打算支持的主机上测试示例。
## 仓库结构
```text
packages/<sample>/
README.md 示例概念、流程、设置和实验
src/register.ts 工具、模式、ui:// 资源和结果构建器
src/<domain>.ts 类型、规范化、固定装置或清单
src/server.ts 独立流式 HTTP 入口点
src/stdio.ts 独立标准输入/输出入口点
app/index.html 固定的 iframe 文档
app/src/main.ts MCP 应用桥和渲染逻辑
app/src/styles.css 应用特定的表示
src/mcp-host.ts 共享服务器和资源管道
src/register-all.ts 聚合工具注册
src/server.ts 聚合 HTTP 服务器
src/stdio.ts 聚合标准输入/输出服务器
```
## 安全性和可移植性规则
- 将 `structuredContent` 视为类型化的应用程序合同，而不是生成的标记。
- 验证每个服务器工具输入，包括来自您自己的 iframe 的调用。
- 将凭证和系统连接保留在拥有它们的服务器上。
- 为不支持 MCP 应用的主机保留有用的 `content`。
- 请求 UI 实际需要的 CSP 域和 iframe 权限。
- 需要明确确认后果性写入。
- 在写入后重新读取权威数据，而不是信任乐观的 UI 状态。
- 分别测试严格和宽容的主机；MCP 兼容性并不使它们的浏览器沙盒策略相同。
## 技术
- [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps)
- [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk)
- [UI5 Web 组件](https://ui5.github.io/webcomponents/)
- [UI 集成卡片](https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/index.html)
- [UI5 MCP 服务器](https://www.npmjs.com/package/@ui5/mcp-server)
MCP 市场