Issuebage MCP Server

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	相同工具 + 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 會拒絕重複使用的金鑰，因此在失敗的呼叫後，請先檢查證書是否已簽發，再使用新金鑰重新呼叫。

安裝後的範例提示詞：「將課程完成證書簽發給 Jane Doe，jane@example.com。」

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，請將 ISSUEBADGE_BASE_URL 指向不同的 API 主機以用於 stdio 伺服器。

開發

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