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 团队用心打造