Snipcart MCP Server

Un serveur MCP (Model Context Protocol) pour interagir avec l'API Snipcart v3.

Installation

1. Clonez ce repository

2. Installez les dépendances :

   npm install

3. Compilez le projet :

   npm run build

⚠️ Important - Facturation Snipcart

ATTENTION : L'utilisation de la clé API de production (SNIPCART_API_KEY_LIVE_SECRET) active automatiquement la facturation Snipcart de 20$/mois. Cette facturation commence dès que vous utilisez la clé live, même pour des tests.

• Environnement de test : Gratuit, utilisez SNIPCART_ENVIRONMENT=test
• Environnement de production : 20$/mois, utilisez SNIPCART_ENVIRONMENT=production

Assurez-vous de bien comprendre les implications financières avant d'activer l'environnement de production.

Configuration

Créez un fichier .env à la racine du projet avec vos clés secrètes Snipcart :

# Clés secrètes Snipcart (pour l'authentification API)
SNIPCART_API_KEY_TEST_SECRET=ST_votre_cle_secrete_test
SNIPCART_API_KEY_LIVE_SECRET=S_votre_cle_secrete_production

# Environnement (test ou production)
SNIPCART_ENVIRONMENT=test

Clés API

Clés secrètes uniquement :

• Clé secrète de test : Pour le développement et les tests (commence par ST_)
• Clé secrète de production : Pour l'environnement de production (commence par S_)

Vous pouvez trouver vos clés secrètes dans votre tableau de bord Snipcart sous Account > API Keys.

⚠️ Important :

• Utilisez uniquement les clés secrètes pour l'authentification API
• Utilisez toujours la clé de test pendant le développement
• Ne commitez jamais vos clés API dans votre code
• Les clés de test et de production donnent accès à des données différentes

Test de configuration

Pour vérifier que votre configuration est correcte, exécutez :

node test-snipcart.cjs

Ce script vérifiera :

• La présence des clés secrètes
• Le format des clés (ST_ pour test, S_ pour production)
• L'authentification avec l'API Snipcart

Utilisation

Configuration MCP

Pour utiliser ce serveur avec un client MCP (comme Claude Desktop), ajoutez la configuration suivante :

1. Copiez le fichier de configuration exemple :

   cp mcp-config.example.json mcp-config.json

2. Modifiez mcp-config.json avec vos chemins et clés :

   • Le chemin ./dist/index.js est relatif au répertoire du projet
   • Remplacez /chemin/vers/votre/SnipcartMCP dans cwd par le chemin absolu vers votre projet
   • Ajoutez vos clés API Snipcart dans les variables d'environnement

   {
       "mcpServers": {
         "snipcart": {
           "command": "npx",
           "args": ["-y", "./dist/index.js"],
           "cwd": "/chemin/vers/votre/SnipcartMCP",
         "env": {
           "SNIPCART_ENVIRONMENT": "test",
           "SNIPCART_API_KEY_TEST_SECRET": "ST_votre_cle_secrete_test",
           "SNIPCART_API_KEY_LIVE_SECRET": "S_votre_cle_secrete_production"
         }
       }
     }
   }

Démarrage manuel

Pour démarrer le serveur MCP manuellement :

npm start

Outils disponibles

Commandes (Orders)

• get_orders : Récupère toutes les commandes avec filtrage optionnel
• get_order : Récupère une commande spécifique par token
• update_order : Met à jour le statut, numéro de suivi ou métadonnées d'une commande

Clients (Customers)

• get_customers : Récupère tous les clients avec filtrage optionnel
• get_customer : Récupère un client spécifique par ID
• get_customer_orders : Récupère toutes les commandes d'un client spécifique

Produits (Products)

• get_products : Récupère tous les produits avec filtrage et tri optionnels
• get_product : Récupère un produit spécifique par ID
• update_product : Met à jour l'inventaire et les métadonnées d'un produit

Remises (Discounts)

• get_discounts : Récupère toutes les remises
• get_discount : Récupère une remise spécifique par ID
• create_discount : Crée une nouvelle remise
• update_discount : Met à jour une remise existante
• delete_discount : Supprime une remise

Exemples d'utilisation

Récupérer toutes les commandes

{
  "tool": "get_orders",
  "arguments": {
    "limit": 10,
    "status": "Processed"
  }
}

Créer une remise

{
  "tool": "create_discount",
  "arguments": {
    "name": "Remise 10%",
    "trigger": "Code",
    "type": "Rate",
    "code": "SAVE10",
    "rate": 10
  }
}

Mettre à jour le statut d'une commande

{
  "tool": "update_order",
  "arguments": {
    "token": "order_token_here",
    "status": "Shipped",
    "trackingNumber": "1234567890"
  }
}

Bonnes pratiques et sécurité

Gestion des clés API

• ✅ Utilisez des variables d'environnement : Ne jamais hardcoder les clés dans le code
• ✅ Séparez les environnements : Utilisez des clés différentes pour test et production
• ✅ Rotation des clés : Changez régulièrement vos clés de production
• ✅ Principe du moindre privilège : Utilisez les clés avec les permissions minimales nécessaires

Développement

• 🧪 Tests en premier : Toujours tester avec l'environnement de test avant la production
• 📝 Logs structurés : Le serveur inclut des logs détaillés pour le debugging
• 🔄 Gestion d'erreurs : Toutes les requêtes API incluent une gestion d'erreurs robuste
• ⚡ Performance : Utilisez les paramètres de pagination pour les grandes collections

Monitoring

• 📊 Surveillez les quotas : Vérifiez régulièrement votre utilisation de l'API
• 🚨 Alertes d'erreurs : Configurez des alertes pour les erreurs 401/403
• 📈 Métriques : Suivez les performances de vos requêtes API

Dépannage

Erreurs courantes

401 Unauthorized

• Vérifiez que votre clé secrète est correcte
• Assurez-vous d'utiliser la bonne clé pour l'environnement
• Vérifiez que la clé n'a pas expiré

404 Not Found

• Vérifiez l'ID/token de la ressource demandée
• Assurez-vous que la ressource existe dans l'environnement correct

Rate Limiting

• Implémentez un délai entre les requêtes
• Utilisez la pagination pour réduire la charge

Logs de debug

Pour activer les logs détaillés :

DEBUG=snipcart:* npm start

API Snipcart

Ce serveur MCP utilise l'API REST Snipcart v3. Pour plus d'informations sur l'API, consultez la documentation officielle.

Contribution

Les contributions sont les bienvenues ! Veuillez :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité
3. Ajouter des tests pour votre code
4. Exécuter node test-snipcart.cjs pour valider
5. Soumettre une pull request

Licence

MIT