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 namedescription(string, required): Badge descriptionissuing_organization_name(string, required): Organization nameidempotency_key(string, required): Unique identifiercustom_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 creationname(string, required): Recipient's full nameidempotency_key(string, required): Unique identifieremail(string, optional): Recipient's emailmetadata(object, optional): Custom field values
Example:
"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%"
💬 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: support@issuebadge.com
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