EuConquisto Composer MCP

# Claude Desktop Testing Guide - Complete Self-Contained Edition **Version**: 2.3.0 **Updated**: July 3, 2025 **Purpose**: Complete testing guidance including UI fix and manual testing protocol **Scope**: End-to-end workflow evaluation for EuConquisto Composer MCP --- ## 🎯 **PROJECT CONTEXT & SCOPE CLARIFICATION** ### **Role & Scope Guidelines** **Based on user guidance from July 2, 2025 testing session:** 1. **Execution Approach**: Execute testing tasks independently whenever possible for direct access to system messages. When necessary, provide step-by-step guidance (one step at a time). 2. **Testing Timeline**: Proceed immediately if this testing guide is adequate. If test plan needs adjustments, make adjustments prior to testing. ### **Infrastructure Status Confirmation** **Based on user confirmation from July 2, 2025:** 3. **JWT Server Status**: Local server is confirmed running on localhost:8080 4. **MCP Tool Access**: Confirmed access to `create_educational_composition` tool ### **Testing Focus Direction** **Based on user guidance:** 5. **Testing Methodology**: Follow the complete 5-phase testing plan as outlined 6. **Testing Approach**: Focus on validation and analysis (not actual composition creation for now) ### **Technical Environment Access** **Based on user confirmation:** 7. **File and Server Access**: Confirmed access to all referenced files and servers. If access issues arise, notify user for proper access provision. --- ## 🎯 **PROJECT CONTEXT & LOCATION** ### **Project Identity** - **Name**: EuConquisto Composer MCP - Complete Workflow Evaluation - **Purpose**: Automated educational content creation using browser automation - **Technology**: TypeScript/JavaScript MCP server with Playwright browser automation - **Target Platform**: https://composer.euconquisto.com (Brazilian educational content platform) ### **Absolute Project Location** ``` /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/ ``` **⚠️ CRITICAL**: This is the ONLY directory you need to access. All project files are within this location. ### **Project Structure Overview** ``` euconquisto-composer-mcp-poc/ ├── dist/ # Compiled scripts │ ├── browser-automation-simple.js # Original script (has path issues) │ └── browser-automation-simple-fixed.js # FIXED script (v2.0.1-fixed) ├── archive/authentication/ │ └── correct-jwt-new.txt # JWT token (3,276 characters) ├── correct-jwt-new.txt # JWT token (fallback location) ├── docs/ │ ├── CLAUDE-DESKTOP-TESTING-GUIDE.md # This file │ ├── progress/ # Progress documentation │ └── troubleshooting/ # Rollback procedures ├── tools/servers/ │ └── jwt-redirect-server-v1.0.2.js # JWT redirect server └── src/ # Source code ``` --- ## 📋 **CURRENT PROJECT STATUS (July 3, 2025) - UI FIX IMPLEMENTED** ### **Implementation Status - BREAKTHROUGH ACHIEVED** - ✅ **UI Selector Fix Applied**: Hamburger menu interaction implemented with multiple fallback strategies - ✅ **Manual Testing Framework**: v2.1.2-manual-test ready for user validation - ✅ **Production Version Ready**: v2.1.1-clean prepared for deployment - ✅ **Infrastructure Operational**: JWT server, MCP server, browser automation fully functional - 🔄 **Manual Testing Phase**: 20-second pause system for user interaction validation - ⏳ **Phase 2 Completion**: Awaiting manual testing validation to proceed to Phase 3-5 ### **Recent Critical Developments (July 3, 2025)** - **UI Challenge Solved**: Hamburger menu (☰) interaction requirement identified and implemented - **Multiple Script Versions**: Created clean production and manual testing versions - **Testing Protocol**: Structured 20-second pause system for user interaction - **Configuration Updated**: Claude Desktop now uses manual testing script - **Documentation Enhanced**: Complete UI fix implementation documented ### **Current Testing Reality** - **Phase 1 Complete**: ✅ Infrastructure validation confirmed operational - **Phase 2 Ready**: ✅ UI fix implemented, manual testing framework ready - **Phases 3-5 Prepared**: ⏳ Ready to proceed after Phase 2 manual validation - **Overall Status**: 90% functional - only user interaction validation remaining ### **Script Versions Available** - **v2.1.1-clean**: Production-ready version with complete UI fix - **v2.1.2-manual-test**: Manual testing version with 20-second pause (currently active) - **v2.0.1-fixed**: Legacy version with JWT path fix (deprecated) - **Location**: `/dist/` directory with multiple deployment options ### **Success Achievements** - ✅ **UI Selector Challenge Solved**: Two-step hamburger menu → save process implemented - ✅ **Multiple Detection Strategies**: 4-layer fallback system for menu button detection - ✅ **Clean MCP Communication**: No JSON protocol conflicts - ✅ **Manual Testing Framework**: Structured validation approach ready - ✅ **Production Deployment Ready**: Multiple script versions available ## 📊 **REALISTIC TESTING EXPECTATIONS** ### **What's Currently Working ✅** - **JWT Token Loading**: Fixed script successfully loads from absolute paths - **MCP Tool Availability**: `create_educational_composition` tool responds - **Browser Automation**: Launches browser and navigates to Composer - **Authentication**: Successfully authenticates and reaches platform interface - **UI Fix Implementation**: Hamburger menu interaction strategies implemented - **Manual Testing Framework**: 20-second pause system for user validation ### **Current Status 🔄** - **Hybrid Solution Validated**: Manual hamburger menu opening + automated save completion - **Full Automation**: NOT ACHIEVED - user intervention required for menu interaction - **Production Workflow**: 90% automated, single manual click required per composition - **User Training**: Required for hamburger menu click during 20-second pause window - **Alternative Options**: Continue UI detection research for full automation or deploy hybrid solution ### **Testing Approach (Updated)** - **Phase 1**: ✅ Complete - Infrastructure fully validated - **Phase 2**: 🔄 Manual testing validation - UI fix implemented, user interaction required - **Phases 3-5**: ⏳ Ready to proceed once Phase 2 manual validation complete - **Focus**: User interaction validation rather than technical debugging --- ## 🔐 **AUTHENTICATION & ACCESS VERIFICATION** ### **Step 1: Verify Project Access** ```bash # Confirm you can access the project directory ls -la /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/ # Expected: You should see the project structure listed above # If you get "Permission denied" or "No such file or directory", STOP and request access ``` ### **Step 2: Verify JWT Token Access** ```bash # Check primary JWT token location cat /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/archive/authentication/correct-jwt-new.txt # Expected: Should display a long JWT token (3,276 characters) # Should start with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6... # If you get access denied, check fallback location: cat /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/correct-jwt-new.txt ``` ### **Step 3: Verify Fixed Script Access** ```bash # Check the fixed script exists ls -la /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/dist/browser-automation-simple-fixed.js # Expected: File should exist and be readable # Should show recent modification date (July 2, 2025) ``` ### **Step 4: Verify Claude Desktop Configuration** ```bash # Check Claude Desktop is configured to use the fixed script cat "/Users/ricardokawasaki/Library/Application Support/Claude/claude_desktop_config.json" | grep -A 5 "euconquisto-composer" # Expected output should include: # "browser-automation-simple-fixed.js" # NOT "browser-automation-simple.js" ``` --- ## 🏗️ **INFRASTRUCTURE VERIFICATION** ### **JWT Redirect Server Status** ```bash # Check if JWT server is running on port 8080 curl -s http://localhost:8080/health 2>/dev/null || curl -s http://localhost:8080/ 2>/dev/null # Expected: HTTP response (even if 500 error, means server is responding) # If no response: Server not running, start with: # cd /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc # node tools/servers/jwt-redirect-server-v1.0.2.js ``` ### **Claude Desktop MCP Configuration** The project is configured as the `euconquisto-composer` MCP server in Claude Desktop with: - **Command**: `node` - **Script**: `/Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/dist/browser-automation-simple-fixed.js` - **Environment**: `NODE_ENV=development` ### **Tool Availability** After Claude Desktop restart, you should have access to: - **Tool Name**: `create_educational_composition` - **Parameters**: `prompt` (required), `subject` (optional), `gradeLevel` (optional) - **Function**: Creates educational compositions using browser automation --- ## 🧪 **TESTING METHODOLOGY** ### **Phase 1: Infrastructure Validation (10 minutes)** **Objective**: Confirm all systems operational before workflow testing #### **Test 1.1: MCP Tool Availability** ```javascript // Try this basic prompt to test tool availability: // "Test MCP tool connectivity - create a simple lesson about addition for 1st grade" // Parameters: { prompt: "Simple addition lesson", subject: "Matemática", gradeLevel: "1º ano" } // Expected Success: Tool responds without "JWT token not found" error // Expected Failure: Clear error message with troubleshooting information ``` #### **Test 1.2: JWT Token Loading** ```javascript // The fixed script includes enhanced logging // Expected console logs when tool is called: // "Attempting to load JWT token from: [absolute_path]" // "JWT token loaded successfully" // OR "Trying fallback JWT token path: [fallback_path]" // Success Criteria: No "JWT token not found" errors in response ``` #### **Test 1.3: Browser Launch Test** ```javascript // Use any simple composition prompt to test browser automation // Expected: Browser window opens showing EuConquisto Composer interface // Expected: Authentication succeeds (no 404 or login errors) // Expected: Composition creation workflow begins ``` ### **Phase 2: Manual Testing Validation (15 minutes) - UPDATED JULY 3, 2025** **Objective**: Validate UI fix implementation through user interaction #### **Manual Testing Protocol** **Current Script**: `browser-automation-manual-test-v2.1.2.js` **Testing Timeline**: 1. **0-10 seconds**: Automatic authentication and composition setup 2. **10-30 seconds**: 20-second pause for manual hamburger menu click 3. **30-35 seconds**: Automatic "Salvar composição" attempt 4. **35-65 seconds**: 30-second observation window before browser close #### **User Actions Required** - **Watch for browser window** opening and navigating to Composer - **During 20-second pause**: Manually click hamburger menu (☰) in top-right - **Observe menu expansion** and "Salvar composição" visibility - **Let automation complete** the save process #### **Test Case 2.1: Manual Validation Test** ```javascript { prompt: "Manual UI Test - Create a lesson about animals for 4th grade", subject: "Ciências", gradeLevel: "4º ano" } // Expected Success Criteria: // ✅ Browser opens and reaches Composer interface // ✅ 20-second pause allows manual hamburger menu click // ✅ Menu expands showing "Salvar composição" option // ✅ Automatic save succeeds after manual menu click // ✅ Composition URL returned successfully ``` #### **Success Validation** - **Manual Interaction Success**: User can click hamburger menu and see expanded options - **Automated Save Success**: Script successfully clicks "Salvar composição" after manual menu expansion - **End-to-End Success**: Complete workflow from prompt to saved composition URL - **Performance**: Total workflow under 35 seconds including manual interaction ### **Phase 3: Error Handling Validation (10 minutes)** #### **Test 3.1: Network Issues** - Temporarily disconnect WiFi during browser session - Expected: Graceful error message with retry suggestions #### **Test 3.2: Authentication Issues** - Test with corrupted or missing JWT token - Expected: Clear authentication failure message #### **Test 3.3: Browser Automation Issues** - Test with browser blocked or unavailable - Expected: Meaningful error with troubleshooting steps ### **Phase 4: Performance Validation (10 minutes)** #### **Metrics to Measure** - **Total Workflow Time**: Target < 30 seconds - **Success Rate**: Target > 90% across multiple attempts - **Error Recovery**: Additional time for retry operations - **Resource Usage**: Browser automation overhead #### **Load Testing** ```javascript // Sequential composition creation: // 1. Science lesson (photosynthesis) // 2. Math lesson (fractions) // 3. Portuguese lesson (grammar) // 4. History lesson (Brazilian independence) // 5. Geography lesson (Brazilian regions) // Measure: Performance consistency across sequential operations ``` ### **Phase 5: Content Quality Assessment (10 minutes)** #### **Quality Criteria** - **BNCC Compliance**: Alignment with Brazilian educational standards - **Age Appropriateness**: Content suitable for specified grade levels - **Portuguese Quality**: Proper grammar and Brazilian terminology - **Interactive Elements**: Engagement components functionality - **Visual Design**: Professional presentation --- ## 🔧 **TROUBLESHOOTING GUIDE** ### **Issue 1: "JWT token not found" Error** **Symptom**: MCP tool responds with "JWT token not found. Please check archive/authentication/correct-jwt-new.txt" **Solution Steps**: 1. **Verify File Exists**: ```bash ls -la /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/archive/authentication/correct-jwt-new.txt ``` 2. **Check Fallback Location**: ```bash ls -la /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/correct-jwt-new.txt ``` 3. **Verify Fixed Script**: - Confirm Claude Desktop config uses `browser-automation-simple-fixed.js` - Restart Claude Desktop if configuration was changed 4. **Emergency Rollback**: - Follow procedures in `/docs/troubleshooting/rollback-instructions-v1.0.0.md` ### **Issue 2: Tool Not Available** **Symptom**: `create_educational_composition` doesn't appear in Claude Desktop tools **Solution Steps**: 1. **Check MCP Configuration**: ```bash grep -A 10 "euconquisto-composer" "/Users/ricardokawasaki/Library/Application Support/Claude/claude_desktop_config.json" ``` 2. **Verify Script Path**: ```bash ls -la /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/dist/browser-automation-simple-fixed.js ``` 3. **Restart Claude Desktop**: - Complete shutdown (Cmd+Q) - Wait 10-15 seconds - Relaunch and wait for MCP servers to load ### **Issue 3: Browser Automation Fails** **Symptom**: Browser opens but doesn't navigate correctly or shows errors **Solution Steps**: 1. **Check JWT Server**: ```bash curl http://localhost:8080/health ``` 2. **Start JWT Server if Needed**: ```bash cd /Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc node tools/servers/jwt-redirect-server-v1.0.2.js ``` 3. **Verify JWT Token Validity**: - Token should be valid until 2025-07-28 - Check for corruption (should be exactly 3,276 characters) ### **Issue 4: Performance Issues** **Symptom**: Workflows taking longer than 30 seconds or failing intermittently **Solution Steps**: 1. **Check System Resources**: Ensure sufficient memory and CPU available 2. **Restart Services**: Restart both JWT server and Claude Desktop 3. **Network Check**: Verify stable internet connection 4. **Fallback Testing**: Use simplified test cases first --- ## 📊 **SUCCESS METRICS & VALIDATION** ### **Functional Success Criteria** - ✅ **End-to-End Completion**: 100% successful workflow execution - ✅ **Component Integration**: All components work seamlessly together - ✅ **Error Handling**: Graceful handling of all tested failure scenarios - ✅ **Content Generation**: High-quality, educationally appropriate content - ✅ **URL Accessibility**: Generated URLs load compositions correctly ### **Performance Success Criteria** - ⏱️ **Workflow Duration**: ≤ 30 seconds per composition (target: 20-25 seconds) - 🎯 **Success Rate**: ≥ 90% successful completion rate - 🔄 **Error Recovery**: ≤ 10 seconds additional time for retry operations - 💾 **Resource Efficiency**: Reasonable memory usage (< 500MB peak) - 📈 **Scalability**: Consistent performance across sequential operations ### **Quality Success Criteria** - 📚 **Educational Standards**: Content aligns with BNCC requirements - 🎓 **Grade Appropriateness**: Content suitable for specified educational levels - 🎨 **Visual Design**: Professional presentation with engaging layouts - 🔗 **Interactivity**: Functional interactive elements and assessments - 🌐 **Accessibility**: Content accessible across different devices and browsers --- ## 🚀 **QUICK START CHECKLIST** ### **Before Starting Testing** - [ ] **Project Access**: Can read files in `/Users/ricardokawasaki/Desktop/euconquisto-composer-mcp-poc/` - [ ] **JWT Token**: Accessible at primary or fallback location - [ ] **Fixed Script**: `browser-automation-simple-fixed.js` exists and is configured - [ ] **JWT Server**: Running on localhost:8080 or ready to start - [ ] **Claude Desktop**: Using fixed script configuration ### **Testing Execution** - [ ] **Phase 1**: Infrastructure validation (10 min) - [ ] **Phase 2**: Single composition workflow (15 min) - [ ] **Phase 3**: Error handling validation (10 min) - [ ] **Phase 4**: Performance benchmarking (10 min) - [ ] **Phase 5**: Content quality assessment (10 min) ### **After Testing** - [ ] **Results Documentation**: Record findings and metrics - [ ] **Issue Identification**: Note any problems encountered - [ ] **Recommendations**: Suggest improvements or next steps - [ ] **Status Update**: Update project documentation --- ## 📞 **ESCALATION & SUPPORT** ### **If Testing Cannot Proceed** 1. **File Access Issues**: Request proper directory permissions 2. **Configuration Issues**: Use rollback procedures in `/docs/troubleshooting/` 3. **Infrastructure Issues**: Check JWT server and Claude Desktop setup 4. **Unknown Issues**: Document exact error messages and context ### **Available Resources** - **Rollback Guide**: `/docs/troubleshooting/rollback-instructions-v1.0.0.md` - **Progress Documentation**: `/docs/progress/` (latest status updates) - **Technical Specs**: Project README and context files - **Alternative Approaches**: Manual testing procedures if automation fails --- ## 📋 **TESTING COMPLETION CRITERIA** ### **Minimum Success Requirements** - **Infrastructure validation**: MCP tool loads and responds - **Basic workflow**: At least one composition created successfully - **Error handling**: Graceful failure recovery demonstrated - **Documentation**: Results recorded for future reference ### **Optimal Success Requirements** - **All 5 phases completed**: Full testing methodology executed - **Performance targets met**: Sub-30 second workflows achieved - **Quality validation**: Educational content meets BNCC standards - **Scalability confirmed**: Sequential operations perform consistently --- **Guide Status**: ✅ **COMPLETE & CURRENT** **No External Searches Required**: All necessary information included **Manual Testing Ready**: v2.1.2 script configured for immediate testing **Last Updated**: July 3, 2025 with UI fix implementation and manual testing protocol **🎯 Objective**: Complete workflow validation through manual UI interaction and automated testing phases**