Expose a self-hosted 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`）

claude mcp add quantux \
  --transport http \
  --url http://124.222.27.183:8091/mcp \
  --header "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>" }
    }
  }
}

Codex CLI（`~/.codex/config.toml`）

[mcp_servers.quantux]
type = "http"
url = "http://124.222.27.183:8091/mcp"
headers = { "Authorization" = "Bearer <MCP_API_KEY>" }

任意 MCP 客户端（通用）

{
  "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），底部放一个"购物车"按钮，最后把按钮连到"购物车"屏幕。

本地开发 / 重新部署

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

README.md Unescape Escape

Quant-UX MCP Server

架构

已部署