fireMCP (Braze Write Server)

# Braze MCP Write Server - Project Summary ## Overview Successfully created a write-enabled extension of the official Braze MCP server with comprehensive safety mechanisms for demo and POC environments. ## What Was Built ### Core Architecture ``` braze_mcp_write/ ├── models/ # Pydantic models for validation │ ├── errors.py # Error response models │ └── responses.py # API response models ├── tools/ # MCP tool implementations │ ├── users_write.py # User tracking operations (5 functions) │ ├── campaigns_write.py # Campaign operations (4 functions) │ ├── canvas_write.py # Canvas operations (4 functions) │ ├── catalogs_write.py # Catalog management (5 functions) │ └── content_blocks_write.py # Content block ops (2 functions) ├── utils/ # Core utilities │ ├── context.py # Braze API context management │ ├── http.py # HTTP client utilities │ ├── logging.py # Logging configuration │ └── safety.py # Safety mechanisms ├── registry_builder.py # Auto-discovery system ├── server.py # FastMCP server └── main.py # Entry point ``` ### Total Functions Implemented: 20 #### User Management (5) - `track_user_data` - Batch track attributes, events, purchases - `update_user_attributes` - Update user profiles - `track_event` - Track custom events - `track_purchase` - Track purchases - `delete_user` - Delete users (with confirmation) - `identify_users` - Merge user profiles #### Campaign Operations (4) - `send_campaign` - Send campaigns immediately - `schedule_campaign` - Schedule campaigns - `update_campaign_schedule` - Update scheduled campaigns - `delete_scheduled_campaign` - Cancel scheduled campaigns #### Canvas Operations (4) - `trigger_canvas` - Trigger Canvas flows - `schedule_canvas` - Schedule Canvas - `update_canvas_schedule` - Update scheduled Canvas - `delete_scheduled_canvas` - Cancel scheduled Canvas #### Catalog Management (5) - `create_catalog_items` - Add items to catalogs - `update_catalog_items` - Update catalog items - `delete_catalog_items` - Remove catalog items - `create_catalog` - Create new catalogs - `delete_catalog` - Delete catalogs #### Content Block Operations (2) - `create_content_block` - Create reusable content - `update_content_block` - Update content blocks ## Safety Features Implemented ### 1. Workspace Validation - Only allows writes to workspaces matching configured patterns (demo-, poc-, test-) - Prevents accidental production writes - Configurable via `BRAZE_ALLOWED_WORKSPACES` ### 2. Write Enable/Disable Toggle - Global kill switch for all write operations - Controlled via `BRAZE_WRITE_ENABLED` environment variable ### 3. Dry Run Mode - Test any operation without making actual API calls - Can be set as default or per-operation - Returns detailed preview of what would be executed ### 4. Confirmation Requirements - Destructive operations require explicit `confirm=True` - Includes: delete_user, delete_catalog, delete_catalog_items - Prevents accidental deletions ### 5. Rate Limiting - Prevents API abuse and respects Braze limits - Configurable per operation type - Default: 1000 sends/hour, 100 catalog updates/minute ### 6. Comprehensive Logging - All operations logged with timestamps - Includes workspace URLs, parameters, and results - Enables audit trails and debugging ## Documentation Created 1. **README.md** - Project overview and features 2. **QUICKSTART.md** - 5-minute setup guide 3. **docs/GETTING_STARTED.md** - Detailed setup instructions 4. **docs/EXAMPLES.md** - Practical usage examples and patterns 5. **docs/SAFETY.md** - Safety best practices and procedures 6. **LICENSE** - MIT License 7. **env.example** - Example environment configuration ## Key Design Decisions ### Following Official Braze MCP Patterns - Used same architecture as official server (tools/, utils/, models/) - Implemented auto-discovery via `__register_mcp_tools__` - Used Google-style docstrings for automatic metadata extraction - Followed existing HTTP request/response patterns ### Safety-First Approach - Multiple layers of protection (workspace, enable/disable, dry run, confirmation) - Conservative defaults (write disabled, production blocked) - Explicit over implicit (require confirm for destructive ops) - Fail-safe design (errors block operations rather than proceeding) ### Developer Experience - Clear error messages with actionable solutions - Comprehensive examples for common scenarios - Dry run for testing without consequences - Batch operations for efficiency ## Configuration ### Required Environment Variables ```bash BRAZE_API_KEY=your-api-key BRAZE_BASE_URL=https://rest.demo-01.braze.com BRAZE_WRITE_ENABLED=true ``` ### Optional Safety Configuration ```bash BRAZE_ALLOW_PRODUCTION=false BRAZE_ALLOWED_WORKSPACES=demo-,poc-,test- BRAZE_DRY_RUN_DEFAULT=false BRAZE_MAX_SENDS_PER_HOUR=1000 BRAZE_MAX_CATALOG_UPDATES_PER_MIN=100 ``` ## Next Steps for User 1. **Install Dependencies** ```bash cd "/Users/saarkia/Documents/Coding/AR Braze MCP" pip install -e . ``` 2. **Configure Environment** - Copy `env.example` to `.env` - Add your Braze API key and demo workspace URL 3. **Configure MCP Client** - Add server configuration to Claude Desktop - Restart Claude 4. **Test Connection** - Run `list_functions()` to see all available functions - Try a dry run operation first 5. **Start Creating Demos** - Follow examples in `docs/EXAMPLES.md` - Use safety features to protect production - Clean up demo data after presentations ## Differences from Official Braze MCP ### Added Features - Write operations (campaigns, canvas, users, catalogs, content blocks) - Comprehensive safety mechanisms - Dry run mode - Confirmation for destructive operations - Rate limiting - Enhanced error handling and logging ### Maintained Compatibility - Same architecture and patterns - Compatible with MCP protocol - Similar function naming conventions - Google-style docstrings ## Testing Recommendations 1. **Unit Tests** (Not yet implemented) - Test each function with dry_run=True - Test workspace validation - Test rate limiting - Test error handling 2. **Integration Tests** (Not yet implemented) - Test against actual demo workspace - Verify all operations work end-to-end - Test safety mechanisms 3. **Manual Testing** - Test each function with real Braze workspace - Verify dry run mode works correctly - Confirm safety mechanisms block inappropriate operations ## Known Limitations 1. **Not Yet Implemented** - Segment management operations - SMS/push token management - Subscription group updates - Email template management 2. **Dependencies** - Requires mcp>=1.0.0, pydantic>=2.0.0, httpx>=0.27.0 - Python 3.10 or higher 3. **Safety Trade-offs** - Multiple safety checks add latency - Workspace validation requires URL patterns - Rate limiting may block legitimate high-volume operations ## Future Enhancements 1. **Additional Operations** - Segment CRUD operations - Message template management - Subscription group management - Analytics and reporting 2. **Enhanced Safety** - Per-user rate limits - Operation audit logs - Rollback capabilities - Integration with monitoring systems 3. **Developer Experience** - Interactive CLI tool - Web dashboard for monitoring - Better error messages with suggestions - Pre-commit hooks for safety checks ## Resources - Official Braze MCP: https://pypi.org/project/braze-mcp-server/ - Braze API Documentation: https://www.braze.com/docs/api/basics/ - MCP Protocol: https://modelcontextprotocol.io/ ## Support For questions or issues: 1. Check the documentation in `docs/` 2. Review examples in `docs/EXAMPLES.md` 3. Consult Braze API documentation 4. Review server logs for detailed error messages ## License MIT License - See LICENSE file for details --- **Status**: ✅ Complete and ready for use **Last Updated**: 2024-11-28 **Version**: 0.1.0