Issuebage MCP Server

oficial

digital badge issuing platform

GitHub

Documentação

Servidor MCP IssueBadge

npm version License: MIT TypeScript MCP

Um servidor Model Context Protocol (MCP) para interagir com a API IssueBadge. Este servidor permite que assistentes de IA como Claude e ChatGPT gerenciem emblemas e certificados digitais usando linguagem natural.

🌟 Funcionalidades

  • 🤖 Gerenciamento de Emblemas com IA: Use linguagem natural para criar, emitir e gerenciar emblemas
  • 🔐 Autenticação Dupla: Suporte para Laravel Sanctum e OAuth2
  • 🏆 Ciclo de Vida Completo do Emblema: Crie modelos, emita para destinatários e verifique a autenticidade
  • 📊 Suporte Multi-inquilino: Isolamento seguro de inquilinos para uso empresarial
  • 🛡️ Proteção de Idempotência: Evite operações duplicadas com salvaguardas integradas
  • 📧 Notificações Automatizadas: Envio automático de e-mail com URLs de verificação
  • 🎨 Campos Personalizados: Suporte flexível a metadados e campos personalizados

🚀 Início Rápido

Pré-requisitos

  • Node.js 18+
  • npm 8+
  • Conta na API IssueBadge com chave de API

Instalação

  1. Clone o repositório

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

  2. Instale as dependências

    npm install

  3. Configure o ambiente

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

  4. Compile o projeto

    npm run build

  5. Teste o servidor

    npm test

⚙️ Configuração

Crie um arquivo .env baseado em .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

🔧 Integração

Claude Desktop

Adicione este servidor à sua configuração do 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"
      }
    }
  }
}

Ações do ChatGPT

  1. Crie um GPT Personalizado no ChatGPT
  2. Importe a especificação OpenAPI da sua instância IssueBadge
  3. Configure a autenticação Bearer token com sua chave de API
  4. Comece a gerenciar emblemas através da conversa!

🛠️ Ferramentas Disponíveis

1. validate_key

Valida chaves de API IssueBadge para autenticação.

Parâmetros:

  • api_key (string, obrigatório): A chave de API a ser validada

Exemplo:

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

2. get_all_badges

Recupera todos os emblemas disponíveis para a organização autenticada.

Parâmetros:

  • limit (number, opcional): Máximo de emblemas a retornar (padrão: 100)

Exemplo:

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

3. create_badge

Cria um novo modelo de emblema com campos personalizados opcionais.

Parâmetros:

  • name (string, obrigatório): Nome do emblema
  • description (string, obrigatório): Descrição do emblema
  • issuing_organization_name (string, obrigatório): Nome da organização
  • idempotency_key (string, obrigatório): Identificador único
  • custom_fields (array, opcional): Definições de campos personalizados
  • E mais parâmetros opcionais...

Exemplo:

"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 um emblema para um destinatário com metadados opcionais.

Parâmetros:

  • badge_id (string, obrigatório): ID do emblema da criação
  • name (string, obrigatório): Nome completo do destinatário
  • idempotency_key (string, obrigatório): Identificador único
  • email (string, opcional): E-mail do destinatário
  • metadata (object, opcional): Valores de campos personalizados

Exemplo:

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

💬 Exemplos em Linguagem Natural

Criando Emblemas

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)

Emitindo Emblemas

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

Operações em Lote

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]

🏗️ Desenvolvimento

Compilando a partir do Código Fonte

# 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

Estrutura do Projeto

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

🔒 Segurança

  • Todas as comunicações da API usam HTTPS
  • As chaves de API são validadas antes de cada requisição
  • Chaves de idempotência previnem operações duplicadas
  • Isolamento de dados multi-inquilino
  • Proteção contra timeout de requisição
  • Tratamento abrangente de erros

📊 Tratamento de Erros

O servidor MCP fornece mensagens de erro detalhadas para problemas comuns:

  • Erros de Autenticação: Chaves de API inválidas ou tokens expirados
  • Erros de Validação: Parâmetros obrigatórios ausentes ou formatos inválidos
  • Erros de Rede: Timeouts de conexão ou indisponibilidade do serviço
  • Erros de Lógica de Negócio: Operações duplicadas ou permissões insuficientes

🌍 Casos de Uso

Instituições Educacionais

  • Conclusão de Curso: Emita emblemas automaticamente quando os alunos concluírem cursos
  • Validação de Habilidades: Crie emblemas baseados em habilidades com pontuações de avaliação
  • Certificados de Graduação: Emita emblemas de graduação em lote com detalhes acadêmicos

Treinamento Corporativo

  • Programas de Certificação: Gerencie certificações profissionais com datas de expiração
  • Treinamento de Conformidade: Acompanhe e verifique a conclusão de treinamentos obrigatórios
  • Desenvolvimento de Habilidades: Emita emblemas para programas internos de desenvolvimento de habilidades

Gestão de Eventos

  • Participação em Conferências: Emita emblemas de participação para eventos e workshops
  • Acompanhamento de Conquistas: Crie sistemas progressivos de emblemas para programas contínuos
  • Reconhecimento de Palestrantes: Gerencie emblemas de reconhecimento para palestrantes e participantes

🤝 Contribuindo

Aceitamos contribuições! Por favor, veja nossas diretrizes de contribuição:

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade: git checkout -b feature/amazing-feature
  3. Faça commit das suas alterações: git commit -m 'Add amazing feature'
  4. Envie para o branch: git push origin feature/amazing-feature
  5. Abra um Pull Request

Diretrizes de Desenvolvimento

  • Siga as melhores práticas de TypeScript
  • Adicione tratamento abrangente de erros
  • Inclua comentários JSDoc para funções
  • Atualize os testes para novas funcionalidades
  • Siga o versionamento semântico

📝 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🆘 Suporte

Obtendo Ajuda

Solução de Problemas

Problemas Comuns

1. Falha na Validação da Chave de API

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

2. Timeout de Conexão

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

3. Erros na Criação de Emblemas

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

🔗 Projetos Relacionados

📈 Roadmap

Versão 1.1

  • Operações de emblemas em lote
  • Filtragem e busca avançadas
  • Integração com webhooks
  • Gerenciamento de modelos de emblemas

Versão 1.2

  • Ferramentas de análise e relatórios
  • Regras personalizadas de validação de emblemas
  • Integração com sistemas de gestão de aprendizagem
  • Automação avançada de fluxos de trabalho

Versão 2.0

  • Suporte à verificação em blockchain
  • Conteúdo de emblemas multilíngue
  • Personalização avançada de marca
  • Integração SSO empresarial

Pronto para revolucionar seu gerenciamento de emblemas? Comece com o Servidor MCP IssueBadge e experimente o poder da administração conversacional de emblemas!

Construído com ❤️ pela equipe IssueBadge