MCP Server

🚀 IssueBadge MCP Server

這是一個用於與 IssueBadge API 交互的模型上下文協議（MCP）服務器。該服務器使 Claude 和 ChatGPT 等 AI 助手能夠使用自然語言管理數字徽章和證書。

🚀 快速開始

前提條件

• Node.js 18+
• npm 8+
• 擁有 IssueBadge API 賬戶及 API 密鑰

安裝

1. 克隆倉庫

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

2. 安裝依賴

   npm install
   

3. 配置環境

   cp .env.example .env
   # 使用你的 IssueBadge API 憑證編輯 .env
   

4. 構建項目

   npm run build
   

5. 測試服務器

   npm test
   

✨ 主要特性

• 🤖 人工智能驅動的徽章管理：使用自然語言創建、頒發和管理徽章
• 🔐 雙重認證：支持 Laravel Sanctum 和 OAuth2 兩種認證方式
• 🏆 完整的徽章生命週期管理：創建模板、頒發給接收者並驗證真實性
• 📊 多租戶支持：為企業應用提供安全的租戶隔離
• 🛡️ 冪等性保護：內置防護機制，防止重複操作
• 📧 自動通知：自動通過電子郵件發送包含驗證 URL 的通知
• 🎨 自定義字段：支持靈活的元數據和自定義字段

📦 安裝指南

參考“快速開始”部分的安裝步驟。

💻 使用示例

基礎用法

以下是一些使用自然語言與服務器交互的示例：

創建徽章

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]

高級用法

以下是使用可用工具的高級示例：

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 john@example.com"
"Issue Python certification to Alice with completion date today and score 95%"

📚 詳細文檔

配置

基於 .env.example 創建一個 .env 文件：

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

# OAuth2 配置（可選）
ISSUEBADGE_OAUTH_URL=https://app.issuebadge.com/api/v1/oauth
ISSUEBADGE_OAUTH_TOKEN=your_oauth_token_here

# 認證方法（sanctum 或 oauth2）
AUTH_METHOD=sanctum

# 服務器配置
MCP_SERVER_NAME=IssueBadge MCP Server
MCP_SERVER_VERSION=1.0.0

# 可選設置
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

1. 在 ChatGPT 中創建一個新的自定義 GPT。
2. 從你的 IssueBadge 實例導入 OpenAPI 規範。
3. 使用你的 API 密鑰配置 Bearer 令牌認證。
4. 通過對話開始管理徽章！

可用工具

參考“使用示例”部分的工具說明。

開發

從源代碼構建

# 克隆倉庫
git clone https://github.com/issuebadge/mcp-server.git
cd mcp-server

# 安裝依賴
npm install

# 構建 TypeScript
npm run build

# 在開發模式下運行
npm run dev

# 代碼檢查
npm run lint

# 代碼格式化
npm run format

項目結構

mcp-server/
├── src/
│   └── index.ts          # 主要的 MCP 服務器實現
├── dist/                 # 編譯後的 JavaScript（自動生成）
├── .env.example         # 環境配置模板
├── package.json         # Node.js 依賴和腳本
├── tsconfig.json        # TypeScript 配置
└── README.md           # 本文件

安全

• 所有 API 通信均使用 HTTPS
• 在每個請求之前驗證 API 密鑰
• 冪等性密鑰防止重複操作
• 多租戶數據隔離
• 請求超時保護
• 全面的錯誤處理

錯誤處理

MCP 服務器為常見問題提供詳細的錯誤消息：

• 認證錯誤：無效的 API 密鑰或過期的令牌
• 驗證錯誤：缺少必需參數或格式無效
• 網絡錯誤：連接超時或服務不可用
• 業務邏輯錯誤：重複操作或權限不足

使用案例

教育機構

• 課程完成：學生完成課程時自動頒發徽章
• 技能驗證：創建帶有評估分數的技能徽章
• 畢業證書：批量頒發帶有學術信息的畢業徽章

企業培訓

• 認證計劃：管理帶有有效期的專業認證
• 合規培訓：跟蹤和驗證強制性培訓完成情況
• 技能發展：為內部技能發展計劃頒發徽章

活動管理

• 會議出席：為活動和研討會頒發出席徽章
• 成就跟蹤：為持續的項目創建漸進式徽章系統
• 演講者認可：管理演講者和參與者的認可徽章

貢獻

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

1. 分叉倉庫
2. 創建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 打開拉取請求

開發指南

• 遵循 TypeScript 最佳實踐
• 添加全面的錯誤處理
• 為函數添加 JSDoc 註釋
• 為新功能更新測試
• 遵循語義化版本控制

支持

獲取幫助

• 📖 文檔：查看本 README 和代碼內註釋
• 🐛 錯誤報告：打開一個問題
• 💬 討論：GitHub 討論
• 📧 電子郵件：support@issuebadge.com

故障排除

常見問題

1. API 密鑰驗證失敗

# 檢查 API 密鑰格式（應以數字|開頭）
# 驗證密鑰未過期
# 確保基本 URL 正確

2. 連接超時

# 檢查網絡連接
# 驗證 IssueBadge 服務狀態
# 在 .env 中增加 REQUEST_TIMEOUT

3. 徽章創建錯誤

# 驗證是否提供了必需字段
# 檢查冪等性密鑰的唯一性
# 驗證組織權限

相關項目

• IssueBadge API：核心徽章管理平臺
• Model Context Protocol：MCP 規範和工具
• Claude Desktop：支持 MCP 的 AI 助手

路線圖

1.1 版本

• [ ] 批量徽章操作
• [ ] 高級過濾和搜索
• [ ] Webhook 集成
• [ ] 徽章模板管理

1.2 版本

• [ ] 分析和報告工具
• [ ] 自定義徽章驗證規則
• [ ] 與學習管理系統集成
• [ ] 高級工作流自動化

2.0 版本

• [ ] 區塊鏈驗證支持
• [ ] 多語言徽章內容
• [ ] 高級品牌定製
• [ ] 企業單點登錄集成

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

準備好徹底改變你的徽章管理方式了嗎？ 立即開始使用 IssueBadge MCP 服務器，體驗對話式徽章管理的強大功能！

由 IssueBadge 團隊用心打造