Issuebage MCP Server

resmi

platform penerbitan lencana digital

Dokumentasi

IssueBadge MCP Server

Server Model Context Protocol (MCP) untuk berinteraksi dengan API IssueBadge. Server ini memungkinkan asisten AI seperti Claude dan ChatGPT untuk mengelola lencana dan sertifikat digital menggunakan bahasa alami.

🌟 Fitur

🤖 Manajemen Lencana Bertenaga AI: Gunakan bahasa alami untuk membuat, menerbitkan, dan mengelola lencana
🔐 Autentikasi Ganda: Dukungan untuk Laravel Sanctum dan OAuth2
🏆 Siklus Hidup Lencana Lengkap: Buat templat, terbitkan ke penerima, dan verifikasi keaslian
📊 Dukungan Multi-tenant: Isolasi tenant yang aman untuk penggunaan perusahaan
🛡️ Perlindungan Idempotensi: Cegah operasi duplikat dengan pengaman bawaan
📧 Notifikasi Otomatis: Pengiriman email otomatis dengan URL verifikasi
🎨 Bidang Kustom: Metadata fleksibel dan dukungan bidang kustom

🚀 Mulai Cepat

Prasyarat

Node.js 18+
npm 8+
Akun IssueBadge API dengan kunci API

Instalasi

Kloning repositori

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

Instal dependensi
```
npm install
```

Konfigurasi lingkungan

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

Bangun proyek
```
npm run build
```
Uji server
```
npm test
```

⚙️ Konfigurasi

Buat file .env berdasarkan .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

🔧 Integrasi

Claude Desktop

Tambahkan server ini ke konfigurasi Claude Desktop Anda:

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

Buat GPT Kustom baru di ChatGPT
Impor spesifikasi OpenAPI dari instansi IssueBadge Anda
Konfigurasi autentikasi token Bearer dengan kunci API Anda
Mulai mengelola lencana melalui percakapan!

🛠️ Alat yang Tersedia

1. `validate_key`

Memvalidasi kunci API IssueBadge untuk autentikasi.

Parameter:

api_key (string, wajib): Kunci API yang akan divalidasi

Contoh:

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

2. `get_all_badges`

Mengambil semua lencana yang tersedia untuk organisasi yang terautentikasi.

Parameter:

limit (number, opsional): Maksimum lencana yang dikembalikan (default: 100)

Contoh:

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

3. `create_badge`

Membuat templat lencana baru dengan bidang kustom opsional.

Parameter:

name (string, wajib): Nama lencana
description (string, wajib): Deskripsi lencana
issuing_organization_name (string, wajib): Nama organisasi
idempotency_key (string, wajib): Pengidentifikasi unik
custom_fields (array, opsional): Definisi bidang kustom
Dan parameter opsional lainnya...

Contoh:

"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`

Menerbitkan lencana kepada penerima dengan metadata opsional.

Parameter:

badge_id (string, wajib): ID lencana dari pembuatan
name (string, wajib): Nama lengkap penerima
idempotency_key (string, wajib): Pengidentifikasi unik
email (string, opsional): Email penerima
metadata (object, opsional): Nilai bidang kustom

Contoh:

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

💬 Contoh Bahasa Alami

Membuat Lencana

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)

Menerbitkan Lencana

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

Operasi Batch

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]

🏗️ Pengembangan

Membangun dari Sumber

# 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

Struktur Proyek

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

🔒 Keamanan

Semua komunikasi API menggunakan HTTPS
Kunci API divalidasi sebelum setiap permintaan
Kunci idempotensi mencegah operasi duplikat
Isolasi data multi-tenant
Perlindungan batas waktu permintaan
Penanganan kesalahan yang komprehensif

📊 Penanganan Kesalahan

Server MCP menyediakan pesan kesalahan terperinci untuk masalah umum:

Kesalahan Autentikasi: Kunci API tidak valid atau token kedaluwarsa
Kesalahan Validasi: Parameter wajib hilang atau format tidak valid
Kesalahan Jaringan: Batas waktu koneksi atau layanan tidak tersedia
Kesalahan Logika Bisnis: Operasi duplikat atau izin tidak mencukupi

🌍 Kasus Penggunaan

Institusi Pendidikan

Penyelesaian Kursus: Terbitkan lencana secara otomatis saat siswa menyelesaikan kursus
Validasi Keterampilan: Buat lencana berbasis keterampilan dengan skor penilaian
Sertifikat Kelulusan: Terbitkan lencana kelulusan secara massal dengan detail akademik

Pelatihan Perusahaan

Program Sertifikasi: Kelola sertifikasi profesional dengan tanggal kedaluwarsa
Pelatihan Kepatuhan: Lacak dan verifikasi penyelesaian pelatihan wajib
Pengembangan Keterampilan: Terbitkan lencana untuk program pengembangan keterampilan internal

Manajemen Acara

Kehadiran Konferensi: Terbitkan lencana kehadiran untuk acara dan lokakarya
Pelacakan Pencapaian: Buat sistem lencana progresif untuk program berkelanjutan
Pengakuan Pembicara: Kelola lencana pengakuan pembicara dan peserta

🤝 Berkontribusi

Kami menyambut kontribusi! Silakan lihat panduan kontribusi kami:

Fork repositori
Buat cabang fitur: git checkout -b feature/amazing-feature
Komit perubahan Anda: git commit -m 'Add amazing feature'
Dorong ke cabang: git push origin feature/amazing-feature
Buka Pull Request

Panduan Pengembangan

Ikuti praktik terbaik TypeScript
Tambahkan penanganan kesalahan yang komprehensif
Sertakan komentar JSDoc untuk fungsi
Perbarui pengujian untuk fitur baru
Ikuti semantic versioning

📝 Lisensi

Proyek ini dilisensikan di bawah Lisensi MIT - lihat file LICENSE untuk detailnya.

🆘 Dukungan

Mendapatkan Bantuan

📖 Dokumentasi: Periksa README ini dan komentar kode sebaris
🐛 Laporan Bug: Buka isu
💬 Diskusi: Diskusi GitHub
📧 Email: [email protected]

Pemecahan Masalah

Masalah Umum

1. Validasi Kunci API Gagal

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

2. Batas Waktu Koneksi

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

3. Kesalahan Pembuatan Lencana

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

🔗 Proyek Terkait

IssueBadge API: Platform manajemen lencana inti
Model Context Protocol: Spesifikasi dan alat MCP
Claude Desktop: Asisten AI dengan dukungan MCP

📈 Peta Jalan

Versi 1.1

Operasi lencana batch
Penyaringan dan pencarian lanjutan
Integrasi webhook
Manajemen templat lencana

Versi 1.2

Alat analitik dan pelaporan
Aturan validasi lencana kustom
Integrasi dengan sistem manajemen pembelajaran
Otomatisasi alur kerja lanjutan

Versi 2.0

Dukungan verifikasi blockchain
Konten lencana multi-bahasa
Kustomisasi merek lanjutan
Integrasi SSO perusahaan

Siap merevolusi manajemen lencana Anda? Mulailah dengan IssueBadge MCP Server dan rasakan kekuatan administrasi lencana percakapan!

Dibangun dengan ❤️ oleh tim IssueBadge

Issuebage MCP Server

Dokumentasi

IssueBadge MCP Server

🌟 Fitur

🚀 Mulai Cepat

Prasyarat

Instalasi

⚙️ Konfigurasi

🔧 Integrasi

Claude Desktop

ChatGPT Actions

🛠️ Alat yang Tersedia

1. validate_key

2. get_all_badges

3. create_badge

4. issue_badge

💬 Contoh Bahasa Alami

Membuat Lencana

Menerbitkan Lencana

Operasi Batch

🏗️ Pengembangan

Membangun dari Sumber

Struktur Proyek

🔒 Keamanan

📊 Penanganan Kesalahan

🌍 Kasus Penggunaan

Institusi Pendidikan

Pelatihan Perusahaan

Manajemen Acara

🤝 Berkontribusi

Panduan Pengembangan

📝 Lisensi

🆘 Dukungan

Mendapatkan Bantuan

Pemecahan Masalah

Masalah Umum

🔗 Proyek Terkait

📈 Peta Jalan

Versi 1.1

Versi 1.2

Versi 2.0

1. `validate_key`

2. `get_all_badges`

3. `create_badge`

4. `issue_badge`