---
name: mcp-app-ui-development
description: 开发、修改、重构和评审本仓库的 MCP App UI，并在每次界面改动后生成与真实实现同步的可交互内联预览。用于涉及 src/mcp-apps、MCP App HTML/CSS、交互状态、响应式布局、视觉验收、商店/闪卡/时间线 App 界面，或用户要求先可视化再验收的任务。
---

# MCP App UI 开发

## 交付契约

把“真实 UI 改动”和“对话内可交互预览”视为同一个交付物。修改界面后不得只描述结果，也不得要求用户打开 Claude Desktop 才能做常规视觉检查。

每次 UI 改动必须完成：

1. 修改仓库中的真实 MCP App。
2. 更新相关回归测试和文档。
3. 生成与当前实现一致的可交互预览。
4. 在同一轮最终回复中直接展示预览。

## 工作流程

### 1. 读取真实实现

先检查与任务相关的文件，不要另造一套平行 UI：

- `src/mcp-apps/index.ts`：界面结构、状态和交互。
- `src/mcp-apps/style.css`：样式、动画和响应式布局。
- `src/core/mcp-apps.ts`：App resource 与工具元数据。
- `tests/unit/core/mcp-app-*-source.test.ts`：UI 源码契约。
- 对应工具 handler：确认结构化响应与动作语义。

保留用户现有改动。先理解状态流，再调整视觉层。

### 2. 明确交互语义

在编码前确定：

- 谁执行动作、谁收到结果。
- 初始、加载、成功、失败和空状态分别显示什么。
- 主交互触发的服务端 action、余额或数据变化、动画终点。
- 连续操作时状态是覆盖、排队还是累积。

文案和动画必须与真实业务方向一致。例如“机器出货给用户”不能表现成“角色收到礼物”。

### 3. 修改真实 MCP App

- 保持 App 自包含，遵守 MCP App CSP；没有明确需要时不依赖外部资源。
- 优先使用语义化 HTML、CSS 和内联 SVG；代码原生视觉不要调用位图生成。
- 保持键盘可操作、`aria-live` 状态反馈和 `prefers-reduced-motion` 降级。
- 至少覆盖常规宽度与窄屏布局，避免文字、按钮、动画或弹层溢出。
- App 内部调用聚合工具时保持现有 action 模型，不为视觉需求拆工具。

### 4. 添加验证

针对改动补充最小而明确的契约测试，重点验证：

- 关键结构和状态反馈存在。
- 已移除的旧角色、旧文案或旧交互不会回归。
- 动画与购买/提交等主动作对应。
- 不会产生多余工具调用或重复 MCP App。

先运行针对性测试：

```bash
pnpm exec vitest run tests/unit/core/mcp-app-*-source.test.ts
pnpm build:mcp-app
```

涉及服务端嵌入时再运行：

```bash
pnpm build:server
```

根据风险决定是否运行 `pnpm test`。不要把构建产物当源文件编辑。

### 5. 生成可交互预览

必须完整读取并遵守当前环境的 `visualize` skill，然后执行以下要求：

- 在当前线程明确可写的 visualization 目录创建 HTML fragment；禁止硬编码历史会话路径。
- 预览必须镜像刚完成的真实 DOM、CSS、文案、数据和主要交互，不能展示尚未实现的概念稿。
- 使用真实形状的示例 payload。需要 Host 或 MCP 调用的行为，只在预览中做等价的本地状态模拟。
- 主按钮必须可点击，并展示余额变化、成功/失败反馈、连续操作和关键动画。
- 预览保持自包含，不使用 `fetch`、XHR 或 WebSocket。
- 使用 visualize skill 的 `render.py` 包装检查 HTML，并确认没有字面量 `\"` 或 `\n`。
- 至少检查约 736px 和 360px 两种宽度；发现溢出、遮挡或不可读时先修复真实 UI，再同步预览。
- 最终回复必须包含该轮预览的 `visualize` 内容引用。

预览是验收面，但不替代真实代码、构建或测试。

## 最终回复

简洁说明已经实现的行为、用户可在预览中点击什么以及验证结果，然后直接展示预览。不要让用户为了判断布局、角色或动画是否合适而先重启 Claude Desktop。

只有涉及真实 MCP Host 集成、缓存或协议行为时，才把 Claude Desktop 作为最后一道集成验收。