🛒 Makiti — MCP Shopping Assistant

Makiti est un serveur MCP (Model Context Protocol) qui agit comme assistant shopping intelligent. Il s’appuie sur Hound pour chercher le web et scraper les retailers, et fournit des outils MCP pour :

• 🔍 rechercher des produits,
• 🏷️ trouver le meilleur prix sur les retailers canadiens,
• ⚖️ comparer des items,
• 💰 trouver les meilleurs deals,
• 📈 estimer l’historique de prix.

---

🚀 Installation

git clone https://github.com/seasayDev/makiti-mcp.git
cd makiti-mcp
npm install

---

⚙️ Configuration requise

Dépendance	Description
Node.js >= 18	Runtime requis
Hound MCP	Serveur MCP de recherche web (wrapper Hermes)
Hermes Agent	Pour consommer les outils Makiti via MCP

Architecture

Makiti ne parle pas à Hound par HTTP : il spawn Hound en sous-processus et communique en JSON-RPC stdio (protocole MCP), exactement comme le fait Hermes. Le chemin du wrapper Hound est configurable via la variable d'environnement HOUND_WRAPPER (défaut : /data/data/com.termux/files/home/.hermes/scripts/hound-wrapper.sh).

[ Agent / Hermes ] ──stdio──> [ Makiti MCP ] ──spawn──> [ Hound MCP ] ──> web

---

🛠️ Outils disponibles

product_search

Rechercher des produits sur le web avec filtres de prix, marque, retailer, condition. Les résultats sont triés du moins cher au plus cher quand un prix est détecté.

{
  "query": "iPhone 15",
  "max_price": 1200,
  "brand": "Apple",
  "retailer": "amazon.ca",
  "condition": "new",
  "limit": 10
}

find_best_price ⭐ (nouveau)

Scraper directement les pages de recherche des retailers canadiens (Amazon.ca, Walmart.ca…) pour trouver le prix le plus bas réel, lu en direct sur les sites. Plus fiable que product_search car il lit les pages produits elles-mêmes.

{
  "query": "usb flash drive 128gb",
  "retailers": ["amazon.ca", "walmart.ca"],
  "limit": 5
}

Retailers supportés : amazon.ca, walmart.ca, bestbuy.ca, canadiantire.ca, staples.ca, newegg.ca.

⚠️ Best Buy Canada bloque le scraping automatisé (HTTP 403) — les erreurs sont listées dans la réponse.

product_compare

Comparer deux produits côte à côte : specs, prix, verdict.

{
  "product_a": "iPhone 15",
  "product_b": "Samsung Galaxy S24",
  "category": "smartphone",
  "budget": 1100
}

find_deals

Trouver les deals/promo actifs pour un produit ou une catégorie (filtré sur la région Canada).

{
  "query": "Nike running shoes",
  "region": "Canada",
  "retailer": "amazon.ca",
  "limit": 10
}

price_history

Suivre/estimer l’historique de prix d’un produit sur plusieurs retailers.

{
  "product": "PlayStation 5",
  "retailers": ["amazon.ca", "bestbuy.ca", "walmart.ca"],
  "days_back": 90
}

makiti_guide

Obtenir des conseils d’utilisation selon ton scénario shopping.

{
  "scenario": "acheter un laptop sous 800 CAD"
}

---

🧠 Leçons apprises (retour d'expérience réel)

Makiti a été mis à l'épreuve sur une vraie recherche (« meilleur prix clé USB 128GB Canada »). Voici ce que cette expérience a révélé, et comment le code a été corrigé.

Leçon 1 — Les filtres site: tuent les recherches Hound

Problème : product_search générait des requêtes comme USB flash drive 128GB site:amazon.ca price → 0 résultat sur tous les moteurs de Hound. Cause : les opérateurs site: combinés à des requêtes longues font échouer les moteurs.

Correction :

• plus aucun site: dans les requêtes ;
• les noms de retailers sont convertis en mots-clés (amazon.ca → amazon canada) ;
• les requêtes sont gardées courtes (< 8 mots).

Leçon 2 — Fallback automatique des moteurs de recherche

Problème : pendant la session, les moteurs google et brave étaient bloqués (engine_blocked), donnant 0 résultat pendant plusieurs minutes.

Correction : hound-client.js implémente un fallback en 3 paliers :

1. google, brave, duckduckgo, yahoo
2. duckduckgo, yahoo, qwant, mojeek
3. startpage, bing

Si un palier renvoie 0 résultat et des moteurs bloqués, on passe au palier suivant.

Leçon 3 — La recherche web seule ne suffit pas : il faut scraper les retailers

Problème : les résultats web donnent des liens de blogs/deals, pas de prix fiables. La méthode gagnante : le fetch direct des pages de recherche des retailers (amazon.ca/s?k=..., walmart.ca/en/search?q=...) a donné les vrais prix en CAD, y compris les promotions en cours (Kingston 64GB à 13,97$ Walmart, PNY 128GB à 26,08$ Amazon).

Correction : nouvel outil find_best_price qui scrappe Amazon.ca et Walmart.ca en parallèle et extrait (produit, prix) avec une heuristique ligne par ligne.

Leçon 4 — Les résultats « deals » partent en vrille géographique

Problème : find_deals sur « USB flash drive » renvoyait des deals hotukdeals (UK) et des sites pakistanais.

Correction : filtrage géographique — on garde les hits contenant des indices canadiens (.ca, Canada, CAD, québec, redflagdeals, slickdeals…) et on élimine les indices étrangers (hotukdeals, .co.uk, pakistan, karachi, indiamart…).

Leçon 5 — Le parsing de prix est un champ de mines

Problème : les pages retailers mélangent prix réels (Now $13.97) et bruit (You save $6.02, $890 sans décimales, Up to $15, headers markdown ##).

Correction (heuristique actuelle) :

• les lignes You save $X ne fournissent jamais un prix ;
• on privilégie les prix avec décimales ($13.97) ;
• on ignore la navigation, les headers markdown, More buying choices, List:, You pay ;
• les titres sont nettoyés (...284.6786 out of 5 stars. 28 reviews → nom seul).

Leçon 6 — La fraîcheur compte

Les prix bougent vite. Toutes les réponses rappellent que les prix sont relevés à l'instant du fetch et doivent être vérifiés sur la page produit avant achat (taxes/livraison non incluses).

---

🗺️ Roadmap (améliorations futures)

• [ ] Parsing JSON-LD/structured data des pages retailers (au lieu de l'heuristique lignes) pour des prix exacts + URLs produits.
• [ ] Contournement Best Buy via le browser stealthy de Hound (actions click/form) — actuellement bloqué 403.
• [ ] price_alert — outil cron qui surveille un produit et notifie quand le prix passe sous un seuil.
• [ ] Cache prix par produit (TTL court) pour éviter de refrapper les retailers à chaque appel.
• [ ] Support USD→CAD pour les retailers américains (conversion + droits de douane indicatifs).
• [ ] Détection de taxes/livraison par province depuis les pages produit.
• [ ] compare_retailers — outil dédié qui croise les prix d'un même modèle sur 4+ retailers.

---

📦 Enregistrement dans Hermes

Dans ~/.hermes/config.yaml, ajoute :

mcp_servers:
  makiti:
    command: node
    args: ["/chemin/absolu/vers/makiti-mcp/server.js"]

Puis redémarre Hermes :

hermes gateway restart   # depuis un shell Termux, pas depuis le chat

Vérification :

hermes mcp list          # makiti doit apparaître ✓ enabled
hermes mcp test makiti   # ✓ Connected + tools discovered

---

🧪 Développement / test

# Vérifier le handshake MCP + un outil réel
printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"product_search","arguments":{"query":"iPhone 15","limit":3}}}' \
  | timeout 100 node server.js

⚠️ Hound démarre en ~15 s au premier appel (proot Ubuntu). Patience sur le premier tools/call.

---

🔧 Scripts npm

npm start   # lancer le serveur MCP (alias node server.js)

---

📄 License

MIT © seasayDev