npm package: @goodangelmedia/skaze-mcp-server
Description: Serveur MCP pour l'API Skaze - Gestion des campagnes publicitaires programmatiques
Author: Good Angel Media
Latest version: 1.0.0

# Serveur MCP Skaze

Serveur Model Context Protocol (MCP) pour interagir avec l'API Skaze - Plateforme de publicité digitale programmatique omnicanale.

## 📋 Description

Ce serveur MCP permet d'accéder aux données de campagnes publicitaires Skaze directement depuis votre environnement Manus. Il fournit des outils pour :

- ✅ Se connecter à l'API Skaze (auto-connexion supportée)
- ✅ Lister les advertisers (annonceurs)
- ✅ Récupérer les campagnes par advertiser
- ✅ Analyser les métriques ROI (impressions, clicks, conversions, revenus)
- ✅ Obtenir des métriques détaillées par date, campagne, format ou SSP
- ✅ Consulter les informations utilisateur

## 🚀 Démarrage rapide

Consultez [`QUICKSTART.md`](QUICKSTART.md) pour une installation rapide en 3 étapes.

## 📦 Installation complète

Consultez [`INSTALLATION.md`](INSTALLATION.md) pour un guide d'installation détaillé.

### Installation en résumé

```bash
# Extraire et installer
tar -xzf skaze-mcp-server-v1.0.0.tar.gz
cd skaze-mcp-server
npm install
npm run build
npm install -g .
```

### Configuration dans Manus

```json
{
  "mcpServers": {
    "skaze-mcp-server": {
      "command": "skaze-mcp-server",
      "args": [],
      "env": {
        "SKAZE_EMAIL": "votre-email@example.com",
        "SKAZE_PASSWORD": "votre-mot-de-passe"
      }
    }
  }
}
```

## 🛠️ Outils disponibles

### Authentification

#### `skaze_login`
Se connecter à l'API Skaze (non nécessaire si auto-connexion configurée).

**Paramètres** :
- `email` (string, requis)
- `password` (string, requis)

#### `skaze_get_user_info`
Récupérer les informations de l'utilisateur connecté.

**Paramètres** : Aucun

### Advertisers

#### `skaze_list_advertisers`
Lister tous les advertisers disponibles.

**Paramètres** :
- `user_id` (number, optionnel)

**Exemple** :
```bash
manus-mcp-cli tool call skaze_list_advertisers --server skaze-mcp-server --input '{}'
```

### Campagnes

#### `skaze_list_campaigns`
Récupérer les campagnes d'un advertiser.

**Paramètres** :
- `advertiser_id` (number, requis)
- `period` (string, optionnel) : `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`
- `date_in` (string, optionnel) : Date de début (YYYY-MM-DD)
- `date_out` (string, optionnel) : Date de fin (YYYY-MM-DD)
- `include_archived` (boolean, optionnel, défaut: false)
- `active_only` (boolean, optionnel, défaut: true)

**Exemple** :
```bash
manus-mcp-cli tool call skaze_list_campaigns --server skaze-mcp-server --input '{
  "advertiser_id": 109,
  "period": "last_30_days"
}'
```

### Métriques ROI

#### `skaze_get_roi_metrics`
Récupérer les métriques ROI globales.

**Paramètres** :
- `advertiser_id` (number, requis)
- `campaign_id` (number, optionnel)
- `period` (string, optionnel)
- `date_in` (string, optionnel)
- `date_out` (string, optionnel)
- `agency` (string, optionnel, défaut: "olyn_group")

**Métriques retournées** :
- Volume : impressions, clicks, visites
- Coûts : spending, CPM, CPC, CPA
- Performance : CTR, CR, MRC
- Vidéo : starts, complétions, VI
- Conversions : DSP et Pixel
- Revenus : DSP et Pixel

**Exemple** :
```bash
manus-mcp-cli tool call skaze_get_roi_metrics --server skaze-mcp-server --input '{
  "advertiser_id": 109,
  "period": "last_7_days"
}'
```

### Métriques détaillées

#### `skaze_get_metrics_by_date`
Métriques agrégées par date.

**Paramètres** :
- `advertiser_id` (number, requis)
- `campaign_id` (number, optionnel)
- `period` (string, optionnel)
- `date_in` / `date_out` (string, optionnel)

#### `skaze_get_metrics_by_campaign`
Métriques agrégées par campagne.

**Paramètres** :
- `advertiser_id` (number, requis)
- `period` (string, optionnel)
- `date_in` / `date_out` (string, optionnel)

#### `skaze_get_metrics_by_format`
Métriques agrégées par format publicitaire (display, vidéo, etc.).

**Paramètres** :
- `advertiser_id` (number, requis)
- `campaign_id` (number, optionnel)
- `period` (string, optionnel)
- `date_in` / `date_out` (string, optionnel)

#### `skaze_get_metrics_by_ssp`
Métriques agrégées par SSP/partenaire.

**Paramètres** :
- `advertiser_id` (number, requis)
- `campaign_id` (number, optionnel)
- `period` (string, optionnel)
- `date_in` / `date_out` (string, optionnel)

## 📊 Exemples d'utilisation dans Manus

### Analyse d'un advertiser

```
Utilise le serveur Skaze pour :
1. Lister tous mes advertisers
2. Récupérer les métriques ROI de l'advertiser 109 sur les 30 derniers jours
3. Analyser les performances par campagne
```

### Comparaison de formats

```
Compare les performances par format publicitaire pour l'advertiser 3 (WWF) 
sur les 7 derniers jours. Montre-moi les impressions, clicks et CTR pour chaque format.
```

### Évolution temporelle

```
Montre-moi l'évolution quotidienne des métriques pour l'advertiser 109 
sur le mois en cours. Crée un graphique avec les impressions et le CTR.
```

### Analyse de campagne spécifique

```
Pour la campagne 2191 de l'advertiser 109 :
1. Récupère les métriques ROI
2. Analyse les performances par format
3. Identifie les meilleurs SSP partenaires
```

## 🔧 Structure du projet

```
skaze-mcp-server/
├── src/
│   └── index.ts              # Code source principal
├── dist/                     # Code compilé (généré)
├── node_modules/             # Dépendances (généré)
├── package.json              # Configuration npm
├── tsconfig.json             # Configuration TypeScript
├── README.md                 # Ce fichier
├── INSTALLATION.md           # Guide d'installation détaillé
├── QUICKSTART.md             # Démarrage rapide
└── .gitignore               # Fichiers à ignorer
```

## 🔐 Sécurité

### Auto-connexion sécurisée

Les identifiants sont :
- ✅ Stockés dans la configuration MCP de Manus
- ✅ Passés via des variables d'environnement (méthode standard et sécurisée)
- ✅ Jamais écrits sur le disque par le serveur
- ✅ Conservés en mémoire uniquement pendant l'exécution

### Bonnes pratiques

- Ne partagez jamais votre fichier de configuration JSON contenant vos identifiants
- Utilisez des utilisateurs API dédiés avec permissions limitées si possible
- Changez régulièrement vos mots de passe
- Ne commitez jamais les identifiants dans le code source

## 🌐 API Skaze

### URL de base
```
https://strapi.sts.prod1.skaze.com
```

### Endpoints utilisés

- `POST /api/auth/local` : Authentification
- `GET /api/users/me` : Informations utilisateur
- `POST /api/datalake/advForMultiClient` : Liste des advertisers
- `GET /api/campaigns` : Campagnes d'un advertiser
- `POST /api/datalake/roi` : Métriques ROI
- `POST /api/datalake/table` : Métriques agrégées

### Documentation complète

La documentation complète de l'API Skaze est disponible dans le SDK Python fourni :
- `Skaze_API_SDK_v1.0/docs/API_REFERENCE.md`
- `Skaze_API_SDK_v1.0/docs/QUICKSTART.md`
- `Skaze_API_SDK_v1.0/docs/EXAMPLES.md`

## 🐛 Dépannage

### Le serveur ne démarre pas

**Erreur** : `skaze-mcp-server: command not found`

**Solution** :
```bash
cd skaze-mcp-server
npm install -g .
```

### Erreur d'authentification

**Erreur** : `Échec de connexion` ou `Non authentifié`

**Solutions** :
1. Vérifiez vos identifiants dans la configuration Manus
2. Testez manuellement :
   ```bash
   export SKAZE_EMAIL="votre-email@example.com"
   export SKAZE_PASSWORD="votre-mot-de-passe"
   skaze-mcp-server
   ```
3. Vérifiez que vous avez accès à `strapi.sts.prod1.skaze.com`

### Pas de données retournées

**Causes possibles** :
- L'advertiser_id n'existe pas ou vous n'y avez pas accès
- La période sélectionnée ne contient pas de données
- Les filtres sont trop restrictifs

**Solution** :
Vérifiez d'abord avec `skaze_list_advertisers` pour obtenir les IDs valides.

### Timeout de connexion

**Solution** :
- Vérifiez votre connexion internet
- Vérifiez que `strapi.sts.prod1.skaze.com` est accessible
- Augmentez le timeout dans le code si nécessaire (actuellement 30s)

## 🔄 Mise à jour

Pour mettre à jour le serveur :

```bash
cd skaze-mcp-server

# Modifier le code si nécessaire

# Recompiler
npm run build

# Réinstaller
npm install -g .
```

Redémarrez Manus pour que les changements soient pris en compte.

## 📝 Développement

### Compiler le code

```bash
npm run build
```

### Tester localement

```bash
# Avec auto-connexion
export SKAZE_EMAIL="votre-email@example.com"
export SKAZE_PASSWORD="votre-mot-de-passe"
node dist/index.js

# Le serveur démarre et se connecte automatiquement
```

### Linter et formater (à ajouter)

```bash
# À configurer selon vos préférences
npm run lint
npm run format
```

## 📄 Licence

MIT

## 👤 Auteur

Good Angel Media

## 🤝 Support

Pour toute question ou problème :
1. Consultez `INSTALLATION.md` pour les problèmes d'installation
2. Consultez `QUICKSTART.md` pour un démarrage rapide
3. Vérifiez les logs du serveur dans Manus
4. Contactez le support Skaze pour les problèmes d'API

## 📚 Documentation associée

- [`INSTALLATION.md`](INSTALLATION.md) : Guide d'installation détaillé
- [`QUICKSTART.md`](QUICKSTART.md) : Démarrage rapide
- `Skaze_API_SDK_v1.0/docs/API_REFERENCE.md` : Référence complète de l'API Skaze
- `Skaze_API_SDK_v1.0/docs/EXAMPLES.md` : Exemples d'utilisation de l'API

## 🎯 Cas d'usage

### Reporting automatisé

Créez des rapports automatiques de performance pour vos clients :
```
Génère un rapport hebdomadaire pour tous mes advertisers avec :
- Impressions totales
- CTR moyen
- Dépenses totales
- Top 3 des campagnes par performance
```

### Analyse comparative

Comparez les performances entre différentes périodes :
```
Compare les métriques de l'advertiser 109 entre :
- Les 7 derniers jours
- Les 7 jours précédents
Identifie les tendances et variations significatives
```

### Optimisation de campagnes

Identifiez les opportunités d'optimisation :
```
Pour l'advertiser 3, analyse :
- Les formats avec le meilleur ROI
- Les SSP les plus performants
- Les créatives avec le meilleur CTR
Recommande des optimisations
```

---

**Version** : 1.0.0  
**Dernière mise à jour** : Octobre 2025  
**Node.js** : 20+  
**TypeScript** : 5+