# 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`（当前 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`）

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