/mcp-playbook

name: mcp-playbook
description: >-
  Deep reference / playbook for correctly driving the crevideo-reach MCP — TikTok Shop affiliate (分销) and affiliate (分销) work:
  tool map (79 tools), the affiliate create flow, TC automation-wrapper vs direct entity, Open Collaboration (OC),
  read-side tool choice, filter schema, ID-space gotchas, message components, naming, reporting gotchas,
  sample approval, email centre, and debugging. Use when creating/listing/debugging outreach automations
  (TC / DM), running Open Collaborations, pulling affiliate analytics (collaboration / product /
  shoppable-video GMV / orders), managing affiliate creators (list / detail / blacklist / tags / lists /
  segments / journeys), discovering creators, approving sample requests, handling DM / email conversations,
  Campaign/marketing remains out of scope. Triggers on
  自动化/目标合作/公开合作/给达人发消息/发邮件/分销报表/分销订单/
  GMV/达人表现/我的达人/找达人/黑名单/分群/申样/私信 and the English equivalents.

Crevideo Reach MCP — Playbook

> **Output language**: respond in the merchant's working language — Chinese for China-POP sellers (分级 / 真实抽成 / 触达阶梯 …), English for US sellers (tier / all-in take-rate / outreach waterfall …). Tool names stay identical in both.

The **deep-reference layer** for the `crevideo-reach` MCP server. The MCP itself ships a baseline tool-map + typical flow via `SERVER_INSTRUCTIONS`; this skill covers what that baseline can't — the create flow, non-obvious constraints, and how to debug when behavior diverges from the brands-app UI.

> **Source of truth**: if anything here disagrees with the **live tool list** in the running session, the **live tools win** (this doc can lag the MCP version). Only call tools that actually exist in the session; never assume historical or future tools.

When NOT to use

• Pure MCP-protocol or Claude-skill mechanics questions → wrong skill.
• Nothing about automations, creators, affiliate analytics, TikTok Shop, or the reach area → don't invoke.

Scope: affiliate (分销)

The MCP exposes affiliate/distribution features. Product onboarding tools are temporarily hidden. Campaign/marketing surfaces (campaign management, `/report/*` campaign reports, creator **marketplace** discovery, custom products, brand sampling) are **not** tools here — say they're out of scope. `query_*_performance` covers **collaboration / affiliate-product / shoppable-video** (affiliate), not campaign reports. There is **no** natural-language→filter and **no** copy-polish endpoint — **you (the LLM) translate the user's words into structured filters yourself**, and you write/edit message copy yourself.

Tool map (79 tools, 15 groups)

Many tools **fold multiple endpoints behind a `view` / `action` / `scope` / `op_type` param** — pass those to drill in; don't expect one tool per endpoint.

• **Automations (💳 on create):** `list_automations`, `get_automation_detail`, `get_automation_task_results`, `preview_target_collab` (free, 10-min token), `create_target_collab`, `create_dm_automation`, `create_tc_dm_automation`, `clone_and_modify_automation`, `start_automation` / `pause_automation` / `delete_automation`, `update_dm_automation_text`, `create_bulk_tc_operation`, `manage_message_templates`, `get_dm_task_message_template`.
• **TC direct entity (no automation wrapper):** `list_target_collaborations`, `get_target_collaboration_detail`, `preview_target_collab_direct`, `create_target_collab_direct`, `update_target_collab_direct`, `cancel_target_collaboration`, `add_creator_to_target_collaboration`. See "TC: two creation paths" below.
• **Open Collaboration (OC):** `list_open_collaborations`, `get_open_collaboration_detail`, `create_open_collaboration`, `modify_open_collaboration`, `remove_open_collaboration`, `manage_open_collaboration_settings` (get/edit), `manage_open_collaboration_sample_rule` (get/edit), `remove_creator_from_open_collaboration`, `list_not_added_open_collaboration_products`, `get_open_collaboration_product_count`, `get_open_collaboration_status_counts`.
• **Reporting (read-only, 3 tools):** `query_collaboration_performance` (`scope`: target/open/both), `query_product_performance`, `query_shoppable_video_performance`. Product/video breakdown/detail views run on **TT-official REAL-TIME data** (matches the brand-app page; video adds GPM + daily avg customers, product AOV is derived GMV÷orders); overview/trend stay on legacy aggregates — small drift between the two is expected, explain it rather than "fix" it. Breakdown lists use cursor pagination: pass each returned `next_page_token` back unchanged as `page_token`; the legacy `page` number does not advance them. **There is NO `query_ai_insight` tool — produce insight yourself by reading these three reports.**
• **Affiliate orders:** `list_affiliate_orders` (TC dimension — the canonical "我分销卖了多少" answer; `target_collaboration_id` REQUIRED), `list_customer_creator_orders` (🚨 naming trap — CA dimension, NOT distribution GMV).
• **Creators:** `list_affiliate_creators`, `get_creator_detail`, `manage_creator_blacklist` (list/add/remove/modify), `update_creator_metadata`, `manage_segment`, `manage_journey`, `manage_creator_lists`, `get_creator_list_overview`, `search_affiliate_creators` (filters **or `creator_keyword` to resolve a @handle → user_id**), `find_similar_creators`, `recommend_creators` (达人罗盘 — backend match-score recommendation by product), `list_customer_advocates`, `manage_customer_advocates` (6 actions — collect/collect_history/set_notes/get_detail/list_records/get_overview; no add_tag), `manage_contact_enrichment` (add_creators is a source switch: manual/filter/list/segment/journey/target_collab).
• **Content:** `list_affiliate_content` (TT-official REAL-TIME published videos — needs `shop_cipher`, optional date range/`account_type`/`page_token`; pass returned `next_page_token` back as `page_token` to continue), `get_affiliate_content_products`, `manage_affiliate_content` (list/add_notes — legacy row ids; use its ids for notes, not the real-time li