Issuebage MCP Server
官方數位徽章發行平台
你可以用 Issuebage MCP 做什麼?
- 驗證您的 API 金鑰 — 請您的助理使用
validate_key檢查您的 IssueBadge 憑證是否有效。 - 列出徽章範本 — 擷取您可用的徽章範本,以便在頒發前挑選正確的範本。
- 頒發憑證 — 依收件人姓名與電子郵件寄送憑證,並回傳公開驗證 URL。
- 檢視 QR 碼 — 列出動態 QR 碼、取得某個 QR 碼及其 PNG 圖像,或檢閱其掃描紀錄。
- 刪除 QR 碼 — 依代碼移除現有的動態 QR 碼。
文件
IssueBadge MCP 伺服器
從任何 AI 代理程式簽發可驗證的憑證與徽章。此 Model Context Protocol 伺服器可讓 Cursor、Claude、VS Code 及其他 MCP 用戶端列出你的 IssueBadge 徽章範本,並依收件人姓名與電子郵件寄送憑證。
有兩種執行方式:
| 遠端(建議) | 本機(stdio) | |
|---|---|---|
| 端點 | https://issuebadge-mcp.issuebadge.workers.dev/mcp | npx issuebadge-mcp-server |
| 驗證 | Authorization: Bearer <API key> 標頭 | ISSUEBADGE_API_KEY 環境變數 |
| 工具 | validate_key、get_all_badges、issue_badge、list_qr_codes、get_qr_code、get_qr_code_scans、delete_qr_code | 相同工具 + create_badge |
| 儲存 | 無,無狀態 | 無 |
你需要一組 IssueBadge API 金鑰:app.issuebadge.com → Developer → API key(https://app.issuebadge.com/developer/index)。
安裝
Cursor
從 Cursor Marketplace 安裝 IssueBadge,並在提示時貼上你的 API 金鑰。或在 Settings → MCP 中手動新增:
{
"mcpServers": {
"issuebadge": {
"type": "streamable-http",
"url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
}
}
}
Claude Code
claude mcp add --transport http issuebadge https://issuebadge-mcp.issuebadge.workers.dev/mcp \
--header "Authorization: Bearer YOUR_ISSUEBADGE_API_KEY"
此儲存庫同時也是 Claude Code 外掛(.claude-plugin/plugin.json),並附帶一個 issuebadge 技能,教導代理程式「列出 → 確認 → 簽發」的工作流程。此外掛的 .mcp.json 會從 ISSUEBADGE_API_KEY 環境變數讀取金鑰,因此請在啟動 Claude Code 前先匯出該變數。
Claude Desktop / 任何 stdio 用戶端
{
"mcpServers": {
"issuebadge": {
"command": "npx",
"args": ["-y", "issuebadge-mcp-server"],
"env": { "ISSUEBADGE_API_KEY": "YOUR_ISSUEBADGE_API_KEY" }
}
}
}
VS Code(Copilot 代理程式模式)
.vscode/mcp.json:
{
"servers": {
"issuebadge": {
"type": "http",
"url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
"headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
}
}
}
工具
| 工具 | 輸入 | 傳回 |
|---|---|---|
validate_key | – | { valid, message } |
get_all_badges | limit? | { badges: [{ id, name, description?, created_at? }] } |
issue_badge | badge_id、name、email?、phone?、idempotency_key?、metadata? | { issue_id, certificate_url, idempotency_key } |
create_badge(僅限 stdio) | name、description、issuing_organization_name、idempotency_key、選用的 badge_logo_path、custom_fields、… | IssueBadge API 回應 |
issue_badge 會將憑證以電子郵件寄給收件人,並傳回公開驗證 URL。每次使用新的 idempotency_key 呼叫都會簽發一張新憑證(若省略,會自動產生一個作為 mcp-<uuid>)。API 會拒絕重複使用的金鑰,因此呼叫失敗後,請先確認憑證是否已簽發,再以新的金鑰重新呼叫。
安裝後的範例提示:「將 Course Completion 憑證簽發給 Jane Doe,jane@example.com。」
動態 QR 碼
| 工具 | 輸入 | 傳回 |
|---|---|---|
list_qr_codes | type?、limit? | { qr_codes: [...], total } |
get_qr_code | code | QR 碼 + PNG 影像區塊 |
get_qr_code_scans | code、limit? | { code, scan_count, scans: [{ scanned_at, referer }], total } |
delete_qr_code | code | { deleted: true, code } |
類型:url、vcard、paypal、wifi、email、phone、sms、maps、event、facebook、twitter、youtube、text、mecard。QR 碼會在 IssueBadge 儀表板中建立與重新指定目標;影像編碼的是 IssueBadge 重新導向(scan_url),因此即使目的地變更,已印出的 QR 碼仍可繼續運作。
範例提示:「建立一個名為 Menu 的 QR 碼,開啟 https://example.com/menu 並顯示給我看。」
ChatGPT 與 OAuth
遠端伺服器也支援 OAuth 2.1,供無法傳送 API 金鑰的主機使用(ChatGPT 應用程式、Claude 連接器):未附 bearer 的請求會收到 401 + WWW-Authenticate: Bearer resource_metadata=…,/.well-known/oauth-protected-resource 指向 https://app.issuebadge.com(PKCE S256、動態用戶端註冊),而簽發的存取權杖會以與 API 金鑰完全相同的方式轉送。issue_badge 會帶有一個小工具(ui://widget/certificate.html,MCP Apps / ChatGPT Apps SDK),用於呈現憑證卡片。請參閱 CHATGPT.md。
隱私與安全性
- 遠端伺服器為無狀態。你的 API 金鑰會從每個請求的
Authorization標頭讀取,轉送至app.issuebadge.com,且絕不會被儲存或記錄。未附金鑰的請求會收到401。 - 唯一聯絡的主機是
app.issuebadge.com。收件人姓名、電子郵件與徽章 ID 會傳送至該處以建立憑證。 - 隱私權政策:https://issuebadge.com/h/policy · 條款:https://issuebadge.com/h/terms · 支援:https://issuebadge.com/h/contact
自行架設遠端伺服器
git clone https://github.com/issuebadge/mcp-server && cd mcp-server
npm install
npm test
npx wrangler deploy --config worker/wrangler.toml # needs a Cloudflare account
GET /health 會傳回 { ok: true }。若你在其他位置執行 IssueBadge,可將 stdio 伺服器的 ISSUEBADGE_BASE_URL 指向不同的 API 主機。
開發
npm install
npm test # vitest: client, tools, worker (mocked IssueBadge API)
npm run build # tsc → dist/ (stdio bin)
npm run dev:worker
目錄結構:src/issuebadge.ts(API 用戶端)、src/tools.ts(兩個主機共用的工具登錄表)、src/stdio.ts(npm bin)、src/createBadge.ts(僅限 stdio 的工具)、worker/index.ts(Cloudflare Worker)、.cursor-plugin/ + mcp.json(Cursor 外掛)、.claude-plugin/ + .mcp.json(Claude Code 外掛)、skills/issuebadge/SKILL.md、server.json(MCP Registry)。
授權條款
MIT