Skip to main content
Glama
affiliate-marketplace-mcp

affiliate-marketplace-mcp

by tody-agent

🌐 Affiliate Marketplace Connector(affiliate-marketplace-connector)

Python Version License: MIT Tests Status MCP Server Platform Video Engine

Affiliate Marketplace Connector(CLI:afflite,MCP:affiliate-marketplace-mcp)是一个专为跨平台(Shopee 和 TikTok Shop)联盟营销生态系统(Affiliate E-Commerce Intelligence)打造的协调中心与 Model Context Protocol(MCP Server) 服务器。

该系统使 AI 智能体(Antigravity、Claude Code、Cursor、Codex、OpenClaw)能够自动化整个流程:

  1. 寻找赢家产品 并跨平台分析价格。

  2. 审核店铺信誉与健康度(Merchant Health Score)。

  3. 通过 "Select options" 抽屉 深度提取 PDP 参数并分类 SKU。

  4. 筛选 10+ 条高质量种子评论,包含视频/图片,用于转化(Seed Social Proof)。

  5. 生成符合 Google Flow(Veo 3.1) 标准的 45 秒视频脚本和视觉提示。

  6. 直接打包到 VideoFactory 项目目录(AIEV / HyperFrames),并带有实时 Web 预览界面。

📖 查看全面指南:MMO 批量自动化全面指南与 5 个实战 JTBD


🎯 5 张 JTBD 地图(Jobs-To-Be-Done)与 100 倍 MMO 自动化思维

该系统围绕联盟营销人员和规模化 MMO 从业者的 5 个核心问题(Jobs-To-Be-Done)设计:

JTBD

情境与动机(Situation & Motivation)

预期结果(Expected Outcome)

执行命令(afflite)

1. 寻找赢家产品

需要找到热门、销量高且处于快速下单价格区间(150k - 500k)的产品。

在 3 秒内筛选出 Affiliate Win Score > 9.0 的前 5-10 个产品。

afflite search all "<keyword>"

2. 店铺信誉审核

避免发货慢、假货、高取消率导致佣金流失的店铺。

仅与 Seller Health Score > 85/100、准时发货率 >98% 的店铺合作。

afflite seller [shopee|tiktok] "<shop>"

3. 痛点提取与评论

需要撰写直击心理的脚本,但手头没有产品样品。

自动深入挖掘 10-15 条带视频/图片的真实评论,标记痛点标签和客户拒绝原因。

afflite product "<url>"

4. 批量生成 45 秒视频

需要每天向渠道矩阵发布 20-50 个视频,且不承担演员、拍摄、剪辑成本。

生成 6 个 CRO 场景脚本,附带 Veo 3.1 提示,并打包到 VideoFactory AIEV 目录。

afflite make-video "<product_id>"

5. 24/7 多智能体运营

希望系统自动后台运行,不受人力限制地扩展。

AI 智能体通过 9 个 MCP JSON-RPC 2.0 工具自动协调。

affiliate-marketplace-mcp


Related MCP server: tiktok-viral-factory

🏗 系统架构(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 个原生 MCP 工具(tools/list)

当连接 MCP 服务器 affiliate-marketplace-mcp 时,AI 智能体可直接访问 9 个工具:

工具名称

功能

主要参数

search_affiliate_products

同时在 Shopee 和 TikTok Shop 上搜索潜在产品,基于关键词和 Win 评分。

query(str)、platform(all | shopee | tiktok)

audit_seller

审核店铺信誉(Mall/Official)、准时发货率、取消率、折扣代码。

shop(str)、platform(shopee | tiktok)

extract_product_intelligence

提取详细参数、从 Select options 抽屉中提取 5 个 SKU,以及 10+ 条带视频/图片附件的评论。

url(str)

get_seed_reviews

提取已按痛点与异议分类的种子评论,用作社会证明。

product_id(str)、has_media_only(bool)、limit(int)

create_videofactory_project

创建符合 VideoFactory(AIEV)标准的项目目录包,包含 meta.json、index.html 和 6 个 CRO 场景脚本。

product_id(str)、voice_engine(VieNeu-TTS | Gemini)

generate_video_storyboard

生成 45 秒 AI 视频脚本(PAS/AIDA),附带针对 Veo 3.1 的超精细图像描述提示。

product_id(str)

query_marketplace_database

直接查询 SQLite 数据库 products.db(产品、变体、店铺、视频项目)。

query_type(products | variants | reviews | shops | video_projects)、limit(int)

marketplace_doctor

全面诊断系统健康:SQLite 数据库、VideoFactory 引擎、Chrome 自动化会话、MCP 配置。

{}(无)

marketplace_repair

自动修复 SQLite 表、VideoFactory 目录权限,并为各 AI 客户端同步 MCP 配置。

{}(无)


📦 安装指南(Installation)

1. 安装源代码与 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 .

安装完成后,系统将注册以下控制台命令到终端:

  • afflite:跨平台联盟营销与 VideoFactory 综合管理 CLI。

  • affiliate-marketplace-mcp:通过 Stdio 的 MCP JSON-RPC 2.0 服务器。

  • shopee-cli:Shopee 研究与交叉审核专用 CLI。

  • shopee-research:Shopee 扫描与提取工具集。

  • tiktok-research:TikTok Shop 扫描与提取工具集。


2. 配置环境变量(可选)

系统自动使用源代码目录中的相对路径。如需自定义,可设置:

# Đườ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. 为各 AI 助手注册 MCP 服务器

A. 适用于 Google Antigravity CLI

将以下内容添加到 Antigravity 的 MCP 配置文件(~/.gemini/antigravity-cli/mcp_config.json):

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

B. 适用于 Claude Desktop App

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

C. 适用于 Cursor IDE

添加到 ~/.cursor/mcp.json 或 Cursor 设置 > MCP 菜单:

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

💻 CLI 使用指南(afflite)

1. 搜索潜在产品(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. 审核店铺信誉(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. 提取产品与 SKU 变体(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. 运行完整自动化流程(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. 生成视频脚本并集成 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. 报告与数据导出(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

🐍 通过 Python 代码使用(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']}")

🗄 SQLite 数据库结构(products.db)

系统按照 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)

Q1:MCP 服务器 affiliate-marketplace-mcp 的运行机制是什么?

服务器使用 Model Context Protocol(MCP) 标准,通过 Stdio(JSON-RPC 2.0) 运行。当 AI 助手(Antigravity、Claude、Cursor)启动时,服务器通过标准输入/输出自动建立连接,无需打开任何辅助网络端口,确保安全性和毫秒级响应速度。

Q2:TikTok Shop 的 "Select options" 中 SKU 变体提取机制如何运作?

TikTok Shop 产品详情页将变体隐藏在交互式 "Select options" 抽屉后面。系统激活 Chrome 自动化会话以打开抽屉,按分类(组合、颜色、电源)解码价格结构,并将完整的价格区间提取到 product_variants 表中。

Q3:生成的 VideoFactory(AIEV)项目目录包含哪些内容?

当运行 afflite make-video <product_id> 时,项目目录会自动生成在 /Volumes/Agency/VideoFactory/video-projects/<slug>,包含:

  • meta.json:符合 VideoFactory 标准的 JSON 格式,包含 6 个 CRO 拍摄场景(Hook、Problem、Reveal、USP、Social Proof、CTA)。

  • hyperframes.json 和 index.html:HTML5/CSS3 HyperFrames 1080x1920 30fps 动态图形结构。

  • assets/hero.jpg:产品的高清原始图片。

  • assets/transcript_tts.txt:按秒标记的越南语配音台词,用于导入 VieNeu-TTS / OmniVoice。

Q4:如何在其他机器上运行时更改 SQLite 文件 products.db?

只需设置环境变量:

export AFFLITE_DB_PATH="/duong_dan_moi/products.db"

所有 CLI 和 MCP 服务器将自动指向新路径,无需修改代码。

Q5:Affiliate Win Score 和 Seller Health Score 的计算公式是什么?

  • Affiliate Win Score(0 - 10):基于 4 个权重计算:已验证销量(35%)、评分星级(25%)、快速下单价格区间 150k-500k(20%)、以及 Shopee Mall / Official Shop 店铺(20%)。

  • Seller Health Score(0 - 100):基于以下评估:平均评分星级(35 分)、准时发货率(25 分)、低于 1% 的低取消率(20 分)、聊天响应速度与粉丝量(20 分)。

Q6:是否支持为 Google Flow(Veo 3.1)生成视频提示?

支持。video-prompt 和 make-video 中的 6 场景脚本专门设计了详细的视觉提示(Extreme close-up、3D panning、8k photorealistic、lighting setup),与 Google Flow(gflow CLI Veo 3.1)100% 兼容。


🧪 自动化单元测试(Unit Testing)

运行包含 18 个测试场景的测试套件:

python3 -m unittest discover tests

结果:

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

OK

📄 版权与许可证(License)

本项目根据 MIT License 许可证分发。由 tody-agent 开发和维护。

Available Tools

9 tools
audit_sellerA

Audit store metrics, fulfillment reliability (on-time dispatch rate, cancellation rate), seller health score (0-100), and vouchers on Shopee or TikTok Shop.

Inputs: shop (required), platform (required).

create_videofactory_projectB

Create a complete ready-to-render VideoFactory (AIEV) project folder at /Volumes/Agency/VideoFactory/video-projects/ with 6 CRO scenes, meta.json, and assets.

Inputs: product_id (required), voice_engine.

extract_product_intelligenceB

Extract full PDP specs, 5 SKU variants from 'Select options' drawer, pricing, and 10+ curated seed reviews with video/photo attachments into SQLite.

Inputs: url (required).

generate_video_storyboardB

Generate a 45s AI video storyboard with 6 structured scenes (Hook, Problem, Hero Reveal, USP, Social Proof, CTA) and Veo 3.1 visual prompts.

Inputs: product_id (required).

get_seed_reviewsA

Retrieve high-converting seed customer reviews from SQLite categorized by pain points, objections, and media attachments for video scripts.

Inputs: product_id (required), limit, has_media_only.

marketplace_doctorB

Diagnose system health across Database, VideoFactory engine, Chrome browser stream, and Multi-Agent MCP client registries.

Inputs: no named parameters.

marketplace_repairA

Automatically heal and repair SQLite tables, VideoFactory directory structures, permissions, and sync MCP configuration files across all clients.

Inputs: no named parameters.

query_marketplace_databaseB

Query local SQLite database /Volumes/Agency/Products/data/products.db to inspect products, variants, shops, or active video projects.

Inputs: limit, query_type.

search_affiliate_productsA

Search winning e-commerce products across Shopee and TikTok Shop Vietnam, expanding keywords and ranking by Affiliate Win Score.

Inputs: query (required), platform.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools target a distinct resource and action, and the descriptions make the search/extract/query pipeline fairly clear. The main ambiguity is between create_videofactory_project and generate_video_storyboard, and extract_product_intelligence vs get_seed_reviews, since both touch seed reviews/scenes.

    Naming Consistency4/5

    Most tools follow a clean snake_case verb_noun pattern (search, audit, extract, get, create, generate, query). marketplace_doctor and marketplace_repair break the pattern by leading with a domain noun instead of a verb, which is a minor consistency miss.

    Tool Count5/5

    Nine tools is within the well-scoped range and each tool earns a place in the product-research-to-video-generation workflow. The set is neither bloated nor too thin.

    Completeness4/5

    The surface covers the core lifecycle: discover product, audit seller, extract product/feedback data, query DB, generate storyboard/project, and diagnose/repair system health. Missing update/delete/publish/export operations are minor gaps since most data flows are one-way into SQLite and VideoFactory.

    Related MCP Connectors

    Related MCP Servers