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)

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 → 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:

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.