Quant-UX MCP Server

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（当前 ila2002@qq.com）登录，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_apply_changes	底层逃生舱：直接提交 raw delta 数组
quantux_health	健康检查

客户端接入配置

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 端点暴露在公网时，务必设置强 MCP_API_KEY，并建议在腾讯云安全组中将 8091 端口的来源限制为可信 IP
• Quant-UX 后端凭据（admin 账号）只在 MCP 服务器内部使用，不会泄露给调用方