Issuebage MCP Server

offiziell

digitale Badge-Ausstellungsplattform

GitHub

Dokumentation

IssueBadge MCP Server

npm version License: MIT TypeScript MCP

Ein Model Context Protocol (MCP) Server für die Interaktion mit der IssueBadge API. Dieser Server ermöglicht KI-Assistenten wie Claude und ChatGPT, digitale Badges und Zertifikate in natürlicher Sprache zu verwalten.

🌟 Funktionen

  • 🤖 KI-gestützte Badge-Verwaltung: Erstellen, Ausstellen und Verwalten von Badges in natürlicher Sprache
  • 🔐 Duale Authentifizierung: Unterstützung für Laravel Sanctum und OAuth2
  • 🏆 Vollständiger Badge-Lebenszyklus: Vorlagen erstellen, an Empfänger ausstellen und Echtheit überprüfen
  • 📊 Multi-Mandanten-Unterstützung: Sichere Mandantenisolation für den Unternehmenseinsatz
  • 🛡️ Idempotenzschutz: Verhinderung doppelter Vorgänge durch integrierte Sicherheitsmechanismen
  • 📧 Automatisierte Benachrichtigungen: Automatischer E-Mail-Versand mit Verifikations-URLs
  • 🎨 Benutzerdefinierte Felder: Flexible Metadaten und Unterstützung für benutzerdefinierte Felder

🚀 Schnellstart

Voraussetzungen

  • Node.js 18+
  • npm 8+
  • IssueBadge API-Konto mit API-Schlüssel

Installation

  1. Repository klonen

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

  2. Abhängigkeiten installieren

    npm install

  3. Umgebung konfigurieren

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

  4. Projekt bauen

    npm run build

  5. Server testen

    npm test

⚙️ Konfiguration

Erstellen Sie eine .env-Datei basierend auf .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

🔧 Integration

Claude Desktop

Fügen Sie diesen Server zu Ihrer Claude Desktop-Konfiguration hinzu:

{
  "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"
      }
    }
  }
}

ChatGPT Actions

  1. Erstellen Sie einen neuen Custom GPT in ChatGPT
  2. Importieren Sie die OpenAPI-Spezifikation von Ihrer IssueBadge-Instanz
  3. Konfigurieren Sie die Bearer-Token-Authentifizierung mit Ihrem API-Schlüssel
  4. Beginnen Sie mit der Badge-Verwaltung per Konversation!

🛠️ Verfügbare Werkzeuge

1. validate_key

Validiert IssueBadge API-Schlüssel zur Authentifizierung.

Parameter:

  • api_key (string, erforderlich): Der zu validierende API-Schlüssel

Beispiel:

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

2. get_all_badges

Ruft alle verfügbaren Badges für die authentifizierte Organisation ab.

Parameter:

  • limit (number, optional): Maximale Anzahl zurückzugebender Badges (Standard: 100)

Beispiel:

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

3. create_badge

Erstellt eine neue Badge-Vorlage mit optionalen benutzerdefinierten Feldern.

Parameter:

  • name (string, erforderlich): Badge-Name
  • description (string, erforderlich): Badge-Beschreibung
  • issuing_organization_name (string, erforderlich): Organisationsname
  • idempotency_key (string, erforderlich): Eindeutige Kennung
  • custom_fields (array, optional): Definitionen benutzerdefinierter Felder
  • Und weitere optionale Parameter...

Beispiel:

"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

Stellt einen Badge an einen Empfänger aus, mit optionalen Metadaten.

Parameter:

  • badge_id (string, erforderlich): Badge-ID aus der Erstellung
  • name (string, erforderlich): Vollständiger Name des Empfängers
  • idempotency_key (string, erforderlich): Eindeutige Kennung
  • email (string, optional): E-Mail des Empfängers
  • metadata (object, optional): Werte für benutzerdefinierte Felder

Beispiel:

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

💬 Beispiele in natürlicher Sprache

Badges erstellen

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)

Badges ausstellen

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

Stapelverarbeitung

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]

🏗️ Entwicklung

Aus dem Quellcode bauen

# 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

Projektstruktur

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

🔒 Sicherheit

  • Alle API-Kommunikationen verwenden HTTPS
  • API-Schlüssel werden vor jeder Anfrage validiert
  • Idempotenzschlüssel verhindern doppelte Vorgänge
  • Datenisolation für mehrere Mandanten
  • Schutz vor Anfrage-Timeouts
  • Umfassende Fehlerbehandlung

📊 Fehlerbehandlung

Der MCP-Server liefert detaillierte Fehlermeldungen für häufige Probleme:

  • Authentifizierungsfehler: Ungültige API-Schlüssel oder abgelaufene Token
  • Validierungsfehler: Fehlende erforderliche Parameter oder ungültige Formate
  • Netzwerkfehler: Verbindungs-Timeouts oder Nichtverfügbarkeit des Dienstes
  • Geschäftslogikfehler: Doppelte Vorgänge oder unzureichende Berechtigungen

🌍 Anwendungsfälle

Bildungseinrichtungen

  • Kursabschluss: Automatische Ausstellung von Badges bei Kursabschluss
  • Kompetenzvalidierung: Erstellung kompetenzbasierter Badges mit Bewertungsergebnissen
  • Abschlusszertifikate: Massenausstellung von Abschluss-Badges mit akademischen Details

Unternehmensschulungen

  • Zertifizierungsprogramme: Verwaltung beruflicher Zertifizierungen mit Ablaufdaten
  • Compliance-Schulungen: Nachverfolgung und Überprüfung obligatorischer Schulungsabschlüsse
  • Kompetenzentwicklung: Ausstellung von Badges für interne Kompetenzentwicklungsprogramme

Veranstaltungsmanagement

  • Konferenzteilnahme: Ausstellung von Teilnahme-Badges für Veranstaltungen und Workshops
  • Leistungsverfolgung: Erstellung progressiver Badge-Systeme für laufende Programme
  • Referentenanerkennung: Verwaltung von Badges für Referenten- und Teilnehmeranerkennung

🤝 Mitwirken

Beiträge sind willkommen! Bitte beachten Sie unsere Mitwirkrichtlinien:

  1. Repository forken
  2. Feature-Branch erstellen: git checkout -b feature/amazing-feature
  3. Änderungen committen: git commit -m 'Add amazing feature'
  4. Auf den Branch pushen: git push origin feature/amazing-feature
  5. Pull Request öffnen

Entwicklungsrichtlinien

  • TypeScript Best Practices befolgen
  • Umfassende Fehlerbehandlung hinzufügen
  • JSDoc-Kommentare für Funktionen einfügen
  • Tests für neue Funktionen aktualisieren
  • Semantische Versionierung befolgen

📝 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe LICENSE-Datei für Details.

🆘 Support

Hilfe erhalten

Fehlerbehebung

Häufige Probleme

1. API-Schlüssel-Validierung fehlgeschlagen

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

2. Verbindungs-Timeout

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

3. Fehler bei der Badge-Erstellung

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

🔗 Verwandte Projekte

📈 Roadmap

Version 1.1

  • Stapelverarbeitung von Badges
  • Erweiterte Filterung und Suche
  • Webhook-Integration
  • Verwaltung von Badge-Vorlagen

Version 1.2

  • Analyse- und Berichtswerkzeuge
  • Benutzerdefinierte Badge-Validierungsregeln
  • Integration mit Lernmanagementsystemen
  • Erweiterte Workflow-Automatisierung

Version 2.0

  • Unterstützung für Blockchain-Verifikation
  • Mehrsprachige Badge-Inhalte
  • Erweiterte Branding-Anpassung
  • Enterprise-SSO-Integration

Bereit, Ihre Badge-Verwaltung zu revolutionieren? Starten Sie mit dem IssueBadge MCP Server und erleben Sie die Leistungsfähigkeit der konversationsbasierten Badge-Administration!

Mit ❤️ vom IssueBadge-Team entwickelt