Mcp Server

笔记 TypeScript

🚀 IssueBadge MCP Server

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

🚀 快速开始

前提条件

Node.js 18+
npm 8+
拥有 IssueBadge API 账户及 API 密钥

安装

克隆仓库

git clone https://github.com/issuebadge/mcp-server.git
cd mcp-server

安装依赖
```
npm install
```

配置环境

cp .env.example .env
# 使用你的 IssueBadge API 凭证编辑 .env

构建项目
```
npm run build
```
测试服务器
```
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

在 ChatGPT 中创建一个新的自定义 GPT。
从你的 IssueBadge 实例导入 OpenAPI 规范。
使用你的 API 密钥配置 Bearer 令牌认证。
通过对话开始管理徽章！

可用工具

参考“使用示例”部分的工具说明。

开发

从源代码构建

# 克隆仓库
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 密钥或过期的令牌
验证错误：缺少必需参数或格式无效
网络错误：连接超时或服务不可用
业务逻辑错误：重复操作或权限不足

使用案例

教育机构

课程完成：学生完成课程时自动颁发徽章
技能验证：创建带有评估分数的技能徽章
毕业证书：批量颁发带有学术信息的毕业徽章

企业培训

认证计划：管理带有有效期的专业认证
合规培训：跟踪和验证强制性培训完成情况
技能发展：为内部技能发展计划颁发徽章

活动管理

会议出席：为活动和研讨会颁发出席徽章
成就跟踪：为持续的项目创建渐进式徽章系统
演讲者认可：管理演讲者和参与者的认可徽章

贡献

我们欢迎贡献！请参阅我们的贡献指南：

分叉仓库
创建功能分支：git checkout -b feature/amazing-feature
提交更改：git commit -m 'Add amazing feature'
推送到分支：git push origin feature/amazing-feature
打开拉取请求

开发指南

遵循 TypeScript 最佳实践
添加全面的错误处理
为函数添加 JSDoc 注释
为新功能更新测试
遵循语义化版本控制

支持

获取帮助

📖 文档：查看本 README 和代码内注释
🐛 错误报告：打开一个问题
💬 讨论：GitHub 讨论
📧 电子邮件：support@issuebadge.com

故障排除

常见问题

1. API 密钥验证失败

# 检查 API 密钥格式（应以数字|开头）
# 验证密钥未过期
# 确保基本 URL 正确

2. 连接超时

# 检查网络连接
# 验证 IssueBadge 服务状态
# 在 .env 中增加 REQUEST_TIMEOUT

3. 徽章创建错误

# 验证是否提供了必需字段
# 检查幂等性密钥的唯一性
# 验证组织权限

路线图

1.1 版本

[ ] 批量徽章操作
[ ] 高级过滤和搜索
[ ] Webhook 集成
[ ] 徽章模板管理

1.2 版本

[ ] 分析和报告工具
[ ] 自定义徽章验证规则
[ ] 与学习管理系统集成
[ ] 高级工作流自动化

2.0 版本

[ ] 区块链验证支持
[ ] 多语言徽章内容
[ ] 高级品牌定制
[ ] 企业单点登录集成

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

准备好彻底改变你的徽章管理方式了吗？ 立即开始使用 IssueBadge MCP 服务器，体验对话式徽章管理的强大功能！

由 IssueBadge 团队用心打造

0 条评论
分类：笔记