🌐 Affiliate Marketplace Connector (affiliate-marketplace-connector)

Affiliate Marketplace Connector (CLI: afflite, MCP: affiliate-marketplace-mcp) là trung tâm điều phối và máy chủ Model Context Protocol (MCP Server) chuyên dụng cho hệ sinh thái tiếp thị liên kết (Affiliate E-Commerce Intelligence) đa nền tảng (Shopee & TikTok Shop).

Hệ thống cho phép các AI Agents (Antigravity, Claude Code, Cursor, Codex, OpenClaw) tự động hóa toàn diện chu trình:

1. Tìm kiếm sản phẩm Win & phân cụm giá đa sàn.
2. Thẩm định uy tín & sức khỏe gian hàng (Merchant Health Score).
3. Bóc tách sâu thông số PDP & phân loại SKU qua drawer "Select options".
4. Chọn lọc 10+ reviews hạt giống chất lượng cao có video/ảnh phục vụ chuyển đổi (Seed Social Proof).
5. Sinh kịch bản video 45s & visual prompts chuẩn Google Flow (Veo 3.1).
6. Đóng gói trực tiếp thư mục dự án VideoFactory (AIEV / HyperFrames) có giao diện Web Preview thời gian thực.

📖 Xem Cẩm Nang Toàn Diện: Cẩm Nang MMO Tự Động Hóa Hàng Loạt & 5 JTBD Thực Chiến

---

🎯 5 Bản Đồ JTBD (Jobs-To-Be-Done) & Tư Duy MMO Tự Động Hóa 100x

Hệ thống được thiết kế xoay quanh 5 bài toán cốt lõi (Jobs-To-Be-Done) của người làm tiếp thị liên kết và MMO quy mô lớn:

JTBD	Tình Huống & Động Lực (Situation & Motivation)	Kết Quả Mong Đợi (Expected Outcome)	Lệnh Thực Thi (afflite)
1. Săn Sản Phẩm Win	Cần tìm sản phẩm hot, có volume bán cao và nằm trong vùng giá chốt đơn nhanh (150k - 500k).	Lọc ra top 5-10 sản phẩm có Affiliate Win Score > 9.0 trong 3 giây.	afflite search all "<keyword>"
2. Thẩm Định Gian Hàng	Tránh shop giao chậm, hàng nhái, tỷ lệ hủy đơn cao làm mất trắng hoa hồng.	Chỉ hợp tác với shop có Seller Health Score > 85/100, tỷ lệ giao đúng hạn >98%.	afflite seller [shopee|tiktok] "<shop>"
3. Bóc Tách Nỗi Đau & Reviews	Cần viết kịch bản đánh trúng tâm lý nhưng không có sản phẩm mẫu trên tay.	Tự động đào sâu 10-15 reviews thật có video/ảnh, gắn thẻ nỗi đau và lý do khách khen.	afflite product "<url>"
4. Sản Xuất Video 45s Hàng Loạt	Cần phủ 20-50 video/ngày lên ma trận kênh mà không tốn chi phí thuê diễn viên, quay dựng.	Sinh kịch bản 6 cảnh CRO kèm prompt Veo 3.1 và đóng gói thư mục VideoFactory AIEV.	afflite make-video "<product_id>"
5. Vận Hành Đa Tác Tử 24/7	Muốn hệ thống tự động chạy ngầm, scale không giới hạn nhân sự.	AI Agents tự động phối hợp qua 9 công cụ MCP JSON-RPC 2.0.	affiliate-marketplace-mcp

---

🏗 Kiến Trúc Hệ Thống (Architecture)

graph TD
    subgraph AI Clients & Agents
        AG[Google Antigravity] 
        CC[Claude Code / Desktop]
        CR[Cursor IDE / Codex]
        VF_API[VideoFactory Web Router]
    end

    subgraph MCP Server & Orchestration Layer
        MCP[affiliate-marketplace-mcp<br/>JSON-RPC 2.0 Stdio]
        CLI[afflite CLI Orchestrator]
    end

    subgraph Core Intelligence Engines
        ShopeeEngine[Shopee Research Suite]
        TikTokEngine[TikTok Shop Suite]
    end

    subgraph Data Processing & Scorer
        SearchCluster[Search & Price Clustering]
        SellerAuditor[Merchant Health & Trust Scorer]
        PDPExtractor[Deep PDP & SKU Options Extractor]
        ReviewCurator[Seed Review & Media Curator]
    end

    subgraph Storage & Export Pipeline
        DB[(SQLite Database<br/>products.db)]
        PromptGen[AI Video Storyboard & Veo 3.1 Engine]
        VFBridge[VideoFactory AIEV Bridge]
    end

    AG -->|MCP Tools/Call| MCP
    CC -->|MCP Tools/Call| MCP
    CR -->|MCP Tools/Call| MCP
    VF_API -->|Direct Call| CLI

    MCP --> ShopeeEngine
    MCP --> TikTokEngine
    CLI --> ShopeeEngine
    CLI --> TikTokEngine

    ShopeeEngine --> SearchCluster & SellerAuditor & PDPExtractor
    TikTokEngine --> SearchCluster & SellerAuditor & PDPExtractor

    SearchCluster & SellerAuditor & PDPExtractor & ReviewCurator --> DB
    DB --> PromptGen & VFBridge
    VFBridge -->|Generate Folder| VFBundles["VideoFactory Projects (/video-projects/<slug>)<br/>• meta.json • index.html • assets/hero.jpg • transcript_tts.txt"]

---

⚡ 9 Công Cụ MCP Native (tools/list)

Khi kết nối máy chủ MCP affiliate-marketplace-mcp, các AI Agent có quyền truy cập trực tiếp 9 công cụ:

Tên Công Cụ	Chức Năng	Tham Số Chính
search_affiliate_products	Tìm kiếm sản phẩm tiềm năng đồng thời trên Shopee & TikTok Shop, bung từ khóa và chấm điểm Win.	query (str), platform (all | shopee | tiktok)
audit_seller	Thẩm định uy tín gian hàng (Mall/Official), tỷ lệ giao hàng đúng hạn, tỷ lệ hủy đơn, mã giảm giá.	shop (str), platform (shopee | tiktok)
extract_product_intelligence	Bóc tách chi tiết thông số, 5 SKU từ drawer Select options và 10+ reviews có đính kèm video/ảnh.	url (str)
get_seed_reviews	Trích xuất reviews hạt giống đã phân loại theo Pain Points & Objections để làm bằng chứng xã hội.	product_id (str), has_media_only (bool), limit (int)
create_videofactory_project	Tạo trọn gói thư mục dự án VideoFactory (AIEV) chuẩn meta.json, index.html và kịch bản 6 cảnh CRO.	product_id (str), voice_engine (VieNeu-TTS | Gemini)
generate_video_storyboard	Sinh kịch bản video AI 45s (PAS/AIDA) kèm câu lệnh mô tả hình ảnh cực nét cho Veo 3.1.	product_id (str)
query_marketplace_database	Truy vấn trực tiếp kho dữ liệu SQLite products.db (sản phẩm, biến thể, gian hàng, video projects).	query_type (products | variants | reviews | shops | video_projects), limit (int)
marketplace_doctor	Chẩn đoán toàn diện sức khỏe hệ thống: SQLite database, VideoFactory engine, Chrome automation session, MCP configs.	{} (none)
marketplace_repair	Tự động sửa chữa bảng SQLite, phân quyền thư mục VideoFactory, và đồng bộ cấu hình MCP cho các AI client.	{} (none)

---

📦 Hướng Dẫn Cài Đặt (Installation)

1. Cài Đặt Mã Nguồn & CLI

# Clone repository từ GitHub
git clone https://github.com/tody-agent/affiliate-marketplace-connector.git
cd affiliate-marketplace-connector

# Cài đặt dạng package phát triển (Editable Mode)
pip install -e .

Sau khi cài đặt, hệ thống sẽ đăng ký sẵn các lệnh console vào Terminal:

• afflite: CLI tổng hợp quản lý affiliate đa sàn & VideoFactory.
• affiliate-marketplace-mcp: Máy chủ MCP JSON-RPC 2.0 qua Stdio.
• shopee-cli: CLI chuyên biệt cho Shopee Research & Cross-Audit.
• shopee-research: Bộ công cụ quét và trích xuất Shopee.
• tiktok-research: Bộ công cụ quét và trích xuất TikTok Shop.

---

2. Cấu Hình Biến Môi Trường (Tùy Chọn)

Hệ thống tự động sử dụng đường dẫn tương đối trong thư mục mã nguồn. Nếu muốn tùy biến, bạn có thể thiết lập:

# Đường dẫn file SQLite lưu trữ dữ liệu
export AFFLITE_DB_PATH="/path/to/your/data/products.db"

# Thư mục xuất dự án VideoFactory (AIEV)
export VIDEOFACTORY_PROJECTS_DIR="/path/to/your/VideoFactory/video-projects"

---

3. Đăng Ký MCP Server Cho Các AI Assistant

A. Cho Google Antigravity CLI

Thêm vào file cấu hình MCP của Antigravity (~/.gemini/antigravity-cli/mcp_config.json):

{
  "mcpServers": {
    "affiliate-marketplace": {
      "command": "affiliate-marketplace-mcp"
    }
  }
}

B. Cho Claude Desktop App

Thêm vào ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "affiliate-marketplace": {
      "command": "affiliate-marketplace-mcp"
    }
  }
}

C. Cho Cursor IDE

Thêm vào ~/.cursor/mcp.json hoặc mục Cursor Settings > MCP:

{
  "mcpServers": {
    "affiliate-marketplace": {
      "command": "affiliate-marketplace-mcp"
    }
  }
}

---

💻 Hướng Dẫn Sử Dụng CLI (afflite)

1. Tìm Kiếm Sản Phẩm Tiềm Năng (search)

# Quét cả 2 sàn Shopee & TikTok Shop
afflite search all "chuột công thái học"

# Quét riêng Shopee
afflite search shopee "bàn phím cơ không dây"

# Quét riêng TikTok Shop
afflite search tiktok "đèn rgb mini quay video"

2. Thẩm Định Uy Tín Gian Hàng (seller)

# Thẩm định gian hàng Shopee Mall
afflite seller shopee "Ugreen Official Mall"

# Thẩm định gian hàng TikTok Shop
afflite seller tiktok "Photoolex Official Store"

3. Bóc Tách Sản Phẩm & SKU Biến Thể (product)

# Tự động nhận diện Shopee hay TikTok Shop từ link hoặc ID
afflite product "https://shopee.vn/product-url"
afflite product "https://www.tiktok.com/view/product/1729463065317050819"

4. Chạy Toàn Bộ Chu Trình Tự Động (pipeline)

# Tự động bung từ khóa -> Lọc top sản phẩm -> Thẩm định Shop -> Bóc tách SKU & Reviews -> Lưu DB
afflite pipeline all "phụ kiện setup góc làm việc"

5. Sinh Kịch Bản Video & Tích Hợp VideoFactory (make-video)

# Xuất kịch bản 6 cảnh và prompt Veo 3.1 ra màn hình terminal
afflite video-prompt "shopee_ugreen_mouse_44426785177"

# Tạo trọn gói thư mục dự án VideoFactory (AIEV)
afflite make-video "tiktok_prod_1729463065317050819"

# Liệt kê danh sách tất cả các dự án VideoFactory đã sinh
afflite video-projects

6. Báo Cáo & Xuất Dữ Liệu (report / export)

# Xem báo cáo tổng hợp các sản phẩm và biến thể trong SQLite
afflite report

# Xuất dữ liệu kịch bản dạng Markdown hoặc JSON
afflite export "shopee_ugreen_mouse_44426785177" --format md

---

🐍 Sử Dụng Qua Python Code (Programmatic API)

from afflite import (
    run_shopee_search,
    run_shopee_seller,
    run_shopee_product,
    run_tiktok_search,
    run_tiktok_seller,
    run_tiktok_product,
    generate_video_prompt_package,
    get_connection
)
from afflite.video_factory_bridge import create_videofactory_project

# 1. Tìm kiếm sản phẩm TikTok Shop
tiktok_results = run_tiktok_search("đèn rgb mini nam châm")
print(f"Tìm thấy {tiktok_results['total_found']} sản phẩm tiềm năng.")

# 2. Bóc tách sản phẩm & reviews
prod_data = run_tiktok_product("https://www.tiktok.com/view/product/1729463065317050819")
print(f"Đã lưu sản phẩm: {prod_data['product_name']} (Điểm Win: {prod_data['win_potential_score']}/10)")

# 3. Tạo thư mục dự án VideoFactory
vf_project = create_videofactory_project(prod_data["product_id"])
print(f"Đã tạo VideoFactory Project tại: {vf_project['project_path']}")
print(f"Xem preview tại: {vf_project['web_ui_url']}")

---

🗄 Cấu Trúc Cơ Sở Dữ Liệu SQLite (products.db)

Hệ thống quản lý dữ liệu quan hệ theo chuẩn chuẩn hóa 3NF:

┌─────────────────────────┐       ┌─────────────────────────┐
│        products         │       │          shops          │
│─────────────────────────│       │─────────────────────────│
│ id (PK)                 │       │ shop_id (PK)            │
│ platform (Shopee/TikTok)│◄──┐   │ shop_name, username     │
│ shop_id (FK) ───────────┼───┼──►│ rating_star, followers  │
│ product_name, brand     │   │   │ response_rate, score    │
│ sale_price_min, max     │   │   └────────────┬────────────┘
│ total_sold, rating_score│   │                │
│ win_potential_score     │   │                ▼
└────────────┬────────────┘   │   ┌─────────────────────────┐
             │                │   │      shop_vouchers      │
             ├────────────────┼──►│─────────────────────────│
             │                │   │ voucher_code, discount  │
             ▼                │   └─────────────────────────┘
┌─────────────────────────┐   │   ┌─────────────────────────┐
│    product_variants     │   │   │     search_sessions     │
│─────────────────────────│   │   │─────────────────────────│
│ sku_name, color, price  │   │   │ id (PK), seed_idea      │
│ connectivity, status    │   │   └────────────┬────────────┘
└─────────────────────────┘   │                │
             │                │                ▼
             ▼                │   ┌─────────────────────────┐
┌─────────────────────────┐   │   │     search_results      │
│     product_reviews     │   │   │─────────────────────────│
│─────────────────────────│   │   │ keyword, price_tier     │
│ username, rating        │   │   │ affiliate_win_score     │
│ review_text, media_type │   │   └─────────────────────────┘
│ pain_point_tag, score   │   │
└─────────────────────────┘   │
             │                │
             ▼                │
┌─────────────────────────┐   │
│  ai_marketing_insights  │   │
│─────────────────────────│   │
│ target_audience, USP    │   │
│ hook_drama, PAS, AIDA   │   │
└─────────────────────────┘   │
             │                │
             ▼                │
┌─────────────────────────┐   │
│      product_media      │   │
│─────────────────────────│   │
│ source_url, local_path  │───┘
└─────────────────────────┘

---

❓ FAQ — Câu Hỏi Thường Gặp

Q1: Máy chủ MCP affiliate-marketplace-mcp chạy trên cơ chế gì?

Máy chủ sử dụng chuẩn Model Context Protocol (MCP) qua Stdio (JSON-RPC 2.0). Khi các AI Assistant (Antigravity, Claude, Cursor) khởi chạy, máy chủ tự động khởi tạo kết nối qua standard input/output mà không cần mở port mạng phụ trợ nào, đảm bảo bảo mật và tốc độ phản hồi tính bằng mili-giây.

Q2: Cơ chế bóc tách biến thể SKU trong "Select options" của TikTok Shop hoạt động thế nào?

TikTok Shop PDP ẩn biến thể đằng sau drawer tương tác "Select options". Hệ thống kích hoạt phiên Chrome Automation để mở drawer, giải mã cấu trúc giá theo từng phân loại (Combo, Màu sắc, Nguồn điện) và bóc tách đầy đủ giá sàn/giá trần vào bảng product_variants.

Q3: Thư mục dự án VideoFactory (AIEV) được tạo ra bao gồm những gì?

Khi chạy afflite make-video <product_id>, thư mục dự án được sinh tự động tại /Volumes/Agency/VideoFactory/video-projects/<slug> bao gồm:

• meta.json: Định dạng JSON tiêu chuẩn VideoFactory với 6 cảnh quay CRO (Hook, Problem, Reveal, USP, Social Proof, CTA).
• hyperframes.json & index.html: Cấu trúc đồ họa chuyển động HTML5/CSS3 HyperFrames 1080x1920 30fps.
• assets/hero.jpg: Ảnh gốc sắc nét của sản phẩm.
• assets/transcript_tts.txt: Lời thoại giọng đọc tiếng Việt theo từng mốc giây để đưa vào VieNeu-TTS / OmniVoice.

Q4: Làm thế nào để thay đổi file SQLite products.db khi chạy trên máy khác?

Bạn chỉ cần gán biến môi trường:

export AFFLITE_DB_PATH="/duong_dan_moi/products.db"

Toàn bộ CLI và MCP Server sẽ tự động trỏ đến đường dẫn mới mà không cần sửa code.

Q5: Điểm Affiliate Win Score và Seller Health Score được tính theo công thức nào?

• Affiliate Win Score (0 - 10): Tính dựa trên 4 trọng số: Lượt bán đã kiểm chứng (35%), Điểm đánh giá sao (25%), Vùng giá chốt đơn nhanh Impulse Buy 150k-500k (20%), và Gian hàng Shopee Mall / Official Shop (20%).
• Seller Health Score (0 - 100): Đánh giá dựa trên: Đánh giá trung bình sao (35đ), Tỷ lệ giao hàng đúng hạn (25đ), Tỷ lệ hủy đơn thấp dưới 1% (20đ), Tốc độ phản hồi chat & lượng Followers (20đ).

Q6: Có hỗ trợ câu lệnh sinh video cho Google Flow (Veo 3.1) không?

Có. Kịch bản 6 cảnh trong video-prompt và make-video được thiết kế đặc biệt với các visual prompts chi tiết (Extreme close-up, 3D panning, 8k photorealistic, lighting setup) tương thích 100% với Google Flow (gflow CLI Veo 3.1).

---

🧪 Kiểm Thử Tự Động (Unit Testing)

Chạy bộ test suite với 18 kịch bản kiểm thử:

python3 -m unittest discover tests

Kết quả:

..................
----------------------------------------------------------------------
Ran 18 tests in 4.228s

OK

---

📄 Bản Quyền & Giấy Phép (License)

Dự án được phân phối dưới giấy phép MIT License. Được phát triển và duy trì bởi tody-agent.