# 主应用：工具页 UI/UX

## 1. 页面定义

| 项目 | 内容 |
| --- | --- |
| 页面名称 | 工具 / MCP 工具管理 |
| 路由 | `/mcp` |
| 页面实现 | `app-instance/frontend/app/(app)/mcp/page.tsx` |
| 关键组件 | `MCPPage`、`Dialog`、`Tabs`、MCP 服务卡片、工具详情面板 |
| 核心任务 | 查看本地/在线 MCP 服务、新增服务、编辑服务、测试连接、删除服务、查看已发现工具 |
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |

## 2. 信息架构与组件层级

```text
AppShell
└── main.pt-16
    └── /mcp
        ├── Page Header
        │   ├── h1 Tools
        │   ├── Refresh
        │   └── Add tool server
        ├── Add / Edit MCP Dialog
        │   ├── ID
        │   ├── Tool timeout
        │   ├── Connection mode tabs
        │   │   ├── Remote MCP server
        │   │   │   ├── URL
        │   │   │   ├── Auth mode
        │   │   │   ├── AuthZ permissions preview
        │   │   │   └── Headers JSON
        │   │   └── Install and launch
        │   │       ├── Command
        │   │       └── Arguments
        │   └── Cancel / Save
        ├── Error Card
        ├── Tool kind tabs
        │   ├── Local tools
        │   └── Online tools
        └── Content grid
            ├── MCP service list
            │   ├── Selectable service content
            │   └── Edit / Test / Delete
            └── Tool details panel
                ├── Empty selection state
                ├── Empty tools state
                └── Tool cards
```

## 3. 布局与响应式规则

- 页面外层使用 `max-w-6xl`，移动端内边距为 `16px`，桌面端为 `24px`。
- 移动端头部按钮自动换行，`Refresh` 和 `Add tool server` 均为 `44px` 高度。
- 内容区默认单列；`xl` 以上变为左侧 MCP 服务列表、右侧工具详情双栏。
- MCP 服务卡片的可选中区域和编辑/测试/删除按钮分离，避免卡片 role button 内嵌按钮。
- 移动端服务卡片头部改为纵向布局，徽章不会挤出右侧边界。
- 长 ID、URL、command、Audience、Scopes、last error 和工具描述都在容器内换行。
- 新增/编辑弹窗限制在当前视口内，内容可滚动，底部 Cancel/Save 保持可达。
- 页面主要按钮、Tab 和服务选择区域均满足 `44px` 触控目标。

## 4. 操作与 UX 逻辑

| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
| --- | --- | --- | --- | --- |
| 刷新工具服务 | 点击 Refresh | 重新拉取 MCP servers、tools、AuthZ 状态 | 获取最新连接和工具发现状态 | 正常 |
| 切换本地/在线工具 | 点击 Local tools / Online tools | 切换服务列表，并清空右侧选中态 | 避免跨分类误看详情 | 正常 |
| 选择服务 | 点击服务卡片内容区域或键盘 Enter/Space | 卡片高亮，右侧显示对应工具 | 查看该 MCP 暴露的工具 | 正常 |
| 测试服务 | 点击 Test | 按钮显示 loading，成功后刷新状态 | 验证 MCP 当前可连接性 | 正常 |
| 新增远程服务 | 点击 Add tool server，填写 URL/Auth/Header，点击 Save | 校验 ID、URL、timeout、Headers JSON，成功后关闭弹窗并刷新 | 接入已部署 MCP 服务 | 正常 |
| 新增本地服务 | 弹窗中切换 Install and launch，填写 command/args，点击 Save | 校验 ID、command、timeout，成功后关闭弹窗并刷新 | 接入本地 stdio MCP 进程 | 正常 |
| 编辑服务 | 点击 Edit | 打开同一弹窗并带入原配置，保存后刷新 | 修改用户自定义 MCP 配置 | 正常 |
| 删除服务 | 点击 Delete，确认浏览器弹窗 | 确认后调用 delete，成功后取消选中并刷新 | 防止误删 MCP 配置 | 正常 |
| JSON 输入错误 | Headers JSON 非对象或语法错误 | 页面错误卡显示解析错误，弹窗保持打开 | 保留用户输入并指出修复方向 | 正常 |
| 加载失败 | servers 接口失败 | 显示错误卡，不阻断页面头部操作 | 明确异常原因并允许重新刷新 | 正常 |

## 5. 响应式测试矩阵

测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、输入、确认弹窗和截图。

| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
| --- | --- | --- | --- | --- |
| 本地服务详情 | `390×844` | 无 | 0 | 可选择服务、查看工具详情、测试连接 |
| 在线服务详情 | `390×844` | 无 | 0 | 超长 ID、URL、Audience、错误信息未撑破页面 |
| 加载错误 | `390×844` | 无 | 0 | 错误卡可读，头部操作仍可见 |
| 在线服务详情 | `320×568` | 无 | 0 | 窄屏卡片徽章和长字符串均正常换行 |
| 在线服务详情 | `390×844` | 无 | 0 | 手机竖屏可完成查看与操作 |
| 在线服务详情 | `844×390` 横屏 | 无 | 0 | 横屏无页面级横向滚动 |
| 在线服务详情 | `768×1024` | 无 | 0 | 平板单列布局稳定 |
| 在线服务详情 | `1365×900` | 无 | 0 | 桌面双栏布局正常 |

### 关键量化证据

- 本地工具页 QA 自动化用例 `4 passed`。
- 部署到 `terminaltest` 后，同一套工具页 QA 自动化用例 `4 passed`。
- 覆盖服务选择、工具详情、Tab 切换、Test、Add、Edit、Delete confirm、Refresh、JSON 错误和加载错误。
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
- 所有实测视口可见小触控目标数为 `0`。

## 6. 已修复问题

| 等级 | 问题 | 修复 |
| --- | --- | --- |
| P1 | `320px` 下在线服务卡片徽章、Audience 长字符串和错误信息横向越界 | 卡片头部移动端纵向布局，所有长字段加 `break-all/min-w-0` |
| P1 | 新增/编辑弹窗内容过高时 Save 按钮在移动端被挤出视口 | Dialog 限制 `max-height`、启用内部滚动，底部操作区 sticky |
| P1 | 删除 MCP 服务没有确认，误删风险高 | 删除前增加浏览器确认弹窗 |
| P2 | 服务卡片整体 `role=button` 内部嵌套 Edit/Test/Delete 按钮 | 改为内容区域可选中，操作按钮独立 |
| P2 | Refresh、Add、Local/Online tabs 和卡片操作按钮触控高度不足 | 统一提升到 `44px` |
| P2 | Headers JSON 错误只显示页面级错误，弹窗可能遮挡操作 | 错误卡可读，弹窗保持打开且操作按钮可达 |

## 7. 剩余观察项

- 本轮自动化使用模拟 MCP 与 AuthZ 数据；真实 MCP 连接超时、鉴权 403 和工具发现异常仍需在后续联测中观察。
- 当前删除使用浏览器原生确认弹窗，后续可统一为应用内确认 Dialog，以保持视觉一致性。