Mcp Playbook

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 → userid), find_similar_creators, recommend_creators (达人罗盘 — backend match-score recommendation by product), list_customer_advocates, manage_customer_advocates (6 actions — collect/collecthistory/setnotes/getdetail/listrecords/getoverview; no addtag), manage_contact_enrichment (addcreators 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 conversationid OR uniqueid='@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 (uniqueid, @ 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 = creatoropen_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 / findsimilar seed / createconversation / sendemail) · 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 = userid, 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

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crevideo
• Source: crevideo/crevideo-reach
• License: MIT
• Homepage: https://www.crevideo.com

Install and usage instructions live in the source repository linked above.