Playbooks

Playbooks support two execution modes, each suited to different use cases:

• Instructions-mode — You provide natural language instructions and a list of allowed tools. When the playbook runs, the LLM reads the instructions and orchestrates the tool calls itself. Best for flexible, judgment-heavy workflows like audits and analyses.
• Steps-mode — You define a fixed sequence of tool calls with templated arguments. The engine executes each step deterministically and assembles a markdown report from the output template. Best for repeatable reports like morning briefings and weekly summaries.

Both modes support typed inputs (date, number, string), cross-step references via {{steps.<id>.text}}templates, and graceful degradation — steps that reference a module you haven't connected are skipped with a warning instead of failing the whole run.

Before you can create a playbook, make sure you have:

• At least one integration connected
• An API key generated
• Your AI client configured with your ShopMCP MCP URL

Once connected, ask your AI client to create a playbook. Example prompts:

• Create a playbook called Morning Briefing that pulls Shopify orders and GA4 traffic for today
• Build a weekly SEO audit playbook that checks GSC rankings and suggests content improvements
• Create a playbook that monitors Meta Ads creative fatigue and flags ads with declining CTR

The AI client calls the create_playbook MCP tool, which saves the playbook to your workspace. It appears in the dashboard immediately — no restart needed.

Every workspace can install ShopMCP's curated template library from /playbooks/templates with one click. The starter set covers the questions ecommerce teams ask every day:

• Morning Ecommerce Briefing — orders + traffic + top queries across all connected platforms
• Weekly Revenue Report — orders, GA4 attribution, GSC impressions
• Inventory Health — low stock across Shopify, Neto, BigCommerce, Magento
• SEO Content Gap Finder — GSC queries with high impressions but low CTR
• Ads Morning Dashboard — spend, ROAS, and top campaigns across Meta, Google, and TikTok Ads
• Creative Fatigue Audit — find ads with rising frequency and falling CTR
• Budget Pacing — project end-of-month ad spend at current run rate
• SEO Title Audit, Competitor Price Check, Weekly SEO Snapshot, and more

Playbooks are registered as MCP tools on every chat session. To run one, just ask your AI client:

• Run the morning ecommerce briefing
• Show me this week's revenue report

The AI client calls run_playbookwith the playbook's slug or id. For steps-mode playbooks, the engine executes each step, calls the referenced MCP tools, and returns a markdown report. For instructions-mode playbooks, the engine returns the instructions and allowed tools to the LLM, which then orchestrates the tool calls itself.

If a step references a module you don't have connected, the engine skips it and includes a warning in the output instead of failing the whole run.

Ask your AI client to modify an existing playbook:

• Update the Morning Briefing playbook to also include Meta Ads spend — calls update_playbook with partial changes (only the provided fields are updated)
• Delete the old SEO audit playbook — calls delete_playbook, which also removes all associated run history

You can also use list_playbooks and get_playbook to browse and inspect playbooks from within your AI client.

Playbooks are stored as JSON. Here are examples of both modes:

Instructions-mode — the LLM follows the instructions using the allowed tools:

json
{
  "name": "SEO Title Audit",
  "description": "Audit product SEO titles and suggest improvements.",
  "instructions": "1. Fetch products (up to the limit).\n2. Check each SEO title — flag missing, < 30 chars, or > 60 chars.\n3. Suggest improved titles.\n4. Present as a markdown table.",
  "tools": ["shopify_get_products"],
  "inputs": {
    "limit": { "type": "number", "label": "Product limit", "default": 50 }
  }
}

Steps-mode — the engine executes each step deterministically:

json
{
  "name": "Morning Ecommerce Briefing",
  "inputs": { "date": { "type": "date", "default": "today" } },
  "steps": [
    { "type": "tool", "id": "orders", "tool": "shopify_get_orders",
      "requiresModule": "shopify", "optional": true,
      "args": { "created_at_min": "{{inputs.date}}" } },
    { "type": "tool", "id": "traffic", "tool": "ga4_run_report",
      "requiresModule": "ga4", "optional": true,
      "args": { "dateRanges": [{ "startDate": "{{inputs.date}}" }],
               "metrics": [{ "name": "sessions" }] } },
    { "type": "tool", "id": "queries", "tool": "gsc_get_search_analytics",
      "requiresModule": "gsc", "optional": true,
      "args": { "startDate": "{{inputs.date}}", "rowLimit": 10 } }
  ],
  "output": { "format": "markdown",
    "template": "# Briefing — {{inputs.date}}\n\n## Orders\n{{steps.orders.text}}\n\n## Traffic\n{{steps.traffic.text}}\n\n## Search\n{{steps.queries.text}}" }
}

Step arguments can reference inputs via {{inputs.<name>}} and earlier step results via {{steps.<id>.text}} or {{steps.<id>.json.<path>}}. Mark steps as optional: true so they degrade gracefully when a module is not connected.

• Connect more integrations to unlock richer cross-platform playbooks. A Morning Briefing with Shopify + GA4 + GSC + Meta Ads gives a far more complete picture than any single source.
• Use instructions-mode for workflows that need judgment or analysis (audits, recommendations). Use steps-mode for repeatable data pulls (daily reports, weekly summaries).
• Add tags when creating playbooks (e.g. daily, seo, ads) so you can filter them in the dashboard.
• Mark steps as optional with optional: true so your playbook produces a partial report rather than failing when a module is not connected.

• Free tier: 5 saved playbooks per workspace, runs count against your daily 100 tool-call cap (each step is one call).
• Pro tier: 50 saved playbooks, runs count against the 10k/day workspace cap.
• Team tier: unlimited saved playbooks, runs count against the seat-scaled cap.