mcp-playbook

name

mcp-playbook

description

Deep reference / playbook for correctly driving the crevideo-reach MCP — TikTok Shop affiliate (分销) work: tool map (79 tools), the 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, or handling DM / email conversations. Affiliate-only — campaign/marketing 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 (分销) only

The MCP exposes only affiliate/distribution features. 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. 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. 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 list's).
• DM conversations: list_conversations, get_conversation_messages, send_message (real outbound — text OR image; for images use image_path (a LOCAL file — only when the MCP runs on your machine, e.g. Claude Desktop) or image_base64 (raw/data-URL base64 — for hosted/web like claude.ai where the server can't read local files: read the image, pass it inline; big images blow the param limit so keep them small); by conversation_id OR unique_id='@handle' which auto-finds/opens the thread so it reaches creators not in the inbox; confirm), search_conversations (find an EXISTING DM by @handle; returns nothing ⇒ no thread yet ⇒ just send_message(unique_id='@handle'), it opens one), create_conversation (open a NEW conversation without sending, idempotent), list_conversation_groups (left-rail groups + counts), list_group_conversations (conversations in one group — use for "show unread DMs"), manage_conversation_groups (create/rename/delete a folder, move/remove a conversation — confirm).
• Email (10 tools, LIVE): list_email_conversations, get_email_detail, send_email, reply_email, manage_email_templates (CRUD), manage_email_drafts (CRUD), mark_email_as_read, move_emails_to_trash, manage_email_groups (folders — list/create/rename/delete/add/move/remove), manage_email_trash (list/restore/delete_permanently). send_email / reply_email are real outbound — confirm intent first.
• Samples (申样): manage_sample_auto_approval (get/update rules), manage_sample_applications (list/approve/reject the manual queue).
• Shops/products: list_shops, list_products, get_product_detail, list_creator_categories.

Renamed tools — never call the old names: list_email_templates → manage_email_templates with action:'list'; list_shop_orders → list_affiliate_orders; list_segments / list_journeys → manage_segment / manage_journey with action:'list' (list returns both official + custom entries).

The canonical create flow

Every automation create chains these 6 phases — don't jump to the final call:

1. Shop         → list_shops if user hasn't specified one
2. Product      → list_products, validate ACTIVATE status, pick commission rate
3. Category IDs → list_creator_categories if filter mentions categories by name
4. Preview      → preview_target_collab with filter + first_count → preview_token
5. Confirm      → show match count + 5 samples + warnings, ASK USER to confirm
6. Create       → create_* with preview_token + final params

Only skip a phase when the user explicitly supplied that data. Don't invent defaults for shop or products.

Creator source alternates (skip preview; need shop_cipher): source='manual' takes appoint_creator_list = TikTok handles (unique_id, @ ok) — the MCP resolves them to the right wire ID space automatically; unknown handles fail fast. 'list' / 'segment' / 'journey' take IDs from the matching manage_* list action; 'target_collab' (DM-only) re-targets a TC automation's creators; 'intelligent_recommend' (TC/combined only — needs a product) takes appoint_creator_list = creator_open_ids from recommend_creators (达人罗盘 / AI Creator Compass). clone_and_modify_automation is filter-source-only — manual-source automations can't be cloned, create anew.

Timing parameters (2026-06-11): tc_schedule/tc_delay_time/tc_time_unit (TC/combined — delay the TC entity creation), send_schedule/... (DM-only — delay the whole send), dm_schedule/... (combined — delay the DM part). All default immediate; 'delay' needs raw amount (NOT seconds) + unit. Follow-ups are delay-only (immediate removed from the product 2026-06-10; default 10 minutes after the previous message) — the initial message still sends immediately. Backend doesn't echo these inputs; verify via tasks[].pending_excute_time on the list row.

TC: two creation paths (NOT interchangeable)

Path	Entry	Produces	When
Automation-wrapper (default)	preview_target_collab → create_target_collab / create_tc_dm_automation	An automation that owns a TC — templates, follow-ups, schedule	User says "建一个推广 / 自动化 / outreach"
Direct entity	preview_target_collab_direct → create_target_collab_direct	A bare TC, no wrapper / DM / follow-ups; manage via update_target_collab_direct, cancel_target_collaboration, add_creator_to_target_collaboration	User has exact creator_open_ids (NOT user_ids, NOT handles) and wants the offer pushed now, or batch work via create_bulk_tc_operation

Direct-entity TCs don't appear in list_automations — list via list_target_collaborations. Wrapper TCs appear in both. Never control a wrapper TC with direct-entity tools — use clone_and_modify_automation / create_bulk_tc_operation.

🆕 update_target_collab_direct can full-replace the products (incl. commission), and creators (creator_open_ids) of a direct TC (mirrors the Edit-Collab drawer; only fields you pass change; message is NOT editable once created). Ad commission (广告佣金, shop_ads_commission_rate_pct 1-80 per product) is supported on create_target_collab / create_tc_dm_automation / update_target_collab_direct / bulk add_products — pass it alongside the standard commission for shop-ads accounts.

OC vs TC (scope mistake to avoid)

"公开合作 / open collab / 让达人主动申请" = OC (public offer, creators apply, you approve — no preview, no creator filter), NOT TC (you invite specific creators). For OC reporting use query_collaboration_performance with scope:'open'. OC sample policy lives in manage_open_collaboration_sample_rule; shop-wide OC defaults in manage_open_collaboration_settings.

Read-side: pick the right tool

Tool	Answers	When
list_automations	"What does the list look like?"	Browsing / finding an ID / filtering by status+type
get_automation_detail	"What is this configured to do + overall stats?"	Name/ID → config / shop / product / filter / overview
get_automation_task_results	"Who got reached, and what happened to each?"	Post-send per-creator status + failure reasons

• list_automations — always pass arrays for statuses / automation_types (scalar is silently ignored). Statuses: pending(=draft)/active/paused/completed/failed. Types: tc/dm/combined. Page ≤ 50, default 10. search_by:'no' matches automation_no; default matches name LIKE.
• get_automation_task_results auto-detects kind+task_id from automation_type — usually just pass automation_id. Draft automations return empty (start first).

Editing without recreate

• update_dm_automation_text — replace one text body in a running DM (text components only; image/product/collab → clone instead).
• create_bulk_tc_operation — 6 actions (add_creators / remove_creators / add_products / remove_products / edit_settings / cancel) batch-mutating the TC behind an automation. TC only — for DM-only automations, clone.
• get_dm_task_message_template — read the template a DM task actually used (diagnose "why did the wire body differ from my draft").
• Anything else (filter / schedule / follow-up structure / non-text component) → clone_and_modify_automation + delete_automation the old one.

High-leverage gotchas (memorize)

• FOUR creator ID spaces ⚠️ (the #1 cause of 101 "bad request"): user_id (numeric — detail / notes / find_similar seed / create_conversation / send_email) · record id (row UUID — tags / blacklist) · creator_open_id (long base64-ish — direct-TC flow only) · unique_id (TikTok handle — what humans type; appoint_creator_list + bulk creator_unique_ids take handles, MCP resolves internally). Rule of thumb: human inputs = handles, analytics = user_id, blacklist/tags = record id, direct-TC = open_id.
• Preview token: 10-min lifetime, one-shot (consumed even if the create later throws), scope-bound to shop+filter+first_count. If a create fails, re-run preview_target_collab before retrying — don't reuse the token.
• Product status = ACTIVATE only: creates hard-fail if any product isn't ACTIVATE (also the Copy-flow silently drops non-ACTIVATE products). Tell the user to reactivate; no workaround.
• *_increment fields are period TOTALS, not deltas — don't read them as growth % (legacy views only; TT-official rows use plain names like gmv/orders).
• TT-official lists use token pagination — tools return page_size rows (≤ 50) + a "Showing N of M" line. If output includes next_page_token, pass it back as page_token to continue; there is no numeric page param. Responses carry latest_available_date ("data as of") — data lags 1-2 days, a missing "today" is not zero performance. For list_affiliate_content, date params mirror brand-app's current performance-window request and are not guaranteed strict video_post_time filters until the backend changes.
• detail view rates are derived, not raw fields (mirrors the brand-app detail drawers): product detail = Sales (AOV=GMV÷orders) + Sales-by-channel (share%) + Traffic funnel (CTR=clicks÷impressions, conversion=orders÷clicks) + Ratings + Top contents/creators; video detail = Sales (GMV/GPM/items/customers) + Conversion funnel (exposure=impressions÷views, CTR-to-views=clicks÷views, conversion=units÷clicks) + ER=(likes+comments+shares)÷views + Audience. Don't look for a "conversion_rate" field — produce/cite the derived value.
• list_affiliate_orders needs target_collaboration_id (backend 504s without it). Cross-TC view: list_target_collaborations first → loop per TC. OC dimension not supported.
• Naming: names are server-allocated; user-facing names get an mcp_YYMMDDHHmm_ prefix. The TC "定向计划名称" is capped at 12 chars and sanitized to [A-Za-z0-9_]; pure-Chinese input falls back to the literal mcp (so multiple Chinese-named automations collide) — keep the part that lands in the automation name short ASCII.
• Paid-tier features: customer-advocates + contact-enrichment are yearly add-ons — a 403 / empty response usually means the account lacks the add-on, not a bug.

Anti-spam / advanced settings (DM & combined)

Param	Effect	Default
reply_handling: 'continue' | 'stop_on_reply'	stop pinging creators who replied	continue
skip_creators_with_prior_replies: bool	skip creators with prior replies	false
skip_messaged_within_days: number (0=off)	skip anyone messaged within N days	off

Message components (summary)

Each DM message is an array of components sent in order. 4 types: text (templated body), image (image_path local path for local MCP, or image_base64 raw/data-URL for hosted/web like claude.ai, ≤10 MB), product (product_id), collab (use_this_tc:true, combined-only — DM-only rejects it). Full wire formats, image OSS-upload mechanics, follow-up sequencing, and unsupported composite types → references/message-components.md.

Conversations + email

• DM: list_conversations / get_conversation_messages / send_message (real outbound — confirm). Triage by group: list_conversation_groups → list_group_conversations (don't client-side filter the flat list for "unread").
• 🚨 DMing a creator NOT in your inbox (not in list_conversations, search_conversations returns nothing, or you only have their @handle): "not in the inbox" means no DM thread exists yet — it does NOT mean they're unreachable. Just call send_message(unique_id='@handle', message_content=...) — it finds-or-opens the conversation and sends, all FREE (exactly the brand-app's "open a chat from the creator's profile"). You do NOT need to chain search_affiliate_creators → create_conversation → send yourself — the tool does it internally. Never stop at "can't find the conversation". (For just opening a thread without sending, create_conversation still exists.) Do NOT fall back to a manual-source create_dm_automation (spends 3 credits + creates a standing automation) for a single cold DM — that's only for bulk outreach.
• Email: thread_id = root_email_id (a per-message id returns code=-1); read get_email_detail before reply_email. send_email requires shop_id (auto-resolves single-shop). Templates are starting drafts, not verbatim sends. Both send tools need confirm:true.

Sample approval (申样)

manage_sample_auto_approval get/update sets the rule thresholds; manage_sample_applications list (needs shop_cipher) → approve / reject by apply_id clears what the rule didn't cover.

Safety defaults (do NOT change without explicit user intent)

• start_immediately defaults to false — only true on literal "立即启动/send now/start now/发吧". Treat true as destructive (messages go to real creators); confirm first.
• per_target_collaboration_creator_count defaults to 50; override only on explicit ask (bound-checked vs shop limit).
• has_free_sample defaults to false.
• Blacklist / segment / journey / creator-list mutations, sample approve/reject, OC removals, email/DM sends — all need confirm:true. Surface the plan, then wait.

Deep references (load on demand)

• references/filters.md — full preview_target_collab filter schema: every field shape, enum buckets, the ×100 / no-×100 rules, and a natural-language→filter example.
• references/message-components.md — the 4 component types' wire formats, image OSS upload, collab-card scope, unsupported composites, and follow-up sequence wire detail.
• references/debugging.md — the 3-layer (curl readback → wire capture → source read) debugging method, common error→cause table, Copy-flow template requirement, sample-approval radios, and the version-change history.