Comment nous avons construit YeloScale : une plateforme e-commerce prête pour MCP à l’ère de la recherche IA
YeloScale est une plateforme de commerce et de livraison construite par OHY Labs pour les marchands qui vendent en ligne et expédient en paiement à la livraison. Elle génère une boutique à partir de l’espace de travail du marchand, publie des pages que Google et les assistants IA peuvent lire, et expose un serveur MCP sécurisé pour que les agents IA puissent travailler avec les commandes, les produits et les boutiques. Cette étude de cas explique ce que nous avons construit, pourquoi, et comment l’ingénierie assistée par IA a façonné le résultat.
Le problème : les marchands jonglent avec dix outils déconnectés
Un marchand type vend via une page sociale et une marketplace, suit son stock dans un tableur, crée ses expéditions sur le portail de chaque transporteur et rapproche les paiements à la livraison à la main. Chaque commande traverse cinq systèmes et personne ne détient la vérité.
Nous voulions un espace de travail unique où le marchand possède ses produits, son stock, ses commandes, ses expéditions et ses paiements, et où les boutiques externes et les transporteurs se branchent comme des intégrations plutôt que de jouer le rôle de base de données. Ce principe, la plateforme est la source de vérité, est devenu la règle qui a contraint chaque décision de conception ensuite.
- Produits et variantes avec le stock réparti entre dépôts et entrepôts.
- Commandes importées depuis Shopify, WooCommerce, ou créées à la main.
- Commandes converties en expéditions et transmises aux transporteurs comme Massar, Sendex, First Delivery, Aramex, DHL, FedEx et UPS.
- Manifestes par transporteur, suivi des expéditions et rapprochement du paiement à la livraison.
- Membres d’équipe, rôles et paramètres d’espace de travail avec une isolation stricte entre tenants.
Architecture : un poste de commande multi-tenant
YeloScale est un monorepo avec un frontend React et Vite, un backend SaaS NestJS sur Postgres, une passerelle de livraison Fastify avec Prisma et des workers BullMQ, ainsi que des services de facturation et d’images séparés. Redis gère le cache et les files d’attente. Tout est livré en conteneurs Docker avec des déploiements blue/green, pour qu’une mise en production n’interrompe jamais un marchand en pleine vente.
Chaque table, service, route API et vue d’interface est cloisonné par espace de travail. Les identifiants des transporteurs sont chiffrés au repos. Le frontend charge les vues en chunks lazy pour que les pages à fort trafic, commandes et expéditions, restent rapides sur un téléphone en entrepôt.
Pourquoi la passerelle de livraison est un service séparé
Les transporteurs ont des API, des limites de débit et des modes de panne incohérents. Les isoler derrière une passerelle unique avec des workers en file d’attente garantit qu’un transporteur lent ne bloque jamais le tableau de bord du marchand, et que chaque appel transporteur est réessayé et journalisé au même endroit.
Des boutiques générées depuis l’espace de travail
Un marchand ne construit pas un site web. Il publie une boutique, et YeloScale la génère à partir de ce qui existe déjà dans l’espace de travail : produits, collections, prix, stock et règles de livraison. La boutique vit sur un lien yeloscale.shop ou un domaine personnalisé, et réutilise le même panier, le même paiement et le même flux de paiement à la livraison sur toutes les boutiques.
Les sections de boutique, les cartes produit et les pages de campagne sont des templates que le marchand configure, pas du code qu’il écrit. Les drops programmés ajoutent des comptes à rebours et des verrous de lancement appliqués côté serveur, pour qu’un client qui change l’horloge de son navigateur ne puisse pas déverrouiller un produit en avance.
- Pages de boutique, de produit et de collection générées depuis les données du catalogue.
- Domaines personnalisés avec certificats automatiques, et sous-domaines yeloscale.shop.
- Drops programmés avec comptes à rebours, verrous de lancement et expiration du cache à l’heure du lancement.
- Lectures du catalogue mises en cache par Redis, avec publication sans interruption.
Conçu pour Google et la recherche IA, pas seulement pour les abonnés
La plupart des crawlers IA n’exécutent pas JavaScript. Une boutique rendue côté client est invisible pour ChatGPT, Claude et Perplexity, et part avec un handicap même sur Google. YeloScale rend donc les pages publiques des boutiques côté serveur, avec du vrai HTML, des URL propres et des données structurées par-dessus.
Chaque boutique publie du JSON-LD Store, Product, Offer, CollectionPage et BreadcrumbList, son propre robots.txt et sitemap.xml, ainsi qu’un fichier llms.txt qui résume la boutique pour les modèles de langage. Un annuaire public de boutiques avec recherche côté serveur permet aux personnes, et aux assistants IA, de trouver une boutique qui vend un produit précis.
Pourquoi cela compte pour un petit marchand
La découverte dépendait auparavant du nombre d’abonnés d’un marchand. Avec des pages crawlables et structurées, une boutique de Tunis peut être citée par un assistant IA qui répond à « où puis-je acheter X » sans payer de publicité. C’est la même discipline d’optimisation pour les moteurs génératifs qu’OHY Labs applique à son propre site.
Le serveur MCP : laisser les agents IA travailler avec les commandes et les produits
MCP, le Model Context Protocol, donne à un agent IA un menu d’outils approuvés avec des schémas et des permissions clairs. YeloScale expose un serveur MCP distant en Streamable HTTP sur un point d’entrée unique, protégé par des jetons OAuth émis par un fournisseur d’identité externe, avec des métadonnées de découverte pour que les clients MCP se connectent sans code sur mesure.
Avant d’écrire le moindre outil, nous avons classé chaque capacité du backend en cinq catégories d’exposition. Les outils publics en lecture seule ne demandent pas d’authentification mais sont limités en débit. Les lectures authentifiées exigent l’appartenance, le scope et la permission dans l’espace de travail. Les écritures réversibles ajoutent des schémas stricts, des clés d’idempotence et des entrées d’audit. Les actions sensibles ou destructrices passent par un flux en deux temps, préparer puis confirmer, avec un jeton signé à usage unique lié à l’acteur et au tenant. Certaines capacités ne sont volontairement jamais exposées.
- Outils en production : lister et consulter les commandes, lister et consulter les produits, lister les espaces de travail, et chercher dans l’annuaire public de boutiques.
- Un exemple de catégorie D : retirer un membre de l’équipe exige un appel de préparation, puis un appel de confirmation avec un jeton à usage unique.
- Le contexte du tenant est dérivé du principal authentifié, jamais d’un argument d’outil.
- Des scopes comme orders:read ou catalog:write correspondent à des permissions fines de l’espace de travail, revérifiées à chaque appel.
- Limites de débit par outil, plafonds de taille des requêtes et des réponses, protection contre le rejeu, et journalisation d’audit dans le journal d’activité.
- Un coupe-circuit principal garde toute la surface MCP éteinte tant que le fournisseur d’identité et les contrôles Inspector ne sont pas validés.
Ce qu’un agent peut en faire
Un agent commercial peut répondre à « quelles commandes d’hier sont encore impayées » à partir de données réelles. Un agent de support peut consulter un produit et son stock avant de répondre à un client. Un agent de recherche peut interroger l’annuaire de boutiques pour trouver les marchands d’une catégorie. Aucun d’eux ne peut dépasser la permission dont dispose déjà l’humain.
Comment les agents IA ont aidé à le construire
YeloScale a été construit par une petite équipe travaillant avec des agents de code IA. La méthode est « spécification d’abord » : chaque fonctionnalité commence par un document de conception écrit, avec le problème, les contraintes, ce qui existe déjà et ce qu’il ne faut surtout pas reconstruire. Les agents implémentent contre cette spécification par petites tâches, chacune avec un brief et un rapport, et chaque changement passe par des tests automatisés avant relecture.
C’est pour cela que le dépôt contient des audits du workflow de commande complet, un modèle de menaces pour le serveur MCP, une matrice fonctionnalités-vers-MCP, des notes de tests de charge et un runbook d’exploitation. La documentation n’est pas un après-coup ; c’est l’entrée qui a rendu le développement assisté par IA fiable.
- Spécifications de conception et briefs par tâche comme contrat entre humains et agents.
- Tests unitaires et de protocole sur les backends, y compris le handshake MCP et l’enregistrement des outils.
- Revues de sécurité sur l’isolation entre tenants avant toute fonctionnalité multi-espaces.
- Déploiements Docker blue/green pilotés depuis la CI, pour des mises en production sans surprise.
Ce que les marchands y gagnent
Un marchand obtient une vraie boutique en ligne, ses commandes et son paiement à la livraison au même endroit, des expéditions envoyées à n’importe quel transporteur pris en charge, et des pages que Google et les assistants IA peuvent lire. Son entreprise devient aussi prête pour les agents : quand il ajoute un agent IA de vente ou de support, le serveur MCP est déjà là avec les bonnes permissions.
Pour OHY Labs, YeloScale est l’implémentation de référence de ce que nous entendons par infrastructure compatible MCP. La même approche, une plateforme source de vérité, des surfaces publiques générées et une couche MCP à permissions, est ce que nous apportons aux plateformes de nos clients.