Issuebage MCP Server

官方

數位徽章發行平台

GitHub

文件

IssueBadge MCP 伺服器

一個用於與 IssueBadge API 互動的模型上下文協定 (MCP) 伺服器。此伺服器讓 Claude 和 ChatGPT 等 AI 助理能夠使用自然語言管理數位徽章和證書。

🌟 功能特色

🤖 AI 驅動的徽章管理：使用自然語言建立、頒發和管理徽章
🔐 雙重驗證：同時支援 Laravel Sanctum 和 OAuth2
🏆 完整的徽章生命週期：建立範本、頒發給收件者並驗證真實性
📊 多租戶支援：為企業用途提供安全的租戶隔離
🛡️ 冪等性保護：透過內建防護機制防止重複操作
📧 自動化通知：自動發送包含驗證網址的電子郵件
🎨 自訂欄位：靈活的詮釋資料和自訂欄位支援

🚀 快速入門

必要條件

Node.js 18+
npm 8+
具有 API 金鑰的 IssueBadge API 帳戶

安裝

複製儲存庫

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

安裝相依套件
```
npm install
```

設定環境

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

建置專案
```
npm run build
```
測試伺服器
```
npm test
```

⚙️ 設定

根據 .env.example 建立一個 .env 檔案：

# 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

🔧 整合

Claude Desktop

將此伺服器新增至您的 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"
      }
    }
  }
}

ChatGPT Actions

在 ChatGPT 中建立一個新的自訂 GPT
從您的 IssueBadge 執行個體匯入 OpenAPI 規格
使用您的 API 金鑰設定 Bearer 權杖驗證
開始透過對話管理徽章！

🛠️ 可用工具

1. `validate_key`

驗證用於身分驗證的 IssueBadge API 金鑰。

參數：

api_key (字串，必要)：要驗證的 API 金鑰

範例：

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

2. `get_all_badges`

擷取已驗證組織的所有可用徽章。

參數：

limit (數字，選用)：要回傳的最大徽章數量 (預設：100)

範例：

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

3. `create_badge`

建立一個包含選用自訂欄位的新徽章範本。

參數：

name (字串，必要)：徽章名稱
description (字串，必要)：徽章描述
issuing_organization_name (字串，必要)：組織名稱
idempotency_key (字串，必要)：唯一識別碼
custom_fields (陣列，選用)：自訂欄位定義
以及更多選用參數...

範例：

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

將徽章頒發給收件者，可包含選用的詮釋資料。

參數：

badge_id (字串，必要)：建立時取得的徽章 ID
name (字串，必要)：收件者的全名
idempotency_key (字串，必要)：唯一識別碼
email (字串，選用)：收件者的電子郵件
metadata (物件，選用)：自訂欄位值

範例：

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

💬 自然語言範例

建立徽章

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)

頒發徽章

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

批次操作

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]

🏗️ 開發

從原始碼建置

# 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

專案結構

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

🔒 安全性

所有 API 通訊均使用 HTTPS
在每個請求之前驗證 API 金鑰
冪等性金鑰可防止重複操作
多租戶資料隔離
請求逾時保護
全面的錯誤處理

📊 錯誤處理

MCP 伺服器針對常見問題提供詳細的錯誤訊息：

驗證錯誤：無效的 API 金鑰或過期的權杖
驗證錯誤：缺少必要參數或格式無效
網路錯誤：連線逾時或服務無法使用
商業邏輯錯誤：重複操作或權限不足

🌍 使用案例

教育機構

課程完成：當學生完成課程時自動頒發徽章
技能驗證：建立包含評量分數的技能型徽章
畢業證書：批次頒發包含學術詳細資料的畢業徽章

企業培訓

認證計畫：管理具有到期日的專業認證
合規培訓：追蹤並驗證強制性培訓的完成情況
技能發展：為內部技能發展計畫頒發徽章

活動管理

會議出席：為活動和工作坊頒發出席徽章
成就追蹤：為持續進行的計畫建立漸進式徽章系統
講者表揚：管理講者和參與者的表揚徽章

🤝 貢獻

我們歡迎貢獻！請參閱我們的貢獻指南：

Fork 儲存庫
建立功能分支：git checkout -b feature/amazing-feature
提交您的變更：git commit -m 'Add amazing feature'
推送到分支：git push origin feature/amazing-feature
開啟 Pull Request

開發指南

遵循 TypeScript 最佳實務
加入全面的錯誤處理
為函式加入 JSDoc 註解
為新功能更新測試
遵循語意化版本控制

📝 授權

本專案採用 MIT 授權 - 詳情請參閱 LICENSE 檔案。

🆘 支援

取得協助

📖 文件：查閱此 README 和內嵌程式碼註解
🐛 錯誤回報：開啟 Issue
💬 討論：GitHub Discussions
📧 電子郵件：[email protected]

疑難排解

常見問題

1. API 金鑰驗證失敗

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

2. 連線逾時

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

3. 徽章建立錯誤

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

🔗 相關專案

IssueBadge API：核心徽章管理平台
模型上下文協定：MCP 規格和工具
Claude Desktop：支援 MCP 的 AI 助理

📈 發展藍圖

版本 1.1

批次徽章操作
進階篩選和搜尋
Webhook 整合
徽章範本管理

版本 1.2

分析和報告工具
自訂徽章驗證規則
與學習管理系統整合
進階工作流程自動化

版本 2.0

區塊鏈驗證支援
多語言徽章內容
進階品牌自訂
企業 SSO 整合

準備好革新您的徽章管理了嗎？ 立即開始使用 IssueBadge MCP 伺服器，體驗對話式徽章管理的強大功能！

由 IssueBadge 團隊用 ❤️ 打造

Issuebage MCP Server

文件

IssueBadge MCP 伺服器

🌟 功能特色

🚀 快速入門

必要條件

安裝

⚙️ 設定

🔧 整合

Claude Desktop

ChatGPT Actions

🛠️ 可用工具

1. validate_key

2. get_all_badges

3. create_badge

4. issue_badge

💬 自然語言範例

建立徽章

頒發徽章

批次操作

🏗️ 開發

從原始碼建置

專案結構

🔒 安全性

📊 錯誤處理

🌍 使用案例

教育機構

企業培訓

活動管理

🤝 貢獻

開發指南

📝 授權

🆘 支援

取得協助

疑難排解

常見問題

🔗 相關專案

📈 發展藍圖

版本 1.1

版本 1.2

版本 2.0

1. `validate_key`

2. `get_all_badges`

3. `create_badge`

4. `issue_badge`