# KizooShop MCP Server

Serveur [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) pour gérer votre boutique **KizooShop** depuis Claude Desktop, Codex ou tout client MCP compatible. 36 outils pour piloter produits, commandes, réservations, services, collections, promos, images et rapports IA — en langage naturel.

## Installation

```bash
npx kizooshop-mcp
```

Ou installation globale :

```bash
npm install -g kizooshop-mcp
```

## Configuration

Deux variables d'environnement sont requises :

| Variable | Description |
|----------|-------------|
| `KIZOOSHOP_API_URL` | URL de votre boutique KizooShop (ex: `https://kizooshop.com`) |
| `KIZOOSHOP_TOKEN` | Clé de connexion IA (générée dans Paramètres > Connexion IA) |

## Connexion à Claude Desktop

Ajoutez cette configuration dans votre fichier `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "kizooshop": {
      "command": "npx",
      "args": ["-y", "kizooshop-mcp"],
      "env": {
        "KIZOOSHOP_API_URL": "https://kizooshop.com",
        "KIZOOSHOP_TOKEN": "votre_clé_ici"
      }
    }
  }
}
```

## Connexion à Codex

```json
{
  "mcpServers": {
    "kizooshop": {
      "command": "npx",
      "args": ["-y", "kizooshop-mcp"],
      "env": {
        "KIZOOSHOP_API_URL": "https://kizooshop.com",
        "KIZOOSHOP_TOKEN": "votre_clé_ici"
      }
    }
  }
}
```

## 36 Outils disponibles

### Produits (5 outils)
- `list_products` — Liste tous les produits avec prix, stock, images et variantes
- `create_product` — Crée un produit simple ou variable (avec variantes)
- `update_product` — Modifie un produit (nom, prix, stock, variantes)
- `delete_product` — Supprime un produit
- `upload_product_images` — Ajoute des images à un produit via URLs (max 10)

### Commandes (5 outils)
- `list_orders` — Liste les commandes avec filtres (statut, pagination)
- `get_order` — Détails complets d'une commande
- `update_order_status` — Change le statut (pending, paid, shipped, delivered, cancelled)
- `update_order_shipping` — Met à jour les infos de livraison (transporteur, n° suivi)
- `refund_order` — Remboursement total ou partiel

### Réservations & Services (8 outils)
- `list_bookings` — Liste les réservations avec détails client et service
- `cancel_booking` — Annule une réservation
- `get_day_slots` — Créneaux disponibles pour un service à une date donnée
- `list_services` — Liste tous les services proposés
- `create_service` — Crée un service ou une location
- `update_service` — Modifie un service existant
- `delete_service` — Supprime un service
- `upload_service_images` — Ajoute des images à un service via URLs (max 10)

### Boutique & Dashboard (6 outils)
- `get_shop_info` — Informations de la boutique (nom, logo, contacts, réseaux sociaux)
- `update_shop_info` — Met à jour les informations publiques
- `get_dashboard_stats` — Statistiques principales (revenus, commandes, clients)
- `get_dashboard_counts` — Compteurs rapides (commandes en attente, stock bas)
- `get_recent_activity` — Flux d'activité récente
- `upload_shop_images` — Ajoute des images à la boutique (logo, couverture ou carrousel)

### Marketing (5 outils)
- `create_promo` — Crée un code promo (pourcentage ou montant fixe)
- `list_promos` — Liste tous les codes promos
- `delete_promo` — Supprime un code promo
- `get_clients_overview` — Vue d'ensemble des clients (nombre, segments)
- `list_reviews` — Liste les avis clients (en attente, approuvés, rejetés)

### Collections (5 outils)
- `create_collection` — Crée une collection thématique
- `list_collections` — Liste toutes les collections
- `update_collection` — Modifie une collection
- `delete_collection` — Supprime une collection
- `upload_collection_images` — Ajoute des images à une collection via URLs (max 5)

### Rapports IA (2 outils)
- `generate_shop_report` — Rapport analytique complet (tendances, recommandations)
- `generate_finance_report` — Rapport financier détaillé (revenus, marges, frais)

## Exemples d'utilisation

Une fois connecté, parlez simplement à Claude :

> « Montre-moi mes produits »

> « Crée un T-shirt coton à 29.99€, stock 100 »

> « Ajoute cette image à mon produit : https://example.com/tshirt.jpg »

> « Quelles sont mes commandes en attente ? »

> « Marque la commande #abc123 comme expédiée avec le suivi DHL 1234567 »

> « Crée un code promo SUMMER25 de 25% valable jusqu'au 31 août »

> « Génère un rapport de ma boutique sur le dernier mois »

> « Ajoute ce logo à ma boutique : https://example.com/logo.png »

## Architecture

```
src/
├── index.ts          # Point d'entrée MCP (stdio transport)
├── client.ts         # Client HTTP avec auth, retry et gestion d'erreurs
├── types.ts          # Types TypeScript et schémas Zod
└── tools/
    ├── products.ts   # 5 outils produits
    ├── orders.ts     # 5 outils commandes
    ├── bookings.ts   # 8 outils réservations & services
    ├── shop.ts       # 6 outils boutique & dashboard
    ├── marketing.ts  # 5 outils marketing
    ├── collections.ts# 5 outils collections
    └── ai.ts         # 2 outils rapports IA
```

### Client HTTP

- **Authentification** — Bearer token dans le header Authorization
- **Retry** — Backoff exponentiel (1s, 2s, 4s) avec jitter ±25%
- **Timeout** — 30s par requête
- **Erreurs structurées** — Codes : `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `SERVER_ERROR`, `NETWORK_ERROR`

## Développement

```bash
git clone https://github.com/kizooshop/kizooshop-mcp.git
cd kizooshop-mcp
npm install
npm run build
npm run dev
```

## Obtenir votre clé de connexion

1. Connectez-vous à votre dashboard KizooShop
2. Allez dans **Paramètres** > **Connexion IA**
3. Cliquez sur **Générer ma clé**
4. Copiez la configuration affichée dans votre client MCP

## License

MIT