claude-product-comparison

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# Product Comparison - Index & Navigation

## Quick Links
- [CLAUDE.md](https://github.com/lola69160/claude-product-comparison/blob/HEAD/CLAUDE.md) - Instructions projet, persona, guidelines
- [Démarrage Rapide](#démarrage-rapide)
- [Skills Disponibles](#skills-disponibles)
- [MCP Apify](#mcp-apify-scraping)
- [Catégories Produits](#catégories-produits-supportées)
- [Exemples](#exemples-dutilisation)

---

## Démarrage Rapide

### Première Comparaison (20-25 min)
```bash
cd product-comparison
claude ""
```

**Workflow automatique**:
1. Validation produits (30 sec)
2. Recherche parallèle 2 subagents (18 min)
3. Génération rapport (5 min)
4. Output: `reports/comparison_DysonV15_vs_SharkStratos_20250115.md`

### Comparaison Cachée (3-5 min)
```bash
# Si produits déjà recherchés < 7 jours
claude "Compare Dyson V15 vs Shark Stratos"
# → Utilise cache, génère rapport directement
```

---

## Navigation Structure

### 1. Configuration (`.claude/`)
| Fichier | Description |
|---------|-------------|
| `settings.json` | Config projet (subagents, hooks, cache) |
| `config.json` | Custom parameters (skills, subagents, logging) |
| `hooks/pre_research.js` | Validate produits avant recherche |
| `hooks/post_collection.js` | Validate qualité données collectées |
| `dev_docs/` | Context, plan, tasks (project memory) |
| `logs/` | Logs execution, erreurs, métriques |

### 2. Skills (`skills/`)
| Skill | Type | Durée | Description |
|-------|------|-------|-------------|
| **product-research-orchestrator** | orchestration | 20-25 min | Coordonne workflow complet, spawn subagents |
| **specs-collector** | data_collection | 2-5 min | Collecte specs depuis manufacturer + Amazon + review sites |
| **reviews-aggregator** | data_collection | 8-10 min | Agrège Amazon + Reddit + experts, analyse sentiment |
| **pricing-tracker** | data_collection | 2-3 min | Track prix multi-retailers, availability |
| **report-generator** | synthesis | 5 min | Génère rapport markdown professionnel |

Détails: `skills/{skill-name}/SKILL.md` (metadata) + `helpers/` (workflows)

### 3. Subagents (`subagents/`)
| Template | Usage | Isolation |
|----------|-------|-----------|
| **product-researcher.md** | Recherche 1 produit (specs + reviews + pricing) | Strict (own context, own folder) |

**Parallélisation**: 2 subagents simultanés (1 par produit) → 2× speedup

### 4. Data (`data/`)
| Dossier | Contenu | TTL |
|---------|---------|-----|
| `category_specs.yaml` | Specs requises par catégorie (électroménager, auto, sport, vélo) | - |
| `cache/specs/` | Specs cachées | 7 jours |
| `cache/reviews/` | Reviews cachées | 7 jours |
| `cache/pricing/` | Pricing caché | 7 jours |
| `research_{timestamp}/` | Résultats recherche session | - |
| `archive/` | Recherches > 30 jours | - |

**Cache strategy**: Check cache avant chaque fetch → 6× speedup si cache hit

### 5. MCP Apify (`.mcp.json`)
| Outil | Usage | Output |
|-------|-------|--------|
| `mcp__apify__apify-slash-rag-web-browser` | Recherche Google + scraping | Markdown |
| `mcp__apify__call-actor` | Appeler Actors spécialisés | JSON structuré |
| `mcp__apify__get-actor-output` | Récupérer résultats Actor | JSON dataset |
| `mcp__apify__search-actors` | Chercher Actors Apify Store | Liste Actors |

**Actors recommandés**:
- `apify/amazon-product-scraper` - Specs + prix Amazon
- `apify/amazon-reviews-scraper` - Reviews Amazon (50+)
- `apify/reddit-scraper` - Posts/comments Reddit

**Stratégie**: MCP Apify (primary) → WebFetch (fallback)

### 6. Rapports (`reports/`)
Format: `comparison_{product1}_vs_{product2}_{timestamp}.md`

**Sections**:
1. Executive Summary
2. Specs Comparison (side-by-side table)
3. Avis Utilisateurs (Amazon, Reddit)
4. Tests Experts (consensus sites spécialisés)
5. Pricing & Availability
6. Verdict par Use Case (budget, performance, beginner)
7. Tableau Récapitulatif
8. Sources

---

## Skills Disponibles

### orchestrator (Skill Principal)
**Pattern**: `compare {product1} vs {product2}`

**Commandes**:
- `compare Dyson V15 vs Shark Stratos`
- `research products iPhone 15 Pro, Samsung Galaxy S24`
- `analyse Décathlon Riverside 500 vs B'Twin Triban 520`

**Workflow**:
1. Valide produits existent
2. Check cache (7j)
3. Spawn 2 subagents parallèles
4. Agrège résultats
5. Trigger report-generator

### specs-collector
**Pattern**: `collect specifications for {product}`

**Sources**: Manufacturer site + Amazon + Review site (category-specific)

**Output**: `specs.json` (9-10 specs selon catégorie)

### reviews-aggregator
**Pattern**: `aggregate reviews for {product}`

**Sources**:
- Users: Amazon (ratings, reviews) + ReCompare Dyson V15 vs Shark Stratosddit (mentions)
- Experts: 2-3 sites selon catégorie

**Output**: `reviews_summary.json` (pros, cons, sentiment, overall_score)

### pricing-tracker
**Pattern**: `track pricing for {product}`

**Retailers**: Amazon + 2-3 sites catégorie

**Output**: `pricing.json` (prix, availability, best_price)

### report-generator
**Pattern**: `generate comparison report`

**Input**: All collected data (specs, reviews, pricing for 2 products)

**Output**: Rapport markdown professionnel

---

## Catégories Produits Supportées

### Électroménager
**Exemples**: Aspirateurs, cafetières, robots cuisine, lave-linge
**Specs**: puissance_W, capacité_L, niveau_bruit_dB, conso_energie, poids_kg
**Review sites**: consumerreports.org, wirecutter.com, lesnumeriques.com
**Retailers**: amazon.fr, boulanger.com, darty.com

### Auto
**Exemples**: Voitures neuves/occasion, motos
**Specs**: motorisation, puissance_ch, conso_L_100km, coffre_L, prix_base
**Review sites**: caradisiac.com, largus.fr, automobile-magazine.fr
**Retailers**: leboncoin.fr, lacentrale.fr, autoscout24.fr

### Sport
**Exemples**: Chaussures running, équipement fitness, outdoor
**Specs**: poids_kg, matériaux, taille, certifications, garantie
**Review sites**: outdoor-mag.fr, i-run.fr
**Retailers**: decathlon.fr, amazon.fr, alltricks.fr

### Vélo
**Exemples**: VTT, route, ville, électrique
**Specs**: type_velo, taille_cadre_cm, poids_kg, nb_vitesses, freins, matériau_cadre, suspension, roues_pouces
**Review sites**: velo-vert.com, citycle.com, lecyclo.com
**Retailers**: decathlon.fr, alltricks.fr, probikeshop.fr

**Ajouter catégorie**: Éditer `data/category_specs.yaml`

---

## Exemples d'Utilisation

### Exemple 1: Vélo VTT
```bash
claude "Compare Décathlon Riverside 500 vs Rockrider ST 530"

# Durée: 20 min (first run), 3 min (cached)
# Output: reports/comparison_Riverside500_vs_ST530_20250115.md

# Rapport inclut:
# - Specs: 9/9 collectées (100%)
# - Reviews: 1,250 Amazon + 15 Reddit + 3 experts
# - Pricing: 4 retailers
# - Verdict: Riverside 500 meilleur rapport qualité/prix
```

### Exemple 2: Électroménager Aspirateurs
```bash
claude "Compare Dyson V15 Detect vs Shark Stratos IZ862H"

# Sources:
# - Specs: dyson.fr + amazon.fr + wirecutter.com
# - Reviews: 2,500 Amazon + 8 Reddit + 2 experts
# - Pricing: Amazon, Boulanger, Darty, Fnac

# Verdict:
# - Meilleur performance: Dyson V15 (aspiration supérieure)
# - Meilleur rapport qualité/prix: Shark Stratos (250€ moins cher)
```

### Exemple 3: Auto
```bash
claude "Compare Peugeot 208 vs Renault Clio 5"

# Sources:
# - Specs: peugeot.fr + renault.fr + caradisiac.com
# - Reviews: 50 Reddit + 3 experts (caradisiac, largus, autoplus)
# - Pricing: leboncoin.fr + lacentrale.fr

# Verdict par use case:
# - Meilleur ville: 208 (compacte, consommation)
# - Meilleur autoroute: Clio (confort, insonorisation)
# - Meilleur rapport qualité/prix: Clio (500€ moins cher équipement équivalent)
```

---

## Métriques Performance

### Durées Moyennes
| Scénario | Durée | Speedup |
|----------|-------|---------|
| First run (no cache) | 20-25 min | Baseline |
| Partial cache (1 product) | 12-15 min | 1.6× |
| Full cache (both products) | 3-5 min | 6× |
| Sequential subagents | 36 min | 0.5× (NOT recommended) |

### Data Quality Targets
- Specs completeness: 90%+ (excellent), 70-89% (good)
- Reviews analyzed: 100+ (high confidence), 10-99 (moderate)
- Retailers checked: 3+ (comprehensive), 1-2 (limited)

### Cost
- **First run**: ~$0.01-0.05 (Apify free tier: 5$ crédit/mois)
- **Cached run**: $0
- **Monthly (20 comparaisons)**: ~$0.50 (largement dans free tier)
- **Fallback WebFetch**: $0

---

## Hooks & Automation

### pre_research.js (UserPromptSubmit)
**Trigger**: User demande comparaison
**Actions**:
1. Extract product names from prompt
2. Validate format (2 produits requis)
3. Check not comparing product with itself
4. Initialize research session ID
5. Create session metadata

### post_collection.js (PostToolUse)
**Trigger**: Write tool saves data file
**Actions**:
1. Detect file type (specs, reviews, pricing, profile)
2. Validate JSON format
3. Check required fields present
4. Calculate completeness score
5. Flag warnings if low quality
6. Log validation results

---

## MCP Apify Scraping

### Configuration
Le fichier `.mcp.json` configure le serveur MCP Apify:
```json
{
  "mcpServers": {
    "apify": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@apify/actors-mcp-server"],
      "env": { "APIFY_TOKEN": "..." }
    }
  }
}
```

### Outils Disponibles

#### `mcp__apify__apify-slash-rag-web-browser`
Recherche Google + scraping en une seule requête.
```
Query: "Dyson V15 specifications site:dyson.fr"
Output: Markdown de la page
```

#### `mcp__apify__call-actor`
Appeler des Actors spécialisés (2 étapes: info → call).

**Amazon Product Scraper**:
```json
{
  "actor": "apify/amazon-product-scraper",
  "step": "call",
  "input": {
    "productUrls": ["https://amazon.fr/dp/B09ABC123"]
  }
}
```

**Amazon Reviews Scraper**:
```json
{
  "actor": "apify/amazon-reviews-scraper",
  "step": "call",
  "input": {
    "productUrls": ["https://amazon.fr/dp/B09ABC123"],
    "maxReviews": 50
  }
}
```

**Reddit Scraper**:
```json
{
  "actor": "apify/reddit-scraper",
  "step": "call",
  "input": {
    "searchPosts": { "term": "Dyson V15 review" },
    "maxPostCount": 20
  }
}
```

#### `mcp__apify__get-actor-output`
Récupérer les résultats complets d'un Actor run.
```json
{
  "datasetId": "abc123...",
  "limit": 100
}
```

### Stratégie d'Utilisation

1. **PRIMARY - MCP Apify**:
   - Amazon specs/reviews → `apify/amazon-*-scraper`
   - Reddit mentions → `apify/reddit-scraper`
   - Recherche Google → `rag-web-browser`

2. **FALLBACK - WebFetch**:
   - Si MCP timeout (>2 min)
   - Si Actor échoue
   - Sites non supportés par Actors

### Avantages MCP vs WebFetch

| Critère | MCP Apify | WebFetch |
|---------|-----------|----------|
| Success rate Amazon | 95%+ | ~70% |
| Reviews par produit | 50-100+ | 10-20 |
| Format output | JSON structuré | HTML à parser |
| Anti-bot handling | Automatique | Manuel |
| Retry logic | Intégré | À implémenter |

---

## Troubleshooting

### Produit Introuvable
```
Error: "Produit 'XYZ' introuvable"
Solution: Vérifier orthographe, essayer avec nom complet
Exemple: "Dyson V15" → "Dyson V15 Detect Absolute"
```

### Specs Incomplètes (< 70%)
```
Warning: "Specs partielles (55%)"
Cause: Source inaccessible ou product page changed
Solution: Continue avec données disponibles, flaggé dans rapport
```

### Cache Corrupted
```
Error: "Cache file invalid JSON"
Action automatique: Delete cache, re-fetch fresh data
Durée: Comme first run (20 min)
```

### Subagent Timeout
```
Warning: "Subagent timeout après 15 min"
Action automatique: Kill subagent, save partial data
Result: Rapport avec données partielles + flag "incomplete"
```

### MCP Actor Échoue
```
Error: "Actor apify/amazon-product-scraper failed"
Action automatique: Fallback vers WebFetch
Solution: Vérifier APIFY_TOKEN dans .mcp.json
```

### MCP Timeout
```
Warning: "MCP call timeout après 2 min"
Action automatique: Continue avec WebFetch
Note: Peut indiquer rate limit Apify atteint
```

---

## Extensibilité

### Ajouter Nouvelle Catégorie
1. Éditer `data/category_specs.yaml`:
```yaml
nouvelle_categorie:
  required_specs: [spec1, spec2, ...]
  review_sites: [site1.com, site2.com]
  retailers: [retailer1.com, retailer2.com]
```

2. Tester:
```bash
claude "Compare [product1 de nouvelle catégorie] vs [product2]"
# Orchestre automatically uses new category config
```

### Ajouter Review Site
1. Éditer `category_specs.yaml` → Ajouter site dans `review_sites[]`
2. reviews-aggregator skill automatically scrapes nouveau site

### Ajouter Retailer
1. Éditer `category_specs.yaml` → Ajouter retailer dans `retailers[]`
2. pricing-tracker skill automatically checks nouveau retailer

---

## Ressources

- **CLAUDE.md**: Instructions complètes, persona, guidelines
- **skills/*/helpers/**: Workflows détaillés par skill
- **subagents/product-researcher.md**: Logic subagent recherche
- **.claude/logs/**: Logs execution pour debugging
- **.mcp.json**: Configuration serveur MCP Apify
- **reports/**: Exemples rapports générés
- **CHANGELOG.md**: Historique des versions

---

**Version**: 1.2
**Date**: 2025-11-19
**Status**: Production-ready
**Mainteneur**: Product Analyst Claude

Product Comparison - Index & Navigation

Quick Links

CLAUDE.md - Instructions projet, persona, guidelines
Démarrage Rapide
Skills Disponibles
MCP Apify
Catégories Produits
Exemples

Démarrage Rapide

Première Comparaison (20-25 min)

cd product-comparison
claude ""

Workflow automatique:

Validation produits (30 sec)
Recherche parallèle 2 subagents (18 min)
Génération rapport (5 min)
Output: reports/comparison_DysonV15_vs_SharkStratos_20250115.md

Comparaison Cachée (3-5 min)

# Si produits déjà recherchés < 7 jours
claude "Compare Dyson V15 vs Shark Stratos"
# → Utilise cache, génère rapport directement

Navigation Structure

1. Configuration (`.claude/`)

Fichier	Description
`settings.json`	Config projet (subagents, hooks, cache)
`config.json`	Custom parameters (skills, subagents, logging)
`hooks/pre_research.js`	Validate produits avant recherche
`hooks/post_collection.js`	Validate qualité données collectées
`dev_docs/`	Context, plan, tasks (project memory)
`logs/`	Logs execution, erreurs, métriques

2. Skills (`skills/`)

Skill	Type	Durée	Description
product-research-orchestrator	orchestration	20-25 min	Coordonne workflow complet, spawn subagents
specs-collector	data_collection	2-5 min	Collecte specs depuis manufacturer + Amazon + review sites
reviews-aggregator	data_collection	8-10 min	Agrège Amazon + Reddit + experts, analyse sentiment
pricing-tracker	data_collection	2-3 min	Track prix multi-retailers, availability
report-generator	synthesis	5 min	Génère rapport markdown professionnel

Détails: skills/{skill-name}/SKILL.md (metadata) + helpers/ (workflows)

3. Subagents (`subagents/`)

Template	Usage	Isolation
product-researcher.md	Recherche 1 produit (specs + reviews + pricing)	Strict (own context, own folder)

Parallélisation: 2 subagents simultanés (1 par produit) → 2× speedup

4. Data (`data/`)

Dossier	Contenu	TTL
`category_specs.yaml`	Specs requises par catégorie (électroménager, auto, sport, vélo)	-
`cache/specs/`	Specs cachées	7 jours
`cache/reviews/`	Reviews cachées	7 jours
`cache/pricing/`	Pricing caché	7 jours
`research_{timestamp}/`	Résultats recherche session	-
`archive/`	Recherches > 30 jours	-

Cache strategy: Check cache avant chaque fetch → 6× speedup si cache hit

5. MCP Apify (`.mcp.json`)

Outil	Usage	Output
`mcp__apify__apify-slash-rag-web-browser`	Recherche Google + scraping	Markdown
`mcp__apify__call-actor`	Appeler Actors spécialisés	JSON structuré
`mcp__apify__get-actor-output`	Récupérer résultats Actor	JSON dataset
`mcp__apify__search-actors`	Chercher Actors Apify Store	Liste Actors

Actors recommandés:

apify/amazon-product-scraper - Specs + prix Amazon
apify/amazon-reviews-scraper - Reviews Amazon (50+)
apify/reddit-scraper - Posts/comments Reddit

Stratégie: MCP Apify (primary) → WebFetch (fallback)

6. Rapports (`reports/`)

Format: comparison_{product1}_vs_{product2}_{timestamp}.md

Sections:

Executive Summary
Specs Comparison (side-by-side table)
Avis Utilisateurs (Amazon, Reddit)
Tests Experts (consensus sites spécialisés)
Pricing & Availability
Verdict par Use Case (budget, performance, beginner)
Tableau Récapitulatif
Sources

Skills Disponibles

orchestrator (Skill Principal)

Pattern: compare {product1} vs {product2}

Commandes:

compare Dyson V15 vs Shark Stratos
research products iPhone 15 Pro, Samsung Galaxy S24
analyse Décathlon Riverside 500 vs B'Twin Triban 520

Workflow:

Valide produits existent
Check cache (7j)
Spawn 2 subagents parallèles
Agrège résultats
Trigger report-generator

specs-collector

Pattern: collect specifications for {product}

Sources: Manufacturer site + Amazon + Review site (category-specific)

Output: specs.json (9-10 specs selon catégorie)

reviews-aggregator

Pattern: aggregate reviews for {product}

Sources:

Users: Amazon (ratings, reviews) + ReCompare Dyson V15 vs Shark Stratosddit (mentions)
Experts: 2-3 sites selon catégorie

Output: reviews_summary.json (pros, cons, sentiment, overall_score)

pricing-tracker

Pattern: track pricing for {product}

Retailers: Amazon + 2-3 sites catégorie

Output: pricing.json (prix, availability, best_price)

report-generator

Pattern: generate comparison report

Input: All collected data (specs, reviews, pricing for 2 products)

Output: Rapport markdown professionnel

Catégories Produits Supportées

Électroménager

Exemples: Aspirateurs, cafetières, robots cuisine, lave-linge Specs: puissance_W, capacité_L, niveau_bruit_dB, conso_energie, poids_kg Review sites: consumerreports.org, wirecutter.com, lesnumeriques.com Retailers: amazon.fr, boulanger.com, darty.com

Auto

Exemples: Voitures neuves/occasion, motos Specs: motorisation, puissance_ch, conso_L_100km, coffre_L, prix_base Review sites: caradisiac.com, largus.fr, automobile-magazine.fr Retailers: leboncoin.fr, lacentrale.fr, autoscout24.fr

Sport

Exemples: Chaussures running, équipement fitness, outdoor Specs: poids_kg, matériaux, taille, certifications, garantie Review sites: outdoor-mag.fr, i-run.fr Retailers: decathlon.fr, amazon.fr, alltricks.fr

Vélo

Exemples: VTT, route, ville, électrique Specs: type_velo, taille_cadre_cm, poids_kg, nb_vitesses, freins, matériau_cadre, suspension, roues_pouces Review sites: velo-vert.com, citycle.com, lecyclo.com Retailers: decathlon.fr, alltricks.fr, probikeshop.fr

Ajouter catégorie: Éditer data/category_specs.yaml

Exemples d'Utilisation

Exemple 1: Vélo VTT

claude "Compare Décathlon Riverside 500 vs Rockrider ST 530"

# Durée: 20 min (first run), 3 min (cached)
# Output: reports/comparison_Riverside500_vs_ST530_20250115.md

# Rapport inclut:
# - Specs: 9/9 collectées (100%)
# - Reviews: 1,250 Amazon + 15 Reddit + 3 experts
# - Pricing: 4 retailers
# - Verdict: Riverside 500 meilleur rapport qualité/prix

Exemple 2: Électroménager Aspirateurs

claude "Compare Dyson V15 Detect vs Shark Stratos IZ862H"

# Sources:
# - Specs: dyson.fr + amazon.fr + wirecutter.com
# - Reviews: 2,500 Amazon + 8 Reddit + 2 experts
# - Pricing: Amazon, Boulanger, Darty, Fnac

# Verdict:
# - Meilleur performance: Dyson V15 (aspiration supérieure)
# - Meilleur rapport qualité/prix: Shark Stratos (250€ moins cher)

Exemple 3: Auto

claude "Compare Peugeot 208 vs Renault Clio 5"

# Sources:
# - Specs: peugeot.fr + renault.fr + caradisiac.com
# - Reviews: 50 Reddit + 3 experts (caradisiac, largus, autoplus)
# - Pricing: leboncoin.fr + lacentrale.fr

# Verdict par use case:
# - Meilleur ville: 208 (compacte, consommation)
# - Meilleur autoroute: Clio (confort, insonorisation)
# - Meilleur rapport qualité/prix: Clio (500€ moins cher équipement équivalent)

Métriques Performance

Durées Moyennes

Scénario	Durée	Speedup
First run (no cache)	20-25 min	Baseline
Partial cache (1 product)	12-15 min	1.6×
Full cache (both products)	3-5 min	6×
Sequential subagents	36 min	0.5× (NOT recommended)

Data Quality Targets

Specs completeness: 90%+ (excellent), 70-89% (good)
Reviews analyzed: 100+ (high confidence), 10-99 (moderate)
Retailers checked: 3+ (comprehensive), 1-2 (limited)

Cost

First run: ~$0.01-0.05 (Apify free tier: 5$ crédit/mois)
Cached run: $0
Monthly (20 comparaisons): ~$0.50 (largement dans free tier)
Fallback WebFetch: $0

Hooks & Automation

pre_research.js (UserPromptSubmit)

Trigger: User demande comparaison Actions:

Extract product names from prompt
Validate format (2 produits requis)
Check not comparing product with itself
Initialize research session ID
Create session metadata

post_collection.js (PostToolUse)

Trigger: Write tool saves data file Actions:

Detect file type (specs, reviews, pricing, profile)
Validate JSON format
Check required fields present
Calculate completeness score
Flag warnings if low quality
Log validation results

MCP Apify Scraping

Configuration

Le fichier .mcp.json configure le serveur MCP Apify:

{
  "mcpServers": {
    "apify": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@apify/actors-mcp-server"],
      "env": { "APIFY_TOKEN": "..." }
    }
  }
}

Outils Disponibles

`mcpapifyapify-slash-rag-web-browser`

Recherche Google + scraping en une seule requête.

Query: "Dyson V15 specifications site:dyson.fr"
Output: Markdown de la page

`mcpapifycall-actor`

Appeler des Actors spécialisés (2 étapes: info → call).

Amazon Product Scraper:

{
  "actor": "apify/amazon-product-scraper",
  "step": "call",
  "input": {
    "productUrls": ["https://amazon.fr/dp/B09ABC123"]
  }
}

Amazon Reviews Scraper:

{
  "actor": "apify/amazon-reviews-scraper",
  "step": "call",
  "input": {
    "productUrls": ["https://amazon.fr/dp/B09ABC123"],
    "maxReviews": 50
  }
}

Reddit Scraper:

{
  "actor": "apify/reddit-scraper",
  "step": "call",
  "input": {
    "searchPosts": { "term": "Dyson V15 review" },
    "maxPostCount": 20
  }
}

`mcpapifyget-actor-output`

Récupérer les résultats complets d'un Actor run.

{
  "datasetId": "abc123...",
  "limit": 100
}

Stratégie d'Utilisation

PRIMARY - MCP Apify:
- Amazon specs/reviews → apify/amazon-*-scraper
- Reddit mentions → apify/reddit-scraper
- Recherche Google → rag-web-browser
FALLBACK - WebFetch:
- Si MCP timeout (>2 min)
- Si Actor échoue
- Sites non supportés par Actors

Avantages MCP vs WebFetch

Critère	MCP Apify	WebFetch
Success rate Amazon	95%+	~70%
Reviews par produit	50-100+	10-20
Format output	JSON structuré	HTML à parser
Anti-bot handling	Automatique	Manuel
Retry logic	Intégré	À implémenter

Troubleshooting

Produit Introuvable

Error: "Produit 'XYZ' introuvable"
Solution: Vérifier orthographe, essayer avec nom complet
Exemple: "Dyson V15" → "Dyson V15 Detect Absolute"

Specs Incomplètes (< 70%)

Warning: "Specs partielles (55%)"
Cause: Source inaccessible ou product page changed
Solution: Continue avec données disponibles, flaggé dans rapport

Cache Corrupted

Error: "Cache file invalid JSON"
Action automatique: Delete cache, re-fetch fresh data
Durée: Comme first run (20 min)

Subagent Timeout

Warning: "Subagent timeout après 15 min"
Action automatique: Kill subagent, save partial data
Result: Rapport avec données partielles + flag "incomplete"

MCP Actor Échoue

Error: "Actor apify/amazon-product-scraper failed"
Action automatique: Fallback vers WebFetch
Solution: Vérifier APIFY_TOKEN dans .mcp.json

MCP Timeout

Warning: "MCP call timeout après 2 min"
Action automatique: Continue avec WebFetch
Note: Peut indiquer rate limit Apify atteint

Extensibilité

Ajouter Nouvelle Catégorie

Éditer data/category_specs.yaml:

nouvelle_categorie:
  required_specs: [spec1, spec2, ...]
  review_sites: [site1.com, site2.com]
  retailers: [retailer1.com, retailer2.com]

Tester:

claude "Compare [product1 de nouvelle catégorie] vs [product2]"
# Orchestre automatically uses new category config

Ajouter Review Site

Éditer category_specs.yaml → Ajouter site dans review_sites[]
reviews-aggregator skill automatically scrapes nouveau site

Ajouter Retailer

Éditer category_specs.yaml → Ajouter retailer dans retailers[]
pricing-tracker skill automatically checks nouveau retailer

Ressources

CLAUDE.md: Instructions complètes, persona, guidelines
skills/*/helpers/: Workflows détaillés par skill
subagents/product-researcher.md: Logic subagent recherche
.claude/logs/: Logs execution pour debugging
.mcp.json: Configuration serveur MCP Apify
reports/: Exemples rapports générés
CHANGELOG.md: Historique des versions

Version: 1.2 Date: 2025-11-19 Status: Production-ready Mainteneur: Product Analyst Claude