EuConquisto Composer MCP

# Browser Automation MCP Server Guide **Version**: 2.0.0 **Created**: 2025-07-02 **Status**: Production Ready ## 🎯 Overview The Browser Automation MCP Server provides a complete solution for creating educational compositions in EuConquisto Composer using browser automation. This approach bypasses API restrictions by using a hybrid strategy: programmatic JSON generation combined with browser automation for persistence. ## 🚀 Quick Start ### 1. Prerequisites - Node.js 18+ installed - Valid JWT token in `archive/authentication/correct-jwt-new.txt` - JWT redirect server files in place ### 2. Installation ```bash # Install dependencies npm install # Install Playwright browsers (if not already installed) npm run install:browsers ``` ### 3. Launch the Server **Option 1: Using the launch script (Recommended)** ```bash ./tools/launch-browser-automation.sh ``` **Option 2: Manual startup** ```bash # Terminal 1: Start JWT redirect server npm run jwt:server # Terminal 2: Start MCP server npm run mcp:browser-automation ``` ## 📚 Usage ### Creating a Composition The server provides a single main tool: `create_educational_composition` **Parameters:** - `prompt` (required): Educational content description - `subject` (optional): Subject area (Ciências, Matemática, História, etc.) - `gradeLevel` (optional): Grade level (e.g., "7º ano") - `title` (optional): Custom title for the composition **Example:** ```json { "prompt": "Create an interactive lesson about photosynthesis for 7th grade students", "subject": "Ciências", "gradeLevel": "7º ano" } ``` ### Workflow Process 1. **Content Generation**: AI generates educational composition JSON 2. **Authentication**: Browser navigates to JWT redirect server 3. **Blank Creation**: Creates empty composition for persistence 4. **Content Injection**: Enriches composition via localStorage 5. **Save & Return**: Saves composition and returns shareable URL ## 🏗️ Architecture ### Components ``` src/ ├── browser-automation-mcp-server.ts # Main MCP server ├── browser-automation/ │ ├── composer-ui-automation.ts # UI automation logic │ └── enhanced-composition-generator.ts # Content generation ``` ### Key Classes 1. **BrowserAutomationMCPServer**: Main server handling MCP protocol 2. **ComposerUIAutomation**: Browser automation workflows 3. **EnhancedCompositionGenerator**: Intelligent content generation ## 🔧 Configuration ### JWT Token Ensure your JWT token is valid and placed at: ``` archive/authentication/correct-jwt-new.txt ``` Current token expires: **2025-07-28** ### Server Ports - JWT Redirect Server: `http://localhost:8080` - MCP Server: Standard I/O (no port) ## 🧪 Testing ### Check JWT Server Status ```bash curl http://localhost:8080/health ``` ### Test Composition Creation Use the MCP test client or integrate with Claude Desktop to test the `create_educational_composition` tool. ## ⚠️ Troubleshooting ### Common Issues 1. **JWT Server Not Running** - Solution: Run `npm run jwt:server` or use launch script 2. **Authentication Failed** - Check JWT token exists and is valid - Verify JWT server is running on port 8080 3. **Browser Automation Errors** - Ensure Playwright is installed: `npm run install:browsers` - Check for browser permissions 4. **Content Not Loading** - Known issue: localStorage injection may require manual refresh - Fallback: Page reload is implemented automatically ### Debug Mode To see detailed logs: ```bash DEBUG=* npm run mcp:browser-automation ``` ## 📋 Element Types Supported The generator supports various educational elements: - **head-1**: Header with background image and author info - **text-1/2**: Rich text content with formatting - **quiz-1**: Single choice quizzes - **flashcards-1**: Interactive flashcards for memorization - **video-1**: Video content integration - **image-1**: Educational images and diagrams - **statement-1**: Summary and conclusion blocks ## 🔄 Workflow Details ### localStorage Structure ```javascript { composition: { id: "composition-{timestamp}", title: "Lesson Title", description: "Description", author: "Sistema Inteligente EuConquisto", created: "YYYY-MM-DD", version: "2.0.0", metadata: { disciplina: "Subject", serie: "Grade Level", duracao_estimada: "45 minutos", tags: ["tag1", "tag2"] }, elements: [ // Array of composition elements ] } } ``` ### URL Persistence After saving, compositions receive: - Encoded URL with composition data - Unique file_uid for database reference - Shareable link for distribution ## 🚧 Known Limitations 1. **Loading Trigger**: localStorage injection requires investigation for automatic loading 2. **UI Dependencies**: Minimal (only 2 operations: create + save) 3. **Performance**: ~20-30 seconds per composition creation 4. **Browser Visibility**: Currently runs in non-headless mode for reliability ## 🔮 Future Enhancements - [ ] Headless browser support for production - [ ] Batch composition creation - [ ] Enhanced error recovery - [ ] API integration when available - [ ] Performance optimizations ## 📞 Support For issues or questions: 1. Check the troubleshooting section 2. Review browser testing results in `/docs/testing/` 3. Examine logs for detailed error information --- **Ready to create amazing educational content with browser automation!** 🎓