IssueBadge MCP Server

# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added - Initial release planning ### Changed - Nothing yet ### Deprecated - Nothing yet ### Removed - Nothing yet ### Fixed - Nothing yet ### Security - Nothing yet ## [1.0.0] - 2024-12-07 ### Added - 🎉 **Initial Release**: Complete MCP server for IssueBadge API - 🔐 **Dual Authentication**: Support for Laravel Sanctum and OAuth2 - 🛠️ **Core Tools**: - `validate_key`: API key validation - `get_all_badges`: Retrieve available badges - `create_badge`: Create new badge templates - `issue_badge`: Issue badges to recipients - 🎨 **Custom Fields**: Support for dynamic badge metadata - 🛡️ **Idempotency Protection**: Prevent duplicate operations - 📧 **Email Notifications**: Automatic badge delivery - 🔄 **Error Handling**: Comprehensive error management with user-friendly messages - 📊 **Multi-tenant Support**: Secure tenant isolation - 🐛 **Debug Mode**: Detailed logging for development - ⚡ **Retry Logic**: Automatic retry for failed requests - 📝 **TypeScript**: Full type safety and IntelliSense support - 🧪 **Input Validation**: Zod schema validation for all inputs - 📚 **Comprehensive Documentation**: README, examples, and API docs ### Features by Tool #### `validate_key` - Validates IssueBadge API keys - Returns authentication status and user information - Supports both Sanctum and OAuth2 tokens #### `get_all_badges` - Retrieves all available badges for organization - Configurable result limit (max 100) - Returns badge IDs and names for easy selection #### `create_badge` - Creates new badge templates - Support for custom fields (text, email, number, date) - File upload support for badge logos - Configurable expiration dates - Organization management #### `issue_badge` - Issues badges to recipients - Email notification system - Custom metadata support - Public verification URLs - Idempotency protection ### Developer Experience - 🚀 **Easy Setup**: Simple npm install and configuration - 📖 **Rich Documentation**: Comprehensive README with examples - 🔧 **Development Tools**: ESLint, Prettier, TypeScript - 🧪 **Testing Support**: Test scripts and examples - 📦 **Multiple Integration Methods**: Claude Desktop, ChatGPT Actions - 🛠️ **Debug Support**: Detailed logging and error messages ### Security Features - 🔐 **Token Validation**: Secure API authentication - 🛡️ **Input Sanitization**: Zod schema validation - 🔒 **Multi-tenant Isolation**: Secure data separation - ⏱️ **Request Timeouts**: Protection against hanging connections - 🔄 **Retry Logic**: Graceful handling of temporary failures ### Integration Support - 🤖 **Claude Desktop**: Full MCP integration - 💬 **ChatGPT Actions**: OpenAPI specification support - 🔌 **Custom Integrations**: Flexible API design - 📱 **Cross-platform**: Works on Windows, macOS, Linux ### Performance Features - ⚡ **Async Operations**: Non-blocking badge management - 🚀 **Connection Pooling**: Efficient HTTP client - 📊 **Rate Limiting**: Respectful API usage - 🔄 **Error Recovery**: Automatic retry with exponential backoff --- ## Release Notes ### What's New in v1.0.0 This is the initial release of the IssueBadge MCP Server! 🎉 **AI-Powered Badge Management**: Transform how you manage digital badges and certificates. Instead of complex API calls, simply tell your AI assistant what you want: - *"Create a badge for Python certification with custom fields for completion date and score"* - *"Issue the web development badge to John Doe with his completion details"* - *"Show me all available badges in our system"* **Key Highlights**: 1. **Natural Language Interface**: Manage badges through conversation with AI assistants 2. **Complete Badge Lifecycle**: Create templates, issue to recipients, verify authenticity 3. **Enterprise Ready**: Multi-tenant support with secure data isolation 4. **Developer Friendly**: TypeScript, comprehensive docs, easy setup 5. **Flexible Integration**: Works with Claude Desktop, ChatGPT, and custom implementations **Getting Started**: ```bash git clone https://github.com/issuebadge/mcp-server.git cd mcp-server npm install cp .env.example .env # Configure your API credentials npm run build ``` **Claude Desktop Setup**: ```json { "mcpServers": { "issuebadge": { "command": "node", "args": ["/path/to/mcp-server/dist/index.js"], "env": { "ISSUEBADGE_API_KEY": "your_api_key" } } } } ``` ### Migration Guide This is the initial release, so no migration is needed. ### Breaking Changes None - this is the initial release. ### Deprecations None - this is the initial release. ### Known Issues - File upload for badge logos requires absolute file paths - Large badge lists (>100) require pagination - Debug logging goes to stderr (not configurable yet) ### Contributors - IssueBadge Team - Initial development and architecture - Community feedback and testing --- ## Future Releases ### Planned for v1.1.0 - [ ] Batch badge operations - [ ] Advanced filtering and search - [ ] Webhook integration for real-time updates - [ ] Badge template management tools - [ ] Enhanced error recovery ### Planned for v1.2.0 - [ ] Analytics and reporting integration - [ ] Custom badge validation rules - [ ] Learning Management System integrations - [ ] Advanced workflow automation ### Planned for v2.0.0 - [ ] Blockchain verification support - [ ] Multi-language badge content - [ ] Advanced branding customization - [ ] Enterprise SSO integration --- ## Support If you encounter any issues or have questions: - 📖 **Documentation**: Check the README and this changelog - 🐛 **Bug Reports**: [Open an issue](https://github.com/issuebadge/mcp-server/issues) - 💬 **Discussions**: [GitHub Discussions](https://github.com/issuebadge/mcp-server/discussions) - 📧 **Email**: support@issuebadge.com --- *Thank you for using IssueBadge MCP Server! 🚀*