# 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
```bash
# 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`):

```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**: 
- **[Getting Started](docs/GETTING-STARTED.md)** - Complete setup guide (10-15 minutes)
- **[API Reference](docs/API-REFERENCE.md)** - Detailed tool documentation with schemas and error handling
- **[Error Reference](docs/ERROR-REFERENCE.md)** - Comprehensive troubleshooting guide
- **[Development Guide](docs/DEVELOPMENT.md)** - Contributing and development workflow
- **[Documentation Index](docs/README.md)** - Complete documentation overview

## Development Mode

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

```javascript
// 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