Apify Ecommerce

E-Commerce Cluster

Answer natural language e-commerce questions by routing to the right Apify Actor and delivering a synthesized answer.

Prerequisites

(No need to check it upfront)

• .env file with APIFY_TOKEN
• Node.js 20.6+ (for native --env-file support)
• mcpc CLI tool: npm install -g @apify/mcpc

Workflow

Copy this checklist and track progress:

Task Progress:
- [ ] Step 1: Detect intent and select Actor
- [ ] Step 2: Fetch Actor schema via mcpc
- [ ] Step 3: Ask user preferences (format, result count)
- [ ] Step 4: Run the Actor
- [ ] Step 5: Analyze results and deliver synthesized answer

Step 1: Detect Intent and Select Actor

Classify the user's message into an intent, then pick the right Actor.

Intent signals:

If multiple intents are detected, ask: "Do you want [intent A] or [intent B]?"

Actor routing table — always try Primary first, switch to Fallback only if it fails or returns 0 results:

Step 2: Fetch Actor Schema

Fetch the Actor's input schema dynamically using mcpc:

export $(grep APIFY_TOKEN .env | xargs) && mcpc --json mcp.apify.com --header "Authorization: Bearer $APIFY_TOKEN" tools-call fetch-actor-details actor:="ACTOR_ID" | jq -r ".content"

Replace ACTOR_ID with the selected Actor (e.g., apify/e-commerce-scraping-tool).

This returns:

• Actor description and README
• Required and optional input parameters
• Output fields (if available)

Step 3: Ask User Preferences

Before running, ask:

1. Output format:
   • Quick answer (default) — synthesized answer in chat, no file saved
   • CSV — full export saved to disk
   • JSON — full export saved to disk
2. Result count — suggest defaults by intent:

Step 4: Run the Actor

Quick answer (display in chat, no file):

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT'

CSV:

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_filename.csv \
  --format csv

JSON:

node --env-file=.env ${CLAUDE_PLUGIN_ROOT}/reference/scripts/run_actor.js \
  --actor "ACTOR_ID" \
  --input 'JSON_INPUT' \
  --output YYYY-MM-DD_filename.json \
  --format json

Step 5: Analyze Results and Deliver Answer

After the run completes, deliver a direct synthesized answer — not a data dump:

• Pricing: price range, average, top 5 cheapest with URLs
• Reviews: average rating, top 3 positive and negative themes, recent snippets
• Bestsellers: top 10 by rank with name, price, rating, URL
• Sellers: total sellers, price range per seller, unauthorized seller flags
• Store-scrape: total products, category breakdown, price range, stock summary
• Tech-stack: platform detected, confidence level, notable plugins
• Food delivery: restaurant count, average rating, price tier breakdown
• Ads intelligence: total ads, active/inactive split, top creative formats

Error Handling

APIFY_TOKEN not found — Ask user to create .env with APIFY_TOKEN=your_token mcpc not found — Ask user to install: npm install -g @apify/mcpc Actor not found — Check Actor ID spelling in routing table Run FAILED — Ask user to check the Apify console link in error output Timeout — Reduce result count or increase --timeout No results — Broaden keyword or switch to Fallback Actor from routing table proxy is required — Add "proxy": {"useApifyProxy": true} to input Platform not detected — Default to apify/e-commerce-scraping-tool with generic intent