Issuebage MCP Server

官方

数字徽章发行平台

GitHub

文档

IssueBadge MCP 服务器

一个用于与 IssueBadge API 交互的模型上下文协议 (MCP) 服务器。该服务器使 Claude 和 ChatGPT 等 AI 助手能够使用自然语言管理数字徽章和证书。

🌟 功能特性

🤖 AI 驱动的徽章管理：使用自然语言创建、颁发和管理徽章
🔐 双重认证：同时支持 Laravel Sanctum 和 OAuth2
🏆 完整的徽章生命周期：创建模板、颁发给接收者并验证真实性
📊 多租户支持：为企业提供安全的租户隔离
🛡️ 幂等性保护：通过内置保护措施防止重复操作
📧 自动通知：自动发送包含验证 URL 的电子邮件
🎨 自定义字段：灵活的元数据和自定义字段支持

🚀 快速开始

先决条件

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`