asmy-mcp-server

Serveur MCP pour Asmy Digital Store. Expose le catalogue produits, les codes promo et les stats de la boutique sous forme d'outils MCP, consommables par un agent (Junior.so, Claude Desktop, ou n'importe quel client MCP).

Backend de données : Firestore. Deux transports : stdio et HTTP (SSE + Streamable HTTP).

Prérequis

• Node >= 18 (Bun recommandé, les scripts npm l'utilisent)

• Un projet Firebase avec Firestore activé

• Une clé de compte de service Firebase

Related MCP server: mcp-server-woocommerce

Installation

bun install          # ou npm install
cp .env.example .env

Configuration

Firebase

Le serveur résout les credentials dans cet ordre (firebase-config.js) :

1. FIREBASE_SERVICE_ACCOUNT — le JSON complet, sur une ligne ou en base64

2. FIREBASE_SERVICE_ACCOUNT_FILE — chemin vers le fichier

3. ./firebase-service-account.json — fallback, à côté de index.js

Si FIREBASE_SERVICE_ACCOUNT est présent mais invalide, il y a fallback sur le fichier avec un warning sur stderr, pas un crash.

En local : le fichier. En prod : la variable d'env (base64 évite les galères d'échappement sur private_key).

Le fichier firebase-service-account.json est déjà dans .gitignore. Il n'y a aucune raison de l'en sortir.

Variables d'environnement

localhost, 127.0.0.1, [::1] et RAILWAY_PUBLIC_DOMAIN (injecté par Railway) sont ajoutés automatiquement à la liste des hôtes autorisés.

Note : env.js est un parseur .env maison, sans dépendance. Il gère les valeurs JSON multi-lignes (accolades) — utile pour coller un service account brut dans le fichier. Il ne gère pas grand-chose d'autre : pas d'interpolation, pas d'échappements exotiques.

Lancer

bun start          # HTTP sur $PORT
bun run dev        # HTTP + watch
bun run start:stdio  # transport stdio

Le serveur choisit stdio si --stdio est passé en argument ou si MCP_STDIO=1. Sinon, HTTP.

Endpoints HTTP

Les deux transports coexistent. Une session ouverte en SSE ne peut pas être reprise sur /mcp (retour -32000).

Les sessions sont stockées en mémoire dans un objet local. Conséquence : une seule instance. Pas de scaling horizontal sans sticky sessions ou store partagé.

Outils exposés

16 outils, tous définis dans index.js.

Produits (collection products)

Promotions (collection promotions)

Divers

get_current_date existe parce que les LLM se trompent de date et génèrent des expiresAt dans le passé. Un agent qui crée un code promo doit l'appeler d'abord.

Conventions

• Les codes promo sont normalisés en majuscules, expiresAt au format YYYY-MM-DD, discount entre 1 et 100.

• Le slug produit est dérivé du nom (NFD, accents retirés, non-alphanumériques remplacés par des tirets).

• Chaque produit renvoyé porte une url construite sur https://asmystore.shop/abonnements/{slug}.

• update_stats push dans history, puis recalcule monthTotal et monthOrders en filtrant sur le préfixe YYYY-MM. Écrire deux fois la même entrée la compte deux fois — il n'y a pas de déduplication.

Recherche d'images

product-image.js résout une icône produit en deux passes :

1. Clearbit (logo.clearbit.com/{domaine}), avec une table de correspondance marque → domaine et un fallback {slug}.com / {slug}.io

2. DuckDuckGo Images

Chaque candidat est validé par un HEAD (puis un GET avec Range si le HEAD ne renvoie rien d'exploitable) pour vérifier que le content-type est bien une image.

Deux réserves à garder en tête : l'endpoint i.js de DuckDuckGo n'est pas une API publique — il faut d'abord scraper un token vqd, et ça peut casser sans préavis. Et les logos récupérés appartiennent aux marques concernées ; à toi de vérifier ce que tu as le droit d'afficher sur la boutique.

En cas d'échec, l'outil renvoie une erreur explicite et le produit est créé sans icône.

Tests

Deux clients de test, tous les deux branchés sur OpenAI pour faire du tool calling en langage naturel. OPENAI_API_KEY requise.

bun run test:mcp                          # spawn le serveur en stdio
bun run test:mcp "Liste les produits actifs"

MCP_SERVER_URL=https://xxx.up.railway.app bun run test:mcp:url
bun test-mcp-url.js https://xxx.up.railway.app "Quelle est la date ?"

Sans argument, les deux entrent en mode REPL. Max 10 tours d'appels d'outils.

Déploiement (Railway)

1. Push le repo (privé) sur GitHub

2. Railway → New Project → Deploy from GitHub

3. Variables : FIREBASE_SERVICE_ACCOUNT (base64), PORT si besoin

4. RAILWAY_PUBLIC_DOMAIN est injecté automatiquement et ajouté aux hôtes autorisés — sinon, renseigner ALLOWED_HOSTS à la main

Le serveur gère SIGINT / SIGTERM : les transports ouverts sont fermés avant l'exit.

Connexion depuis Junior.so

Dashboard → agent → Integrations → Create → Custom → MCP, puis l'URL SSE :

https://<ton-domaine>.up.railway.app/sse

Junior parle la spec 2024-11-05, donc /sse et pas /mcp. Les 16 outils sont listés automatiquement après connexion.

Migration des promos

migrate-promos.js est un script one-shot pour rapatrier les codes promo du localStorage du front vers Firestore.

1. Sur asmystore.shop, console dev : localStorage.getItem("asmy-admin-promos")

2. Coller le JSON dans la constante PROMOS_JSON du script

3. bun migrate-promos.js

Attention : ce script lit firebase-service-account.json en dur, il ne passe pas par firebase-config.js. Les variables d'env ne fonctionnent pas ici, il faut le fichier. Le script est destiné à être lancé une fois puis oublié.

Côté front, penser à basculer les lectures/écritures promo de localStorage vers la collection promotions, sinon les deux sources divergent.

Dépannage

Firebase non configuré au démarrage — ni FIREBASE_SERVICE_ACCOUNT, ni FIREBASE_SERVICE_ACCOUNT_FILE, ni le fichier par défaut n'ont été trouvés.

JSON Firebase incomplet — le JSON est parsé mais il manque type: "service_account" ou private_key. Typiquement un copier-coller tronqué ou un base64 mal terminé.

Requêtes rejetées en prod alors que ça marche en local — protection contre le DNS rebinding. Le host n'est pas dans allowedHosts. Renseigner ALLOWED_HOSTS.

Session not found sur /messages — la session SSE a expiré ou le serveur a redémarré. Les sessions sont en mémoire, un redéploiement les efface toutes.

Le client ne voit aucun outil — vérifier qu'on tape bien /sse (spec legacy) et pas /mcp, et que GET / répond.