172 lines
8.6 KiB
Markdown
172 lines
8.6 KiB
Markdown
# Quant-UX MCP Server
|
||
|
||
Expose a self-hosted [Quant-UX](https://github.com/KlausSchaefers/quant-ux)
|
||
prototyping instance to any MCP client (Claude Code, Codex CLI, Cursor,
|
||
DeepSeek Harness, ...) over **Streamable HTTP**.
|
||
|
||
## 架构
|
||
|
||
```
|
||
┌──────────────────────── 服务器 124.222.27.183 ────────────────────────┐
|
||
│ │
|
||
│ ┌───────────────┐ ┌────────────────┐ ┌──────────────────────┐ │
|
||
│ │ quantux-mcp │──▶│ quant-ux- │──▶│ quant-ux-backend │ │
|
||
│ │ :8091 (MCP) │ │ frontend :8082 │ │ :8080 (Java, REST) │ │
|
||
│ └───────────────┘ └────────────────┘ └──────────────────────┘ │
|
||
│ ▲ quantux_default 网络 │
|
||
└────────┼─────────────────────────────────────────────────────────────┘
|
||
│ HTTPS/HTTP + Bearer API Key
|
||
┌────┴─────┐ ┌─────────┐ ┌───────┐
|
||
│Claude Code│ │ Codex CLI │ │ ...任何 MCP 客户端 │
|
||
└──────────┘ └─────────┘ └───────┘
|
||
```
|
||
|
||
## 已部署
|
||
|
||
| 项目 | 值 |
|
||
|---|---|
|
||
| MCP 端点 | `http://124.222.27.183:8091/mcp` |
|
||
| 传输 | Streamable HTTP（MCP 协议 2025-11-25） |
|
||
| 鉴权 | `Authorization: Bearer <MCP_API_KEY>`（`.env` 中） |
|
||
| Quant-UX 账号 | 服务器以 `QUX_ADMIN_EMAIL` 自动登录；JWT 临近到期时线程安全刷新，agent 无需关心登录 |
|
||
| 容器 | `quantux-mcp`（docker compose，`restart: always`），接入 `quantux_default` 网络 |
|
||
|
||
## 工具清单（14 个）
|
||
|
||
| 工具 | 说明 |
|
||
|---|---|
|
||
| `quantux_login` / `quantux_register` | 登录 / 注册 Quant-UX 账号 |
|
||
| `quantux_list_apps` / `quantux_get_app` / `quantux_dump_app` | 列出 / 概览 / 原始模型 |
|
||
| `quantux_create_app` / `quantux_delete_app` | 创建 / 删除原型（默认 375×667，可设桌面尺寸） |
|
||
| `quantux_add_screen` | 添加屏幕（第一个自动成为起始屏） |
|
||
| `quantux_add_widget` | 添加组件：Box/Label/Button/TextBox/Password/TextArea/Image/Icon/HotSpot |
|
||
| `quantux_update_widget` / `quantux_delete_widget` | 修改样式/位置/文案 / 删除组件 |
|
||
| `quantux_connect_flow` | 画交互连线（点击 A 跳转 B） |
|
||
| `quantux_export_html` | **导出为单文件离线交互 HTML**（内嵌模型+图片，双击即用，**自动附带一致性验证结果**） |
|
||
| `quantux_verify_export` | **导出后跑完整一致性测试**（渲染/连线/跳转/控件/图表/表格/动画/类型覆盖，返回详细报告） |
|
||
| `quantux_apply_changes` | 底层逃生舱：直接提交 raw delta 数组 |
|
||
| `quantux_health` | 健康检查 |
|
||
|
||
## 一致性验证（quantux_verify_export）
|
||
|
||
每次导出后自动运行（quickjs 内执行引擎 + DOM 桩），检查项：
|
||
|
||
- **渲染**：起始屏组件数、屏幕层结构
|
||
- **连线**：连线驱动元素数、点击跳转（before→after 屏幕名）
|
||
- **控件**：输入可编辑、CheckBox 切换、下拉选项
|
||
- **数据组件**：图表 SVG 数、表格数、进度条/评分/步进器
|
||
- **动画**：屏幕过渡是否应用
|
||
- **覆盖**：组件类型分 supported / partial / unsupported
|
||
|
||
示例（GoAuto 导出自动验证结果）：`verdict=PASS, widgetCount=72, wiredCount=6, navigation=true`
|
||
|
||
命令行独立使用：`python quantux_verify.py --file export.html` 或 `--app <id>`
|
||
|
||
## 导出离线交互 HTML
|
||
|
||
任何原型都可以导出成一个**完全离线的单文件 HTML**（双击即可在浏览器里点击交互，无需服务器）：
|
||
|
||
- 通过 MCP：调用 `quantux_export_html(app_id)`，得到文件名
|
||
- 下载：使用 `quantux_export_html` 返回的短期、单文件范围下载地址；默认 10 分钟有效
|
||
- 或从服务器 `~/quantux-mcp/exports/` 目录直接取
|
||
- 已实测：CMAutoBuy（1366×768，194 组件，点击跳转正常）、GoAuto（商品列表→详情跳转正常）
|
||
|
||
支持组件：Box / Label / Button / TextBox / Password / TextArea / Image / Icon / HotSpot / CheckBox / RadioBox / Switch / ToggleButton / SegmentButton / SegmentPicker / DropDown；高级组件（图表、数据网格、逻辑块）以背景盒渲染。
|
||
|
||
**交互一致性（与 Quant-UX 线上模拟器对齐，jsdom 实测通过）**：
|
||
|
||
| Quant-UX 线上交互 | 导出 HTML | 状态 |
|
||
|---|---|---|
|
||
| 连线跳转（点击按钮→目标屏幕） | ✅ click 事件导航 | ✅ 一致 |
|
||
| 连线事件类型 | click / dblclick / mouseover | ✅ 一致 |
|
||
| 组连线（group→屏幕） | ✅ 组内任一组件触发 | ✅ 一致 |
|
||
| 输入框打字 / 密码框 / 日期 | ✅ 可输入（非只读） | ✅ 一致 |
|
||
| CheckBox / RadioBox / Switch 切换 | ✅ 点击切换选中态 | ✅ 一致 |
|
||
| DropDown 下拉选择 | ✅ 选项渲染+选择 | ✅ 一致 |
|
||
| ToggleButton / SegmentButton 按压 | ✅ 点击按压态 | ✅ 一致 |
|
||
| **屏幕动画**（fade/slide/zoom/grow + 时长/缓动） | ✅ CSS 过渡（读 screen.animation 配置） | ✅ 一致 |
|
||
| **图表** Bar / Line / Pie / Ring（MultiRing/StackedRing 近似） | ✅ 内联 SVG + 调色板 | ✅ 一致（数据格式 props.data 二维数组） |
|
||
| **表格**（表头+数据行，props.data CSV 格式） | ✅ HTML table | ✅ 一致 |
|
||
| **ProgressBar / Rating / Stepper / HSlider / VolumeSlider / LockSlider** | ✅ 渲染+交互 | ✅ 一致 |
|
||
| **IFrameWidget / NavBar / NavMenu / QDate / QDateDropDown / Tree / SortableList** | ✅ 基础渲染 | ✅ 一致 |
|
||
| **Repeater / DataList 模板重复**（rows/grid 布局、间距、自动分布） | ✅ 行×列重复渲染模板，每个副本可交互 | ✅ 一致（静态模式；数据绑定需后端时以行×列填充） |
|
||
| Rest / Script / LogicOr / 数据绑定（需后端） | 以背景盒渲染 | ❌ 离线无法支持 |
|
||
|
||
## 客户端接入配置
|
||
|
||
### Claude Code（`claude mcp add` 或项目 `.mcp.json`）
|
||
|
||
```bash
|
||
claude mcp add quantux \
|
||
--transport http \
|
||
--url http://124.222.27.183:8091/mcp \
|
||
--header "Authorization: Bearer <MCP_API_KEY>"
|
||
```
|
||
|
||
或 `.mcp.json`（项目根目录）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quantux": {
|
||
"type": "http",
|
||
"url": "http://124.222.27.183:8091/mcp",
|
||
"headers": { "Authorization": "Bearer <MCP_API_KEY>" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Codex CLI（`~/.codex/config.toml`）
|
||
|
||
```toml
|
||
[mcp_servers.quantux]
|
||
type = "http"
|
||
url = "http://124.222.27.183:8091/mcp"
|
||
headers = { "Authorization" = "Bearer <MCP_API_KEY>" }
|
||
```
|
||
|
||
### 任意 MCP 客户端（通用）
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"quantux": {
|
||
"type": "http",
|
||
"url": "http://124.222.27.183:8091/mcp",
|
||
"headers": { "Authorization": "Bearer <MCP_API_KEY>" }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
> `<MCP_API_KEY>` 见服务器 `~/quantux-mcp/.env`。
|
||
|
||
## Agent 使用示例
|
||
|
||
给 agent 的自然语言指令：
|
||
|
||
> 用 quantux 工具创建一个 375×667 的"购物 App"原型：先建应用，再加一个"商品列表"屏幕，放 3 个商品卡片（Box+Label），底部放一个"购物车"按钮，最后把按钮连到"购物车"屏幕。
|
||
|
||
## 本地开发 / 重新部署
|
||
|
||
```bash
|
||
cd ~/quantux-mcp
|
||
sudo docker compose up -d --build # 重建并启动
|
||
sudo docker compose logs -f quantux-mcp # 日志
|
||
sudo docker compose down # 停止
|
||
```
|
||
|
||
环境变量（`.env`）：
|
||
- `MCP_API_KEY`：调用方必须携带的 Bearer 密钥
|
||
- `QUX_ADMIN_EMAIL` / `QUX_ADMIN_PASSWORD`：启动时自动登录的账号
|
||
- `QUX_BASE_URL`：Quant-UX 前端地址（容器内默认 `http://quant-ux-frontend:8082`）
|
||
- `MCP_EXPORT_TOKEN_TTL_SECONDS`：导出文件短期下载令牌有效期，默认 600 秒，范围 60～3600 秒
|
||
|
||
## 安全提示
|
||
|
||
- MCP 端点暴露在公网时，**务必设置强 `MCP_API_KEY`**，并建议在腾讯云安全组中将 8091 端口的来源限制为可信 IP
|
||
- Quant-UX 后端凭据（admin 账号）只在 MCP 服务器内部使用，不会泄露给调用方
|
||
- 长期 `MCP_API_KEY` 只允许放在 Authorization 请求头；不得放入导出 URL、工单或日志。导出地址使用随机短期令牌，并且只允许下载对应的单个文件。
|
||
- 健康检查中的 `logged_in` / `token_valid` 表示 Quant-UX JWT 当前仍有效，`token_expires_at` 为 UTC 到期时间；不能再用“Token 字符串存在”代替有效登录。
|