rkm097git/euconquisto-composer-mcp-poc

EuConquisto Composer MCP

Educational content creation system with direct API integration for EuConquisto Composer platform.

Current Version: v1.1.0 (Fail-Fast Reliability Suite)

✨ What's New in v1.1.0

• Fail-Fast Validation: All 7 tools enhanced with comprehensive error reporting
• Development Mode: Clear, actionable error messages for faster debugging
• Dynamic Content Adaptation: Supports 6 different content formats automatically
• No Breaking Changes: Fully backward compatible with v1.0.0
• Comprehensive API Documentation: Complete reference for all 7 workflow tools

Features

• 🎯 Direct API Integration: No browser automation complexity
• 🚀 7-Step Workflow: Complete lesson creation pipeline
• 📚 Universal Content Support: Any educational topic without templates
• 🔍 Comprehensive Validation: Immediate feedback on issues
• 🌐 Brazilian Education Focus: Grade levels and BNCC compliance

Quick Start

Prerequisites

• Node.js 18+
• Claude Desktop
• EuConquisto Composer account credentials

Installation

# Clone repository
git clone https://github.com/yourusername/euconquisto-composer-mcp-poc.git
cd euconquisto-composer-mcp-poc

# Install dependencies
npm install

Configuration

Update your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "euconquisto-composer-direct": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "/absolute/path/to/euconquisto-composer-mcp-poc/dist/direct-api-server-v1.0.0.js"
      ],
      "env": {
        "EUCONQUISTO_ACCESS_TOKEN": "your_access_token_here",
        "EUCONQUISTO_PROJECT_UID": "your_project_uid_here",
        "EUCONQUISTO_CONNECTORS": "[{\"uid\":\"your_connector_uid\",\"name\":null,\"type\":\"Composer_1\",\"permissions\":[]}]",
        "NODE_ENV": "development",
        "MCP_DEBUG": "true"
      }
    }
  }
}

Important: Replace /absolute/path/to/euconquisto-composer-mcp-poc/ with your actual project path.

Usage

1. Restart Claude Desktop
2. Use the 7-step workflow:
   • get_smart_guidance - Get educational guidance with widget predictions
   • analyze_content_for_widgets - Analyze content structure (6 formats supported)
   • get_widget_requirements - Get widget specifications with validation rules
   • validate_lesson_data - Validate lesson structure with fail-fast error reporting
   • format_for_composer - Format for Composer API with structure verification
   • save_composition_direct_api - Save to platform via direct API
   • open_composition_editor - Open in browser with navigation checks

📚 Complete Documentation Suite:

• - Complete setup guide (10-15 minutes)
• - Detailed tool documentation with schemas and error handling
• - Comprehensive troubleshooting guide
• - Contributing and development workflow
• - Complete documentation overview

Development Mode

v1.1.0 introduces fail-fast validation with detailed error messages:

// Example error response
{
  success: false,
  error: {
    code: 'VALIDATION_FAILED',
    message: 'Detailed error description',
    troubleshooting: {
      requiredInputStructure: { ... },
      commonIssues: [ ... ],
      debugSteps: [ ... ]
    }
  }
}

Architecture

• Direct API: Environment-based authentication
• No Browser Automation: Simple, reliable HTTP calls
• Modular Tools: Each step is independent
• Fail-Fast: Immediate validation feedback

License

MIT

Support

For issues or questions, please open a GitHub issue.

Status: ✅ Production Ready with Enhanced Development Mode