EuConquisto Composer MCP

# Task: Natural Language Processing Implementation **Priority**: High **Created**: 2025-06-29 **Assigned**: Claude Code **Estimated Effort**: 3-4 implementation sessions ## Objective Implement the core Natural Language Processing layer that converts natural language prompts into automated educational composition creation using the existing MCP server infrastructure. ## Requirements - [ ] Create NLP prompt analysis module that parses educational content requests - [ ] Implement composition planning logic that maps content to appropriate widget types - [ ] Build MCP integration layer that executes composition creation via existing tools - [ ] Add error handling and validation for malformed or impossible requests - [ ] Create testing suite with sample educational prompts - [ ] Integrate with existing euconquisto-composer MCP server (7 tools available) ## Architecture Overview ### Core Components Needed: 1. **Prompt Parser** (`src/nlp/prompt-parser.ts`) - Educational content type detection (lesson, quiz, presentation, etc.) - Key concept extraction and learning objective identification - Content structure analysis (introduction, main content, exercises, summary) 2. **Composition Planner** (`src/nlp/composition-planner.ts`) - Widget selection logic using existing TypeScript interfaces - Content flow design (header → text → images → activities → quiz) - Template matching based on educational content patterns 3. **MCP Executor** (`src/nlp/mcp-executor.ts`) - Integration with existing 7 MCP tools - Composition workflow orchestration (create → populate → save) - Error handling and retry logic for MCP operations 4. **Content Generator** (`src/nlp/content-generator.ts`) - AI integration for educational content creation - Widget-specific content formatting (headers, text, lists, etc.) - Brazilian Portuguese educational content optimization ### Integration Points: - **Existing MCP Server**: Use `create-new-composition`, `edit-composition-metadata`, `save-composition` - **Widget Interfaces**: Leverage `mcp-interface-structure.ts` definitions (10 element types, 50+ widgets) - **Authentication**: Use existing JWT token system for composer access ## Implementation Strategy ### Phase 1: Core NLP Infrastructure ```typescript // Target file: src/nlp/nlp-processor.ts interface NLPRequest { prompt: string; language?: 'pt-BR' | 'en'; educationLevel?: 'elementary' | 'middle' | 'high' | 'university'; subject?: string; } interface CompositionPlan { title: string; description: string; widgets: WidgetPlan[]; metadata: CompositionMetadata; } ``` ### Phase 2: Educational Content Patterns ```typescript // Educational content type detection patterns const CONTENT_PATTERNS = { lesson: /(?:ensinar|explicar|aula sobre|lição)/i, quiz: /(?:quiz|teste|avaliação|perguntas)/i, presentation: /(?:apresentação|slides|mostrar)/i, workshop: /(?:workshop|oficina|atividade prática)/i }; ``` ### Phase 3: Widget Selection Logic ```typescript // Leverage existing widget types from mcp-interface-structure.ts const WIDGET_SELECTION = { intro: () => ['cabecalho', 'texto'], content: () => ['texto', 'imagem', 'lista'], interactive: () => ['interatividade', 'quiz'], summary: () => ['texto', 'marcadores'] }; ``` ## Sample Implementation Flow 1. **Input**: "Criar uma aula sobre fotossíntese para ensino médio" 2. **Parse**: Extract content_type='lesson', subject='fotossíntese', level='high' 3. **Plan**: Generate composition with header → intro text → explanation → diagram → quiz 4. **Execute**: Use MCP tools to create composition with planned widgets 5. **Output**: Functional composition URL ready for use ## Testing Requirements - [ ] Unit tests for prompt parsing with 20+ educational scenarios - [ ] Integration tests with MCP server (all 7 tools) - [ ] End-to-end tests with complete workflow (prompt → composition URL) - [ ] Performance tests for response time < 30 seconds - [ ] Error handling tests for invalid prompts and MCP failures ## Implementation Notes ### Technical Constraints: - Use existing MCP server (euconquisto-composer-enhanced v0.1.6) - Follow TypeScript interfaces in `mcp-interface-structure.ts` - Maintain compatibility with Playwright browser automation - Support Brazilian Portuguese educational content ### Success Criteria: - Convert natural language prompts to functional compositions - Generate appropriate educational content for detected subjects - Create coherent widget sequences that enhance learning - Handle errors gracefully with meaningful user feedback - Achieve < 30 second end-to-end processing time ### Dependencies: - Existing MCP server tools (7 available, all operational) - TypeScript widget interfaces (10 element types defined) - Browser automation infrastructure (Playwright + DOM selectors) - Authentication system (JWT tokens working) ### File Structure: ``` src/nlp/ ├── nlp-processor.ts # Main NLP coordination ├── prompt-parser.ts # Natural language analysis ├── composition-planner.ts # Widget selection and flow ├── content-generator.ts # Educational content creation ├── mcp-executor.ts # MCP tool integration └── __tests__/ # Comprehensive test suite ``` ### Environment Variables Needed: ```bash # Add to .env file OPENAI_API_KEY=your_key_here # For content generation GEMINI_API_KEY=your_key_here # Alternative AI provider NLP_LANGUAGE_DEFAULT=pt-BR # Brazilian Portuguese NLP_EDUCATION_LEVEL_DEFAULT=middle # Default education level ``` ## Coordination Notes - **Claude Desktop Role**: Provided architecture design and requirements analysis - **Claude Code Role**: Implement all TypeScript modules and testing suite - **Integration Point**: Leverage existing MCP server without modifications - **Validation**: Test with sample prompts before expanding functionality