EuConquisto Composer MCP

--- document: Automated MCP Injection Tool Specification version: 1.0.0 status: active author: Claude Code created: 2025-06-30 last_updated: 2025-06-30 --- # Automated MCP Injection Tool Specification ## 🎯 **Overview** Specification for implementing `inject-and-view-composition` MCP tool that provides seamless, automated localStorage injection with optimal user experience for non-technical users. ## 📋 **Requirements Summary** ### **Primary Objective** Create fully automated MCP tool that generates interactive Composer compositions (not static HTML) and provides "click here to view" user experience. ### **Success Criteria** - ✅ **Zero manual steps** for end users - ✅ **Interactive widgets** in native Composer interface - ✅ **One-click viewing** from Claude Desktop response - ✅ **Professional UX** comparable to commercial tools ## 🔧 **Technical Specification** ### **MCP Tool Definition** ```typescript { name: "inject-and-view-composition", description: "Generate educational composition and inject into Composer for interactive viewing", inputSchema: { type: "object", properties: { prompt: { type: "string", description: "Educational content request (e.g., 'Create lesson about photosynthesis for 7th grade')" }, subject: { type: "string", description: "Subject area (optional, auto-detected if not provided)" }, gradeLevel: { type: "string", description: "Target grade level (optional, auto-detected if not provided)" } }, required: ["prompt"] } } ``` ### **Implementation Architecture** #### **Phase 1: Content Generation** (5 minutes) - **Input**: User prompt from Claude Desktop - **Process**: Use validated `working-intelligent-mcp-server.ts` system - **Output**: Complete composition JSON with Brazilian educational compliance - **Quality**: Leverage Phase 2 validated systems (100% success rate) #### **Phase 2: Browser Automation** (10 minutes) - **Authentication**: Use JWT redirect server (localhost:8080) - **Navigation**: Access `composer.euconquisto.com` with authenticated session - **Injection**: Execute localStorage injection using Option B validated mechanism - **Interface Discovery**: Find actual Composer editing interface (resolve 404 issue) #### **Phase 3: User Experience** (5 minutes) - **Validation**: Confirm composition loads with interactive widgets - **URL Generation**: Create direct link to injected composition - **Response Format**: Return structured response to Claude Desktop ## 🎨 **User Experience Flow** ### **Step 1: Request** ``` User → Claude Desktop: "Create a lesson about photosynthesis for 7th grade" ``` ### **Step 2: Processing** ``` Claude Desktop → MCP Tool: inject-and-view-composition - Generates composition JSON (fotossíntese example format) - Opens browser with JWT authentication - Injects composition into localStorage - Navigates to Composer interface - Validates interactive widget loading ``` ### **Step 3: Response** ``` Claude Desktop → User: ✅ Interactive composition created successfully! 📚 **Lesson**: Fotossíntese - Como as Plantas Produzem Alimento 🎯 **Grade Level**: 7º ano do Ensino Fundamental 🎨 **Widgets**: Header, Text, Video, Flashcards, Quiz (5 total) ⏱️ **Duration**: 50 minutes 🌐 **Click here to view**: https://composer.euconquisto.com/view/[composition-id] ``` ## 📁 **Implementation Files** ### **Core Implementation** - **MCP Tool**: `/src/mcp-tools/inject-and-view-composition.ts` - **Browser Controller**: `/src/automation/composition-injector.ts` - **Interface Discovery**: `/src/automation/composer-interface-mapper.ts` ### **Supporting Systems** - **Content Generation**: Existing `working-intelligent-mcp-server.ts` (validated) - **localStorage Injection**: Existing `tools/injection/localStorage-injection-v1.0.0.js` (validated) - **Authentication**: Existing JWT redirect server (operational) ### **Testing & Validation** - **End-to-End Test**: `/tests/mcp/test-inject-and-view-e2e.js` - **User Journey Test**: `/tests/workflows/test-complete-user-flow.js` ## 🔍 **Technical Challenges & Solutions** ### **Challenge 1: Composer Interface Access** **Current Status**: 404 errors on `/composer`, `/editor` paths **Solution Strategy**: - Inspect authenticated dashboard for composer access points - Map actual composer URLs through browser automation - Test different path combinations with authenticated session ### **Challenge 2: Composition Auto-Loading** **Current Status**: localStorage injection works, auto-loading unvalidated **Solution Strategy**: - Identify JavaScript events that trigger composition loading - Implement composition load triggers if needed - Validate widget rendering through screenshot comparison ### **Challenge 3: Direct URL Generation** **Current Status**: Need to create shareable composition links **Solution Strategy**: - Investigate Composer URL patterns for direct composition access - Generate stable composition IDs for URL construction - Validate link accessibility from external contexts ## 📊 **Quality Assurance Metrics** ### **Performance Targets** - **Total execution time**: ≤ 30 seconds end-to-end - **Success rate**: ≥ 95% for composition generation and injection - **Browser automation reliability**: ≥ 98% (based on Option B results) ### **User Experience Validation** - **Click-to-view success**: 100% (links must always work) - **Widget interactivity**: All composition elements fully functional in Composer - **Visual consistency**: Generated compositions match Composer design standards ### **Technical Validation** - **localStorage persistence**: 100% reliability across sessions - **Authentication integration**: Seamless JWT token handling - **Error recovery**: Graceful handling of network and browser issues ## 🚀 **Implementation Phases** ### **Phase A: Interface Discovery** (5 minutes) - Map authentic Composer editing interface URLs - Identify composition loading mechanisms - Establish direct access patterns ### **Phase B: MCP Tool Creation** (10 minutes) - Implement `inject-and-view-composition` tool - Integrate with existing intelligent systems - Add browser automation wrapper ### **Phase C: End-to-End Validation** (5 minutes) - Test complete user workflow - Validate interactive widget functionality - Confirm "click here to view" experience ## ✅ **Acceptance Criteria** ### **Functional Requirements** - [ ] MCP tool responds to composition requests - [ ] Generates educationally appropriate Brazilian Portuguese content - [ ] Successfully injects composition into Composer localStorage - [ ] Provides working "click here to view" links - [ ] Compositions display with interactive widgets (not static HTML) ### **Non-Functional Requirements** - [ ] ≤ 30 seconds total execution time - [ ] Graceful error handling and user feedback - [ ] Compatible with existing project architecture - [ ] Follows established coding patterns and documentation standards ### **User Experience Requirements** - [ ] Zero manual steps required from users - [ ] Clear completion messaging with actionable next steps - [ ] Professional presentation suitable for educational contexts - [ ] Reliable performance for non-technical users ## 📋 **Dependencies** ### **Existing Systems** ✅ **VALIDATED** - **Content Generation**: `working-intelligent-mcp-server.ts` (Phase 2 validated) - **localStorage Injection**: Option B implementation (100% functional) - **Authentication**: JWT redirect server (operational) - **Browser Automation**: Playwright infrastructure (tested) ### **External Dependencies** - **Composer Platform**: `composer.euconquisto.com` (requires interface discovery) - **JWT Token**: Valid authentication token (available in `archive/authentication/`) ## 🎯 **Success Definition** **This specification is complete when:** 1. **Non-technical users** can request compositions in natural language 2. **Claude Desktop** receives requests and calls the MCP tool seamlessly 3. **Automated system** generates, injects, and provides viewable compositions 4. **Users click a link** and immediately see interactive educational content 5. **Compositions use native Composer widgets** (header, text, video, flashcards, quiz) **Ready for implementation approval and execution.**