EuConquisto Composer MCP

# v1.1.0 Fail-Fast Implementation Documentation ## Overview The v1.1.0 release introduces comprehensive fail-fast validation across all 7 MCP tools, transforming the development experience with clear, actionable error messages and detailed troubleshooting guidance. ## Design Philosophy ### Core Principles 1. **Fail Fast**: Validate inputs immediately, reject invalid data before processing 2. **Clear Errors**: Provide specific, actionable error messages 3. **No Silent Failures**: Remove all auto-fix fallbacks that hide issues 4. **Developer First**: Include troubleshooting guides in every error ### Strategic Goals - **Accelerate Development**: Reduce debugging time with clear error context - **Maintain Flexibility**: Preserve dynamic content adaptation capability - **Ensure Reliability**: Catch issues early in the workflow - **Improve Documentation**: Self-documenting error messages ## Known Limitations ### Claude Desktop Behavior Despite fail-fast implementation, Claude Desktop may still attempt to work around errors: 1. **Error Workarounds**: Claude Desktop treats tool errors as recoverable and may try alternative approaches 2. **Sequential Thinking**: May use sequential thinking tool multiple times to plan workarounds 3. **Workflow Bypass**: May create content directly in chat instead of following MCP workflow **Current Mitigation**: - Using `ErrorCode.InternalError` instead of `InvalidParams` for more severe errors - Prefixing errors with "FATAL:" to indicate severity - Clear messaging that "workflow cannot continue" **Developer Workflow**: 1. Watch for error messages in Claude Desktop output 2. When errors occur, manually stop and fix the issue 3. Restart the workflow with corrected inputs 4. Use development mode (`NODE_ENV=development`) for detailed logs ## Implementation Details ### Tool-by-Tool Enhancements #### 1. get-smart-guidance-v1.1.0.js **Purpose**: Educational guidance with widget predictions **Key Validations**: - Prompt must be non-empty string (5-1000 chars) - Subject must be from predefined list (if provided) - Grade level must follow Brazilian format (if provided) **Example Error**: ``` ❌ PROMPT LENGTH ERROR: Prompt too short: 3 characters. Minimum required: 5 characters Received: "abc" Provide a meaningful educational topic description. ``` #### 2. analyze-content-for-widgets-v1.1.0.js **Purpose**: Dynamic content analysis and widget mapping **Key Features**: - 6 content format auto-detection - Comprehensive structure validation - Content preservation with error reporting **Supported Formats**: 1. `structured_sections` - Standard Claude Desktop format 2. `content_sections` - Legacy format 3. `object_content` - Structured object content 4. `string_content` - Markdown string content 5. `flat_educational` - Flat object with educational properties 6. `minimal_text` - Basic text fields **Example Error**: ``` ❌ CONTENT FORMAT ERROR: Content format not recognized. Detected keys: [title, data, info] Expected educational content with structure like: title, sections, content, etc. ``` #### 3. get-widget-requirements-v1.1.0.js **Purpose**: Provide API requirements for selected widgets **Key Validations**: - Widget types must be from supported list - Input format flexibility (array, object, nested) - Comprehensive extraction with fallbacks **Supported Widgets**: - head-1, head-2 (Headers) - text-1, text-2 (Content) - quiz-1, quiz-2 (Assessments) - flashcards-1, flashcards-2 (Vocabulary) - image-1, image-2 (Visual) - list-1, list-2 (Structured) **Example Error**: ``` ❌ UNSUPPORTED WIDGET TYPES ERROR: These widget types are not supported: custom-widget Supported widget types: • head-1 • text-1 • quiz-1 • flashcards-1 • image-1 • list-1 Check widget type spelling and ensure they're from the supported list. ``` #### 4. validate-lesson-data-v1.1.0.js **Purpose**: Comprehensive lesson data validation **Validation Phases**: 1. Structure validation (metadata + widgets) 2. Metadata completeness 3. Widget array validation 4. Educational flow checks 5. Content quality assessment **No Auto-Fix Policy**: All issues must be resolved by the user/AI **Example Error**: ``` ❌ MISSING METADATA FIELDS ERROR: Required fields missing: gradeLevel, subject Required metadata fields: • topic: string • gradeLevel: string • subject: string Received metadata: { "topic": "Photosynthesis" } ``` #### 5. format-for-composer-v1.1.0.js **Purpose**: Transform to exact Composer JSON format **Key Features**: - Strict widget transformation - Structure validation - Composer API compliance **Example Error**: ``` ❌ WIDGET 3 TRANSFORMATION ERROR: Quiz widget content.questions array is required Widget: { "id": "quiz_001", "type": "quiz-1", "content": {} } ``` #### 6. save-composition-direct-api (integrated) **Purpose**: Direct API save without browser **Error Handling**: - API response validation - Network error handling - Authentication verification #### 7. open-composition-editor-v1.1.0.js **Purpose**: Browser navigation to saved composition **Key Validations**: - Composition UID format - Playwright availability - Navigation success **Example Error**: ``` ❌ BROWSER LAUNCH ERROR: Browser launch failed: Cannot find module 'playwright' Ensure Playwright is installed: 'npx playwright install chromium' ``` ## Error Response Structure ### Standard Error Format ```javascript { success: false, error: { code: 'SPECIFIC_ERROR_CODE', message: 'Detailed error description with context', timestamp: '2025-01-20T10:30:00.000Z', processingTime: 125, failFast: true, developmentMode: true, troubleshooting: { requiredInputStructure: { // Expected input format }, validationChecks: [ // What is being validated ], commonIssues: [ // Frequent problems ], debugSteps: [ // How to debug ] } } } ``` ### Error Code Categories - `*_STRUCTURE_ERROR` - Input structure issues - `*_VALIDATION_FAILED` - Content validation failures - `*_TYPE_ERROR` - Type mismatches - `*_FORMAT_ERROR` - Format issues - `*_MISSING_*_ERROR` - Missing required data ## Development Workflow ### 1. Enable Development Mode ```json { "env": { "NODE_ENV": "development", "MCP_DEBUG": "true" } } ``` ### 2. Read Error Messages Carefully Each error provides: - Specific issue description - Expected vs received data - Resolution steps - Debug guidance ### 3. Follow Troubleshooting Steps Errors include numbered debug steps: ``` debugSteps: [ "1. Check if input.lessonData exists", "2. Verify metadata has required fields", "3. Ensure widgets is an array", "4. Check widget types are supported", "5. Validate content structure" ] ``` ### 4. Use Input Structure Documentation Every error shows expected format: ```javascript requiredInputStructure: { lessonData: { metadata: { topic: "string - lesson title", gradeLevel: "string - grade level", subject: "string - subject area" }, widgets: [...] } } ``` ## Migration Guide ### From v1.0.0 to v1.1.0 **No Code Changes Required** - v1.1.0 is fully backward compatible **Configuration Update**: 1. Add to Claude Desktop config: ```json "NODE_ENV": "development", "MCP_DEBUG": "true" ``` 2. Restart Claude Desktop **What Changes**: - Errors appear immediately instead of silent failures - More detailed error messages - Debug logs in console - No auto-fix attempts ## Performance Impact ### Validation Overhead - Average: 5-10ms per tool - Negligible impact on overall performance - Benefits outweigh minimal overhead ### Debug Mode - Additional logging when `MCP_DEBUG=true` - ~20% more console output - No impact on functionality ## Best Practices ### 1. Input Validation - Always provide complete input structures - Check tool documentation for required fields - Use TypeScript/JSDoc for better IDE support ### 2. Error Handling - Read full error message - Check troubleshooting section - Follow debug steps sequentially ### 3. Development Flow - Start with `get_smart_guidance` - Create complete content before analysis - Validate at each step - Save frequently ### 4. Content Structure - Use consistent formatting - Include all required metadata - Provide substantial content - Follow widget guidelines ## Common Issues and Solutions ### Issue: "claudeContent is required and must be an object" **Solution**: Ensure you pass the content in the correct structure: ```javascript { claudeContent: { title: "Lesson Title", sections: [...], // or other supported formats } } ``` ### Issue: "No valid widget types found" **Solution**: Check that widget types are from supported list and properly formatted ### Issue: "Playwright browser not installed" **Solution**: Run `npx playwright install chromium` ### Issue: "Direct API not configured" **Solution**: Ensure environment variables are set in Claude Desktop config ## Future Enhancements ### Planned for v1.2.0 - Performance profiling in errors - Suggestion engine for fixes - Validation caching - Batch error reporting ### Planned for v1.3.0 - AI-powered error resolution - Visual error reporting - Integration testing suite - Custom validation rules ## Conclusion The v1.1.0 fail-fast implementation significantly improves the development experience by providing immediate, clear feedback on issues. This approach reduces debugging time, improves code quality, and maintains the system's flexibility for dynamic content adaptation. **Key Takeaway**: Errors are now your friend - they guide you to the solution!