Issuebage MCP Server

resmi

dijital rozet verme platformu

GitHub

Dokümantasyon

IssueBadge MCP Sunucusu

npm version License: MIT TypeScript MCP

IssueBadge API ile etkileşim kurmak için bir Model Bağlam Protokolü (MCP) sunucusu. Bu sunucu, Claude ve ChatGPT gibi yapay zeka asistanlarının doğal dil kullanarak dijital rozetleri ve sertifikaları yönetmesini sağlar.

🌟 Özellikler

  • 🤖 Yapay Zeka Destekli Rozet Yönetimi: Rozetleri oluşturmak, vermek ve yönetmek için doğal dil kullanın
  • 🔐 Çift Kimlik Doğrulama: Hem Laravel Sanctum hem de OAuth2 desteği
  • 🏆 Tam Rozet Yaşam Döngüsü: Şablonlar oluşturun, alıcılara verin ve doğruluğunu onaylayın
  • 📊 Çok Kiracılı Destek: Kurumsal kullanım için güvenli kiracı izolasyonu
  • 🛡️ Idempotency Koruması: Dahili güvenlik önlemleriyle yinelenen işlemleri önleyin
  • 📧 Otomatik Bildirimler: Doğrulama URL'leri ile otomatik e-posta gönderimi
  • 🎨 Özel Alanlar: Esnek meta veri ve özel alan desteği

🚀 Hızlı Başlangıç

Ön Koşullar

  • Node.js 18+
  • npm 8+
  • API anahtarına sahip IssueBadge API hesabı

Kurulum

  1. Depoyu klonlayın

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

  2. Bağımlılıkları yükleyin

    npm install

  3. Ortamı yapılandırın

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

  4. Projeyi derleyin

    npm run build

  5. Sunucuyu test edin

    npm test

⚙️ Yapılandırma

.env.example dosyasını temel alarak bir .env dosyası oluşturun:

# 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

🔧 Entegrasyon

Claude Desktop

Bu sunucuyu Claude Desktop yapılandırmanıza ekleyin:

{
  "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. ChatGPT'de yeni bir Özel GPT oluşturun
  2. IssueBadge örneğinizden OpenAPI spesifikasyonunu içe aktarın
  3. API anahtarınızla Bearer token kimlik doğrulamasını yapılandırın
  4. Sohbet yoluyla rozetleri yönetmeye başlayın!

🛠️ Mevcut Araçlar

1. validate_key

Kimlik doğrulama için IssueBadge API anahtarlarını doğrular.

Parametreler:

  • api_key (string, zorunlu): Doğrulanacak API anahtarı

Örnek:

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

2. get_all_badges

Kimliği doğrulanmış kuruluş için mevcut tüm rozetleri getirir.

Parametreler:

  • limit (number, isteğe bağlı): Döndürülecek maksimum rozet sayısı (varsayılan: 100)

Örnek:

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

3. create_badge

İsteğe bağlı özel alanlarla yeni bir rozet şablonu oluşturur.

Parametreler:

  • name (string, zorunlu): Rozet adı
  • description (string, zorunlu): Rozet açıklaması
  • issuing_organization_name (string, zorunlu): Kuruluş adı
  • idempotency_key (string, zorunlu): Benzersiz tanımlayıcı
  • custom_fields (array, isteğe bağlı): Özel alan tanımları
  • Ve daha fazla isteğe bağlı parametre...

Örnek:

"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

İsteğe bağlı meta verilerle bir alıcıya rozet verir.

Parametreler:

  • badge_id (string, zorunlu): Oluşturmadan alınan rozet kimliği
  • name (string, zorunlu): Alıcının tam adı
  • idempotency_key (string, zorunlu): Benzersiz tanımlayıcı
  • email (string, isteğe bağlı): Alıcının e-postası
  • metadata (object, isteğe bağlı): Özel alan değerleri

Örnek:

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

💬 Doğal Dil Örnekleri

Rozet Oluşturma

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)

Rozet Verme

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

Toplu İşlemler

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]

🏗️ Geliştirme

Kaynaktan Derleme

# 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

Proje Yapısı

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

🔒 Güvenlik

  • Tüm API iletişimleri HTTPS kullanır
  • API anahtarları her istekten önce doğrulanır
  • Idempotency anahtarları yinelenen işlemleri önler
  • Çok kiracılı veri izolasyonu
  • İstek zaman aşımı koruması
  • Kapsamlı hata yönetimi

📊 Hata Yönetimi

MCP sunucusu, yaygın sorunlar için ayrıntılı hata mesajları sağlar:

  • Kimlik Doğrulama Hataları: Geçersiz API anahtarları veya süresi dolmuş token'lar
  • Doğrulama Hataları: Eksik zorunlu parametreler veya geçersiz formatlar
  • Ağ Hataları: Bağlantı zaman aşımları veya hizmet kullanılamaması
  • İş Mantığı Hataları: Yinelenen işlemler veya yetersiz izinler

🌍 Kullanım Örnekleri

Eğitim Kurumları

  • Kurs Tamamlama: Öğrenciler kursları tamamladığında otomatik olarak rozet verin
  • Beceri Doğrulama: Değerlendirme puanlarıyla beceri tabanlı rozetler oluşturun
  • Mezuniyet Sertifikaları: Akademik detaylarla toplu mezuniyet rozetleri verin

Kurumsal Eğitim

  • Sertifikasyon Programları: Son kullanma tarihleriyle profesyonel sertifikaları yönetin
  • Uyumluluk Eğitimi: Zorunlu eğitim tamamlamayı takip edin ve doğrulayın
  • Beceri Geliştirme: Dahili beceri geliştirme programları için rozetler verin

Etkinlik Yönetimi

  • Konferans Katılımı: Etkinlikler ve atölyeler için katılım rozetleri verin
  • Başarı Takibi: Devam eden programlar için aşamalı rozet sistemleri oluşturun
  • Konuşmacı Tanıma: Konuşmacı ve katılımcı tanıma rozetlerini yönetin

🤝 Katkıda Bulunma

Katkılarınızı memnuniyetle karşılıyoruz! Lütfen katkı yönergelerimize bakın:

  1. Depoyu çatallayın
  2. Bir özellik dalı oluşturun: git checkout -b feature/amazing-feature
  3. Değişikliklerinizi işleyin: git commit -m 'Add amazing feature'
  4. Dala gönderin: git push origin feature/amazing-feature
  5. Bir Çekme İsteği açın

Geliştirme Yönergeleri

  • TypeScript en iyi uygulamalarını takip edin
  • Kapsamlı hata yönetimi ekleyin
  • Fonksiyonlar için JSDoc yorumları ekleyin
  • Yeni özellikler için testleri güncelleyin
  • Semantik sürümlemeyi takip edin

📝 Lisans

Bu proje MIT Lisansı altında lisanslanmıştır - ayrıntılar için LICENSE dosyasına bakın.

🆘 Destek

Yardım Alma

Sorun Giderme

Yaygın Sorunlar

1. API Anahtarı Doğrulaması Başarısız

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

2. Bağlantı Zaman Aşımı

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

3. Rozet Oluşturma Hataları

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

🔗 İlgili Projeler

📈 Yol Haritası

Sürüm 1.1

  • Toplu rozet işlemleri
  • Gelişmiş filtreleme ve arama
  • Webhook entegrasyonu
  • Rozet şablon yönetimi

Sürüm 1.2

  • Analitik ve raporlama araçları
  • Özel rozet doğrulama kuralları
  • Öğrenme yönetim sistemleriyle entegrasyon
  • Gelişmiş iş akışı otomasyonu

Sürüm 2.0

  • Blok zinciri doğrulama desteği
  • Çok dilli rozet içeriği
  • Gelişmiş marka özelleştirme
  • Kurumsal SSO entegrasyonu

Rozet yönetiminizde devrim yapmaya hazır mısınız? IssueBadge MCP Sunucusu ile başlayın ve sohbet tabanlı rozet yönetiminin gücünü deneyimleyin!

IssueBadge ekibi tarafından ❤️ ile geliştirildi