# 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 字符串存在”代替有效登录。