# 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

## Installation

```bash
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

| Variable | Défaut | Rôle |
| --- | --- | --- |
| `PORT` | `3000` | Port HTTP |
| `HOST` | `0.0.0.0` | Interface d'écoute |
| `ALLOWED_HOSTS` | — | Hôtes autorisés, séparés par des virgules. Requis quand on bind sur `0.0.0.0` |
| `FIREBASE_SERVICE_ACCOUNT` | — | JSON du service account (une ligne ou base64) |
| `FIREBASE_SERVICE_ACCOUNT_FILE` | — | Chemin alternatif vers le JSON |
| `MCP_STDIO` | — | `1` force le transport stdio |
| `OPENAI_API_KEY` | — | Clients de test uniquement |
| `OPENAI_MODEL` | `gpt-4o-mini` | Clients de test uniquement |
| `MCP_SERVER_URL` | — | `test-mcp-url.js` uniquement |

`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

```bash
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

| Route | Méthode | Description |
| --- | --- | --- |
| `/` | GET | Health check, renvoie le nom du serveur et la liste des endpoints |
| `/mcp` | ALL | Streamable HTTP (spec 2025-11-25), sessions via header `mcp-session-id` |
| `/sse` | GET | SSE legacy (spec 2024-11-05) — c'est ce que consomme Junior.so |
| `/messages` | POST | Canal retour du transport SSE, session via `?sessionId=` |

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`)

| Outil | Description |
| --- | --- |
| `list_products` | Catalogue avec statut, prix, stock |
| `get_product` | Détail par slug ou id Firestore |
| `create_product` | Création. `autoFindImage=true` déclenche la recherche d'icône |
| `update_product` | Mise à jour partielle |
| `set_product_status` | `active` / `draft` / `featured` |
| `duplicate_product` | Copie avec nouveau nom optionnel |
| `delete_product` | Suppression définitive |
| `find_product_image` | Recherche d'icône seule, sans écrire en base |

**Promotions** (collection `promotions`)

| Outil | Description |
| --- | --- |
| `list_promos` | Tous les codes |
| `get_promo` | Recherche par code |
| `create_promo` | Refuse les doublons de code |
| `update_promo` | Code, réduction ou expiration |
| `delete_promo` | Suppression |

**Divers**

| Outil | Description |
| --- | --- |
| `get_stats` | Lit `stats/overview` |
| `update_stats` | Ajoute une entrée et recalcule les totaux du mois |
| `get_current_date` | Date courante en `Africa/Douala` (UTC+1) |

`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.

```bash
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.