IssueBadge MCP Server

A Model Context Protocol (MCP) server for interacting with the IssueBadge API. This server enables AI assistants like Claude and ChatGPT to manage digital badges and certificates using natural language.

🌟 Features

🤖 AI-Powered Badge Management: Use natural language to create, issue, and manage badges
🔐 Dual Authentication: Support for both Laravel Sanctum and OAuth2
🏆 Complete Badge Lifecycle: Create templates, issue to recipients, and verify authenticity
📊 Multi-tenant Support: Secure tenant isolation for enterprise use
🛡️ Idempotency Protection: Prevent duplicate operations with built-in safeguards
📧 Automated Notifications: Automatic email delivery with verification URLs
🎨 Custom Fields: Flexible metadata and custom field support

🚀 Quick Start

Prerequisites

Node.js 18+
npm 8+
IssueBadge API account with API key

Installation

Clone the repository

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

Install dependencies
```
npm install
```

Configure environment

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

Build the project
```
npm run build
```
Test the server
```
npm test
```

⚙️ Configuration

Create a .env file based on .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

🔧 Integration

Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "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

Create a new Custom GPT in ChatGPT
Import the OpenAPI specification from your IssueBadge instance
Configure Bearer token authentication with your API key
Start managing badges through conversation!

🛠️ Available Tools

1. `validate_key`

Validates IssueBadge API keys for authentication.

Parameters:

api_key (string, required): The API key to validate

Example:

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

2. `get_all_badges`

Retrieves all available badges for the authenticated organization.

Parameters:

limit (number, optional): Maximum badges to return (default: 100)

Example:

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

3. `create_badge`

Creates a new badge template with optional custom fields.

Parameters:

name (string, required): Badge name
description (string, required): Badge description
issuing_organization_name (string, required): Organization name
idempotency_key (string, required): Unique identifier
custom_fields (array, optional): Custom field definitions
And more optional parameters...

Example:

"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`

Issues a badge to a recipient with optional metadata.

Parameters:

badge_id (string, required): Badge ID from creation
name (string, required): Recipient's full name
idempotency_key (string, required): Unique identifier
email (string, optional): Recipient's email
metadata (object, optional): Custom field values

Example:

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

💬 Natural Language Examples

Creating Badges

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)

Issuing Badges

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

Batch Operations

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]

🏗️ Development

Building from Source

# 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

Project Structure

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

🔒 Security

All API communications use HTTPS
API keys are validated before each request
Idempotency keys prevent duplicate operations
Multi-tenant data isolation
Request timeout protection
Comprehensive error handling

📊 Error Handling

The MCP server provides detailed error messages for common issues:

Authentication Errors: Invalid API keys or expired tokens
Validation Errors: Missing required parameters or invalid formats
Network Errors: Connection timeouts or service unavailability
Business Logic Errors: Duplicate operations or insufficient permissions

🌍 Use Cases

Educational Institutions

Course Completion: Automatically issue badges when students complete courses
Skill Validation: Create skill-based badges with assessment scores
Graduation Certificates: Bulk issue graduation badges with academic details

Corporate Training

Certification Programs: Manage professional certifications with expiration dates
Compliance Training: Track and verify mandatory training completion
Skill Development: Issue badges for internal skill development programs

Event Management

Conference Attendance: Issue attendance badges for events and workshops
Achievement Tracking: Create progressive badge systems for ongoing programs
Speaker Recognition: Manage speaker and participant recognition badges

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow TypeScript best practices
Add comprehensive error handling
Include JSDoc comments for functions
Update tests for new features
Follow semantic versioning

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

Getting Help

📖 Documentation: Check this README and inline code comments
🐛 Bug Reports: Open an issue
💬 Discussions: GitHub Discussions
📧 Email: [email protected]

Troubleshooting

Common Issues

1. API Key Validation Failed

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

2. Connection Timeout

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

3. Badge Creation Errors

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

🔗 Related Projects

IssueBadge API: Core badge management platform
Model Context Protocol: MCP specification and tools
Claude Desktop: AI assistant with MCP support

📈 Roadmap

Version 1.1

Batch badge operations
Advanced filtering and search
Webhook integration
Badge template management

Version 1.2

Analytics and reporting tools
Custom badge validation rules
Integration with learning management systems
Advanced workflow automation

Version 2.0

Blockchain verification support
Multi-language badge content
Advanced branding customization
Enterprise SSO integration

Ready to revolutionize your badge management? Get started with IssueBadge MCP Server and experience the power of conversational badge administration!

Built with ❤️ by the IssueBadge team