# Webcake MCP — cầu nối lấy đơn/lead từ Webcake về Claude

Một dịch vụ nhỏ làm **2 việc trong 1**:

1. **Hứng webhook Webcake** tại `POST /webhook/webcake` — mỗi khi có đơn/lead trên landing
   page, Webcake bắn dữ liệu tới đây và nó lưu lại (SQLite).
2. **Cổng MCP** tại `/mcp` — để Claude Code đọc/tra cứu đơn đã lưu bằng các tool.

```
Webcake (form/đơn)  ──POST──►  dịch vụ này  ──►  Claude Code đọc qua MCP
   landing page              (hứng + lưu đơn)      list_orders / search_orders ...
```

> **Vì sao phải làm thế này?** Webcake **không có REST API kéo dữ liệu**. Thứ Webcake gọi là
> "Kết nối API" thực chất là **webhook đẩy ra một chiều**. Nên ta dựng một chỗ công khai để
> hứng, rồi cho Claude đọc từ đó.

## Các MCP tool

| Tool | Chức năng |
|------|-----------|
| `list_orders(limit, since, status, page_name, event)` | Liệt kê đơn mới nhất, có lọc |
| `get_order(order_id)` | Chi tiết 1 đơn (kèm payload gốc) |
| `search_orders(query, limit)` | Tìm theo SĐT / tên / email / mã đơn |
| `order_stats(since)` | Thống kê tổng & theo trạng thái |

---

## A. Chạy thử trên máy (local)

```bash
pip install -r requirements.txt
# đặt token tạm và chạy
set WEBHOOK_TOKEN=test123        # Windows CMD;  PowerShell: $env:WEBHOOK_TOKEN="test123"
uvicorn server:app --host 127.0.0.1 --port 8000
```

Mở `http://127.0.0.1:8000/` thấy dòng "Webcake MCP server OK" là chạy được.

---

## B. Deploy lên hosting (để Webcake bắn tới 24/7)

Webhook cần **URL công khai luôn bật**. Khuyến nghị host **luôn chạy** (đừng dùng gói "ngủ khi
rảnh" vì đơn đến lúc server đang ngủ có thể bị mất).

### Cách 1 — Railway (khuyến nghị, luôn chạy, dễ nhất)

1. Đẩy thư mục `webcake-mcp/` này lên một repo GitHub.
2. Vào [railway.app](https://railway.app) → **New Project → Deploy from GitHub repo** → chọn repo.
   Railway tự nhận `Dockerfile` và build.
3. Tab **Variables**, thêm:
   - `WEBHOOK_TOKEN` = một chuỗi bí mật dài (vd bấm tạo ngẫu nhiên).
   - `DB_PATH` = `/data/webcake.db`
4. Tab **Settings → Volumes**: tạo volume mount vào `/data` (để đơn không mất khi deploy lại).
5. Tab **Settings → Networking → Generate Domain** để lấy URL công khai, vd
   `https://webcake-mcp-production.up.railway.app`.

### Cách 2 — Render.com

Đã có sẵn `render.yaml`. Vào Render → **New → Blueprint** → trỏ vào repo. Render đọc file này,
tự tạo dịch vụ + volume + token. (Gói `free` sẽ ngủ khi rảnh — đổi sang `starter` nếu cần chắc.)

Sau khi deploy xong, URL của anh sẽ có dạng `https://<tên>.<host>`. Ghi nhớ 2 thứ:
- **Webhook URL**: `https://<tên>.<host>/webhook/webcake?token=<WEBHOOK_TOKEN>`
- **MCP URL**:     `https://<tên>.<host>/mcp`

---

## C. Cấu hình bên Webcake (đổ đơn về đây)

Theo tài liệu Webcake (Dashboard → Tích hợp → Tài khoản liên kết):

1. **Thêm cấu hình kết nối API**, dán vào ô **API URL**:
   ```
   https://<tên>.<host>/webhook/webcake?token=<WEBHOOK_TOKEN>
   ```
   (Token đã nằm trong URL nên **không cần** điền API Request Header.)
2. **Thêm cấu hình Form** và map các trường muốn gửi. Nên bật các trường:
   `name`, `phone`, `email`, `short_address`, `province`, `district`, `commune`,
   `page_name`, `location`, `status`, `display_id`, `inserted_at`,
   `utm_source`, `utm_medium`, `utm_campaign`, `variations` (sản phẩm — cần nối POS).
   *(Server tự nhận mọi trường; đây chỉ là các trường nó bóc tách sẵn để tra cứu.)*
3. **Kết nối cấu hình API với landing page** → chọn điều kiện đồng bộ
   (Hoàn thành form / Thanh toán thành công / …). Có thể thêm `&event=payment_success`
   vào cuối URL để phân biệt loại sự kiện.
4. Bấm gửi thử một đơn trên landing page rồi kiểm tra bằng `order_stats` (mục D).

---

## D. Nối vào Claude Code

Đây là **remote MCP** (qua HTTP). Đăng ký một lần:

```bash
claude mcp add --transport http webcake https://<tên>.<host>/mcp
```

Xong, trong Claude Code anh hỏi kiểu *"liệt kê 10 đơn mới nhất"*, *"tìm đơn của số 0901234567"*,
*"hôm nay có bao nhiêu đơn đã thanh toán"* — Claude sẽ gọi các tool tương ứng.

---

## Ghi chú

- **Token**: nếu để trống `WEBHOOK_TOKEN`, server sẽ nhận mọi webhook (không nên khi chạy thật).
- **Dữ liệu**: đây là bản sao để tra cứu; đơn gốc vẫn nằm trong Webcake/Pancake.
- **Bảo mật MCP**: bản này chưa đặt auth cho `/mcp` (chỉ dựa vào URL khó đoán). Nếu cần chặt
  hơn có thể thêm token cho MCP — hỏi để bổ sung.