Issuebage MCP Server

officiel

plateforme d'émission de badges numériques

GitHub

Documentation

Serveur MCP IssueBadge

npm version License: MIT TypeScript MCP

Un serveur Model Context Protocol (MCP) pour interagir avec l'API IssueBadge. Ce serveur permet aux assistants IA comme Claude et ChatGPT de gérer des badges numériques et des certificats en langage naturel.

🌟 Fonctionnalités

  • 🤖 Gestion de badges assistée par IA : Utilisez le langage naturel pour créer, émettre et gérer des badges
  • 🔐 Double authentification : Prise en charge de Laravel Sanctum et OAuth2
  • 🏆 Cycle de vie complet des badges : Créez des modèles, émettez-les aux destinataires et vérifiez leur authenticité
  • 📊 Support multi-tenant : Isolation sécurisée des locataires pour une utilisation en entreprise
  • 🛡️ Protection d'idempotence : Empêchez les opérations en double grâce à des sécurités intégrées
  • 📧 Notifications automatisées : Envoi automatique d'e-mails avec des URL de vérification
  • 🎨 Champs personnalisés : Métadonnées flexibles et prise en charge des champs personnalisés

🚀 Démarrage rapide

Prérequis

  • Node.js 18+
  • npm 8+
  • Compte API IssueBadge avec clé API

Installation

  1. Cloner le dépôt

    git clone https://github.com/issuebadge/mcp-server.git
cd mcp-server

  2. Installer les dépendances

    npm install

  3. Configurer l'environnement

    cp .env.example .env
# Edit .env with your IssueBadge API credentials

  4. Compiler le projet

    npm run build

  5. Tester le serveur

    npm test

⚙️ Configuration

Créez un fichier .env basé sur .env.example :

# API Configuration
ISSUEBADGE_BASE_URL=https://app.issuebadge.com/api/v1
ISSUEBADGE_API_KEY=

# OAuth2 Configuration (Alternative)
ISSUEBADGE_OAUTH_URL=https://app.issuebadge.com/api/v1/oauth
ISSUEBADGE_OAUTH_TOKEN=your_oauth_token_here

# Authentication Method (sanctum or oauth2)
AUTH_METHOD=sanctum

# Server Configuration
MCP_SERVER_NAME=IssueBadge MCP Server
MCP_SERVER_VERSION=1.0.0

# Optional Settings
REQUEST_TIMEOUT=30000
DEBUG=false
MAX_RETRIES=3
RETRY_DELAY=1000

🔧 Intégration

Claude Desktop

Ajoutez ce serveur à votre configuration Claude Desktop :

{
  "mcpServers": {
    "issuebadge": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "ISSUEBADGE_BASE_URL": "https://app.issuebadge.com
/api/v1",
        "ISSUEBADGE_API_KEY": "",
        "AUTH_METHOD": "sanctum"
      }
    }
  }
}

Actions ChatGPT

  1. Créez un GPT personnalisé dans ChatGPT
  2. Importez la spécification OpenAPI depuis votre instance IssueBadge
  3. Configurez l'authentification par jeton Bearer avec votre clé API
  4. Commencez à gérer les badges par la conversation !

🛠️ Outils disponibles

1. validate_key

Valide les clés API IssueBadge pour l'authentification.

Paramètres :

  • api_key (chaîne, requis) : La clé API à valider

Exemple :

"Validate my API key: 1|abcdef123456789..."

2. get_all_badges

Récupère tous les badges disponibles pour l'organisation authentifiée.

Paramètres :

  • limit (nombre, optionnel) : Nombre maximum de badges à retourner (par défaut : 100)

Exemple :

"Show me all available badges"
"List the first 50 badges"

3. create_badge

Crée un nouveau modèle de badge avec des champs personnalisés optionnels.

Paramètres :

  • name (chaîne, requis) : Nom du badge
  • description (chaîne, requis) : Description du badge
  • issuing_organization_name (chaîne, requis) : Nom de l'organisation
  • idempotency_key (chaîne, requis) : Identifiant unique
  • custom_fields (tableau, optionnel) : Définitions de champs personnalisés
  • Et d'autres paramètres optionnels...

Exemple :

"Create a badge called 'Web Development Certificate' for completing our full-stack course"
"Create a Python certification badge with custom fields for completion date and final score"

4. issue_badge

Émet un badge à un destinataire avec des métadonnées optionnelles.

Paramètres :

  • badge_id (chaîne, requis) : ID du badge issu de la création
  • name (chaîne, requis) : Nom complet du destinataire
  • idempotency_key (chaîne, requis) : Identifiant unique
  • email (chaîne, optionnel) : E-mail du destinataire
  • metadata (objet, optionnel) : Valeurs des champs personnalisés

Exemple :

"Issue the Web Development badge to John Doe with email [email protected]"
"Issue Python certification to Alice with completion date today and score 95%"

💬 Exemples en langage naturel

Création de badges

Human: "Create a badge for JavaScript mastery with fields for completion date and project count"

AI: I'll create a JavaScript mastery badge with the custom fields you specified.

✨ Badge Created Successfully!
🏷️ Badge Name: JavaScript Mastery Certificate
🆔 Badge ID: js_mastery_2024_001
📋 Custom fields: completion_date (date), project_count (number)

Émission de badges

Human: "Issue the JavaScript badge to Sarah Chen with completion date December 1st and 5 projects completed"

AI: I'll issue the JavaScript mastery badge to Sarah Chen with the specified details.

🎉 Badge Issued Successfully!
📧 Recipient: Sarah Chen  
🔗 Verification URL: https://yourdomain.com/verify/xyz123
📅 Completion Date: 2024-12-01
📊 Projects: 5

Opérations par lots

Human: "Create completion badges for all students in my Python course who scored above 85%"

AI: I'll help you create and issue completion badges for high-performing students. First, let me create a Python Course Completion badge, then we can issue it to qualified students.

[Creates badge and processes student list]

🏗️ Développement

Compilation depuis les sources

# Clone the repository
git clone https://github.com/issuebadge/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Lint code
npm run lint

# Format code
npm run format

Structure du projet

mcp-server/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (generated)
├── .env.example         # Environment configuration template
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

🔒 Sécurité

  • Toutes les communications API utilisent HTTPS
  • Les clés API sont validées avant chaque requête
  • Les clés d'idempotence empêchent les opérations en double
  • Isolation des données multi-tenant
  • Protection contre les délais de requête
  • Gestion complète des erreurs

📊 Gestion des erreurs

Le serveur MCP fournit des messages d'erreur détaillés pour les problèmes courants :

  • Erreurs d'authentification : Clés API invalides ou jetons expirés
  • Erreurs de validation : Paramètres requis manquants ou formats invalides
  • Erreurs réseau : Délais de connexion ou indisponibilité du service
  • Erreurs de logique métier : Opérations en double ou permissions insuffisantes

🌍 Cas d'utilisation

Établissements d'enseignement

  • Achèvement de cours : Émettez automatiquement des badges lorsque les étudiants terminent des cours
  • Validation des compétences : Créez des badges basés sur les compétences avec des scores d'évaluation
  • Certificats de fin d'études : Émettez en masse des badges de fin d'études avec des détails académiques

Formation en entreprise

  • Programmes de certification : Gérez les certifications professionnelles avec des dates d'expiration
  • Formation à la conformité : Suivez et vérifiez l'achèvement des formations obligatoires
  • Développement des compétences : Émettez des badges pour les programmes internes de développement des compétences

Gestion d'événements

  • Participation à des conférences : Émettez des badges de participation pour des événements et ateliers
  • Suivi des réalisations : Créez des systèmes de badges progressifs pour des programmes continus
  • Reconnaissance des intervenants : Gérez les badges de reconnaissance pour les intervenants et participants

🤝 Contribution

Nous accueillons les contributions ! Veuillez consulter nos directives de contribution :

  1. Forker le dépôt
  2. Créer une branche de fonctionnalité : git checkout -b feature/amazing-feature
  3. Valider vos modifications : git commit -m 'Add amazing feature'
  4. Pousser vers la branche : git push origin feature/amazing-feature
  5. Ouvrir une Pull Request

Directives de développement

  • Suivez les meilleures pratiques TypeScript
  • Ajoutez une gestion complète des erreurs
  • Incluez des commentaires JSDoc pour les fonctions
  • Mettez à jour les tests pour les nouvelles fonctionnalités
  • Suivez le versionnage sémantique

📝 Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.

🆘 Support

Obtenir de l'aide

Dépannage

Problèmes courants

1. Échec de la validation de la clé API

# Check API key format (should start with number|)
# Verify the key hasn't expired
# Ensure correct base URL

2. Délai de connexion

# Check network connectivity
# Verify IssueBadge service status
# Increase REQUEST_TIMEOUT in .env

3. Erreurs de création de badge

# Verify required fields are provided
# Check idempotency key uniqueness
# Validate organization permissions

🔗 Projets connexes

📈 Feuille de route

Version 1.1

  • Opérations de badges par lots
  • Filtrage et recherche avancés
  • Intégration de webhooks
  • Gestion des modèles de badges

Version 1.2

  • Outils d'analyse et de reporting
  • Règles de validation de badges personnalisées
  • Intégration avec les systèmes de gestion de l'apprentissage
  • Automatisation avancée des flux de travail

Version 2.0

  • Support de vérification par blockchain
  • Contenu de badge multilingue
  • Personnalisation avancée de la marque
  • Intégration SSO d'entreprise

Prêt à révolutionner votre gestion de badges ? Démarrez avec le serveur MCP IssueBadge et découvrez la puissance de l'administration conversationnelle des badges !

Construit avec ❤️ par l'équipe IssueBadge