EuConquisto Composer MCP

# EuConquisto Composer MCP v5.2.0 - Project State Documentation **Version**: 5.2.0 FULLY OPERATIONAL **Date**: January 15, 2025 **Status**: 🎉 Complete End-to-End Success **Architecture**: JIT (Just-In-Time) Workflow with Exact API Compliance ## 🚨 CRITICAL: Version Verification Checklist Before proceeding with ANY work, verify you have the correct v5.2.0 state: ### ✅ Version Indicators - [ ] `package.json` shows version `"5.2.0"` - [ ] Main field points to `"dist/browser-automation-api-jit-v5.1.0.js"` - [ ] Description includes "Fully Operational v5.2.0" - [ ] Git log shows recent commits about v5.2.0 - [ ] `/bin/` contains only 2 files: `fix-startup-scripts.sh` and `start-production.sh` - [ ] `/src/tools/` contains exactly 11 JIT workflow tools - [ ] JWT token exists at `/config/jwt-token.txt` (centralized v1.0.0) ### ❌ Warning Signs of Old/Wrong Version - [ ] Multiple startup scripts in `/bin/` (should only have 2) - [ ] Version below 5.2.0 in package.json - [ ] Missing JIT tools in `/src/tools/` - [ ] References to old versions (v4.0.3, v5.0.0, etc.) in active files - [ ] Main field pointing to non-JIT server files ## 📁 Current Directory Structure ### Root Directory (Clean State) ``` /euconquisto-composer-mcp-poc/ ├── CLAUDE.md # Project memory (CRITICAL - always read first) ├── CLAUDE-DESKTOP-CONFIG.json # Claude Desktop configuration ├── SYSTEM_PROMPT.md # System prompt for Claude ├── VERSION-HISTORY.md # Complete version history ├── README.md # Project readme ├── package.json # v5.2.0 configuration ├── package-lock.json # Dependency lock file ├── tsconfig.json # TypeScript config ├── tsconfig-minimal.json # Minimal TS config ├── PROJECT-STATE-v5.2.0.md # THIS FILE ``` ### Critical Production Directories ``` ├── /bin/ # Startup scripts (ONLY 2 FILES) │ ├── fix-startup-scripts.sh # Script fixer utility │ └── start-production.sh # MAIN PRODUCTION STARTUP │ ├── /config/ # Configuration files │ ├── claude-desktop-config.json │ ├── claude-desktop-config-jit.json │ ├── claude-desktop-config-working.json │ ├── claude_desktop_config_minimal.json │ ├── jwt-token.txt # JWT token storage │ └── project.json # Project configuration │ ├── /dist/ # Production build │ ├── browser-automation-api-jit-v5.1.0.js # MAIN SERVER (JIT) │ ├── index.js # Entry point │ └── [various compiled files] │ ├── /src/ # Source code │ ├── /config/ # Configuration modules │ │ └── jwt-manager.js # 🔐 CENTRALIZED JWT MANAGER v1.0.0 │ ├── /guidance/ # Guidance system │ └── /tools/ # JIT WORKFLOW TOOLS (11 files) │ ├── get-smart-guidance.js # Step 1: Lightweight guidance │ ├── analyze-content-for-widgets.js # Step 2: Content analysis │ ├── get-widget-requirements.js # Step 3: API requirements │ ├── validate-lesson-data.js # Step 4: Auto-fix validation │ ├── format-for-composer.js # Step 5: Minimal transformation │ ├── save-composition-api.js # Step 6: Enhanced API save │ ├── open-composition-editor.js # Step 7: Workflow finalization │ ├── api-save-debugger.js # Debug utilities │ ├── payload-optimizer.js # Payload optimization │ ├── format-for-composer-fixed.js # Fixed formatter │ └── format-for-composer-backup.js # Backup formatter │ ├── /tools/ # Development tools │ ├── /servers/ # Server utilities │ │ └── jwt-redirect-server-v1.0.2.js # JWT redirect server (uses centralized JWT) │ ├── generate-docs.sh # Documentation generator │ ├── setup-dev-environment.sh # Dev setup │ └── validate-mcp-server.js # MCP validation ``` ### Documentation Structure ``` ├── /docs/ # Main documentation │ ├── INDEX-v5.2.0.md # Version index │ ├── technical-knowledge-base.md # CRITICAL technical reference │ ├── /milestones/ # Achievement documentation │ │ └── v5.2.0-fully-operational.md │ ├── /references/ # API references │ │ ├── json-example.md # OFFICIAL API FORMAT │ │ └── [other references] │ ├── /technical/ # Technical docs │ ├── /deployment/ # Deployment guides │ ├── /user/ # User documentation │ └── /project-management/ # Project organization ``` ### Archive Structure (Historical Files) ``` ├── /archive/ # All old/historical files │ ├── /authentication/ # JWT tokens │ ├── /old-versions/ # Previous server versions │ ├── /old-startup-scripts/ # Legacy startup scripts │ ├── /deployment-outdated/ # Old deployment docs │ └── [other archived items] ``` ## 🔑 Critical Files and Their Purposes ### Production Server - **Main Server**: `/dist/browser-automation-api-jit-v5.1.0.js` - Purpose: JIT workflow implementation with 7-step process - Token efficient (65% reduction) - Handles all MCP tools and browser automation ### JIT Workflow Tools (7 Steps) 1. **get-smart-guidance.js**: Lightweight guidance with widget prediction 2. **analyze-content-for-widgets.js**: Intelligent content analysis 3. **get-widget-requirements.js**: Just-in-time API requirements 4. **validate-lesson-data.js**: Auto-fix validation (prevents errors) 5. **format-for-composer.js**: Minimal transformation to API format 6. **save-composition-api.js**: Enhanced API save with error handling 7. **open-composition-editor.js**: Complete workflow finalization ### Authentication (Centralized v1.0.0) 🔐 - **JWT Token**: `/config/jwt-token.txt` ✅ **CENTRALIZED** - Valid token for API access - Managed by JWT Manager v1.0.0 (`/src/config/jwt-manager.js`) - Single secure location, no duplicates - Used by all components via centralized manager - DO NOT modify or regenerate - **JWT Manager Architecture**: - **Single Source of Truth**: Only `/config/jwt-token.txt` is used - **No Fallbacks**: Enhanced security by eliminating duplicate locations - **Token Validation**: Built-in JWT format and expiration checking - **Error Handling**: Clear error messages with specific file paths - **CLI Testing**: Run `node src/config/jwt-manager.js` for diagnostics ### Startup Scripts - **Production Start**: `/bin/start-production.sh` - Single entry point for production - Includes 4GB memory allocation - Proper error handling ### Configuration - **Package.json**: Version 5.2.0, main points to JIT server - **Claude Desktop Config**: Multiple configs for different scenarios - **Project Config**: `/config/project.json` ## 🚀 Starting the System ### Production Commands (Use Any) ```bash # Recommended - NPM script npm run start:production # Alternative - Direct MCP start npm run mcp:start # Shell script ./bin/start-production.sh ``` ### Memory Configuration All scripts include 4GB heap allocation: ```bash NODE_OPTIONS="--max-old-space-size=4096" ``` ## 🔍 System Verification Commands ### Check Version State ```bash # Verify package version grep '"version"' package.json # Check main server grep '"main"' package.json # List startup scripts ls -la bin/ # Check JIT tools ls -la src/tools/ # Verify centralized JWT token ls -la config/jwt-token.txt # Test JWT Manager node src/config/jwt-manager.js ``` ### Git State Verification ```bash # Check current branch git branch --show-current # View recent commits git log --oneline -5 # Check for uncommitted changes git status ``` ## 🛡️ Recovery Procedures ### If Wrong Version Detected 1. **STOP** - Do not make any changes 2. **Verify** current state: ```bash grep version package.json git log --oneline -1 ``` 3. **Check** for correct v5.2.0 markers 4. **Report** discrepancy before proceeding ### Safe Git Operations #### Before Any Commit ```bash # Always check status first git status # Review changes git diff # Stage carefully git add -p # Interactive staging # Commit with clear message git commit -m "feat: [description] - v5.2.0" ``` #### Creating Backups ```bash # Before major changes git stash save "backup-before-[operation]-$(date +%Y%m%d-%H%M%S)" # Create branch backup git branch backup-v5.2.0-$(date +%Y%m%d-%H%M%S) ``` ### Emergency Rollback ```bash # If something goes wrong git reset --hard HEAD~1 # Undo last commit git checkout -- . # Discard all changes ``` ## 📊 v5.2.0 System Components ### Core Features - ✅ **Universal Content Generation**: Any educational topic - ✅ **JIT Workflow**: 7-step token-efficient process - ✅ **API Compliance**: Exact match with EuConquisto format - ✅ **Browser Automation**: Playwright-based with JWT auth - ✅ **Error Prevention**: Auto-fix validation system - ✅ **Performance**: ~250ms generation time ### Workflow Summary 1. User provides educational prompt 2. Claude generates natural content 3. System analyzes for widget mapping 4. Retrieves exact API requirements JIT 5. Validates with auto-fix capabilities 6. Formats to exact API structure 7. Saves via API and opens in browser ### Key Achievements - **Token Reduction**: 65% (8,400 → 2,952 tokens) - **Performance**: 99.97% faster than targets - **Success Rate**: 100% end-to-end completion - **HTTP Status**: All 200 OK (500 errors resolved) ## 🔐 Security Considerations ### JWT Token (Centralized v1.0.0) - Location: `/config/jwt-token.txt` ✅ **SECURE CENTRALIZED LOCATION** - Manager: `/src/config/jwt-manager.js` (Single source of truth) - Do NOT commit changes to this file - Do NOT share or expose the token - All components use centralized JWT manager - Valid for API access to EuConquisto ### API Endpoints - Production: `https://api.digitalpages.com.br/` - All requests use Bearer authentication - HTTPS only, no HTTP fallback ## 📝 Development Guidelines ### Before Making Changes 1. Read `/CLAUDE.md` for project context 2. Check `/docs/technical-knowledge-base.md` 3. Verify you have v5.2.0 state 4. Create feature branch if needed ### Code Standards - Maintain JIT architecture - Preserve working components - Follow exact API format from `/docs/references/json-example.md` - Test thoroughly before commits ### Documentation Updates - Update CLAUDE.md for major changes - Keep version history current - Document any new discoveries - Maintain this PROJECT-STATE file ## 🎯 Quick Reference Paths ### Most Important Files ``` /CLAUDE.md # Project memory /docs/technical-knowledge-base.md # Technical foundation /docs/references/json-example.md # API format reference /dist/browser-automation-api-jit-v5.1.0.js # Main JIT server /bin/start-production.sh # Startup script /config/jwt-token.txt # Centralized JWT token /src/config/jwt-manager.js # JWT Manager v1.0.0 ``` ### Key Documentation ``` /docs/milestones/v5.2.0-fully-operational.md # Current achievement /VERSION-HISTORY.md # Complete history /docs/technical/jit-architecture-deep-dive.md # JIT details /docs/deployment/production-deployment-guide.md # Deployment guide ``` ## ⚠️ Critical Warnings ### DO NOT - ❌ Modify working JWT token - ❌ Change main server path in package.json - ❌ Delete or move JIT tools - ❌ Revert to old versions - ❌ Create multiple startup scripts - ❌ Ignore version verification ### ALWAYS - ✅ Verify v5.2.0 state before work - ✅ Read CLAUDE.md first - ✅ Check technical knowledge base - ✅ Test changes thoroughly - ✅ Commit with clear messages - ✅ Update documentation ## 🏁 Summary This is the **v5.2.0 FULLY OPERATIONAL** state of EuConquisto Composer MCP. The system is working perfectly with: - Complete end-to-end functionality - JIT workflow implementation - Exact API compliance - Production-ready deployment **Last Verified**: January 15, 2025 **Status**: FULLY OPERATIONAL **Confidence**: Maximum --- **Remember**: Always verify you have the correct v5.2.0 state before making any changes. When in doubt, check this file and CLAUDE.md first!