EuConquisto Composer MCP

# Error Reference Guide - EuConquisto Composer MCP v1.1.0 **Version**: v1.1.0 (Fail-Fast Reliability Suite) **Last Updated**: January 21, 2025 **Purpose**: Comprehensive error reference with troubleshooting solutions --- ## 🚨 **Fail-Fast Error Handling** v1.1.0 implements fail-fast validation across all 7 tools: - **Immediate Error Detection**: Issues are caught and reported immediately - **Detailed Error Context**: Each error includes specific troubleshooting information - **No Silent Failures**: All validation issues surface with clear messages - **Development-Friendly**: Enhanced error messages for faster debugging --- ## 🔍 **Error Response Structure** All v1.1.0 tools return errors in this standardized format: ```json { "success": false, "error": { "code": "SPECIFIC_ERROR_CODE", "message": "Human-readable error description", "failFast": true, "developmentMode": true, "troubleshooting": { "requiredInputStructure": { "field": "Expected format and type" }, "commonIssues": [ "List of common causes for this error" ], "debugSteps": [ "Step-by-step debugging instructions" ] } } } ``` --- ## 🛠️ **Error Codes by Tool** ### **get_smart_guidance Errors** #### **PROMPT_VALIDATION_ERROR** **Cause**: Invalid or missing prompt input **Common Issues**: - Empty or null prompt - Prompt too short (less than 10 characters) - Non-string prompt value **Solution**: ```javascript // ❌ Wrong { prompt: "" } { prompt: null } { prompt: "short" } // ✅ Correct { prompt: "Create a lesson about photosynthesis for 7th grade" } ``` #### **SUBJECT_VALIDATION_ERROR** **Cause**: Invalid subject parameter **Common Issues**: - Subject not in allowed enum list - Typos in subject names **Solution**: ```javascript // ❌ Wrong { subject: "biology" } { subject: "sciences" } // ✅ Correct { subject: "science" } // Valid: science, math, history, geography, language, arts ``` #### **GRADE_LEVEL_VALIDATION_ERROR** **Cause**: Invalid grade level format **Common Issues**: - Incorrect format pattern - Missing grade indicators **Solution**: ```javascript // ❌ Wrong { gradeLevel: "7" } { gradeLevel: "seventh" } // ✅ Correct { gradeLevel: "7th grade" } { gradeLevel: "5th ano" } ``` --- ### **analyze_content_for_widgets Errors** #### **CONTENT_VALIDATION_ERROR** **Cause**: Invalid content input **Common Issues**: - Empty or null content - Content too short (less than 50 characters) - Non-string content value **Solution**: ```javascript // ❌ Wrong { content: "" } { content: "Too short" } // ✅ Correct { content: "Photosynthesis is the process by which plants convert sunlight into energy..." } ``` #### **CONTENT_FORMAT_ERROR** **Cause**: Unsupported content format **Common Issues**: - Invalid format type - Typos in format names **Solution**: ```javascript // ❌ Wrong { contentFormat: "word" } { contentFormat: "pdf" } // ✅ Correct { contentFormat: "markdown" } // Valid: markdown, html, plain_text, structured, lesson_plan, mixed ``` #### **ANALYSIS_DEPTH_ERROR** **Cause**: Invalid analysis depth parameter **Solution**: ```javascript // ✅ Correct { analysisDepth: "detailed" } // Valid: basic, detailed, comprehensive ``` --- ### **get_widget_requirements Errors** #### **WIDGET_SELECTION_ERROR** **Cause**: Invalid widget selection **Common Issues**: - Empty widget array - Too many widgets selected (>10) - Invalid widget types **Solution**: ```javascript // ❌ Wrong { selectedWidgets: [] } { selectedWidgets: ["invalid-widget"] } { selectedWidgets: ["head-1", "text-1", ...] } // >10 items // ✅ Correct { selectedWidgets: ["head-1", "text-1", "image-1", "quiz-1"] } ``` #### **UNSUPPORTED_WIDGET_TYPES_ERROR** **Cause**: Widget types not supported by the system **Supported Widgets**: - `head-1`, `text-1`, `text-2`, `text-3`, `text-4`, `text-5` - `image-1`, `image-2`, `list-1`, `list-2`, `list-3` - `quiz-1`, `flashcards-1`, `table-1` --- ### **validate_lesson_data Errors** #### **VALIDATION_FAILED** **Cause**: Lesson data structure validation failed **Common Issues**: - Missing required metadata fields - Text fields not HTML-wrapped - Incorrect widget field names - Invalid array structures **Solution Examples**: ```javascript // ❌ Wrong - Text not HTML wrapped { metadata: { category: "Science" }, // Should be "<p>Science</p>" widgets: [...] } // ✅ Correct - HTML wrapped { metadata: { category: "<p>Science</p>", duration: "<p>45 minutes</p>", subject: "<p>Biology</p>" }, widgets: [...] } ``` #### **MISSING_METADATA_ERROR** **Cause**: Required metadata fields missing **Required Fields**: - `category` (HTML wrapped) - `duration` (HTML wrapped) - `subject` (HTML wrapped) #### **HTML_WRAPPING_ERROR** **Cause**: Text content not properly HTML wrapped **Solution**: All text content must be wrapped in `<p>` tags ```javascript // ❌ Wrong "This is text content" // ✅ Correct "<p>This is text content</p>" ``` #### **WIDGET_STRUCTURE_ERROR** **Cause**: Widget objects have incorrect structure **Common Issues**: - Missing required widget fields - Incorrect field names (e.g., `options` instead of `choices`) - Invalid nested structures --- ### **format_for_composer Errors** #### **FORMAT_VALIDATION_ERROR** **Cause**: Input data cannot be formatted for Composer API **Common Issues**: - Invalid lesson data structure - Missing required formatting fields - Incompatible data types #### **STRUCTURE_VERIFICATION_ERROR** **Cause**: Output structure doesn't match Composer API requirements **Solution**: Ensure input data passes `validate_lesson_data` first --- ### **save_composition_direct_api Errors** #### **API_AUTHENTICATION_ERROR** **Cause**: Authentication with EuConquisto API failed **Common Issues**: - Invalid or expired access token - Missing environment variables - Incorrect token format **Solution**: 1. Verify `EUCONQUISTO_ACCESS_TOKEN` is set correctly 2. Check token expiration date 3. Ensure token has proper permissions #### **API_SAVE_ERROR** **Cause**: Direct API save operation failed **Common Issues**: - Network connectivity issues - Invalid composition data - API endpoint unavailable - Insufficient permissions **Debug Steps**: 1. Check network connectivity 2. Verify API endpoint status 3. Validate composition data structure 4. Check API response for specific error details #### **PROJECT_CONFIGURATION_ERROR** **Cause**: Project or connector configuration invalid **Solution**: 1. Verify `EUCONQUISTO_PROJECT_UID` is correct 2. Check `EUCONQUISTO_CONNECTORS` format 3. Ensure connector has proper permissions --- ### **open_composition_editor Errors** #### **BROWSER_NAVIGATION_ERROR** **Cause**: Failed to open composition in browser **Common Issues**: - Invalid composition UID - Browser automation failure - Network connectivity issues #### **COMPOSITION_UID_ERROR** **Cause**: Invalid composition UID format **Solution**: Ensure UID follows UUID format (36 characters with hyphens) ```javascript // ✅ Correct format "123e4567-e89b-12d3-a456-426614174000" ``` --- ## 🔧 **General Troubleshooting** ### **Environment Setup Issues** #### **NODE_ENV Configuration** Ensure proper environment configuration: ```json { "env": { "NODE_ENV": "development", "MCP_DEBUG": "true" } } ``` #### **Memory Issues** If encountering memory errors: ```json { "args": [ "--max-old-space-size=4096", "path/to/server.js" ] } ``` ### **Debug Mode** Enable enhanced debugging: ```json { "env": { "MCP_DEBUG": "true", "NODE_ENV": "development" } } ``` **Debug Output Includes**: - Detailed validation steps - Input/output data structures - Processing timestamps - Internal error context ### **Common Resolution Steps** 1. **Check Input Format**: Verify input matches expected schema 2. **Enable Debug Mode**: Set `MCP_DEBUG=true` for detailed logs 3. **Validate Environment**: Ensure all required environment variables are set 4. **Test Incrementally**: Test each tool individually to isolate issues 5. **Check Dependencies**: Verify Node.js version and package installations --- ## 📊 **Error Prevention Best Practices** ### **Input Validation** - Always validate input format before calling tools - Use TypeScript or JSON schema validation - Test with minimal examples first ### **Error Handling** - Implement proper try-catch blocks - Log errors with context information - Provide user-friendly error messages ### **Development Workflow** - Use fail-fast validation during development - Test with invalid inputs to understand error responses - Keep error handling documentation updated --- ## 🆘 **Getting Additional Help** ### **When to Report Issues** - Unexpected error codes not documented here - Error messages that don't provide clear resolution steps - Inconsistent error behavior across tools ### **Information to Include** - Complete error response (with credentials redacted) - Input data that caused the error - Environment configuration - Node.js and package versions - Steps to reproduce the issue ### **Support Resources** - **[API Reference](docs/API-REFERENCE.md)** - Complete tool documentation - **[Getting Started](docs/GETTING-STARTED.md)** - Setup and configuration - **[GitHub Issues](https://github.com/yourusername/euconquisto-composer-mcp-poc/issues)** - Bug reports --- **Last Updated**: January 21, 2025 **Version**: v1.1.0 Fail-Fast Reliability Suite **Status**: ✅ COMPLETE - Comprehensive error reference with troubleshooting solutions