EuConquisto Composer MCP

# NLP Implementation Architecture Analysis **Document Type**: Architectural Analysis **Created**: 2025-06-29 **Author**: Claude Desktop **Status**: Planning Complete, Ready for Implementation ## Executive Summary The Natural Language Processing implementation represents the core value proposition of the EuConquisto Composer MCP project. With the infrastructure breakthrough (DOM selectors fixed, MCP server operational), we can now implement the missing NLP layer that converts natural language prompts into automated educational composition creation. ## Current Infrastructure Assessment ### ✅ Available Foundation - **MCP Server**: euconquisto-composer-enhanced v0.1.6 (7 tools operational) - **Widget System**: 10 element types, 50+ widget variations (TypeScript interfaces complete) - **Browser Automation**: Playwright + DOM selectors working - **Authentication**: JWT token system functional ### ❌ Missing Components - **Natural Language Processing**: Prompt parsing and content analysis - **Composition Planning**: AI-driven widget selection and flow design - **Content Generation**: Educational content creation for detected subjects - **Integration Layer**: Bridge between NLP analysis and MCP execution ## Architectural Design ### 1. NLP Processing Pipeline ``` Natural Language Prompt → Parse → Plan → Generate → Execute → Composition URL ``` **Flow Details:** 1. **Input**: "Criar uma aula sobre fotossíntese para ensino médio" 2. **Parse**: content_type='lesson', subject='fotossíntese', level='high' 3. **Plan**: header → intro → content → diagram → quiz widget sequence 4. **Generate**: Educational content for each planned widget 5. **Execute**: Use MCP tools to create actual composition 6. **Output**: Functional composition ready for use ### 2. Core Modules Architecture #### A. Prompt Parser (`src/nlp/prompt-parser.ts`) **Responsibility**: Natural language understanding for educational content **Key Capabilities:** - Educational content type detection (lesson, quiz, presentation, workshop) - Subject matter identification and learning objective extraction - Target audience and education level analysis - Language detection and Brazilian Portuguese optimization **Integration**: Standalone module with clear input/output interfaces #### B. Composition Planner (`src/nlp/composition-planner.ts`) **Responsibility**: Educational design and widget selection **Key Capabilities:** - Pedagogical flow design (introduction → content → practice → assessment) - Widget type selection based on content requirements - Template matching for common educational patterns - Accessibility and engagement optimization **Integration**: Uses TypeScript interfaces from `mcp-interface-structure.ts` #### C. Content Generator (`src/nlp/content-generator.ts`) **Responsibility**: AI-powered educational content creation **Key Capabilities:** - Subject-specific content generation (Brazilian curriculum aligned) - Widget-appropriate content formatting (headers, text, lists, activities) - Age-appropriate language and complexity adjustment - Multilingual support with Portuguese focus **Integration**: AI API integration (OpenAI/Gemini) with fallback content #### D. MCP Executor (`src/nlp/mcp-executor.ts`) **Responsibility**: Composition creation orchestration **Key Capabilities:** - MCP tool sequencing (create → populate → save workflow) - Error handling and retry logic for browser automation - Progress tracking and user feedback - URL generation and composition persistence **Integration**: Direct integration with existing 7 MCP tools ### 3. Data Flow Architecture ```typescript interface NLPRequest { prompt: string; context?: { language: 'pt-BR' | 'en'; educationLevel: 'elementary' | 'middle' | 'high' | 'university'; subject?: string; duration?: number; // minutes }; } interface ParsedPrompt { contentType: 'lesson' | 'quiz' | 'presentation' | 'workshop'; subject: string; learningObjectives: string[]; targetAudience: EducationLevel; estimatedDuration: number; } interface CompositionPlan { metadata: { title: string; description: string; author: string; tags: string[]; }; widgets: WidgetPlan[]; flow: PedagogicalFlow; } interface WidgetPlan { type: ElementType; subtype?: string; content: GeneratedContent; position: number; dependencies?: string[]; } ``` ## Implementation Strategy ### Phase 1: Foundation (Session 1) - Core NLP processor with basic prompt parsing - Simple widget selection logic for common patterns - MCP integration for basic composition creation - End-to-end testing with 3-5 sample prompts ### Phase 2: Enhancement (Session 2) - Advanced AI content generation integration - Sophisticated pedagogical flow design - Error handling and edge case management - Expanded testing suite with 20+ scenarios ### Phase 3: Optimization (Session 3) - Performance optimization for sub-30 second processing - Brazilian educational curriculum alignment - Advanced widget features and interactivity - Production-ready error handling and logging ### Phase 4: Production (Session 4) - Comprehensive testing and validation - Documentation and user guides - Monitoring and analytics integration - Production deployment preparation ## Risk Assessment ### Low Risk - **MCP Integration**: Infrastructure proven operational - **Widget Interfaces**: Comprehensive TypeScript definitions available - **Authentication**: JWT system working correctly ### Medium Risk - **AI API Integration**: Rate limits and API reliability considerations - **Content Quality**: Ensuring educational content meets standards - **Performance**: 30-second processing time requirement ### Mitigation Strategies - **Fallback Content**: Pre-generated content templates for common subjects - **Caching**: Store common prompt patterns and generated content - **Progressive Enhancement**: Start with simple widgets, add complexity gradually ## Success Metrics ### Technical Metrics - **Processing Time**: < 30 seconds end-to-end - **Success Rate**: > 95% for well-formed prompts - **Error Handling**: Graceful degradation for edge cases ### Educational Metrics - **Content Quality**: Age-appropriate and curriculum-aligned - **Engagement**: Interactive elements and varied widget types - **Accessibility**: Support for different learning styles ### User Experience Metrics - **Ease of Use**: Natural language input without special syntax - **Flexibility**: Support for various educational content types - **Reliability**: Consistent composition creation and saving ## Next Steps for Claude Code 1. **Review Task**: Examine `docs/tasks/nlp-implementation-task.md` 2. **Environment Setup**: Install AI API dependencies and configure keys 3. **Phase 1 Implementation**: Start with core NLP processor module 4. **Testing**: Create sample prompts and validate MCP integration 5. **Iteration**: Report back findings and request architecture adjustments ## Architecture Decisions ### Technology Choices - **TypeScript**: Leverages existing codebase and type safety - **Modular Design**: Independent modules for easier testing and maintenance - **AI Integration**: OpenAI/Gemini APIs for content generation - **Brazilian Focus**: Portuguese language and curriculum optimization ### Design Patterns - **Strategy Pattern**: Multiple content generation strategies - **Factory Pattern**: Widget creation based on educational requirements - **Observer Pattern**: Progress tracking and error reporting - **Command Pattern**: MCP tool execution with undo/retry capabilities This analysis provides the foundation for Claude Code to implement the NLP system that will complete the core value proposition of automatic educational composition creation.