Issuebage MCP Server

oficial

plataforma de emisión de insignias digitales

GitHub

Documentación

Servidor MCP IssueBadge

npm version License: MIT TypeScript MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) para interactuar con la API de IssueBadge. Este servidor permite a asistentes de IA como Claude y ChatGPT gestionar insignias y certificados digitales usando lenguaje natural.

🌟 Características

  • 🤖 Gestión de Insignias Potenciada por IA: Usa lenguaje natural para crear, emitir y gestionar insignias
  • 🔐 Autenticación Dual: Soporte para Laravel Sanctum y OAuth2
  • 🏆 Ciclo de Vida Completo de la Insignia: Crea plantillas, emite a destinatarios y verifica autenticidad
  • 📊 Soporte Multi-tenant: Aislamiento seguro de inquilinos para uso empresarial
  • 🛡️ Protección de Idempotencia: Previene operaciones duplicadas con salvaguardas integradas
  • 📧 Notificaciones Automatizadas: Envío automático de correos electrónicos con URLs de verificación
  • 🎨 Campos Personalizados: Soporte flexible para metadatos y campos personalizados

🚀 Inicio Rápido

Prerrequisitos

  • Node.js 18+
  • npm 8+
  • Cuenta de API IssueBadge con clave API

Instalación

  1. Clona el repositorio

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

  2. Instala las dependencias

    npm install

  3. Configura el entorno

    cp .env.example .env
# Edit .env with your IssueBadge API credentials

  4. Construye el proyecto

    npm run build

  5. Prueba el servidor

    npm test

⚙️ Configuración

Crea un archivo .env basado en .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

🔧 Integración

Claude Desktop

Añade este servidor a tu configuración de 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"
      }
    }
  }
}

Acciones de ChatGPT

  1. Crea un nuevo GPT Personalizado en ChatGPT
  2. Importa la especificación OpenAPI desde tu instancia de IssueBadge
  3. Configura la autenticación de token Bearer con tu clave API
  4. ¡Empieza a gestionar insignias a través de la conversación!

🛠️ Herramientas Disponibles

1. validate_key

Valida las claves API de IssueBadge para autenticación.

Parámetros:

  • api_key (string, requerido): La clave API a validar

Ejemplo:

"Validate my API key: 1|abcdef123456789..."

2. get_all_badges

Recupera todas las insignias disponibles para la organización autenticada.

Parámetros:

  • limit (number, opcional): Máximo de insignias a devolver (por defecto: 100)

Ejemplo:

"Show me all available badges"
"List the first 50 badges"

3. create_badge

Crea una nueva plantilla de insignia con campos personalizados opcionales.

Parámetros:

  • name (string, requerido): Nombre de la insignia
  • description (string, requerido): Descripción de la insignia
  • issuing_organization_name (string, requerido): Nombre de la organización
  • idempotency_key (string, requerido): Identificador único
  • custom_fields (array, opcional): Definiciones de campos personalizados
  • Y más parámetros opcionales...

Ejemplo:

"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

Emite una insignia a un destinatario con metadatos opcionales.

Parámetros:

  • badge_id (string, requerido): ID de la insignia desde la creación
  • name (string, requerido): Nombre completo del destinatario
  • idempotency_key (string, requerido): Identificador único
  • email (string, opcional): Correo electrónico del destinatario
  • metadata (object, opcional): Valores de campos personalizados

Ejemplo:

"Issue the Web Development badge to John Doe with email [email protected]"
"Issue Python certification to Alice with completion date today and score 95%"

💬 Ejemplos en Lenguaje Natural

Creando Insignias

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)

Emitiendo Insignias

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

Operaciones por Lotes

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]

🏗️ Desarrollo

Construyendo desde el Código Fuente

# 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

Estructura del Proyecto

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

🔒 Seguridad

  • Todas las comunicaciones API usan HTTPS
  • Las claves API se validan antes de cada solicitud
  • Las claves de idempotencia previenen operaciones duplicadas
  • Aislamiento de datos multi-tenant
  • Protección contra tiempo de espera de solicitudes
  • Manejo integral de errores

📊 Manejo de Errores

El servidor MCP proporciona mensajes de error detallados para problemas comunes:

  • Errores de Autenticación: Claves API inválidas o tokens expirados
  • Errores de Validación: Parámetros requeridos faltantes o formatos inválidos
  • Errores de Red: Tiempos de espera de conexión o servicio no disponible
  • Errores de Lógica de Negocio: Operaciones duplicadas o permisos insuficientes

🌍 Casos de Uso

Instituciones Educativas

  • Finalización de Cursos: Emite insignias automáticamente cuando los estudiantes completan cursos
  • Validación de Habilidades: Crea insignias basadas en habilidades con puntuaciones de evaluación
  • Certificados de Graduación: Emite insignias de graduación por lotes con detalles académicos

Capacitación Corporativa

  • Programas de Certificación: Gestiona certificaciones profesionales con fechas de vencimiento
  • Capacitación de Cumplimiento: Rastrea y verifica la finalización de capacitación obligatoria
  • Desarrollo de Habilidades: Emite insignias para programas internos de desarrollo de habilidades

Gestión de Eventos

  • Asistencia a Conferencias: Emite insignias de asistencia para eventos y talleres
  • Seguimiento de Logros: Crea sistemas de insignias progresivas para programas en curso
  • Reconocimiento de Oradores: Gestiona insignias de reconocimiento para oradores y participantes

🤝 Contribuciones

¡Agradecemos las contribuciones! Por favor, consulta nuestras pautas de contribución:

  1. Haz un fork del repositorio
  2. Crea una rama de funcionalidad: git checkout -b feature/amazing-feature
  3. Confirma tus cambios: git commit -m 'Add amazing feature'
  4. Sube a la rama: git push origin feature/amazing-feature
  5. Abre un Pull Request

Pautas de Desarrollo

  • Sigue las mejores prácticas de TypeScript
  • Añade manejo integral de errores
  • Incluye comentarios JSDoc para funciones
  • Actualiza las pruebas para nuevas funcionalidades
  • Sigue el versionado semántico

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🆘 Soporte

Obtener Ayuda

Solución de Problemas

Problemas Comunes

1. Fallo en la Validación de la Clave API

# Check API key format (should start with number|)
# Verify the key hasn't expired
# Ensure correct base URL

2. Tiempo de Espera de Conexión

# Check network connectivity
# Verify IssueBadge service status
# Increase REQUEST_TIMEOUT in .env

3. Errores al Crear Insignias

# Verify required fields are provided
# Check idempotency key uniqueness
# Validate organization permissions

🔗 Proyectos Relacionados

📈 Hoja de Ruta

Versión 1.1

  • Operaciones de insignias por lotes
  • Filtrado y búsqueda avanzados
  • Integración de Webhooks
  • Gestión de plantillas de insignias

Versión 1.2

  • Herramientas de análisis e informes
  • Reglas de validación de insignias personalizadas
  • Integración con sistemas de gestión de aprendizaje
  • Automatización avanzada de flujos de trabajo

Versión 2.0

  • Soporte de verificación blockchain
  • Contenido de insignias multilingüe
  • Personalización avanzada de marca
  • Integración SSO empresarial

¿Listo para revolucionar tu gestión de insignias? ¡Comienza con el Servidor MCP IssueBadge y experimenta el poder de la administración conversacional de insignias!

Construido con ❤️ por el equipo de IssueBadge