Issuebage MCP Server

IssueBadge MCP Server

Сервер Model Context Protocol (MCP) для взаимодействия с API IssueBadge. Этот сервер позволяет ИИ-ассистентам, таким как Claude и ChatGPT, управлять цифровыми значками и сертификатами с помощью естественного языка.

🌟 Возможности

• 🤖 Управление значками с помощью ИИ: Используйте естественный язык для создания, выдачи и управления значками
• 🔐 Двойная аутентификация: Поддержка Laravel Sanctum и OAuth2
• 🏆 Полный жизненный цикл значков: Создавайте шаблоны, выдавайте получателям и проверяйте подлинность
• 📊 Поддержка мультитенантности: Безопасная изоляция тенантов для корпоративного использования
• 🛡️ Защита идемпотентности: Предотвращение дублирующих операций с помощью встроенных механизмов
• 📧 Автоматические уведомления: Автоматическая отправка писем с URL-адресами для проверки
• 🎨 Настраиваемые поля: Гибкая поддержка метаданных и пользовательских полей

🚀 Быстрый старт

Предварительные требования

• 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
   # Edit .env with your IssueBadge API credentials
   

4. Соберите проект

   npm run build
   

5. Протестируйте сервер

   npm test
   

⚙️ Конфигурация

Создайте файл .env на основе .env.example:

# 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

1. Создайте новый Custom GPT в ChatGPT
2. Импортируйте спецификацию OpenAPI из вашего экземпляра IssueBadge
3. Настройте аутентификацию с помощью Bearer-токена, используя ваш ключ API
4. Начинайте управлять значками через диалог!

🛠️ Доступные инструменты

1. validate_key

Проверяет ключи API IssueBadge для аутентификации.

Параметры:

• 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 (строка, необязательно): 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%"

💬 Примеры на естественном языке

Создание значков

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 или просроченные токены
• Ошибки валидации: Отсутствуют обязательные параметры или неверный формат
• Сетевые ошибки: Тайм-ауты соединения или недоступность сервиса
• Ошибки бизнес-логики: Дублирующие операции или недостаточно прав

🌍 Варианты использования

Образовательные учреждения

• Завершение курса: Автоматическая выдача значков при завершении курсов студентами
• Подтверждение навыков: Создание значков на основе навыков с оценками
• Сертификаты об окончании: Массовая выдача значков об окончании с академическими данными

Корпоративное обучение

• Программы сертификации: Управление профессиональными сертификациями с датами истечения срока
• Обучение по соблюдению требований: Отслеживание и проверка завершения обязательного обучения
• Развитие навыков: Выдача значков для внутренних программ развития навыков

Управление мероприятиями

• Посещение конференций: Выдача значков за посещение мероприятий и семинаров
• Отслеживание достижений: Создание прогрессивных систем значков для текущих программ
• Признание докладчиков: Управление значками для признания докладчиков и участников

🤝 Участие в проекте

Мы приветствуем вклад! Пожалуйста, ознакомьтесь с нашими рекомендациями по участию:

1. Сделайте форк репозитория
2. Создайте ветку для функции: git checkout -b feature/amazing-feature
3. Зафиксируйте изменения: git commit -m 'Add amazing feature'
4. Отправьте ветку: git push origin feature/amazing-feature
5. Откройте Pull Request

Рекомендации по разработке

• Следуйте лучшим практикам TypeScript
• Добавляйте комплексную обработку ошибок
• Включайте комментарии JSDoc для функций
• Обновляйте тесты для новых функций
• Следуйте семантическому версионированию

📝 Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.

🆘 Поддержка

Получение помощи

• 📖 Документация: Смотрите этот README и встроенные комментарии кода
• 🐛 Отчеты об ошибках: Создать issue
• 💬 Обсуждения: GitHub Discussions
• 📧 Email: support@issuebadge.com

Устранение неполадок

Типичные проблемы

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: Основная платформа управления значками
• Model Context Protocol: Спецификация и инструменты MCP
• Claude Desktop: ИИ-ассистент с поддержкой MCP

📈 Дорожная карта

Версия 1.1

• Пакетные операции со значками
• Расширенная фильтрация и поиск
• Интеграция вебхуков
• Управление шаблонами значков

Версия 1.2

• Инструменты аналитики и отчетности
• Пользовательские правила проверки значков
• Интеграция с системами управления обучением
• Расширенная автоматизация рабочих процессов

Версия 2.0

• Поддержка верификации через блокчейн
• Многоязычное содержимое значков
• Расширенная настройка брендинга
• Интеграция корпоративного единого входа (SSO)

---

Готовы революционизировать управление значками? Начните работу с IssueBadge MCP Server и ощутите мощь диалогового администрирования значков!

Создано с ❤️ командой IssueBadge