Issuebage

IssueBadge MCP 服务

从任意 AI Agent 颁发可验证的证书和徽章。这个 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 技能，指导 Agent 按照列出 → 确认 → 颁发的工作流操作。插件的 .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 Agent 模式）

.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（[email protected]）颁发课程完成证书。”

动态 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。在 IssueBadge 控制面板中创建 QR 码并更改其目标地址；图像中编码的是 IssueBadge 重定向地址（scan_url），因此即使目标地址发生变化，已打印的码仍可使用。

提示词示例：“创建一个名为 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。

隐私与安全

• 远程服务是无状态的。每个请求都会从 Authorization 标头中读取你的 API key，将其转发到 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 可执行文件）、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 注册表）。

许可证

MIT